Finding and Replacing Text in Multiple Files

To open the Find/Replace in Files dialog box, use the Find/Replace in Files action that is available in the following locations::

The operation works on both local and remote files from an (S)FTP, WebDAV or CMS server.

It enables you to define Search for or Search for and Replace operations across a number of files. You can use Perl-like regular expression syntax to match patterns in text content. The replace operation can bind regular expression capturing groups ($1, $2, etc.) from the find pattern.

Tip: To replace the tag-name start tag and its attributes with the new-tag-name tag use as Text to find the expression <tag-name(\s+)(.*)> and as Replace with the expression <new-tag-name$1$2>.

The encoding used to read and write the files is detected from the XML header or from the BOM. If a file does not have an XML header or BOM Oxygen XML Author uses by default the UTF-8 encoding for files of type XML, that is for files with one of the extensions: .xml, .xsl, .fo, .xsd, .rng, .nvdl, .sch, .wsdl or an extension associated with the XML editor type. For the other files it uses the encoding configured for non-XML files.

You can cancel a long operation at any time by pressing the Cancel button of the progress dialog box displayed when the operation is executed.

Since the content of read-only files cannot be modified, the Replace operation is not processing those files. For every such file, a warning message is displayed in the message panel.

Figure: Find / Replace in Files Dialog Box

The dialog box contains the following options:

  • Text to find - The target character string to search for. You can search for Unicode characters specified in the \uNNNN format. Also, hexadecimal notation (\xNNNN) and octal notation (\0NNNN) can be used. In this case you have to select the Regular expression option. For example, to search for a space character you can use the \u0020 code.
  • Case sensitive - When selected, the search operation follows the exact letter case of the value entered in the Text to find field.
  • Whole words only - Only entire occurrences of a word are included in the search operation.
  • Ignore extra whitespaces - If selected, the application normalizes the content (collapses any sequence of whitespace characters into a single space) and trims its leading and trailing whitespaces when performing the search operation.
  • Regular expression - When this option is selected, you can use regular expressions in Perl-like regular expressions syntax to look for specific pieces of text.
    • Dot matches all - A dot used in a regular expression also matches end of line characters.
    • Canonical equivalence - If selected, two characters will be considered a match if, and only if, their full canonical decompositions match. For example, the ã symbol can be inserted as a single character or as two characters (the a character, followed by the tilde character). This option is not selected by default.
  • XPath - The XPath 2.0 expression you input in this combo is used for restricting the search scope.
    Note: The Content Completion Assistant helps you input XPath expressions, valid in the current context.
  • Enable XML search options - This option is only available when editing in Text mode. It provides access to a set of options that allow you to search specific XML component types:
    • Element names - Only the element names are included in the search operation that ignores XML-tag notations ('<', '/', '>'), attributes or white-spaces.
    • Element contents - Search in the text content of XML elements.
    • Attribute names - Only the attribute names are included in the search operation, without the leading or trailing white-spaces.
    • Attribute values - Only the attribute values are included in the search operation, without single quotes(') or double quotes(").
    • Comments - Only the content of comments is included in the search operation, excluding the XML comment delimiters ('<!--', '-->').
    • PIs (Processing Instructions) - Only the content are searched, skipping '<?', '?>'. e. g.: <?processing instruction?>
    • CDATA - Searches inside content of CDATA sections.
    • DOCTYPE - Searches inside content of DOCTYPE sections.
    • Entities - Only the entity names are searched.

    The two buttons Select All and Deselect All allow a simple activation and deactivation of all types of XML components.

    Note: Even if you select all options of the Enable XML search options section, the search is still XML-aware. If you want to perform the search over the entire file content, deselect Enable XML search options.
  • Replace with - The character string with which to replace the target. It may contain regular expression group markers if the search expression is a regular expression and the Regular expression checkbox is selected.
  • Make backup files with extension - In the replace process Oxygen XML Author makes backup files of the modified files. The default extension is .bak, but you can change the extension as you prefer.
  • Selected project resources - Searches only in the selected files of the currently opened project. This option is not displayed when this dialog box is opened from the contextual menu of the DITA Maps Manager view and Archive Browser view.
  • Project files - Searches in all files from the current project. This option is not displayed when this dialog box is opened from the contextual menu of the DITA Maps Manager view and Archive Browser view.
  • All opened files - Searches in all files opened in Oxygen XML Author (regular files or DITA maps). You are prompted to save all modified files before any operation is performed. This option is not displayed when this dialog box is started from the contextual menu of the DITA Maps Manager view and Archive Browser view.
  • Current file directory - The search is done in the directory of the file opened in the current editor panel. If there is no opened file, this option is not available. Also, this option is not displayed when this dialog box is opened from the contextual menu of the DITA Maps Manager view and Archive Browserview.
  • Current DITA Map hierarchy - The search is done in all maps and topics referenced by the currently selected DITA map, opened in the DITA Maps Manager view.
  • Opened archive - The search is done in an archive opened in the Archive Browser view. Displayed only when this dialog box is opened from the Archive Browser view.
  • Specified path - Chooses the search path.
  • Include files - Narrows the scope of the operation only to the files that match the given filters.
  • Recurse subdirectories - When selected, the search is performed recursively for the specified scope. The one exception is that this option is ignored if the scope is set to All opened files.
  • Include hidden files - When selected, the search is also performed in the hidden files.
  • Include archives - When selected, the search is also done in all individual file entries from all supported ZIP-type archives.
  • Show separate results for each search expression - When selected, the application opens a new tab to display the result of each new search expression. When the option is unchecked, the search results are displayed in the Find in Files tab, replacing any previous search results.
  • Find All - Executes a find operation and returns the result list to the message panel. The results are displayed in a view that allows grouping the results as a tree with two levels.
  • Replace All - Replaces all occurrences of the target contained in the specified files.

When you replace a fragment of text, Oxygen XML Author provides a preview of the changes you make. The Preview dialog box is divided in two sections. The first section presents a list of all the documents containing the fragment of text you want to modify. The second section offers a view of the original file and a view of the final result. It also allows you to highlight all changes using the vertical bar from the right side of the view. The Next change and Previous change buttons allow you to navigate through the changes displayed in the Preview dialog box.

Use this option with caution. Global search and replace across all project files does not open the files containing the targets, nor does it prompt on a per occurrence basis, to confirm that a replace operation must be performed. As the operation simply matches the string defined in the find field, this may result in replacement of matching strings that were not originally intended to be replaced.