The Advanced Find & Replace dialog is available from the main window. Select "Advanced Find & Replace" from the Command menu or click the find icon on the Find & Replace panel (See the View menu).
Advanced find and replace does everything the regular find and replace does and more. The search button will be disabled when there are no files in the FAR file list.
When Prompt Mode is checked you will see a Find & Replace confirmation / preview window as each match is found.
The Preview dialog (Replace mode)
File: Name of current file being searched. This field is readonly and can be copied (select and press Ctrl+C).
Options: Click "Options" (or press Alt+O or Ctrl+O) to access the options popup.
- Show Low ASCII Characters: Makes visible all low ASCII characters such as Linefeed, Carriage Return and Tab characters.
- Open File: Open the current file in the default application (according to the windows file association).
- Open As Text: Open the current file in your text editor (as defined in FAR Preferences dialog).
- View As Hex Dump: View the current file in raw hexadecimal format.
- Copy: Copy the selected text to the Windows clipboard (top text control).
Note: If you modify the current file using an external application, when you switching back to FAR, click "Next". If you have unsaved changes in FAR, then at the time of FAR saving the file, you will be given the options of:
- Save & continue
- Skip file save
- Reload file and search it again.
Text found - Line#: Displays the line number where the match text was found.
Text found: This text window display a slab of text from the current file with the match text selected, and underlined in the middle. If the current file size is very big then you will see the text <snip> at top and/or bottom of the text. Note that removing the highlight will not upset the replacement. This found text can not be edited.
Replace with: In Replace mode this displays the text that will replace the highlighted /underlined text above. This text can be edited.
When you edit the replacement text, the background color will change to a bright yellow. Right click the text control and select "Revert", to return to the original replacement text. Take care with dynamic replacements (containing $A$ etc) as once you change the text the dynamic changes are disabled until you "Revert" to the original text again.
The preview dialog has the following buttons in replace mode:
Yes Perform the replacement. No Skip the replacement. Cancel Terminate multi-file find and replace. The current file in memory will not be saved. This means any other changes made to the current file will be lost. Changes made to other files have already been saved to disk. Replace All Turns prompting off for the rest of this session of multi-file find and replace. Next file Skip the current replacement, save all changes to the current file and move to the next file in the file list.
The preview dialog has the following buttons in find only mode (Replace Text checkbox is deselected):
Next Go and search for another match. Cancel Terminate multi-file search. Find All Turns prompting off for the rest of this find session. This is useful to quickly see how many matches are in the file list. Each match is recorded in the main file list. Next file Stop searching the current file and move onto the next file in the FAR file list.
Search definitions are stored in .FarRun files (a format usually used by FAR batch script files). The file format is the same as batch script, so this file will help those who create FAR batch files.
When saving, search definitions are merged with the target file. So extra file content such as comments or non-search commands will remain after performing a save. Note however the Save As dialog allows you to fully overwrite the target file, as well as save just the current definition. When a .FarRun file is loaded, only definitions containing search item (FindStart=) are loaded.
The .FarRun files are just text files. We encourage you to edit this directly. The [DEFAULT] section defines the order (as you see it in the search definition dropdown). If you delete the [DEFAULT] section, or any of its items, then the items will be found as the section names and the [DEFAULT] section will be fully recreated next time you save. Because the name DEFAULT has special meaning, you will see that if you create a definition called DEFAULT then it's saved in a file section called [_DEFAULT].
File > New Create a new search definition file. Each search definition file can store hundreds of search definitions. File > Open Load a previously saved search definition file. File > Reopen Load a previously saved search definition file. A list the most recently used files is available. Click a file name to reload that file. This same list is available by clicking the file link. File > Save Save all definitions (all definitions in the Search Definition dropdown) to the current file. If definitions were removed you will be asked to confirm the deletion of these files. FAR basically finds those definitions that exist only in the target file and gives you the opportunity to keep them or discard them. Clicking the Save buttons performs the same action. File > Save As Save to the file name and location of your choice.
Checkbox: Save All (default setting is checked). Uncheck this box to save only the current search definition. Remember that definitions are appended to the target file by default, so don't be surprised if the resultant file contains more than one item (even though you unchecked this box). If you only want the current definition in the target file, then make sure you save to a new file name, or check the Replace File checkbox below.
Checkbox: Replace File - Check this to delete the target file before saving. The default is NOT to delete first, and to try and merge with the target file settings.
Edit as Text Opens the search definition file in a text editor. The preferred text editor for FAR can be set in the FAR Preferences dialog. Options These settings are menu checkboxes. They are additional advanced options that effect search. You can also check/uncheck these settings by clicking their icons in the options group box.
DOS "\" = UNIX "/"
- File paths in MS HTML can contain a mixture of both DOS and UNIX file separators. When this setting is checked DOS paths will match UNIX paths and visa-versa. Leave this setting checked unless searching for string containing slashes.
Find first Occurrence Only
- Normally FAR finds every occurrence in a file. Check this if you only want to find just the first occurrence in each file.
Match Start of File Only
- Causes search to match only the very start of each file. So a match, if found, will begin at character 1 of each file.
The file link displays the current search definition file. All the search definitions loaded in the Search Definition dropdown were read from this file. When you save, they will be saved back to this file.
Double click the link to open the file in your text editor. See "File > Edit as Text" above. Click the link to access the most recently used file list and other file commands.
To store a definition, press the Add button and enter a unique name for the definition.
To recall a previously stored definition, select a name from the dropdown.
To remove a definition, first select the definition from the dropdown, then press the Remove button.
Note that these settings and changes are stored in memory until Save or Search are clicked. Then they are saved permanently to file.
Typically you would leave all setting checked for HTML work. These are the same checkboxes as you see in the Find Panel on the FAR main window.
[X] Prompt Mode
In prompt mode you get to preview each match found. No replacement is done until you click the Yes or All button. Always start a search with this setting enabled, you can always click the Replace All button to skip further prompting. See Preview Dialog below.
[X] Ignore Case
- When checked, a search for say Boy will match BOY and boy.
[X] Ignore CR LF
- HTML documents often breaks lines at unpredictable places. Check this option to search right through all line breaks. A line break is seen as a single space. Leave this setting checked unless specifically searching for line breaks characters.
EG. To search for Carriage Return, Linefeed characters enter the code $#13$$#10$
[X] Ignore Multi-Spaces
- Multiple spaces have no meaning in HTML and can make text difficult to find. Check this option to treat all multiple spaces as a single space. Normally you would leave this setting checked. Just make sure your Find text contains only single spaces, otherwise you will never match.
[X] Search All Files
- Uncheck this option to search only the selected files in the FAR file list.
The other iconic settings represent advanced search settings found in the options menu. They are linked to the options menu items. Click them to check/uncheck the equivalent options menu items.
Start with:Enter the text you want to find. To find text spanning between some start and end text check the "Ending with" checkbox and enter end text. The match will include the start and end text.
Start with: <body
End with: >
Will match <body> as well as <body Onload='myfunc()'>
Check this box and enter end text to find a block of text with known start and end text. See Start with above.
Check this box and enter some text to add a further constraint to the search. When checked, only text containing this text will match.
Start with: <body
End with: >
Will not match <body>, but will match <body Onload='myfunc()'>
Not Containing:Check this box and enter some text to add a further constraint to the search. When checked, only text that does not contain this text will match.12/05/2007 - FAR build 667 - Change in the way Containing and Not Containing works.
Start with: <body
End with: >
Not Contains: Onload
Will match <body>, but will not match <body Onload='myfunc()'>
In this version of FAR if you use a Containing or Not Containing text that matches the beginning the Start with text, we now ignore the hit (which is mostly useless), and move the search file pointer on just past the 'Start with' match text.
Note: there is a setting in Settings.ini that can switch off this new behavior.
Start with: xxx
End with: yyy
Not Contains: xxx
If the file contain xxx xxx yyy FAR will now match xxx yyy only, ignoring the first xxx hit. Previous versions would never generate a hit at all.
Start with: xxxFAR will match text xxx xxx yyy but not text xxx yyy. For previous versions the Contains text does nothing since it always matched the Start with text.
End with: yyy
Uncheck the "Replace Text" box to find text only. When checked the replace text entry field. Enter single or multiple lines of text. Any line breaks entered will be used.
For special advanced command codes see Advanced Settings Pane below.
Displays a list of advanced commands that can be inserted into the replace text entry field (you should first set the insert point in the replace text entry field). Note that some commands such as $L$, $M$ open an intermediate dialog to allow you to select a file.
$$ commands are described below.
Hide and show the advanced settings pane.
Displays some info and extra fields for a number of advanced $$ replacement commands. See below.
Provides easy access to the $A$, $B$, $C$ Substring definition dialogs.
Relative Path page
Click the browse button [...] and select a file to insert into your files. The file name is wrapped in $R$[...] command script and inserted into the edit field. You can then copy this command text into your replace text. More on the $R$ command below.
Move Link page
More on the $M$ command below.
Enter any notes you want to store with the current definition (plain text only).
Save any changes, close the dialog and start searching. The button is disabled if there are no files are in the FAR file list (main window).
Saves any changes made. Same as the "File > Save (ctrl+S)" command.
Discard any unsaved changes made since the dialog was opened and close the dialog. Esc key will also cancel the dialog. You will be prompted to save any unsaved changes.
Special codes of the form $x$ can be inserted into the Replacement text (and Find text where specified). When a find and replace is performed any codes found will be expanded. These commands can also be inserted into the replace text (adv dialog) using the [v] button.
$A$,$B,$C$ $A*$,$B*$,$C*$ Substrings $#nn$ Special Character command $L$, $L+, $L*$ Lowercase commands $F$, $F.$, $F*$ File name commands $DT$, $DT$[format], $D-$ File date time commands $I$ Insert text from file command $O$, $O-$, $O1$, $O2$ Original Match Text commands $R$ Relative Path command $T$ Set HTML Title command $M$ Move Link command $X*$, $X+$, $X-$, $X@$ XML Data Island commands (separate topic)
Easy access to the $$ commands can be gained from the [V] button and drop down list.
$A$,$B$ & $C$ represent substrings extracted from the match text found during find and replace.
See Define Substring dialog help.
[New for FAR HTML 5]
$A*$,$B*$ & $C*$ are similar to $A$..$C$ and use the same $A$..$C$ definitions you setup using the Define Substring dialog.
- $A$ is a substring of the current match text. It is recalculated for every match text found (this could be many times for a single file).
- $A*$ is a substring of the current file. It is recalculated once as each file is loaded for searching. With $A*$ you could, for example, setup a $A$ definition that found the substring between <title> and </title>.
So $A$ is recalculated every time FAR finds a search hit. And $A*$ is calculated whenever a file is loaded for search.
See Define Substring dialog help.
If the special character string $#nn$ is found in a find or replace entry field then during Find and Replace $#nnn$ will be replaced by the char representation of nnn.
$#13$ is replaced by the CR char
$#10$ is replaced by the LF char
$#09$ is replaced by the Tab char
Note: If you try and search for CR/LF characters, search will probably fail until you turn off the search option "Ignore CR LF Chars".
Use $L$ to set all HTML tag strings to lowercase. Use separately from all other commands. This special command requires the following settings:
Set Start with: <
Set End with: >
Set Replace: $L$ (any other text entered around $L$ is ignored)
Click the search button. All tags containing upper case chars will be changed to lowercase. Test this with prompt mode on.
This command was written to assist those moving from HTML to XHTML or XML.
Note: The search command finds the first '<' character and begins changes from there.
Example: <A HREF="SOMEFILE"> would be converted to <a HREF="SOMEFILE">.
$L+$ is the same but includes the Tag Attributes.
Example: <A HREF="SOMEFILE"> would be converted to <a href="SOMEFILE">.
$L*$ makes everything lowercase.
Set Start with: href="
Set End with: "
Set Replace: $L*$ (any other text entered around $L$ is ignored)
This will force everything in the match string to lowercase.
Example: <A HREF="SOMEFILE">Click me</A>
would be converted to <a href="somefile">click me</a>.
%format% codes are the same as Batch date time formats.
Start with: <body
End with: >
Replace with: $O$
Will match <body ???> in each HTML file and replace <body ???> with itself followed by <script... on the next line.
Tip: How would I add text to only those files that don't already have the text? For example add a Style Sheet include statement to HTML files that do not already have the include text.
- Add all your HTML files to the FAR file list.
- Perform a Find to locate the files that already contain the new text.
- From the main window sort your list by clicking on the "Matches" column heading.
- Now you have all the up to date files in a bunch. Select these and remove them from the list.
- Perform the required text insert on the remaining files.
Another option is to first strip all existing text and the add the new text to every file.
This command can insert text from an external file. This command can be used in the Replace text only.
The file name must be an absolute path surrounded by square brackets as shown above. When the replacement is performed, FAR will replace "$I$[xxx]" with the text found in the supplied ASCII file.
This command is very useful for inserting Style Sheet or Script file names (relative paths) into files scatted though different folders. The different folders mean that the relative path would need to be constantly adjusted.
Syntax 1: $R$[c:\path\file.ext]
The file name must be an absolute path surrounded by square brackets as shown above. When the replacement is performed, FAR will replace "$R$[xxx]" with the calculated relative path.
Syntax 2: $R$[int:n] where n is an integer offset usually 0
This inserts the folder depth as a number string (depth relative to the root of the FAR file list).
$R$[int:0] would be replaced with '0' if the current file is in the root folder, '1' if file is 1 folder below the root folder, '2' if 2 folders below etc.
$R$[int:10] - 10 is an offset. This would be replaced with '10' if the file is in the root folder, '11' if file is 1 folder down from the root folder etc.
Syntax 3: $R$[str:ss] where ss is a string
This inserts string 'ss' repeated n times where n is the folder depth relative to the root FAR file list).
$R$[str:..\] would be replaced with '' if the file is in the root folder, '..\' if file is 1 folder down from the root folder, '..\..\' if file is 2 folders down from the root folder etc.
So this is yet another another way to insert a relative file path.
EG. $R$[..\]SomeFile.JS -- If SomeFile.JS lived in the root folder (of the FAR file list) then FAR inserts the correct number of '..\' strings before the 'SomFile.JS' text.
On Adv Find and Replace dialog, in the [V] drop down insert menu you will see "$R$[..] -- Insert NavScript.js web help script".
This uses the above commands to insert the following text.
Basically it's for Web Uncompressed Help where you want to insert a link into every to reopen the navigation pane. You can read more here about the script.
More on Syntax 1 - $R$[c:\path\file.ext]
How to do it:
- In the Relative Path page click the [...] browse button and select a file to insert.
- The edit field will now show: $R$[x:\path\file.ext]
- Insert this text into the required position in the Replace text using Copy (Ctrl+C) and Paste (Ctrl+V).
Start with: <header>
Replace with: $O$
<link rel="stylesheet" type="text/css"
This will find the start of the header block "<header>" and replace it with itself closely followed by a CSS include statement. The "$R$[c:\site\html\farstyles.css]" will be replaced with the appropriate relative path for that file. EG. "farstyles.css" or "../farstyles.css" or "../html/farstyles.css" etc.
The resultant relative path will contain UNIX separators "/" since DOS separators "\" don't work in some HTML environments. If you want to force DOS separators then temporarily uncheck the "DOS "\" = UNIX "/"" check box.
This command is useful when you have to set the HTML document title <title>xxx</title>, of many documents to say the first <h1> string found in each document.
This command can only be used in the replacement text block.
NewTitle can be anything from plain text to a combination of text and other tags.
Lets say our HTML file titles have been set incorrectly and we want to set each title to the first H1 text found in each document. I.E. <h1>ThisText</h1> --> <title>ThisText</title>.
Set up the search params as follows:
Start with: <h1
End with: </h1>
This will find the string <h1 ??>text</h1>.
To extract the actual text in the middle we will need to define a $A$ substring.
$A$.Find Sub Str No = 1
$A$.Start Text = ">"
$A$.End Text = "<"
$A$.Include Start End Text=No
So now every search hit will contain the H1 text in our $A$ variable.
All we need now is the replace text:
Replace with: $T$$A$
When you perform a search everything after $T$, in this case the H1 text stored inside $A$, is inserted between the documents <Title> and </title> tags. Experiment and get a feel for its scope.
We made this command so we could move certain binary files (.pdf, .doc. zip etc) to a separate folder system. To be precise we move the binary downloads outside the Help web, convert the links to absolute links dynamically at run-time using script then convert the entire help web to a CHM. Without the binary files the CHM is quite small and we can ship the entire web + binary files (the ones that fit) on CDROM to our support staff. So anyway, we have included this code into FAR in case others find it handy.
Warning: Great care must be taken. When experimenting with this command, make sure you experiment on a copy of the help web first. The command can save a lot of time but also cause a lot of damage if your rules are not setup correctly. It is not simple to use, but maybe we can improve it in the future.
Old location base dir:
Base folder used by all the items in column 1 of the Relocation Rules list.
New location base dir:
Base folder used by all the items in column 2 of the Relocation Rules list.
Note: The "New Location Base Folder" must be on the same disk as the Help Web. This is because FAR performs a file rename, not do a copy and delete.
File Types to move:
A list of all file types you want to move with the $M$ command. Each file extension should start with a dot and be separated from each other by a space. Example: ".zip .exe .pdf"
Note: HTML files cannot be moved. Any HTML files added here will be ignored.
During the $M$ move command each link we find is expanded to a full path. It is then tested to see if the file type matches one of the file types list above. Next we search download the list, testing if "Old location base dir"/OldLocation(n) is part of the current links path. If it is, we then change the links path to "New location base dir"/NewLocation(n) + Link file name. We then make the link path relative again and if the "Link is Unix" is checked, we change all file separators from DOS (\) to Unix (/). After every matching link has been changed in all files in FAR file list, we finally move all binary files effected to their new location.
Note: You can optionally make the last item in the list an empty string (Old Location = '') which means that if all tests fail then the final rule will be used.
See "The $M$ Procedure" below for instructions on how to auto fill this list. The list also has a right-click menu.
Link is Unix:
Check this if all links changed should be Unix links (/). Normally you would leave this checked.
The $M$ Procedure:
- Set up relocation rules. Which files to move where?
Turn off all drop filters and drop your help web onto the FAR main window. Sort by File Ext and then remove all content files from the list (HTML, GIF, JPG, CSS, TXT, JS etc). This leaves just the required ZIP, DOC, PDF etc files you want to move.
- Click the Define $M$ button (Move Link Page, Adv Search dialog).
The Move Link Setup dialog will appear.
- Right-Click the list and Select the Auto-Fill command. This fills the "File Types to move" Field with all File Extensions you want to move. It also files the "Old Location Base Folder" and the Relocation Rules list. At move time this list is searched from top to bottom and the first match is used.
Blue List Items
Some list items may be highlighted in blue. Care must be taken with these items since they represent items that point to files with the same file name (EG. files.zip and HTML\files.zip). Removing a blue item may mean that you move and link to the incorrect duplicate file name.
The List shows a list of rules of how files will be moved and links renamed. As each link is found FAR checks
1. Does the link point to a valid local file.
2. Find the first folder in the list that is part of the current link path ("Old Location Base Folder" + "\" + OldLocation(N)). Once a match is found the "New Location Base Folder" + "\" + NewLocation(n) folder is used as the new file location. The new link will of course be given the appropriate relative path.
Important: Check the List
Take some time to examine the file list. Move items to the bottom of the list that might mask other items.
Example: ("Old Location" column)
Old Location Base Dir: "c:\fred\downloads"
Note that "downloads" masks the item "downloads\tools". For a link = "c:\fred\downloads\tools\delete.exe", "downloads" would match before "downloads\tools". Normally the Auto-Fill command will sort the items correctly, still to be safe always check your list before moving files. In the above case we need to move the "downloads" item lower down in the list.
- Once you have entered a "New Location Base Folder" and have your rules setup click OK to save and return to the FAR File list.
- Performing the Move
Now we have rules to find and move files stored away, drop onto FAR only your HTML files (use a drop filter or remove all non-HTML files). We are going to change all the links to the specified binary files.
- Set up the Adv Search as follows.
Start with: <a
End with: >
Replace with: $M$
and press the Search Button. The rules you set up before are used to relocate all specified files/links. After all HTML files have been scanned and links renamed, the binary files effected are moved.
Note1: Cancelling the search half way through can cause problems since several links can point to a single file. If this happens, get a fresh copy of the web.
Note2: During the process, links containing the "New Location Base Folder" are ignored. I.E. Links already moved will not be moved again.
Note3: If a link points to a non-existent file then no change or move is performed. Thus file links such as ftp:, http:, mailto: and broken links will all be ignored.
Note4: The files are not moved until every link has been found and changed.
Note5: Links to other HTML files are ignored. HTML files cannot be relocated.
- Finally, once finished you should search the main folder for any stray ZIP, PDF etc files that were not moved. If files are found, then they are probably:
a) orphan files that are not linked to, Or
b) maybe linked to via script (if you link via script), Or
c) file paths that may contain HTML unfriendly chars like #, %.
Orphan files should be deleted if not used as they take up disk space.
That's it for the $M$ command. There is still more work to do if you plan to convert the binary file links into scripted links and the web files into a CHM.