"Fossies" - the Fresh Open Source Software Archive

Member "manual/manual.html" (27 Dec 2020, 166967 Bytes) of package /linux/privat/regexSearch-4_3.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    2 <!DOCTYPE html
    3    PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    4    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    5 
    6 <html
    7    xmlns="http://www.w3.org/1999/xhtml"
    8    xml:lang="en">
    9 
   10   <head>
   11     <meta
   12        http-equiv="content-type"
   13        content="application/xhtml+xml;charset=UTF-8"/>
   14     <meta
   15        content="initial-scale=1"
   16        name="viewport"/>
   17     <title>RegexSearch : Manual</title>
   18     <link
   19        href="style/blankaspect-common.css"
   20        rel="stylesheet"
   21        type="text/css"/>
   22     <link
   23        href="style/blankaspect-manual.css"
   24        rel="stylesheet"
   25        type="text/css"/>
   26     <link
   27        href="style/regexSearch-manual.css"
   28        rel="stylesheet"
   29        type="text/css"/>
   30     <script
   31        src="scripts/Toc.js"
   32        type="text/javascript">
   33     </script>
   34     <script
   35        src="scripts/init.js"
   36        type="text/javascript">
   37     </script>
   38   </head>
   39 
   40   <body>
   41 
   42     <!-- Title -->
   43 
   44     <div class="title">
   45       <h1>RegexSearch 4.3 : Manual</h1>
   46     </div>
   47 
   48     <!--=====================================================================================-->
   49 
   50     <!-- Table of contents -->
   51 
   52     <div class="section">
   53       <h2 id="toc">Table of contents</h2>
   54       <div id="tocRoot">
   55         <div class="wrap" id="tocPlaceholder">
   56           You must have JavaScript enabled in your browser to generate the table of contents.
   57         </div>
   58       </div>
   59     </div>
   60 
   61     <!--=====================================================================================-->
   62 
   63     <!-- Introduction -->
   64 
   65     <div class="section">
   66       <h2 id="section1">1&nbsp; Introduction</h2>
   67       <p class="tocLink">
   68         [ <a href="#toc">Table of contents</a> ]
   69       </p>
   70 
   71       <p class="wrap">
   72         RegexSearch is a Java application that performs <i>find</i> and <i>find-and-replace</i>
   73         searches for regular expressions on multiple text files.  It is distributed under
   74         version 3 of the <a class="external"
   75         href="https://www.gnu.org/licenses/gpl-3.0.html">GNU General Public License</a>; for
   76         details, see the file <code>license.txt</code> that is included in the RegexSearch
   77         distribution.
   78       </p>
   79       <p class="wrap">
   80         RegexSearch has the following features:
   81       </p>
   82       <ul class="list">
   83         <li class="spaced wrap">
   84           It can search for literal text or regular expressions.
   85         </li>
   86         <li class="spaced">
   87           <div class="wrap">
   88             The search can be performed on the following:
   89           </div>
   90           <ul class="noSpaceAbove">
   91             <li class="wrap">
   92               a single file,
   93             </li>
   94             <li class="wrap">
   95               a directory, with optional recursion,
   96             </li>
   97             <li class="wrap">
   98               the files and directories listed in a text file,
   99             </li>
  100             <li class="wrap">
  101               the files in which the target was found in a previous search, or
  102             </li>
  103             <li class="wrap">
  104               text on the system clipboard.
  105             </li>
  106           </ul>
  107           <div class="wrap">
  108             Files can be included in and excluded from the search by means of pathname filters,
  109             which allow bounded recursion.
  110           </div>
  111         </li>
  112         <li class="spaced wrap">
  113           Occurrences of the target expression within each file are displayed in a scrollable
  114           window, with the matched text highlighted.
  115         </li>
  116         <li class="spaced wrap">
  117           Occurrences of the target expression can be replaced individually or globally.  If the
  118           target is a regular expression, the replacement can include arbitrary parts of the
  119           matched text.
  120         </li>
  121         <li class="spaced wrap">
  122           Replacements can be previewed, then accepted or rejected.
  123         </li>
  124         <li class="spaced wrap">
  125           The parsing and matching of regular expressions is performed by the robust Java
  126           regular-expression engine.  The syntax of Java&apos;s regular expressions is similar
  127           to that of Python and Perl.
  128         </li>
  129         <li class="spaced wrap">
  130           The results of a search (number of matches, number of replacements) are displayed for
  131           each file in which a match is found.  The results can be copied to the system
  132           clipboard in a form that is suitable for use as a list file to limit the scope of a
  133           new search.
  134         </li>
  135         <li class="spaced wrap">
  136           Although a file cannot be edited in RegexSearch&apos;s text view, a command can be
  137           issued to open the file in an external editor.
  138         </li>
  139       </ul>
  140 
  141       <p class="wrap">
  142         The website of the RegexSearch project is at <a class="external"
  143         href="http://regexsearch.sourceforge.net/">http://regexsearch.sourceforge.net/</a> .
  144       </p>
  145 
  146     </div>
  147 
  148     <!--=====================================================================================-->
  149 
  150     <!-- Requirements -->
  151 
  152     <div class="section">
  153       <h2 id="section2">2&nbsp; Requirements</h2>
  154       <p class="tocLink">
  155         [ <a href="#toc">Table of contents</a> ]
  156       </p>
  157 
  158       <p class="wrap">
  159         RegexSearch is a Java application that requires a Java runtime environment that supports
  160         Java SE 8 (Java 1.8), such as Oracle&apos;s <a class="external"
  161         href="https://www.oracle.com/java/technologies/javase-jre8-downloads.html">Java Runtime
  162         Environment</a> (JRE), version 8 or later.
  163       </p>
  164 
  165     </div>
  166 
  167     <!--=====================================================================================-->
  168 
  169     <!-- Contents of the distribution -->
  170 
  171     <div class="section">
  172       <h2 id="section3">3&nbsp; Contents of the distribution</h2>
  173       <p class="tocLink">
  174         [ <a href="#toc">Table of contents</a> ]
  175       </p>
  176 
  177       <p class="wrap">
  178         The following files are included in the distribution:
  179       </p>
  180 
  181       <table class="distribution">
  182         <tr>
  183           <td class="file">regexSearch.jar</td>
  184           <td class="wrap">
  185             The executable JAR (Java archive) file of the RegexSearch application.
  186           </td>
  187         </tr>
  188         <tr>
  189           <td class="file">regexSearch-config.xml</td>
  190           <td class="wrap">
  191             The <a href="#section5-2">configuration file</a> for RegexSearch, which contains the
  192             default values for the configuration properties.
  193           </td>
  194         </tr>
  195         <tr>
  196           <td class="file">license.txt</td>
  197           <td class="wrap">
  198             A copy of the licence under which RegexSearch is distributed (GNU General Public
  199             License, version 3).
  200           </td>
  201         </tr>
  202         <tr>
  203           <td class="file">dtd/searchParams.dtd</td>
  204           <td class="wrap">
  205             The DTD (document type definition) of a RegexSearch search-parameter document.
  206             (RegexSearch does not use the DTD; it is provided only for reference.)
  207           </td>
  208         </tr>
  209         <tr>
  210           <td class="file">
  211             <div>images/regexSearch.png</div>
  212             <div>images/regexSearch.ico</div>
  213           </td>
  214           <td class="wrap">
  215             A 256&times;256-pixel PNG image and a 256&times;256-pixel Windows-format icon that
  216             can be used to customise a desktop icon for the RegexSearch application.
  217           </td>
  218         </tr>
  219         <tr>
  220           <td class="file">
  221             <div>manual/manual.html</div>
  222             <div>manual/images/*.png</div>
  223             <div>manual/scripts/*.js</div>
  224             <div>manual/style/*.css</div>
  225           </td>
  226           <td class="wrap">
  227             This manual, its image files, scripts and stylesheets.  Any modifications to the
  228             manual for the latest version of RegexSearch will appear in the online version of
  229             the document, to which there is a link on the <a class="external"
  230             href="http://regexsearch.sourceforge.net/">RegexSearch website</a>.
  231           </td>
  232         </tr>
  233       </table>
  234 
  235     </div>
  236 
  237     <!--=====================================================================================-->
  238 
  239     <!-- Installing and running RegexSearch -->
  240 
  241     <div class="section">
  242       <h2 id="section4">4&nbsp; Installing and running RegexSearch</h2>
  243       <p class="tocLink">
  244         [ <a href="#toc">Table of contents</a> ]
  245       </p>
  246 
  247       <p class="wrap">
  248         RegexSearch consists of a single JAR (executable Java archive) file,
  249         <code>regexSearch.jar</code> and a <a href="#section5-2">configuration file</a>,
  250         <code>regexSearch-config.xml</code>, which contains <a href="#section8-5-1">user
  251         preferences</a>.  The use of the configuration file is optional but recommended.  The
  252         application can be installed in two ways: with the RegexSearchInstaller program or by
  253         copying files from the <code>.zip</code> or <code>.tar.gz</code> archive of the
  254         RegexSearch executable distribution.
  255       </p>
  256 
  257       <h3 id="section4-1">4.1&nbsp; Executing a JAR file</h3>
  258 
  259       <p class="wrap">
  260         Both the RegexSearch application and the installer are executable JAR (Java archive)
  261         files that <a href="#section2">require a Java runtime environment</a>, which includes a
  262         program named <code>java</code> for running JAR files &mdash; a Java launcher.  When you
  263         install a Java runtime environment, it may create an association on your system between
  264         JAR files and its Java launcher.  (Oracle&apos;s Java runtime environment on Windows
  265         associates JAR files with an additional Java launcher named <code>javaw</code> that runs
  266         without a console window.)  If so, or if you have created the association yourself, you
  267         will be able to run a JAR file directly (eg, by double-clicking on an icon of the JAR
  268         file in a file manager).  If not, you can run a JAR file by invoking the
  269         <code>java</code> launcher tool from a command line and supplying the location of the
  270         JAR file as an argument.  There are examples below of command lines for running the JAR
  271         file of the RegexSearch application under <a href="#section4-3-1">Linux/UNIX</a> and <a
  272         href="#section4-3-2">Windows</a>.
  273       </p>
  274 
  275       <h3 id="section4-2">4.2&nbsp; Installing RegexSearch</h3>
  276 
  277       <h4 id="section4-2-1">4.2.1&nbsp; Installation with the installer program</h4>
  278       <p class="wrap">
  279         The installer is an executable JAR (Java archive) file that <a href="#section2">requires
  280         the same Java runtime environment</a> as the RegexSearch application itself.  It can be
  281         run directly or indirectly in the ways <a href="#section4-1">described above</a>.
  282       </p>
  283       <p class="wrap">
  284         In the opening display of the installer, you can choose the components that you want to
  285         install and the directories in which they will be installed.  It is recommended that you
  286         install the configuration file in its <a href="#defaultDirectory">default directory</a>;
  287         the default directories of the other components should also be suitable for most users.
  288         If you install the executable file and the configuration file, a file named
  289         <code>regexSearch-properties.xml</code> will be generated and written to the same
  290         directory as the executable file to inform the RegexSearch application of the location
  291         of the configuration file.  This file is required only if the configuration file was not
  292         installed in the default directory or in the same directory as the executable file.
  293       </p>
  294       <p class="wrap">
  295         Any existing file that has the same name as an installed file will be overwritten
  296         without warning except for a configuration file, whose properties will be preserved if
  297         they conflict with the properties of the new file.
  298       </p>
  299       <p class="wrap">
  300         The final display of the installer has a <span class="command">Show files</span> command
  301         that displays a list of files that were installed.  If the installation was successful,
  302         you might want to keep a list of the files so that you will know where to find them when
  303         you uninstall RegexSearch, which does not have an automated means of uninstallation.  If
  304         the installation failed, you might want to remove any files that were installed.
  305       </p>
  306 
  307       <h4 id="section4-2-2">4.2.2&nbsp; Direct installation</h4>
  308       <p class="wrap">
  309         The direct installation of RegexSearch consists simply of copying the JAR file and,
  310         optionally, the default configuration file to suitable locations on your system.  If the
  311         configuration file is not installed in its <a href="#defaultDirectory">default
  312         directory</a>, you will need to inform the RegexSearch application of the <a
  313         href="#section5-2-1">location of the configuration file</a>, which can be done either on
  314         the command line or in a properties file.
  315       </p>
  316 
  317       <h3 id="section4-3">4.3&nbsp; Running RegexSearch</h3>
  318 
  319       <p class="wrap">
  320         The RegexSearch application is an executable JAR (Java archive) file that <a
  321         href="#section2">requires a Java runtime environment</a>.  The JAR file can be run
  322         directly or indirectly in the ways <a href="#section4-1">described above</a>.
  323       </p>
  324       <p class="wrap">
  325         If you run the RegexSearch application from a command line, the command line may contain
  326         <a href="#section5-1">configuration properties</a>, including the location of a
  327         configuration file.  The following subsections describe how to run RegexSearch from a
  328         command line.
  329       </p>
  330 
  331       <h4 id="section4-3-1">4.3.1&nbsp; Running under Linux/UNIX</h4>
  332       <p class="wrap">
  333         Assuming that your <code>PATH</code> environment variable includes the path to the
  334         <code>java</code> tool and that you have copied <code>regexSearch.jar</code> to the
  335         directory <code>/home/slothrop/bin/regexsearch/</code>, the command
  336       </p>
  337       <div class="commandLine">
  338         <code>java -jar /home/slothrop/bin/regexsearch/regexSearch.jar</code>
  339       </div>
  340       <p class="wrap">
  341         will run the RegexSearch application.
  342       </p>
  343       <p class="wrap">
  344         The file <code>regexSearch.png</code> can be used as the icon for the RegexSearch
  345         application.
  346       </p>
  347 
  348       <h4 id="section4-3-2">4.3.2&nbsp; Running under Windows</h4>
  349       <p class="wrap">
  350         The RegexSearch application does not require a console window, so you can use the
  351         <code>javaw</code> launcher rather than the <code>java</code> launcher unless you
  352         particularly want a console window.  Assuming that your <code>PATH</code> environment
  353         variable includes the path to the <code>javaw</code> tool and that you have copied
  354         <code>regexSearch.jar</code> to the directory
  355         <code>C:\Program&nbsp;Files\RegexSearch\</code>, the command
  356       </p>
  357       <div class="commandLine">
  358         <code>javaw -jar &quot;C:\Program&nbsp;Files\RegexSearch\regexSearch.jar&quot;</code>
  359       </div>
  360       <p class="wrap">
  361         will run the RegexSearch application.
  362       </p>
  363       <p class="wrap">
  364         The file <code>regexSearch.ico</code> can be used as the icon for the RegexSearch
  365         application.
  366       </p>
  367 
  368       <h3 id="section4-4">4.4&nbsp; Uninstalling RegexSearch</h3>
  369 
  370       <p class="wrap">
  371         RegexSearch does not have an automated means of uninstallation.  To remove it from your
  372         system, delete the file <code>regexSearch.jar</code> from the location to which it was
  373         written when you installed RegexSearch.  If you want to remove RegexSearch completely,
  374         you should also delete the configuration file, <code>regexSearch-config.xml</code>,
  375         which may be at its <a href="#defaultDirectory">default location</a>, and any other
  376         files that were installed (eg, the manual).
  377       </p>
  378 
  379     </div>
  380 
  381     <!--=====================================================================================-->
  382 
  383     <!-- Configuration -->
  384 
  385     <div class="section">
  386       <h2 id="section5">5&nbsp; Configuration</h2>
  387       <p class="tocLink">
  388         [ <a href="#toc">Table of contents</a> ]
  389       </p>
  390 
  391       <p class="wrap">
  392         When it starts up, RegexSearch is configured with <i>configuration properties</i> that
  393         are read from two sources: the <a href="#section5-1">command line</a> that is used to
  394         run the Java launcher and a <a href="#section5-2">configuration file</a> whose location
  395         may be explicitly specified.  If the same property is specified on the command line and
  396         in a configuration file, the value from the configuration file takes precedence.
  397       </p>
  398       <p class="wrap">
  399         The recommended method of setting the properties in a configuration file is with the <a
  400         class="command" href="#section8-5-1">Options &gt; Preferences</a> command.  For
  401         command-line properties, which must be edited manually, the form of the property values
  402         is given in an <a href="#sectionB">appendix</a>, and it can also be inferred by
  403         generating a configuration file with the desired values and inspecting the contents of
  404         the file.
  405       </p>
  406 
  407       <h3 id="section5-1">5.1&nbsp; Command-line properties</h3>
  408       <p class="wrap">
  409         When RegexSearch is run by means of the <code>java</code> launcher, configuration
  410         properties may be specified on the command line using the standard Java form
  411         <code>-D<i>name</i>=&quot;<i>value</i>&quot;</code>; eg,
  412         <code>-Dapp.appearance.textViewViewableSize=&quot;96,&nbsp;32&quot;</code>.  (The
  413         quotation marks around the value aren&apos;t necessary if the value doesn&apos;t contain
  414         spaces.)  RegexSearch&apos;s command-line configuration properties all have the prefix
  415         <code>app.</code> . A list of all the properties that are recognised by RegexSearch is
  416         given in an <a href="#sectionB">appendix</a>.
  417       </p>
  418       <p class="wrap">
  419         One particular property, <span class="configProperty">app.configDir</span>, is used to
  420         specify the directory that contains a configuration file, as <a
  421         href="#section5-2-1">described below</a>.  The value of the <span
  422         class="configProperty">app.configDir</span> property may contain <a
  423         href="#sectionA">special constructs</a> for system properties, environment variables and
  424         the user&apos;s home directory.
  425       </p>
  426 
  427       <h3 id="section5-2">5.2&nbsp; Configuration file</h3>
  428       <p class="wrap">
  429         The configuration file is named <code>regexSearch-config.xml</code>.  RegexSearch
  430         doesn&apos;t require a configuration file: it uses a default value for any configuration
  431         property that is missing from the source(s) of configuration.  Similarly, if it finds a
  432         property value to be invalid, RegexSearch will display a message to this effect and use
  433         the default value of the property.  If the configuration file contains a property that
  434         was specified on the command line, the value from the configuration file is used.
  435       </p>
  436       <p class="wrap">
  437         If the configuration has changed when you exit the application normally (ie, using the
  438         <a class="command" href="#section8-1-3">File &gt; Exit</a> command or an equivalent),
  439         RegexSearch will save its configuration to a configuration file.  If a configuration
  440         file was read on startup, it will overwrite that file; otherwise, it will write a
  441         configuration file to the default directory described above, unless the value of the
  442         <span class="configProperty">app.configDir</span> property was an empty string.
  443       </p>
  444       <p class="wrap">
  445         A configuration file can be written explicitly with the <span class="command">Save
  446         configuration</span> command within the <span class="component">Preferences</span>
  447         dialog.
  448       </p>
  449 
  450       <h4 id="section5-2-1">5.2.1&nbsp; Location of the configuration file</h4>
  451       <p class="noBottomMargin wrap">
  452         When it starts up, RegexSearch is informed of the location of the configuration file
  453         with the <span class="configProperty">app.configDir</span> property, which may be set in
  454         two ways:
  455       </p>
  456       <ul class="continuationList">
  457         <li class="wrap">
  458           in a file named <code>regexSearch-properties.xml</code> that resides in the same
  459           directory as the <code>regexSearch.jar</code> JAR file, or
  460         </li>
  461         <li class="wrap">
  462           on the command line that runs the <code>java</code> launcher.
  463         </li>
  464       </ul>
  465       <p class="wrap">
  466         If the <span class="configProperty">app.configDir</span> property is set both in the
  467         properties file and on the command line, the value in the properties file takes
  468         precedence.
  469       </p>
  470       <p class="wrap">
  471         The <code>regexSearch-properties.xml</code> file is normally written by the <a
  472         href="#section4-2-1">installer</a>.  If you create the file manually, it should have the
  473         following form, with the example pathname replaced by the actual pathname:
  474       </p>
  475       <pre class="codeFragment">
  476 &lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; standalone=&quot;no&quot;?&gt;
  477 &lt;!DOCTYPE properties SYSTEM &quot;http://java.sun.com/dtd/properties.dtd&quot;&gt;
  478 &lt;properties&gt;
  479 &lt;entry key=&quot;app.configDir&quot;&gt;/home/slothrop/.blankaspect/regexSearch&lt;/entry&gt;
  480 &lt;/properties&gt;</pre>
  481 
  482       <p class="wrap">
  483         If the configuration file were located in a directory named <code>config</code> in the
  484         user&apos;s home directory, the sample command lines given above would become:
  485       </p>
  486       <table class="commandLine">
  487         <tr>
  488           <td class="system"><a href="#section4-3-1">Linux/UNIX</a>:</td>
  489           <td class="command wrap">
  490             <code>java -Dapp.configDir=&quot;~/config&quot; -jar
  491             /home/slothrop/bin/regexsearch/regexSearch.jar</code>
  492           </td>
  493         </tr>
  494         <tr>
  495           <td class="system"><a href="#section4-3-2">Windows</a>:</td>
  496           <td class="command wrap">
  497             <code>javaw -Dapp.configDir=&quot;~/config&quot; -jar
  498             &quot;C:\Program&nbsp;Files\RegexSearch\regexSearch.jar&quot;</code>
  499           </td>
  500         </tr>
  501       </table>
  502 
  503       <p class="wrap">
  504         The existence and value of the <span class="configProperty">app.configDir</span>
  505         property determines the locations that are searched for a configuration file:
  506       </p>
  507       <ul class="list">
  508         <li class="spaced wrap">
  509           If the <span class="configProperty">app.configDir</span> property exists and the
  510           property value is an empty string, RegexSearch will start without a configuration
  511           file.  No configuration file will be written when the application exits.
  512         </li>
  513         <li class="spaced wrap">
  514           If the <span class="configProperty">app.configDir</span> property exists and the
  515           property value is not empty, RegexSearch will look for a configuration file in the
  516           directory specified by the property.  An error message is displayed if a configuration
  517           file is not found in the specified directory.
  518         </li>
  519         <li class="spaced">
  520           <div class="wrap">
  521             If the <span class="configProperty">app.configDir</span> property does not exist,
  522             RegexSearch will look for a configuration file at two other locations:
  523           </div>
  524           <ol class="list">
  525             <li class="spaced">
  526               <div><i>The current working directory</i></div>
  527               <div class="wrap">
  528                 The current working directory, which is denoted by the environment variable
  529                 <code>$PWD</code> on Linux/UNIX systems, depends on the system and the way in
  530                 which RegexSearch was run.
  531               </div>
  532             </li>
  533             <li class="spaced" id="defaultDirectory">
  534               <div><i>The default directory</i></div>
  535               <div class="wrap">
  536                 On Linux/UNIX systems, the default directory is
  537                 <code>$HOME/.blankaspect/regexSearch</code>, where <code>$HOME</code> is the
  538                 environment variable that denotes the user&apos;s home directory.  On Windows
  539                 systems, the default directory is
  540                 <code>%APPDATA%\blankaspect\regexSearch</code>, where <code>%APPDATA%</code> is
  541                 a system environment variable.
  542               </div>
  543             </li>
  544           </ol>
  545         </li>
  546       </ul>
  547 
  548     </div>
  549 
  550     <!--=====================================================================================-->
  551 
  552     <!-- Search parameters -->
  553 
  554     <div class="section">
  555       <h2 id="section6">6&nbsp; Search parameters</h2>
  556       <p class="tocLink">
  557         [ <a href="#toc">Table of contents</a> ]
  558       </p>
  559 
  560       <p class="wrap">
  561         The parameters of a search consist of:
  562       </p>
  563       <ul class="list">
  564         <li class="wrap">
  565           a <a href="#section6-1">file set</a> that determines the files that are searched,
  566         </li>
  567         <li class="wrap">
  568           the literal text or regular expression that is the <a href="#section6-2">target</a> of
  569           the search,
  570         </li>
  571         <li class="wrap">
  572           the <a href="#section6-3">replacement</a> text, if the search is
  573           <i>find-and-replace</i>, and
  574         </li>
  575         <li class="wrap">
  576           some flags (<i>replace</i>, <i>regular expression</i>, <i>ignore case</i> and <i>show
  577           not found</i>).
  578         </li>
  579       </ul>
  580       <p class="wrap">
  581         The search parameters are stored collectively as an XML file.  The DTD of the current
  582         version of a search-parameter file (<code>searchParams.dtd</code>) is included in the
  583         RegexSearch distribution.  It is provided only for reference because RegexSearch does
  584         not validate search-parameter files against the DTD.
  585       </p>
  586       <p class="wrap">
  587         A search-parameter file may contain multiple file sets, targets and replacements, and
  588         each file set may contain multiple <a href="#section6-1-1">pathnames</a> and <a
  589         href="#section6-1-2">pathname filters</a>, though only a single pathname, inclusion
  590         filter, exclusion filter, target and replacement are used in a search.  For each of
  591         those five parameters, RegexSearch&apos;s user interface allows you to select from the
  592         list of available values, to edit or delete existing values and to add new ones to the
  593         list.
  594       </p>
  595       <p class="wrap">
  596         When RegexSearch is run, search parameters are read from the file denoted by the
  597         configuration property <a class="configProperty"
  598         href="#cp-path-defaultSearchParameters">path.defaultSearchParameters</a>.  The current
  599         set of search parameters can be saved with the <a class="command"
  600         href="#section8-1-2">File &gt; Save search parameters</a> command, and files saved in
  601         this way can be opened with the <a class="command" href="#section8-1-1">File &gt; Open
  602         search parameters</a> command.  When you open a new search-parameter file or exit
  603         RegexSearch, you will be prompted to save the current search parameters if a
  604         search-parameter file was read, either automatically at startup or explicitly, and the
  605         parameters have changed since the file was read.  A change to the file-set index or a
  606         parameter index is regarded as a change to the file.
  607       </p>
  608 
  609       <h3 id="section6-1">6.1&nbsp; File set</h3>
  610       <p class="wrap">
  611         A <i>file set</i> specifies the files that are searched in a <i>find</i> or
  612         <i>find-and-replace</i> operation.  A file set has a <a href="#section6-1-3">file-set
  613         kind</a> and, depending on its file-set kind, it may also have a <a
  614         href="#section6-1-1">pathname</a> and two kinds of <a href="#section6-1-2">pathname
  615         filter</a>: an inclusion filter and an exclusion filter.
  616       </p>
  617 
  618       <h4 id="section6-1-1">6.1.1&nbsp; Pathname</h4>
  619       <p class="wrap">
  620         Depending on the file-set kind, the <i>pathname</i> of a file set may be direct or
  621         indirect.  A direct pathname denotes either a single file or a base directory that, in
  622         conjunction with inclusion and exclusion filters, defines the scope of a search.  An
  623         indirect pathname denotes a file that contains a list of files and directories to be
  624         searched.  A pathname may be absolute or relative; a relative pathname is relative to
  625         the current working directory.
  626       </p>
  627 
  628       <h4 id="section6-1-2">6.1.2&nbsp; Pathname filters</h4>
  629       <p class="wrap">
  630         The inclusion filters and exclusion filters of a file set are two kinds of <i>pathname
  631         filter</i>.  A pathname filter is a set of patterns that determines, usually in
  632         conjunction with a base pathname, the files that are searched.  A file is included in a
  633         search if it matches at least one pattern in the inclusion filter <small>AND</small>
  634         none of the patterns in the exclusion filter.  The maximum number of patterns in a
  635         filter is 64.
  636       </p>
  637       <p class="wrap">
  638         A pattern is a pathname that may include <i>wildcards</i>.  There are three wildcards:
  639         two filename wildcards and a pathname wildcard.
  640       </p>
  641 
  642       <h5 id="section6-1-2-1">6.1.2.1&nbsp; Filename wildcards</h5>
  643       <p class="wrap">
  644         The filename wildcards, &apos;<code>?</code>&apos; and &apos;<code>*</code>&apos;, have
  645         their usual meaning: &apos;<code>?</code>&apos; matches a single character and
  646         &apos;<code>*</code>&apos; matches zero or more characters in a pathname component (a
  647         filename or directory name).  For example, the pattern &quot;foo*.txt&quot; will match
  648         the filenames <code>foo.txt</code>, <code>food.txt</code> and <code>football.txt</code>.
  649         Following the UNIX convention (but differing from the Windows convention), a dot,
  650         &apos;<code>.</code>&apos;, has no special significance in patterns: it is matched by
  651         the &apos;<code>*</code>&apos; wildcard.  Thus, the pattern &quot;foo*&quot; will match
  652         the filenames <code>foo</code>, <code>football.txt</code> and
  653         <code>food.store.log</code>.
  654       </p>
  655 
  656       <h5 id="section6-1-2-2">6.1.2.2&nbsp; Pathname wildcards</h5>
  657       <p class="wrap">
  658         The pathname wildcard, &apos;<code>**</code>&apos;, matches zero or more pathname
  659         components.  Its use in a pathname pattern is analogous to the use of
  660         &apos;<code>*</code>&apos; in a filename pattern.  By itself, the pattern
  661         &apos;<code>**</code>&apos; is the recursive analogue of &apos;<code>*</code>&apos;: it
  662         matches all files in or below the base directory.  Used as a pathname component in a
  663         larger pattern, &apos;<code>**</code>&apos; denotes a recursive portion of the pathname
  664         that may be bounded above or below by a non-recursive pathname.  For example,
  665       </p>
  666       <ul class="list">
  667         <li class="wrap">
  668           the pattern &quot;**/*.txt&quot; matches all files with the filename suffix
  669           <code>.txt</code> in the base directory and in all directories below the base
  670           directory;
  671         </li>
  672         <li class="wrap">
  673           the pattern &quot;editor/**/config/*.xml&quot; matches all files with the filename
  674           suffix <code>.xml</code> in all directories named <code>config</code> that are in or
  675           below the directory named <code>editor</code> in the base directory;
  676         </li>
  677         <li class="wrap">
  678           the pattern &quot;**/test/**/*.java&quot; matches all files with the filename suffix
  679           <code>.java</code> in or below any directory named <code>test</code> that is below the
  680           base directory (or in the base directory, if it is named <code>test</code>).
  681         </li>
  682       </ul>
  683       <p class="wrap">
  684         A pathname-filter pattern may be either relative to a base directory (in a directory or
  685         list file set), or it may be absolute.  The pathname components in a pattern are
  686         separated with a &apos;<code>/</code>&apos; character (U+002F).  (A
  687         &apos;<code>\</code>&apos; may be used as the directory separator on the Windows
  688         platform, but &apos;<code>/</code>&apos; is recommended because
  689         &apos;<code>\</code>&apos; is used as the escape character in <a
  690         href="#section7-5-2">filter fields</a>.) A pattern that ends with a directory separator
  691         is assumed to be followed by an implicit &apos;<code>**</code>&apos;. A pattern that,
  692         when appended to its base directory, denotes an existing directory is assumed to be
  693         followed by an implicit &apos;<code>/**</code>&apos;. A pattern may contain dot and
  694         double-dot components (&apos;<code>.</code>&apos; and &apos;<code>..</code>&apos;), but
  695         only if they appear <em>before</em> the first wildcard in the pattern.
  696       </p>
  697       <p class="wrap">
  698         A file is matched against a pathname-filter pattern by converting both the pattern
  699         (appended to a base directory, if the pattern is relative) and the pathname of the
  700         target file to a canonical form.  An error may occur in converting the pattern to
  701         canonical form if, for example, the resulting pathname is illegal or access to part of
  702         the file system is not permitted.
  703       </p>
  704 
  705       <h4 id="section6-1-3">6.1.3&nbsp; File-set kinds</h4>
  706       <p class="wrap">
  707         A <i>file-set kind</i> may be one of File, Directory, List, Results or Clipboard.  The
  708         five kinds of file set are described below.
  709       </p>
  710 
  711       <h5 id="section6-1-3-1">6.1.3.1&nbsp; File</h5>
  712       <p class="wrap">
  713         The search is performed on the file denoted by the pathname of the file set.  No
  714         inclusion filter or exclusion filter is applied.
  715       </p>
  716 
  717       <h5 id="section6-1-3-2">6.1.3.2&nbsp; Directory</h5>
  718       <p class="wrap">
  719         The pathname of the file set denotes the base directory of the search.  (A search is not
  720         necessarily confined to this directory and the directories below it because the
  721         inclusion filter may contain patterns that denote pathnames outside the base directory.)
  722         An inclusion filter and an exclusion filter may be specified.  If no inclusion filter is
  723         specified, a filter consisting of the single pattern &apos;<code>**</code>&apos; (match
  724         all recursively) is assumed.  Any relative patterns (see <a
  725         href="#section6-1-2">pathname filter</a>) in the inclusion filter and exclusion filter
  726         are relative to the base directory.
  727       </p>
  728       <p class="wrap">
  729         The files in a directory are searched in order of filename.  The ordering is
  730         lexicographic (ie, the Unicode values of characters in the filename are compared) and
  731         platform-dependent: it is case-sensitive on Linux/UNIX systems, but alphabetic case is
  732         ignored on Windows systems.  Recursion is specified implicitly by <a
  733         href="#section6-1-2-2">pathname wildcards</a>.  A recursive search on a directory is
  734         depth-first: files in subdirectories are searched before the files in the directory.
  735         Like files, subdirectories are searched in order of name.  If the inclusion filter
  736         contains any absolute patterns, the files or directories specified by those patterns are
  737         searched <em>after</em> the base directory.
  738       </p>
  739 
  740       <h5 id="section6-1-3-3">6.1.3.3&nbsp; List</h5>
  741       <p class="wrap">
  742         The pathname of the file set is assumed to denote a text file, each of whose non-empty
  743         lines denotes the pathname of a file or directory that is to be searched.  A line of the
  744         list file may contain a comment, beginning with a &apos;<code>;</code>&apos; character.
  745         If a line contains a comment, any characters after the last non-space character before
  746         the comment are ignored (eg, the line &quot;simple-filename.txt&nbsp;;&nbsp;file
  747         #23&quot; is parsed as &quot;simple-filename.txt&quot;).  Empty lines are ignored.  The
  748         pathnames are validated before the search starts, and the search will not proceed unless
  749         each pathname denotes an existing directory or a regular file.
  750       </p>
  751       <p class="wrap">
  752         An inclusion filter and an exclusion filter may be specified.  If no inclusion filter is
  753         specified, a filter consisting of the single pattern &apos;<code>**</code>&apos; (match
  754         all recursively) is assumed.
  755       </p>
  756       <p class="wrap">
  757         The search of the pathnames in the list is equivalent to a sequence of searches on file
  758         sets whose file-set kind is either File or Directory according to whether a pathname
  759         denotes a file or directory.  If the pathname denotes a directory, the inclusion filter
  760         and any exclusion filter are applied to it.  If the inclusion filter contains any
  761         absolute patterns, the files or directories specified by those patterns are searched
  762         <em>after</em> all the pathnames in the list.
  763       </p>
  764 
  765       <h5 id="section6-1-3-4">6.1.3.4&nbsp; Results</h5>
  766       <p class="wrap">
  767         The files that will be searched are those from the last list of files to be saved with
  768         the <a class="command" href="#section8-4-3">Search &gt; Save results</a> command.  The
  769         current list of saved results can be viewed with the <a class="command"
  770         href="#section8-4-4">Search &gt; View saved results</a> command.  No inclusion filter or
  771         exclusion filter is applied.
  772       </p>
  773 
  774       <h5 id="section6-1-3-5">6.1.3.5&nbsp; Clipboard</h5>
  775       <p class="wrap">
  776         This denotes a &quot;pseudo-file&quot;: the contents of the system clipboard.  If the
  777         clipboard contains text, the text will be searched in the same way as if it were read
  778         from a file.  In a <i>find-and-replace</i> search, if any changes are made to the text,
  779         the modified text is put back on the clipboard at the end of the search.  No inclusion
  780         filter or exclusion filter is applied.
  781       </p>
  782 
  783       <h3 id="section6-2">6.2&nbsp; Target</h3>
  784       <p class="wrap">
  785         The <i>target</i> of the search &mdash; the pattern that you are attempting to match in
  786         the files that are searched &mdash; can be either literal text or a regular expression.
  787         The corresponding kinds of search are referred to below as <i>literal-text search</i>
  788         and <i>regular-expression search</i>.
  789       </p>
  790 
  791       <h3 id="section6-3">6.3&nbsp; Replacement</h3>
  792       <p class="wrap">
  793         The <i>replacement</i> is an expression that will be used to replace occurrences of the
  794         target pattern in a <i>find-and-replace</i> search.  The interpretation of the
  795         replacement differs according to whether the target is literal text or a regular
  796         expression.  Both types of replacement may contain <i>metasymbols</i> &mdash; special
  797         sequences that are introduced with an escape character.  By default, the escape
  798         character is a backslash, &apos;<code>\</code>&apos;, but it can be changed with the <a
  799         class="configProperty"
  800         href="#cp-general-replacementEscapeCharacter">general.replacementEscapeCharacter</a>
  801         configuration property if, for example, you want to avoid having to escape the
  802         backslashes in Windows pathnames.  In a replacement, an escape character must always be
  803         escaped by prefixing another escape character to it (eg, &apos;<code>\\</code>&apos;, if
  804         the escape character is &apos;<code>\</code>&apos;).
  805       </p>
  806 
  807       <h4 id="section6-3-1">6.3.1&nbsp; Literal-text replacement</h4>
  808       <p class="wrap">
  809         The following metasymbols may appear in a literal-text replacement string.  It is
  810         assumed that the escape character is &apos;<code>\</code>&apos;.
  811       </p>
  812 
  813       <table class="regex">
  814         <tr>
  815           <td class="shaded">\t</td>
  816           <td>Tab character, U+0009</td>
  817         </tr>
  818         <tr>
  819           <td class="shaded">\n</td>
  820           <td>Line-feed character, U+000A</td>
  821         </tr>
  822         <tr>
  823           <td class="shaded">\u<i>nnnn</i></td>
  824           <td class="wrap">
  825             Unicode character U+<i>nnnn</i>, where <i>n</i> is a hexadecimal digit character,
  826             [0-9A-Fa-f]
  827           </td>
  828         </tr>
  829         <tr>
  830           <td class="shaded">\\</td>
  831           <td>Literal escape character</td>
  832         </tr>
  833       </table>
  834 
  835       <h4 id="section6-3-2">6.3.2&nbsp; Regular-expression replacement</h4>
  836       <p class="wrap">
  837         The following metasymbols may appear in a regular-expression replacement string.  It is
  838         assumed that the escape character is &apos;<code>\</code>&apos;.
  839       </p>
  840 
  841       <table class="regex">
  842         <tr>
  843           <td class="shaded">\t</td>
  844           <td>Tab character, U+0009</td>
  845         </tr>
  846         <tr>
  847           <td class="shaded">\n</td>
  848           <td>Line-feed character, U+000A</td>
  849         </tr>
  850         <tr>
  851           <td class="shaded">\u<i>nnnn</i></td>
  852           <td class="wrap">
  853             Unicode character U+<i>nnnn</i>, where <i>n</i> is a hexadecimal digit character,
  854             [0-9A-Fa-f]
  855           </td>
  856         </tr>
  857         <tr>
  858           <td class="shaded">\\</td>
  859           <td>Literal escape character</td>
  860         </tr>
  861         <tr>
  862           <td class="shaded">\<i>n</i></td>
  863           <td class="wrap">
  864             Capturing group in the target pattern, where <i>n</i> is the decimal index of the
  865             group
  866           </td>
  867         </tr>
  868         <tr>
  869           <td class="shaded">\L<i>n</i></td>
  870           <td>
  871             <div class="wrap">
  872               Capturing group in the target pattern, where <i>n</i> is the decimal index of the
  873               group.
  874             </div>
  875             <div class="wrap">
  876               All alphabetic characters in the group are converted to lower case.
  877             </div>
  878           </td>
  879         </tr>
  880         <tr>
  881           <td class="shaded">\U<i>n</i></td>
  882           <td>
  883             <div class="wrap">
  884               Capturing group in the target pattern, where <i>n</i> is the decimal index of the
  885               group.
  886             </div>
  887             <div class="wrap">
  888               All alphabetic characters in the group are converted to upper case.
  889             </div>
  890           </td>
  891         </tr>
  892       </table>
  893 
  894     </div>
  895 
  896     <!--=====================================================================================-->
  897 
  898     <!-- The display -->
  899 
  900     <div class="section">
  901       <h2 id="section7">7&nbsp; The display</h2>
  902       <p class="tocLink">
  903         [ <a href="#toc">Table of contents</a> ]
  904       </p>
  905 
  906       <p class="wrap">
  907         The main display consists of two windows:
  908       </p>
  909       <ul class="list">
  910         <li class="wrap">
  911           the <i>main window</i>, which is divided into the <a href="#section7-2"><i>text
  912           view</i></a> and <a href="#section7-3"><i>result area</i></a>;
  913         </li>
  914         <li class="wrap">
  915           the <i>control dialog</i>.
  916         </li>
  917       </ul>
  918       <p class="wrap">
  919         The main window is always visible.  The control dialog may be hidden and made visible
  920         with the <a class="command" href="#section8-3-1">Hide control dialog / Show control
  921         dialog</a> command.
  922       </p>
  923 
  924       <h3 id="section7-1">7.1&nbsp; Column width and row height</h3>
  925       <p class="wrap">
  926         The width and/or height of some text components are specified in logical units of
  927         columns and rows.  The width of a column and the height of a row are determined by the
  928         font that is used to display text within the component: the height of a row is the
  929         height of the font, and the width of a column is the width of a zero character (U+0030),
  930         or, if the font doesn&apos;t have a glyph for the zero character, the width of the glyph
  931         that is used for characters that are not defined.
  932       </p>
  933 
  934       <h3 id="section7-2">7.2&nbsp; Text view</h3>
  935       <p class="wrap">
  936         The text view is the text area at the top of the main window in which the contents of a
  937         file are displayed.  <em>The text view is not editable.</em> The following attributes of
  938         the text view are configurable:
  939       </p>
  940       <ul class="list">
  941         <li class="wrap">
  942           the <a href="#cp-appearance-textViewViewableSize">dimensions of the viewable area</a>
  943           (number of columns &times; number of rows),
  944         </li>
  945         <li class="wrap">
  946           the <a href="#cp-appearance-textViewMaxNumColumns">maximum number of columns</a>,
  947         </li>
  948         <li class="wrap">
  949           the <a href="#cp-font">font</a>,
  950         </li>
  951         <li class="wrap">
  952           the type of <a href="#cp-appearance-textViewTextAntialiasing">antialiasing</a> that is
  953           performed on the text,
  954         </li>
  955         <li class="wrap">
  956           the <a href="#cp-appearance-textAreaColour">colours</a>.
  957         </li>
  958       </ul>
  959       <p class="wrap">
  960         The number of viewable columns in the text view is also used as the number of viewable
  961         columns in the <a href="#section7-3">result area</a>.  If the two areas use different
  962         fonts, the actual width of the text view and result area is the wider of the two areas.
  963       </p>
  964       <p class="wrap">
  965         The colours of the text view are also applied to the result area and to the fields in
  966         the <span class="component">Search options</span> dialog.
  967       </p>
  968 
  969       <h4 id="section7-2-1">7.2.1&nbsp; How tab characters are displayed</h4>
  970       <p class="wrap">
  971         When a file containing tab characters (U+0009) is displayed in the text view,
  972         RegexSearch uses two configuration properties &mdash; <a
  973         href="#cp-tabWidth-fileFilter"><i>tab-width filters</i></a> and default tab width
  974         &mdash; to determine how the tab characters are converted to spaces.  A tab-width filter
  975         maps a filename filter (a set of patterns that are used to match filenames) to the
  976         number of spaces that will be used to replace tab characters when displaying a matching
  977         file.  If none of the defined tab-width filters matches the file, the default tab width
  978         is used.  If the tab width is zero, tab characters are not expanded but rendered as a
  979         U+2192 (rightwards arrow) character, or as the &quot;not defined&quot; glyph if the font
  980         doesn&apos;t contain a glyph for the arrow character.
  981       </p>
  982       <p class="wrap">
  983         The filename-filter part of the tab-width filter consists of one or more filename
  984         patterns separated by spaces; for instance, &quot;*.cpp *.h&quot;. If a filename matches
  985         one of the patterns, it is included in the search in the case of the inclusive filter or
  986         excluded from the search in the case of the exclusive filter.  A pattern may be a
  987         literal filename or it may contain the wildcards &apos;<code>*</code>&apos; and
  988         &apos;<code>?</code>&apos;, which have their usual meaning: &apos;<code>*</code>&apos;
  989         matches zero or more characters and &apos;<code>?</code>&apos; matches a single
  990         character.
  991       </p>
  992 
  993       <h3 id="section7-3">7.3&nbsp; Result area</h3>
  994       <p class="wrap">
  995         The result area is the text area at the bottom of the main window in which the results
  996         of a search are displayed.  <em>The result area is not editable.</em> The following
  997         information is displayed in the result area after a search:
  998       </p>
  999       <ul class="list">
 1000         <li class="wrap">
 1001           A list of files in which the search target was found, along with the number of
 1002           occurrences that were found, which may be fewer than the total number of occurrences
 1003           in the file if the search of the file was incomplete.  For a <i>find-and-replace</i>
 1004           search, the number of replacements that were made is also displayed.
 1005         </li>
 1006         <li class="wrap">
 1007           Some aggregate counts for the search: the number of files searched, the number of
 1008           files containing matches, and the total number of matches.
 1009         </li>
 1010         <li class="wrap">
 1011           If the <span class="component">Show not found</span> check box of the control dialog
 1012           is selected, a list of files in which the search target was not found.
 1013         </li>
 1014         <li class="wrap">
 1015           Lists of files that could not be searched or whose attributes could not be set in a
 1016           <i>find-and-replace</i> search.  (A search will fail if, for example, the canonical
 1017           pathname of the file cannot be obtained or the file was too long for the file buffer
 1018           or an error occurred when reading the file.)  The problematic files are listed under
 1019           an appropriate heading.
 1020         </li>
 1021       </ul>
 1022       <p class="wrap">
 1023         After a search, files that are listed in the result area can be opened with an external
 1024         editor as though the <a class="command" href="#section8-2-1">Edit &gt; Edit file</a>
 1025         command were issued on the file during a search.  The <a class="configProperty"
 1026         href="#cp-editor-command">command that invokes the external editor</a> is issued by
 1027         holding down the Ctrl key and clicking the left mouse button on the chosen pathname in
 1028         the result area.
 1029       </p>
 1030       <p class="wrap">
 1031         The following attributes of the result area are configurable:
 1032       </p>
 1033       <ul class="list">
 1034         <li class="wrap">
 1035           the <a href="#cp-appearance-resultAreaNumRows">number of rows</a>,
 1036         </li>
 1037         <li class="wrap">
 1038           the <a href="#cp-font">font</a>,
 1039         </li>
 1040         <li class="wrap">
 1041           the <a href="#cp-appearance-textAreaColour">colours</a>.
 1042         </li>
 1043       </ul>
 1044       <p class="wrap">
 1045         The number of viewable columns in the <a href="#section7-2">text view</a> is also used
 1046         as the number of viewable columns in the result area.  If the two areas use different
 1047         fonts, the actual width of the text view and result area is the wider of the two areas.
 1048       </p>
 1049       <p class="wrap">
 1050         The maximum number of columns in the result area is fixed at 1024.
 1051       </p>
 1052       <p class="wrap">
 1053         The colours of the result area are also applied to the text view.
 1054       </p>
 1055 
 1056       <h3 id="section7-4">7.4&nbsp; File-set controls</h3>
 1057       <p class="wrap">
 1058         The file-set controls, which can be found in the top row of the control dialog, consist
 1059         of a drop-down list for selecting the file-set kind, a group of three buttons for
 1060         inserting, duplicating and deleting file sets, and a group of four buttons for
 1061         navigating the list of file sets and changing the position of the current file set in
 1062         the list.
 1063       </p>
 1064       <p class="wrap">
 1065         The index of the current file set and the number of file sets in the list are shown in a
 1066         box between the two pairs of navigation buttons.  &quot;End&quot; indicates that the
 1067         file-set position is at the end of the list; there is no current file set.  A file set
 1068         may be inserted at the end of the list.
 1069       </p>
 1070 
 1071       <h4 id="section7-4-1">7.4.1&nbsp; File-set kind drop-down list</h4>
 1072       <p class="wrap">
 1073         The drop-down list is used to select the <a href="#section6-1-3">file-set kind</a>.  The
 1074         <a href="#section7-5-1"><span class="component">Pathname</span> field</a> and <a
 1075         href="#section7-5-2"><span class="component">Include</span> and <span
 1076         class="component">Exclude</span> fields</a> are enabled or disabled according to the
 1077         file-set kind.
 1078       </p>
 1079 
 1080       <h4 id="section7-4-2">7.4.2&nbsp; File-set command buttons</h4>
 1081       <p class="wrap">
 1082         A file set can be added to and removed from the list of file sets with the commands that
 1083         are associated with the group of three buttons in the top row of the control dialog.
 1084         Each command can also be issued from the keyboard.
 1085       </p>
 1086 
 1087       <h5 id="section7-4-2-1">7.4.2.1&nbsp; <span class="command">Insert</span></h5>
 1088       <p class="wrap">
 1089         The <span class="command">Insert</span> command inserts a new file set into the list at
 1090         the current file-set index.  To add a new file set to the end of the list, first
 1091         navigate to the end of the list.  The <span class="command">Insert</span> command can be
 1092         issued by pressing the F2 key.
 1093       </p>
 1094 
 1095       <h5 id="section7-4-2-2">7.4.2.2&nbsp; <span class="command">Duplicate</span></h5>
 1096       <p class="wrap">
 1097         The <span class="command">Duplicate</span> command makes a copy of the current file-set,
 1098         inserts the copy into the list <em>after</em> the current index, then selects the copy.
 1099         The <span class="command">Duplicate</span> command can be issued by pressing the F3 key.
 1100       </p>
 1101 
 1102       <h5 id="section7-4-2-3">7.4.2.3&nbsp; <span class="command">Delete</span></h5>
 1103       <p class="wrap">
 1104         The <span class="command">Delete</span> command deletes the current file-set after you
 1105         have confirmed the deletion.  The <span class="command">Delete</span> command can be
 1106         issued by pressing the F4 key.
 1107       </p>
 1108 
 1109       <h4 id="section7-4-3">7.4.3&nbsp; File-set navigation buttons</h4>
 1110       <p class="wrap">
 1111         The list of file sets can be navigated and the position of the current file set in the
 1112         list can be changed with the commands that are associated with the group of four arrow
 1113         buttons and barred-arrow buttons in the top row of the control dialog.  Each command can
 1114         also be issued from the keyboard.
 1115       </p>
 1116       <p class="wrap">
 1117         The arrow buttons select the previous or next file set in the list.  The current
 1118         file-set index continues to change while the mouse button is pressed or until the start
 1119         or end of the list is reached.  Holding down the Ctrl key while clicking on or pressing
 1120         the arrow buttons will move the current file set up or down the list.  The <span
 1121         class="command">Go to previous</span> and <span class="command">Go to next</span>
 1122         commands can be issued by pressing the F6 and F7 keys respectively.  The <span
 1123         class="command">Move up</span> and <span class="command">Move down</span> commands can
 1124         be issued by pressing Ctrl+F6 and Ctrl+F7 respectively.
 1125       </p>
 1126       <p class="wrap">
 1127         The barred-arrow buttons select the first file set in the list or go to the end of the
 1128         list (where no file set is selected).  The <span class="command">Go to start</span> and
 1129         <span class="command">Go to end</span> commands can be issued by pressing the F5 and F8
 1130         keys respectively.
 1131       </p>
 1132 
 1133       <h3 id="section7-5">7.5&nbsp; Parameter fields</h3>
 1134       <p class="wrap">
 1135         The five most prominent components in the control dialog are referred to as <i>parameter
 1136         fields</i>.  Two of the fields &mdash; the <span class="component">Target</span> and
 1137         <span class="component">Replacement</span> fields &mdash; are text areas rather than
 1138         fields, and the size of these text areas can be configured with the <a
 1139         class="configProperty"
 1140         href="#cp-appearance-parameterEditorSize">appearance.parameterEditorSize</a> property.
 1141         The width of these two fields determines the width of the other three parameter fields.
 1142       </p>
 1143       <p class="wrap">
 1144         Each parameter field maintains a history list: a list of the most recent values that
 1145         were entered in the field, up to a maximum of 64 items.  A parameter field is similar in
 1146         operation to a combo box except that an item is not moved to the top of the list when it
 1147         is selected.  (The order of items in the list may be changed in the editor; see below.)
 1148       </p>
 1149       <p class="noBottomMargin wrap">
 1150         A value is entered into the field explicitly by pressing Ctrl+Enter or implicitly when
 1151       </p>
 1152       <ul class="continuationList">
 1153         <li class="wrap">
 1154           the field&apos;s pop-up menu is displayed,
 1155         </li>
 1156         <li class="wrap">
 1157           a file set is inserted or duplicated,
 1158         </li>
 1159         <li class="wrap">
 1160           a different file set is selected,
 1161         </li>
 1162         <li class="wrap">
 1163           a search is performed, or
 1164         </li>
 1165         <li class="wrap">
 1166           the search parameters are saved.
 1167         </li>
 1168       </ul>
 1169       <p class="wrap">
 1170         When a value is entered in the field, it is inserted at the top of the list.
 1171       </p>
 1172       <p class="wrap">
 1173         A history list can be navigated and edited in several ways.  Navigation and editing
 1174         commands are available from a pop-up menu that is activated in a system-dependent manner
 1175         (eg, by pressing or releasing the right mouse button) or by pressing the context-menu
 1176         key when the field has keyboard focus.  The <span class="command">Select previous
 1177         item</span> and <span class="command">Select next item</span> commands that are
 1178         available from the pop-up menu can also be issued by pressing Ctrl+PageUp and
 1179         Ctrl+PageDown respectively.  The <span class="command">Delete</span> command can be
 1180         issued by pressing Ctrl+Shift+Delete.
 1181       </p>
 1182       <p class="wrap">
 1183         All the parameter fields have an <span class="command">Edit</span> command that displays
 1184         an editor in which the items in the field&apos;s history list can be edited.  The
 1185         command is available from the field&apos;s pop-up menu and can also be issued by
 1186         pressing Alt+Enter.  (For the filter fields, the command can be issued with the Edit
 1187         button adjacent to the field.)  Within the list editor, the position of an item in the
 1188         list can be changed by dragging it with the mouse, or by pressing Ctrl+Shift+Up or
 1189         Ctrl+Shift+Down when the list has keyboard focus.  The Delete key and Delete button
 1190         delete the selected item after confirmation, while Shift+Delete and Shift+left-click on
 1191         the Delete button delete the selected item without confirmation.
 1192       </p>
 1193 
 1194       <h4 id="section7-5-1">7.5.1&nbsp; <span class="component">Pathname</span> field</h4>
 1195       <p class="wrap">
 1196         A pathname can be entered in the field by typing, by selecting a file using the
 1197         &quot;<span class="component">&hellip;</span>&quot; button adjacent to the field, or by
 1198         dragging a file or directory from, for example, a file browser and dropping it onto the
 1199         field or onto other parts of the control dialog or onto the main window.
 1200       </p>
 1201       <ul class="list">
 1202         <li class="wrap">
 1203           Dropping a file or directory onto the <span class="component">Pathname</span> field
 1204           will replace the pathname in the field and add the new item to the history list.
 1205         </li>
 1206         <li class="wrap">
 1207           Dropping a file or directory onto other parts of the control dialog or onto the main
 1208           window will <em>duplicate the current file set</em> and replace the pathname in the
 1209           <span class="component">Pathname</span> field in the new file set.
 1210         </li>
 1211       </ul>
 1212 
 1213       <h4 id="section7-5-2">7.5.2&nbsp; <span class="component">Include</span> and
 1214                                                         <span class="component">Exclude</span> fields</h4>
 1215       <p class="wrap">
 1216         The fields contain a pathname filter: a set of patterns separated by spaces.  Within the
 1217         field, the backslash, &apos;<code>\</code>&apos;, acts as an escape character to allow
 1218         the inclusion of space characters in patterns.  The escape convention in the filter
 1219         fields is that a character following a &apos;<code>\</code>&apos; is treated as a
 1220         literal character, and a single trailing &apos;<code>\</code>&apos; is ignored.  Thus,
 1221         you would use &apos;<code>\&nbsp;</code>&apos; for a literal space and
 1222         &apos;<code>\\</code>&apos; for a literal backslash.  Because of this, it is recommended
 1223         that you use a &apos;<code>/</code>&apos; to separate pathname components in patterns on
 1224         the Windows platform.
 1225       </p>
 1226       <p class="wrap">
 1227         The individual patterns of a pathname filter can be edited from the <span
 1228         class="component">Edit pattern</span> dialog &mdash; the third-level editor that is
 1229         invoked with the <span class="command">Edit</span> command in the <span
 1230         class="component">Edit filter</span> dialog that is invoked by the <span
 1231         class="command">Edit</span> command in the list editor that is invoked by the <span
 1232         class="command">Edit</span> command in the <span class="component">Include</span> or
 1233         <span class="component">Exclude</span> field.  (Got that?)  Note that no escape
 1234         character is used in the <span class="component">Pattern</span> field of the <span
 1235         class="component">Edit pattern</span> dialog.
 1236       </p>
 1237       <p class="wrap">
 1238         The history list of the <span class="component">Exclude</span> field set may contain an
 1239         empty string (ie, &quot;exclude nothing&quot;).
 1240       </p>
 1241 
 1242       <h4 id="section7-5-3">7.5.3&nbsp; <span class="component">Target</span> and
 1243                             <span class="component">Replacement</span> fields</h4>
 1244       <p class="wrap">
 1245         The <span class="component">Target</span> and <span class="component">Replacement</span>
 1246         fields are actually text areas that can contain multiple lines of text.  The <span
 1247         class="component">Replacement</span> field is enabled only if the <span
 1248         class="component">Replace</span> check box is selected.
 1249       </p>
 1250       <p class="wrap">
 1251         Text in the <span class="component">Target</span> and <span
 1252         class="component">Replacement</span> fields can include tab characters (U+0009) and
 1253         line-feed characters (U+000A), which are entered in the field by pressing Ctrl+Tab and
 1254         Enter respectively.  Line feeds are not displayed in a special way in the field, so, if
 1255         your target or replacement isn&apos;t behaving as you expected, it may be that you have
 1256         an unwanted &mdash; and invisble &mdash; line feed at the end of the field.
 1257       </p>
 1258       <p class="wrap">
 1259         The fields may use a <a href="#section7-5-3-1">tab surrogate</a> to display tab
 1260         characters.  Some characters in the fields may be <i>escaped</i> in two different ways:
 1261         <a href="#section7-5-3-2">tabs and line feeds</a> can be escaped separately, and an
 1262         <span class="command">Escape</span> command can be applied to the field.  The <span
 1263         class="command">Escape</span> command behaves differently in the <a
 1264         href="#section7-5-3-3"><span class="component">Target</span> field</a> and the <a
 1265         href="#section7-5-3-4"><span class="component">Replacement</span> field</a>.
 1266       </p>
 1267 
 1268       <h5 id="section7-5-3-1">7.5.3.1&nbsp; Tab surrogate</h5>
 1269       <p class="wrap">
 1270         Within the <span class="component">Target</span> and <span
 1271         class="component">Replacement</span> fields, tabs are replaced with the character that
 1272         is denoted by the <a class="configProperty"
 1273         href="#cp-appearance-tabSurrogate">appearance.tabSurrogate</a> configuration property.
 1274         The default tab surrogate is the tab character (U+0009) itself; in this case, tabs are
 1275         displayed as a number of spaces up to the next tab stop, and the tab width is denoted by
 1276         the <a class="configProperty"
 1277         href="#cp-tabWidth-targetAndReplacement">tabWidth.targetAndReplacement</a> configuration
 1278         property.  It is important to understand that the tab surrogate is not just a substitute
 1279         glyph: it actually replaces each occurrence of the tab character in the field unless
 1280         tabs are <a href="#section7-5-3-2">escaped</a>.  When the content of the field is used
 1281         (eg, in a search), the tab surrogate is converted either to a tab character or to a tab
 1282         sequence (&quot;\t&quot;) as appropriate, so you should choose as tab surrogate a
 1283         character that is unlikely to appear in any target or replacement text.
 1284       </p>
 1285 
 1286       <h5 id="section7-5-3-2">7.5.3.2&nbsp; Escaping tabs and line feeds</h5>
 1287       <p class="wrap">
 1288         Tabs and line feeds may be escaped (ie, converted to the escape sequences
 1289         &quot;<code>\t</code>&quot; and &quot;<code>\n</code>&quot; respectively) in the <span
 1290         class="component">Target</span> and <span class="component">Replacement</span> fields by
 1291         selecting the <span class="component">Tabs escaped</span> or <span
 1292         class="component">Line feeds escaped</span> item in the field&apos;s pop-up menu.  (In
 1293         reality, it is the tab surrogate that is converted to &quot;<code>\t</code>&quot;, but
 1294         the existence of tab surrogates is ignored in this section so as not to complicate
 1295         matters.)  Deselecting the menu item reverses the procedure: each occurrence of
 1296         &quot;<code>\t</code>&quot; or &quot;<code>\n</code>&quot; is converted to a tab
 1297         character or line-feed character, even if the &apos;<code>\</code>&apos; is itself
 1298         escaped with another backslash.  You will need to be careful about toggling the escaping
 1299         of tabs and line feeds if the text contains literal &quot;<code>\t</code>&quot; or
 1300         &quot;<code>\n</code>&quot; sequences.  Within the field, the escaping of tabs and line
 1301         feeds can be toggled from the keyboard with Ctrl+T and Ctrl+N respectively.  Indicators
 1302         appear alongside a field in which tabs or line feeds are escaped.
 1303       </p>
 1304       <p class="wrap">
 1305         When a regular-expression search is performed, any tab characters and line-feed
 1306         characters in the <span class="component">Target</span> field are escaped automatically
 1307         in the target pattern that is used in the search.  Tabs and line feeds are also escaped
 1308         in the list of target or replacement items displayed in the editor, in the <span
 1309         class="component">Select item</span> submenu displayed in the field&apos;s pop-up menu,
 1310         and when targets and replacements are saved to a search-parameter file.
 1311       </p>
 1312 
 1313       <h5 id="section7-5-3-3">7.5.3.3&nbsp; The <span class="command">Escape</span> command for
 1314                               the <span class="component">Target</span> field</h5>
 1315       <p class="wrap">
 1316         The <span class="component">Escape</span> button adjacent to the <span
 1317         class="component">Target</span> field is enabled only when the <span
 1318         class="component">Regular expression</span> check box is selected.  The <span
 1319         class="command">Escape</span> command for the <span class="component">Target</span>
 1320         field prefixes a &apos;<code>\</code>&apos; to each metacharacter in the field.  The set
 1321         of metacharacters on which the command operates is denoted by the <a
 1322         class="configProperty"
 1323         href="#cp-general-escapedMetacharacters">general.escapedMetacharacters</a> configuration
 1324         property.  The default value of the property is the set of characters that are used in
 1325         metasymbols outside a character class delimited by square brackets:
 1326       </p>
 1327       <p class="shaded">
 1328         &nbsp;&nbsp;$&nbsp;(&nbsp;)&nbsp;*&nbsp;+&nbsp;.&nbsp;?&nbsp;[&nbsp;\&nbsp;]&nbsp;^&nbsp;{&nbsp;|&nbsp;}
 1329       </p>
 1330       <p class="wrap">
 1331         (&apos;<code>]</code>&apos; and &apos;<code>}</code>&apos; are not metacharacters but
 1332         are included in the set for symmetry.)
 1333       </p>
 1334       <p class="wrap">
 1335         If tabs or line feeds are escaped in the <span class="component">Target</span> field and
 1336         the backspace character is in the set of escaped metacharacters, the
 1337         &apos;<code>\</code>&apos; prefix to the escaped tabs and line feeds will itself be
 1338         escaped by the <span class="command">Escape</span> command.  Unless the text contains
 1339         literal &quot;<code>\t</code>&quot; or &quot;<code>\n</code>&quot; sequences, it may be
 1340         best to unescape tabs and line feeds before issuing the <span
 1341         class="command">Escape</span> command.
 1342       </p>
 1343 
 1344       <h5 id="section7-5-3-4">7.5.3.4&nbsp; The <span class="command">Escape</span> command for
 1345                               the <span class="component">Replacement</span> field</h5>
 1346       <p class="wrap">
 1347         The <span class="command">Escape</span> command for the <span
 1348         class="component">Replacement</span> field, which can be issued with the button adjacent
 1349         to the field, prefixes an escape character to each escape character in the field.  (The
 1350         escape character for a replacement is specified by the <a class="configProperty"
 1351         href="#cp-general-replacementEscapeCharacter">general.replacementEscapeCharacter</a>
 1352         configuration property.)  If the escape character is &apos;<code>\</code>&apos;, it may
 1353         be best to unescape tabs and line feeds before issuing the <span
 1354         class="command">Escape</span> command unless the text contains literal
 1355         &quot;<code>\t</code>&quot; or &quot;<code>\n</code>&quot; sequences.
 1356       </p>
 1357 
 1358       <h3 id="section7-6">7.6&nbsp; Check boxes</h3>
 1359       <p class="wrap">
 1360         At the bottom of the control dialog are four check boxes.
 1361       </p>
 1362 
 1363       <h4 id="section7-6-1">7.6.1&nbsp; The <span class="component">Replace</span> check box</h4>
 1364       <p class="wrap">
 1365         If the <span class="component">Replace</span> check box is selected, the search mode is
 1366         <i>find</i>.  If the check box is <i>not</i> selected, the search mode is
 1367         <i>find-and-replace</i>.
 1368       </p>
 1369 
 1370       <h4 id="section7-6-2">7.6.2&nbsp; The <span class="component">Regular expression</span> check box</h4>
 1371       <p class="wrap">
 1372         If the <span class="component">Regular expression</span> check box is selected, the
 1373         search target is a regular expression.  If the check box is <i>not</i> selected, the
 1374         search target is literal text.
 1375       </p>
 1376 
 1377       <h4 id="section7-6-3">7.6.3&nbsp; The <span class="component">Ignore case</span> check box</h4>
 1378       <p class="wrap">
 1379         If the <span class="component">Ignore case</span> check box is selected, the case of
 1380         alphabetic characters is ignored when matching a search target.  If the check box is
 1381         <i>not</i> selected, matching is case-sensitive.
 1382       </p>
 1383 
 1384       <h4 id="section7-6-4">7.6.4&nbsp; The <span class="component">Show not found</span> check box</h4>
 1385       <p class="wrap">
 1386         If the <span class="component">Show not found</span> check box is selected, the results
 1387         that are displayed in the <a href="#section7-3">result area</a> at the end of a search
 1388         will include a list of files that were searched but in which the target was not found.
 1389         If the check box is <i>not</i> selected, the list of &quot;not found&quot; files will be
 1390         omitted from the search results.
 1391       </p>
 1392 
 1393       <h3 id="section7-7">7.7&nbsp; Window size</h3>
 1394       <p class="wrap">
 1395         The main window is not directly resizeable but its size can be modified indirectly by
 1396         means of some of the configuration properties that relate to the <a
 1397         href="#section7-2">text view</a> and <a href="#section7-3">result area</a>.
 1398       </p>
 1399       <p class="wrap">
 1400         The control dialog is resizeable.  The initial size of the dialog is determined by the
 1401         <a class="configProperty"
 1402         href="#cp-appearance-parameterEditorSize">appearance.parameterEditorSize</a>
 1403         configuration property, which can be edited in the <span
 1404         class="component">Preferences</span> dialog.  If the control dialog has been resized
 1405         using the GUI, the value of the <span
 1406         class="configProperty">appearance.parameterEditorSize</span> property that is written to
 1407         the configuration file when RegexSearch exits is obtained from the actual dimensions of
 1408         the <span class="component">Target</span> and <span class="component">Replacement</span>
 1409         fields, overriding any changes to the configuration property that were made in the <span
 1410         class="component">Preferences</span> dialog.
 1411       </p>
 1412       <p class="wrap">
 1413         As was mentioned above, the size of some text components &mdash; including the text view
 1414         and result area &mdash; is determined by the font that they use to display text, as well
 1415         as any properties that explicitly control their dimensions in terms of columns and rows.
 1416         Any changes to configuration properties that affect the size of the main window or
 1417         control dialog will not take effect until the next time that RegexSearch is run.
 1418       </p>
 1419 
 1420     </div>
 1421 
 1422     <!--=====================================================================================-->
 1423 
 1424     <!-- Commands -->
 1425 
 1426     <div class="section">
 1427       <h2 id="section8">8&nbsp; Commands</h2>
 1428       <p class="tocLink">
 1429         [ <a href="#toc">Table of contents</a> ]
 1430       </p>
 1431 
 1432       <p class="wrap">
 1433         RegexSearch&apos;s main commands are accessible from its main menu.  Some of the
 1434         commands are also accessible from a pop-up menu that is activated in a system-dependent
 1435         manner (eg, by pressing or releasing the right mouse button) while the mouse cursor is
 1436         over one of the text areas or the background of the control dialog.
 1437       </p>
 1438 
 1439       <h3 id="section8-1">8.1&nbsp; <span class="component">File</span> menu</h3>
 1440 
 1441       <h4 id="section8-1-1">8.1.1&nbsp; <span class="command">Open search parameters</span></h4>
 1442       <p class="wrap">
 1443         The <span class="command">Open search parameters</span> command brings up a
 1444         file-selection dialog in which you can choose the file that you want to open.  If the
 1445         file has the correct format, the search parameters are loaded from it and the
 1446         application&apos;s display is updated.  If the current search parameters were read from
 1447         a file, either automatically at startup or explicitly, and the parameters have changed
 1448         since the file was read, you will be asked whether you want to save the current
 1449         parameters before the new parameters are loaded.
 1450       </p>
 1451 
 1452       <h4 id="section8-1-2">8.1.2&nbsp; <span class="command">Save search parameters</span></h4>
 1453       <p class="wrap">
 1454         The <span class="command">Save search parameters</span> command brings up a
 1455         file-selection dialog in which you can choose the file to which you want to save the
 1456         current set of search parameters.  A file that is saved in this way can be specified as
 1457         the <a href="#cp-path-defaultSearchParameters">default search parameters</a> that will
 1458         be loaded when RegexSearch starts up.
 1459       </p>
 1460 
 1461       <h4 id="section8-1-3">8.1.3&nbsp; <span class="command">Exit</span></h4>
 1462       <p class="wrap">
 1463         This command terminates the application.  If you have made changes to search parameters
 1464         that were read from a file, you will be asked whether you want to save them.
 1465       </p>
 1466 
 1467       <h3 id="section8-2">8.2&nbsp; <span class="component">Edit</span> menu</h3>
 1468 
 1469       <h4 id="section8-2-1">8.2.1&nbsp; <span class="command">Edit file</span></h4>
 1470       <p class="wrap">
 1471         The <span class="command">Edit file</span> command executes a specified system command
 1472         in a separate process.  The command line, which is specified with the <a
 1473         class="configProperty" href="#cp-editor-command">editor.command</a> configuration
 1474         property, may include a placeholder for the pathname of the file that is currently
 1475         displayed in the text view.  The intended purpose of the command line is to open the
 1476         currently displayed file in a text editor, though it can be used for other purposes.
 1477       </p>
 1478       <p class="wrap">
 1479         When using the <span class="command">Edit file</span> command during a
 1480         <i>find-and-replace</i> search, remember that the file in the text editor will not be
 1481         synchronised with the file in RegexSearch&apos;s buffer, which may subsequently be
 1482         written back to the file system with modifications if replacements have been made in the
 1483         file, even if the replacements were made before the <span class="command">Edit
 1484         file</span> command was issued.  (If the <span class="command">Edit file</span> command
 1485         is issued while the <a class="component" href="#section8-4-1-2">Search options</a>
 1486         dialog is displayed, the <span class="command">Next file</span> option in the dialog can
 1487         be used to discard any changes to the current file.)
 1488       </p>
 1489       <p class="wrap">
 1490         After a search has finished, the external editor can be invoked on files that are
 1491         selected from those listed in the <a href="#section7-3">result area</a>.
 1492       </p>
 1493 
 1494       <h4 id="section8-2-2">8.2.2&nbsp; <span class="command">Edit file, deferred</span></h4>
 1495       <p class="wrap">
 1496         This command is available only during a <i>find-and-replace</i> search.  It behaves
 1497         similarly to the <a class="command" href="#section8-2-1">Edit file</a> command except
 1498         that the associated system command (specified with the <a class="configProperty"
 1499         href="#cp-editor-command">editor.command</a> configuration property) is not executed
 1500         until the search of the current file is finished and, if any replacements have been
 1501         made, the modified file has been written to the file system.
 1502       </p>
 1503 
 1504       <h3 id="section8-3">8.3&nbsp; <span class="component">View</span> menu</h3>
 1505 
 1506       <h4 id="section8-3-1">8.3.1&nbsp; <span class="command">Hide control dialog</span> /
 1507                             <span class="command">Show control dialog</span></h4>
 1508       <p class="wrap">
 1509         If the control dialog is visible, this command is named <span class="command">Hide
 1510         control dialog</span> and it makes the control dialog invisible.  If the control dialog
 1511         is hidden, this command is named <span class="command">Show control dialog</span> and it
 1512         makes the control dialog visible.
 1513       </p>
 1514 
 1515       <h3 id="section8-4">8.4&nbsp; <span class="component">Search</span> menu</h3>
 1516 
 1517       <h4 id="section8-4-1">8.4.1&nbsp; <span class="command">Search</span></h4>
 1518       <p class="wrap">
 1519         When you issue a <span class="command">Search</span> command, RegexSearch first
 1520         validates the search parameters and displays an error message for the first parameter
 1521         that is invalid.  If the file-set kind is List, the specified list file is read and
 1522         parsed.  In a search of multiple files, the files are searched in the order described in
 1523         the <a href="#section6-1-3-2">Directory</a> and <a href="#section6-1-3-3">List</a>
 1524         file-set kinds.
 1525       </p>
 1526       <p class="wrap">
 1527         Within a file, the search proceeds from the start of the file to the end.  If a match of
 1528         the target expression is found, the search will resume at the first character after the
 1529         last character in the matched text, or, if a replacement is made, at the first character
 1530         after the replacement.
 1531       </p>
 1532       <p class="wrap">
 1533         When the first match of the target expression is found, the file in which the match
 1534         occurred is displayed in the text view, and the matched text is highlighted.  A <span
 1535         class="component">Search options</span> dialog box is displayed; the type of dialog
 1536         depends on the search mode, <i>find</i> or <i>find-and-replace</i>.  Because the <span
 1537         class="component">Search options</span> dialog is non-modal, the text in the text view
 1538         can be scrolled while the dialog is displayed.
 1539       </p>
 1540       <p class="wrap">
 1541         The options in the <span class="component">Search options</span> dialog can be selected
 1542         either by clicking on the appropriate button or by pressing a key or key combination.
 1543         In addition to the usual Java Alt+<i>&lt;key&gt;</i> combination, each option (apart
 1544         from <span class="component">Cancel</span>, whose keyboard equivalent is the Escape key)
 1545         can be selected by pressing the key by itself (ie, without the Alt key).
 1546       </p>
 1547       <p class="wrap">
 1548         At the end of a search, the aggregate results are displayed in the result area.  The
 1549         results include a list of any files or directories that were not processed because of an
 1550         error and a list of files or directories whose pathname could not be converted to
 1551         canonical form.  If the <a href="#cp-general-fileWritingMode">file-writing mode</a> is
 1552         <i>Use a temporary file, preserve attributes</i>, the results of a
 1553         <i>find-and-replace</i> search include a separate list of files that were written but
 1554         whose attributes were not set.
 1555       </p>
 1556 
 1557       <h5 id="section8-4-1-1">8.4.1.1&nbsp; The <span class="component">Search options</span>
 1558                               dialog in <i>find</i> mode</h5>
 1559       <p class="wrap">
 1560         In <i>find</i> mode, the <span class="component">Search options</span> dialog has four
 1561         options:
 1562       </p>
 1563       <dl class="basic">
 1564         <dt>Yes</dt>
 1565         <dd class="wrap">
 1566           The search is resumed in the current file.  If no more matches are found in the
 1567           current file, the search proceeds to the next file.  If another occurrence is found,
 1568           the matched text is highlighted and the <span class="component">Search options</span>
 1569           dialog is displayed again.
 1570         </dd>
 1571 
 1572         <dt>Global</dt>
 1573         <dd class="wrap">
 1574           The search is resumed in the current file, and proceeds through all the files in the
 1575           file set without displaying the <span class="component">Search options</span> dialog
 1576           again.  As each file is searched, if any matches are found in the file, the number of
 1577           matches for that file is displayed in the result area.  To make the search faster,
 1578           files are not displayed in the text view during a global search.
 1579         </dd>
 1580         <dd class="wrap">
 1581           A global search in <i>find</i> mode can be used to generate a list of files in which a
 1582           match of the target expression was found.
 1583         </dd>
 1584 
 1585         <dt>Next file</dt>
 1586         <dd class="wrap">
 1587           The current file is skipped, and the search is resumed with the next file.  If another
 1588           occurrence is found, the matched text is highlighted and the <span
 1589           class="component">Search options</span> dialog is displayed again.
 1590         </dd>
 1591 
 1592         <dt>Cancel</dt>
 1593         <dd class="wrap">
 1594           The search is terminated.
 1595         </dd>
 1596       </dl>
 1597 
 1598       <h5 id="section8-4-1-2">8.4.1.2&nbsp; The <span class="component">Search options</span>
 1599                               dialog in <i>find-and-replace</i> mode</h5>
 1600       <p class="wrap">
 1601         In <i>find-and-replace</i> mode, the <span class="component">Search options</span>
 1602         dialog has seven options:
 1603       </p>
 1604       <dl class="basic">
 1605         <dt>Yes</dt>
 1606         <dd class="wrap">
 1607           The occurrence of the matched text is replaced, and the search is resumed in the
 1608           current file.  If no more matches are found in the current file, the search proceeds
 1609           to the next file.  If another occurrence is found, the matched text is highlighted and
 1610           the <span class="component">Search options</span> dialog is displayed again.
 1611         </dd>
 1612 
 1613         <dt>No</dt>
 1614         <dd class="wrap">
 1615           The occurrence of the matched text is not replaced, and the search is resumed in the
 1616           current file.  If no more matches are found in the current file, the search proceeds
 1617           to the next file.  If another occurrence is found, the matched text is highlighted and
 1618           the <span class="component">Search options</span> dialog is displayed again.
 1619         </dd>
 1620 
 1621         <dt>Preview</dt>
 1622         <dd class="wrap">
 1623           The occurrence of the matched text is replaced.  The replacement is displayed in the
 1624           text view, highlighted.  Another dialog box is displayed in which you are asked
 1625           whether you want to keep the replacement, to restore the original text or to cancel
 1626           the search.  In that dialog, the <span class="command">Keep</span>, <span
 1627           class="command">Restore</span> and <span class="command">Cancel</span> options are
 1628           equivalent respectively to the <span class="command">Yes</span>, <span
 1629           class="command">No</span> and <span class="command">Cancel</span> options in the <span
 1630           class="component">Search options</span> dialog.
 1631         </dd>
 1632 
 1633         <dt>This file</dt>
 1634         <dd class="wrap">
 1635           The occurrence of the matched text is replaced, along with all remaining occurrences
 1636           in the current file.  The current file is saved, and the search proceeds to the next
 1637           file.  If another occurrence is found in a subsequent file, the matched text is
 1638           highlighted and the <span class="component">Search options</span> dialog is displayed
 1639           again.
 1640         </dd>
 1641 
 1642         <dt>Global</dt>
 1643         <dd class="wrap">
 1644           The occurrence of the matched text is replaced, along with all remaining occurrences
 1645           in the current file and any subsequent files.  The search proceeds through all the
 1646           files in the file set without displaying the <span class="component">Search
 1647           options</span> dialog again.  To make the search faster, the text view is not updated
 1648           during a global search.
 1649         </dd>
 1650 
 1651         <dt>Next file</dt>
 1652         <dd class="wrap">
 1653           The occurrence of the matched text is not replaced.  Any changes to the current file
 1654           are saved and the search is resumed with the next file.  If another occurrence is
 1655           found, the matched text is highlighted and the <span class="component">Search
 1656           options</span> dialog is displayed again.
 1657         </dd>
 1658 
 1659         <dt>Cancel</dt>
 1660         <dd class="wrap">
 1661           The search is terminated.  Any changes to the current file are discarded.
 1662         </dd>
 1663       </dl>
 1664 
 1665       <h5 id="section8-4-1-3">8.4.1.3&nbsp; How files are processed</h5>
 1666       <p class="wrap">
 1667         Some aspects of RegexSearch&apos;s behaviour when processing files are worth noting in
 1668         order that you may avoid the unintended consequences of that behaviour.  RegexSearch
 1669         assumes that the files it reads during a search are text files that have a specified
 1670         character set and encoding.  It also assumes that certain characters or character
 1671         sequences in the files are line separators.  The implications of these two assumptions
 1672         are discussed below.
 1673       </p>
 1674       <p class="wrap">
 1675         When a file is read during a search, the bytes of the file are converted to 16-bit
 1676         Unicode according to the configuration property <a class="configProperty"
 1677         href="#cp-general-characterEncoding">general.characterEncoding</a>.  A character
 1678         encoding, such as UTF-8, maps between sequences of bytes and 16-bit Unicode values.
 1679       </p>
 1680       <p class="wrap">
 1681         Within the file, all occurrences of the characters LF (U+000A) and CR (U+000D), and the
 1682         character sequence (CR, LF) are treated as line separators.  The kind of line separator
 1683         is recorded for possible later use.  If the file contains more than one kind of line
 1684         separator, the most numerous kind of line separator prevails.  If the numbers of
 1685         different kinds are equal, the precedence from highest to lowest is: LF &ndash; CR
 1686         &ndash; CR+LF.
 1687       </p>
 1688       <p class="wrap">
 1689         In <i>find</i> mode, the processing of a file ends at this point: the processing is
 1690         internal, and no physical changes are made to the stored file.  In
 1691         <i>find-and-replace</i> mode, a file may be modified as a result of a replacement, and
 1692         the file written back to the file system.  If the <a class="configProperty"
 1693         href="#cp-general-preserveLineSeparator">general.preserveLineSeparator</a> configuration
 1694         property has the value <code>true</code>, the file is written with the kind of line
 1695         separator that was detected when it was read; otherwise, it is written with an LF line
 1696         separator.
 1697       </p>
 1698       <p class="wrap">
 1699         The way in which a modified file is written to the file system is determined by the <a
 1700         class="configProperty" href="#cp-general-fileWritingMode">general.fileWritingMode</a>
 1701         configuration property.  A file may be written directly, or it may be written first to a
 1702         temporary file that is renamed after the entire file has been written.  If a temporary
 1703         file is used, the owner, group and permissions of the file may be set to those of the
 1704         original file on systems that support it.  (Linux is the only system that is known to do
 1705         so.)  See the description of the <a class="configProperty"
 1706         href="#cp-general-fileWritingMode">general.fileWritingMode</a> property for more details
 1707         on its use.
 1708       </p>
 1709 
 1710 
 1711       <h4 id="section8-4-2">8.4.2&nbsp; <span class="command">Copy results</span></h4>
 1712       <p class="wrap">
 1713         The <span class="command">Copy results</span> command copies the contents of the result
 1714         area to the system clipboard.  The <a class="configProperty"
 1715         href="#cp-general-copyResultsAsListFile">general.copyResultsAsListFile</a> configuration
 1716         property controls the format of the text that is placed on the clipboard: the results
 1717         can be either in the form in which they appear in the result area or in a form that is
 1718         suitable for use as a <a href="#section6-1-3-3">list file</a> in a new search, with
 1719         match/replacement counts converted to comments.
 1720       </p>
 1721 
 1722       <h4 id="section8-4-3">8.4.3&nbsp; <span class="command">Save results</span></h4>
 1723       <p class="wrap">
 1724         The <span class="command">Save results</span> command saves the list of files from the
 1725         results of the last search (ie, the files in which an occurrence of the target was
 1726         found).  A list of files that is saved with this command can be used as the file set for
 1727         a further search if you select Results as the file-set kind.
 1728       </p>
 1729 
 1730       <h4 id="section8-4-4">8.4.4&nbsp; <span class="command">View saved results</span></h4>
 1731       <p class="wrap">
 1732         The <span class="command">View saved results</span> command displays the last list of
 1733         files to be saved with the <span class="command">Save results</span> command, which
 1734         allows you to see the files that will comprise the file set if Results is selected as
 1735         the file-set kind.
 1736       </p>
 1737 
 1738       <h3 id="section8-5">8.5&nbsp; <span class="component">Options</span> menu</h3>
 1739 
 1740       <h4 id="section8-5-1">8.5.1&nbsp; <span class="command">Preferences</span></h4>
 1741       <p class="wrap">
 1742         The <span class="command">Preferences</span> command brings up a tabbed dialog box in
 1743         which the configuration properties of RegexSearch can be edited.  The properties on the
 1744         various tabbed pages are described below.
 1745       </p>
 1746       <p class="wrap">
 1747         Some of the configuration properties in the <span class="component">Preferences</span>
 1748         dialog are edited with a <i>spinner</i> &mdash; a graphical component that consists of a
 1749         text field adjacent to a pair of small buttons.  The value in the text field may be
 1750         edited manually, or it may be incremented and decremented by one of the following
 1751         methods:
 1752       </p>
 1753       <ul class="list">
 1754         <li class="wrap">
 1755           clicking on the small up/down buttons;
 1756         </li>
 1757         <li class="wrap">
 1758           pressing the up/down arrow keys;
 1759         </li>
 1760         <li class="wrap">
 1761           rotating the mouse wheel with the mouse cursor over the spinner when the text field
 1762           has keyboard focus (ie, the caret is displayed in the field).
 1763         </li>
 1764       </ul>
 1765       <p class="wrap">
 1766         Using the last two methods, the amount by which the value is incremented or decremented
 1767         can be modified by holding down the Ctrl, Shift or Ctrl+Shift keys, which correspond to
 1768         increments of 10, 100 and 1000 respectively.
 1769       </p>
 1770 
 1771       <div class="preferences">
 1772         <div>
 1773           <div class="sectionTitle" id="section8-5-1-a">General</div>
 1774         </div>
 1775 
 1776         <div>
 1777           <div id="cp-general-characterEncoding">
 1778             <dl>
 1779               <dt>Character encoding</dt>
 1780               <dd class="wrap">
 1781                 This property denotes the character encoding that is used to map between the
 1782                 bytes of a file and Unicode values when reading and writing files.  Different
 1783                 implementations of Java may support different character encodings, though every
 1784                 implementation must support a few common encodings, including ISO 8859-1
 1785                 (Latin-1) and UTF-8.  The drop-down list contains the character encodings that
 1786                 are available in the current implementation.  At the top of the list is the
 1787                 value <code>&lt;default encoding&gt;</code>, which denotes the platform- and
 1788                 locale-dependent default character encoding.
 1789               </dd>
 1790               <dd class="spaceAbove wrap">
 1791                 The default value is determined at runtime by the Java virtual machine,
 1792                 depending on the locale and platform.
 1793               </dd>
 1794             </dl>
 1795           </div>
 1796         </div>
 1797         <div>
 1798           <div id="cp-general-escapedMetacharacters">
 1799             <dl>
 1800               <dt>Escaped metacharacters</dt>
 1801               <dd class="wrap">
 1802                 This is the set of characters that will be escaped (ie, characters that will
 1803                 have &apos;<code>\</code>&apos; prefixed to them) when the <a class="command"
 1804                 href="#section7-5-3-3">Escape</a> command is applied to a regular-expression
 1805                 target.
 1806               </dd>
 1807               <dd class="spaceAbove wrap">
 1808                 The default value is <code>$()*+.?[\]^{|}</code>
 1809               </dd>
 1810             </dl>
 1811           </div>
 1812         </div>
 1813         <div>
 1814           <div id="cp-general-replacementEscapeCharacter">
 1815             <dl>
 1816               <dt>Replacement escape character</dt>
 1817               <dd class="wrap">
 1818                 This is the character that is used as the escape character in <a
 1819                 href="#section6-3">replacement</a> expressions.  Your choice of character is
 1820                 limited to the punctuation characters that are displayed in the drop-down list.
 1821               </dd>
 1822               <dd class="spaceAbove wrap">
 1823                 The default value is <code>\</code> (backslash, U+005C).
 1824               </dd>
 1825             </dl>
 1826           </div>
 1827         </div>
 1828         <div>
 1829           <div id="cp-general-ignoreFilenameCase">
 1830             <dl>
 1831               <dt>Ignore case of filenames</dt>
 1832               <dd class="wrap">
 1833                 If you select <code>Yes</code>, alphabetic case will be ignored when matching
 1834                 pathnames against the patterns in an inclusion or exclusion filter and when
 1835                 matching filenames against the patterns in a tab-width filter (eg, the filename
 1836                 pattern &quot;*.txt&quot; will match the filenames <code>foo.txt</code> and
 1837                 <code>BAR.TXT</code>).
 1838               </dd>
 1839               <dd class="spaceAbove wrap">
 1840                 The default value is <code>No</code>.
 1841               </dd>
 1842             </dl>
 1843           </div>
 1844         </div>
 1845         <div>
 1846           <div id="cp-general-fileWritingMode">
 1847             <dl>
 1848               <dt>File-writing mode</dt>
 1849               <dd>
 1850                 <div class="wrap">
 1851                   This property determines how files that are modified during a
 1852                   <i>find-and-replace</i> search are written back to the file system.
 1853                 </div>
 1854                 <dl class="inner1">
 1855                   <dt>Direct</dt>
 1856                   <dd class="wrap">
 1857                     The file is written directly to an existing file (ie, the existing file is
 1858                     overwritten).  Using this method, the file attributes are preserved but
 1859                     there is a risk that the existing file may be corrupted if there is a system
 1860                     failure while the file is being written.
 1861                   </dd>
 1862 
 1863                   <dt>Use a temporary file</dt>
 1864                   <dd class="wrap">
 1865                     The file is first written to a temporary file.  When the temporary file has
 1866                     been written and closed, the existing file is deleted and the temporary file
 1867                     renamed.  This is safer than the direct-writing mode but it does not
 1868                     preserve the file attributes on Linux/UNIX.  (Files were always written in
 1869                     this way by RegexSearch prior to the introduction of this configuration
 1870                     property in version 2.2.)
 1871                   </dd>
 1872 
 1873                   <dt>Use a temporary file, preserve attributes</dt>
 1874                   <dd class="wrap">
 1875                     With this option, the file is first written to a temporary file, as with the
 1876                     previous option.  After the temporary file has been renamed, the Linux/UNIX
 1877                     <code>chmod</code>, <code>chgrp</code> and <code>chown</code> commands are
 1878                     issued with the <code>--reference</code> option, which should set the
 1879                     file&apos;s permissions, group and owner to those of the original file.
 1880                     Linux is known to support the <code>--reference</code> option for these
 1881                     three commands; other UNIX-like systems may support it.  Because it involves
 1882                     the additional execution of three system commands, this file-writing mode is
 1883                     slower than the other two.
 1884                   </dd>
 1885                 </dl>
 1886               </dd>
 1887               <dd class="spaceAbove wrap">
 1888                 The default value is <code>Use a temporary file</code>.
 1889               </dd>
 1890             </dl>
 1891           </div>
 1892         </div>
 1893         <div>
 1894           <div id="cp-general-preserveLineSeparator">
 1895             <dl>
 1896               <dt>Preserve line-separator kind</dt>
 1897               <dd class="wrap">
 1898                 If you select <code>Yes</code>, a file in which replacements are made during a
 1899                 <i>find-and-replace</i> search will be written with the same kind of line
 1900                 separator &mdash; LF (U+000A), CR (U+000D) or CR+LF &mdash; that it had when it
 1901                 was read.  (Files that have more than one kind of line separator will be written
 1902                 with the kind of line separator that is most numerous.)  If this property has
 1903                 the value <code>No</code>, files modified by RegexSearch will be written with LF
 1904                 (UNIX-style) line separators.
 1905               </dd>
 1906               <dd class="spaceAbove wrap">
 1907                 The default value is <code>Yes</code>.
 1908               </dd>
 1909             </dl>
 1910           </div>
 1911         </div>
 1912         <div>
 1913           <div id="cp-general-showUnixPathnames">
 1914             <dl>
 1915               <dt>Display UNIX-style pathnames</dt>
 1916               <dd>
 1917                 <div class="wrap">
 1918                   If you select <code>Yes</code>, pathnames are displayed in a reduced
 1919                   &quot;UNIX style&quot; in some parts of the GUI.  A pathname is converted from
 1920                   its platform-specific form in two steps:
 1921                 </div>
 1922                 <ol class="noTopMargin">
 1923                   <li class="wrap">
 1924                     If the pathname starts with the user&apos;s home directory, the latter is
 1925                     replaced by &apos;<code>~</code>&apos;.
 1926                   </li>
 1927                   <li class="wrap">
 1928                     The file-separator character (&apos;<code>\</code>&apos; on Windows systems)
 1929                     is replaced by &apos;<code>/</code>&apos;.
 1930                   </li>
 1931                 </ol>
 1932               </dd>
 1933               <dd class="spaceAbove wrap">
 1934                 The default value is <code>No</code>.
 1935               </dd>
 1936             </dl>
 1937           </div>
 1938         </div>
 1939         <div>
 1940           <div id="cp-general-selectTextOnFocusGained">
 1941             <dl>
 1942               <dt>Select text when focus is gained</dt>
 1943               <dd class="wrap">
 1944                 If you select <code>Yes</code>, all the text in a text field will be
 1945                 automatically selected when the field gains keyboard focus, regardless of how
 1946                 the focus is transferred.
 1947               </dd>
 1948               <dd class="spaceAbove wrap">
 1949                 The default value is <code>Yes</code>.
 1950               </dd>
 1951             </dl>
 1952           </div>
 1953         </div>
 1954         <div>
 1955           <div id="cp-general-mainWindowLocation">
 1956             <dl>
 1957               <dt>Save location of main window</dt>
 1958               <dd class="wrap">
 1959                 If you select <code>Yes</code>, the location of the main window on the screen
 1960                 will be saved to the configuration file when you exit the application.  The next
 1961                 time that RegexSearch is run, its main window will be positioned at the
 1962                 previously saved location.
 1963               </dd>
 1964               <dd class="spaceAbove wrap">
 1965                 The default value is <code>Yes</code>.
 1966               </dd>
 1967             </dl>
 1968           </div>
 1969         </div>
 1970         <div>
 1971           <div id="cp-general-hideControlDialogWhenSearching">
 1972             <dl>
 1973               <dt>Hide control dialog when searching</dt>
 1974               <dd class="wrap">
 1975                 If this property has the value <code>Yes</code> and the control dialog has not
 1976                 been explicitly hidden, it is automatically hidden during a search and made
 1977                 visible again when the search ends.  If the control dialog is hidden in this
 1978                 way, the <a class="command" href="#section8-3-1">Show control dialog</a> command
 1979                 can be used to make it visible during a search.
 1980               </dd>
 1981               <dd class="spaceAbove wrap">
 1982                 The default value is <code>No</code>.
 1983               </dd>
 1984             </dl>
 1985           </div>
 1986         </div>
 1987         <div>
 1988           <div id="cp-general-copyResultsAsListFile">
 1989             <dl>
 1990               <dt>Copy search results as list file</dt>
 1991               <dd class="wrap">
 1992                 This property controls the format of the text that the <a class="command"
 1993                 href="#section8-4-2">Copy results</a> command places on the system clipboard.
 1994                 If you select <code>No</code>, the results are in the form in which they appear
 1995                 in the result area of the main window.  If you select <code>Yes</code>, the
 1996                 results are converted into a form that is suitable for use as a <a
 1997                 href="#section6-1-3-3">list file</a> in a new search.
 1998               </dd>
 1999               <dd class="spaceAbove wrap">
 2000                 The default value is <code>No</code>.
 2001               </dd>
 2002             </dl>
 2003           </div>
 2004         </div>
 2005       </div>
 2006 
 2007       <div class="preferences">
 2008         <div>
 2009           <div class="sectionTitle" id="section8-5-1-b">Appearance</div>
 2010         </div>
 2011 
 2012         <div>
 2013           <div id="cp-appearance-lookAndFeel">
 2014             <dl>
 2015               <dt>Look-and-feel</dt>
 2016               <dd class="wrap">
 2017                 The look-and-feel (LAF) can be selected from a list of the LAFs that are
 2018                 available on the current system.
 2019               </dd>
 2020               <dd class="spaceAbove wrap">
 2021                 The default value is the cross-platform LAF, currently called Metal.
 2022               </dd>
 2023             </dl>
 2024           </div>
 2025         </div>
 2026         <div>
 2027           <div id="cp-appearance-textAntialiasing">
 2028             <dl>
 2029               <dt>Text antialiasing</dt>
 2030               <dd class="wrap">
 2031                 This determines the kind of antialiasing that is performed when text is drawn in
 2032                 custom or partially customised user-interface components (eg, in drop-down
 2033                 lists).  Note that antialiasing is only a hint in Java; the implementation is
 2034                 not required to perform the chosen antialiasing.
 2035               </dd>
 2036               <dd class="spaceAbove wrap">
 2037                 This property has no effect on the antialiasing of text in standard UI
 2038                 components, such as labels and menus, which is determined by the Java
 2039                 implementation and the desktop setting for antialiasing text (often referred to
 2040                 as &quot;font smoothing&quot;).  You can override the desktop setting with the
 2041                 unsupported system property <code><a class="external"
 2042                 href="https://docs.oracle.com/javase/7/docs/technotes/guides/2d/flags.html#aaFonts">awt.useSystemAAFontSettings</a></code>.
 2043               </dd>
 2044               <dd class="spaceAbove wrap">
 2045                 This property does not control text antialiasing in the text view, which is
 2046                 configured independently with the property <a class="configProperty"
 2047                 href="#cp-appearance-textViewTextAntialiasing">appearance.textViewTextAntialiasing</a>.
 2048               </dd>
 2049               <dd class="spaceAbove wrap">
 2050                 The text antialiasing property can have the following values:
 2051               </dd>
 2052               <dd>
 2053                 <dl class="inner1">
 2054                   <dt>Default</dt>
 2055                   <dd class="wrap">
 2056                     The desktop setting for text antialiasing (font smoothing) is used, if the
 2057                     Java implementation recognises one; otherwise, no antialiasing is performed.
 2058                   </dd>
 2059 
 2060                   <dt>None</dt>
 2061                   <dd class="wrap">
 2062                     No antialiasing is performed.
 2063                   </dd>
 2064 
 2065                   <dt>Standard</dt>
 2066                   <dd class="wrap">
 2067                     This selects pixel-oriented antialiasing rather than subpixel antialiasing.
 2068                     It is suitable for non-LCD displays.
 2069                   </dd>
 2070 
 2071                   <dt>Subpixel, horizontal RGB</dt>
 2072                   <dt>Subpixel, horizontal BGR</dt>
 2073                   <dt>Subpixel, vertical RGB</dt>
 2074                   <dt>Subpixel, vertical BGR</dt>
 2075                   <dd class="wrap">
 2076                     These four options are intended to optimise the rendering of text for LCD
 2077                     displays using subpixel antialiasing with subpixels in the chosen
 2078                     arrangement.  Selecting an option that does not correspond to the actual
 2079                     arrangement of subpixels in your LCD display may result in blurred text.
 2080                     The most common arrangement of subpixels is horizontal RGB.
 2081                   </dd>
 2082                 </dl>
 2083               </dd>
 2084               <dd class="wrap">
 2085                 The default value is <code>Default</code>.
 2086               </dd>
 2087             </dl>
 2088           </div>
 2089         </div>
 2090         <div>
 2091           <div id="cp-appearance-parameterEditorSize">
 2092             <dl>
 2093               <dt>Size of parameter editor</dt>
 2094               <dd class="wrap">
 2095                 These are the dimensions (number of columns &times; number of rows) of the <span
 2096                 class="component">Target</span> and <span class="component">Replacement</span>
 2097                 fields in the control dialog.  The width of a column is the width of a zero
 2098                 character (U+0030) in the field&apos;s font.  If the control dialog is resized
 2099                 using the GUI, the size of the parameter editor that was set in the <span
 2100                 class="component">Preferences</span> dialog is overridden by the actual size of
 2101                 the <span class="component">Target</span> and <span
 2102                 class="component">Replacement</span> fields when the configuration properties
 2103                 are saved on exiting RegexSearch.
 2104               </dd>
 2105               <dd class="spaceAbove wrap">
 2106                 The default dimensions are 80 &times; 4.
 2107               </dd>
 2108             </dl>
 2109           </div>
 2110         </div>
 2111         <div>
 2112           <div id="cp-appearance-resultAreaNumRows">
 2113             <dl>
 2114               <dt>Number of rows in result area</dt>
 2115               <dd class="wrap">
 2116                 This determines the viewable height of the result area.
 2117               </dd>
 2118               <dd class="spaceAbove wrap">
 2119                 The default value is 4.
 2120               </dd>
 2121             </dl>
 2122           </div>
 2123         </div>
 2124         <div>
 2125           <div id="cp-appearance-tabSurrogate">
 2126             <dl>
 2127               <dt>Tab surrogate</dt>
 2128               <dd class="wrap">
 2129                 This is the character that is used in place of a tab character in the <span
 2130                 class="component">Target</span> and <span class="component">Replacement</span>
 2131                 fields.  Its role is described in the section on the <a
 2132                 href="#section7-5-3-1">tab surrogate</a>.  You can enter either a single
 2133                 character or four hexadecimal-digit characters in the <span
 2134                 class="component">Tab surrogate</span> field.  The hexadecimal digits will be
 2135                 interpreted as a Unicode value.  If a character is a control code or it cannot
 2136                 be displayed in the field&apos;s font, it is displayed in the field as its
 2137                 four-digit Unicode value.
 2138               </dd>
 2139               <dd class="spaceAbove wrap">
 2140                 The default value is the tab character, U+0009.
 2141               </dd>
 2142             </dl>
 2143           </div>
 2144         </div>
 2145         <div>
 2146           <div id="cp-appearance-textViewViewableSize">
 2147             <dl>
 2148               <dt>Text view: viewable size</dt>
 2149               <dd class="wrap">
 2150                 These are the dimensions (number of columns &times; number of rows) of the area
 2151                 in which the contents of a file are displayed.  The physical size of the text
 2152                 view is also determined by its font.
 2153               </dd>
 2154               <dd class="spaceAbove wrap">
 2155                 The default dimensions are 96 &times; 24.
 2156               </dd>
 2157             </dl>
 2158           </div>
 2159         </div>
 2160         <div>
 2161           <div id="cp-appearance-textViewMaxNumColumns">
 2162             <dl>
 2163               <dt>Text view: maximum number of columns</dt>
 2164               <dd class="wrap">
 2165                 This is the upper bound of the width of the text view; lines of text displayed
 2166                 in the text view are truncated at this bound.  The bound applies only to
 2167                 <em>displayed</em> text: the actual text is not truncated.  (The use of this
 2168                 property makes the display of text more efficient.)
 2169               </dd>
 2170               <dd class="spaceAbove wrap">
 2171                 The default value is 256.
 2172               </dd>
 2173             </dl>
 2174           </div>
 2175         </div>
 2176         <div>
 2177           <div id="cp-appearance-textViewTextAntialiasing">
 2178             <dl>
 2179               <dt>Text view: text antialiasing</dt>
 2180               <dd class="wrap">
 2181                 This determines the kind of antialiasing that is performed when text is drawn in
 2182                 the text view.  It is independent from the general text antialiasing property in
 2183                 order to allow, for example, a bitmap font to be used in the text view.  The
 2184                 values that this property may have are described for the <a
 2185                 class="configProperty"
 2186                 href="#cp-appearance-textAntialiasing">appearance.textAntialiasing</a> property.
 2187               </dd>
 2188               <dd class="wrap">
 2189                 The default value is <code>Default</code>.
 2190               </dd>
 2191             </dl>
 2192           </div>
 2193         </div>
 2194         <div>
 2195           <div id="cp-appearance-textAreaColour">
 2196             <dl>
 2197               <dt>Text area colours</dt>
 2198               <dd class="wrap">
 2199                 These are the four colours that are used when drawing text in the text view, the
 2200                 result area and the fields in the <span class="component">Search options</span>
 2201                 dialog.  Clicking on a colour button brings up a colour-selection dialog.
 2202               </dd>
 2203             </dl>
 2204           </div>
 2205         </div>
 2206       </div>
 2207 
 2208       <div class="preferences">
 2209         <div>
 2210           <div class="sectionTitle" id="section8-5-1-d">Tab width</div>
 2211         </div>
 2212 
 2213         <div>
 2214           <div id="cp-tabWidth-fileFilter">
 2215             <dl>
 2216               <dt>Text view: tab-width filters, default tab width</dt>
 2217               <dd class="wrap">
 2218                 When a file containing tab characters (U+0009) is displayed, RegexSearch uses
 2219                 two properties &mdash; a list of tab-width filters and a default tab width
 2220                 &mdash; to determine how the tab characters are converted to spaces.  A
 2221                 tab-width filter is a filename filter that is mapped to a tab width.  The
 2222                 filename filter consists of one or more space-separated filename patterns (eg,
 2223                 &quot;*.c *.cpp *.h *.hpp&quot;).  Up to 64 tab-width filters can be specified.
 2224                 Filters are applied in the order in which they appear in the list.  The default
 2225                 tab width is used for a file whose name does not match any filter.
 2226               </dd>
 2227               <dd class="spaceAbove wrap">
 2228                 New filters can be added to the list, and items in the list can be edited,
 2229                 deleted or their position in the list changed.  The Delete key and Delete button
 2230                 delete the selected item after confirmation, while Shift+Delete and
 2231                 Shift+left-click on the Delete button delete the selected item without
 2232                 confirmation.  The position of an item in the list can be changed by dragging it
 2233                 with the mouse, or by pressing Ctrl+Shift+Up or Ctrl+Shift+Down when the list
 2234                 has keyboard focus.
 2235               </dd>
 2236               <dd class="spaceAbove wrap">
 2237                 The default value of the default tab width is 8.
 2238               </dd>
 2239             </dl>
 2240           </div>
 2241         </div>
 2242         <div>
 2243           <div id="cp-tabWidth-targetAndReplacement">
 2244             <dl>
 2245               <dt>Target and replacement editors: tab width</dt>
 2246               <dd class="wrap">
 2247                 This is the tab width that is used in the target and replacement editors if the
 2248                 tab surrogate is the tab character (U+0009) itself.
 2249               </dd>
 2250               <dd class="spaceAbove wrap">
 2251                 The default value of the tab width in the target and replacement editors is 8.
 2252               </dd>
 2253             </dl>
 2254           </div>
 2255         </div>
 2256       </div>
 2257 
 2258       <div class="preferences">
 2259         <div>
 2260           <div class="sectionTitle" id="section8-5-1-e">Editor</div>
 2261         </div>
 2262 
 2263         <div>
 2264           <div id="cp-editor-command">
 2265             <dl>
 2266               <dt>Command</dt>
 2267               <dd>
 2268                 <div class="wrap">
 2269                   This property can be used to specify a command line that will invoke a text
 2270                   editor, either
 2271                 </div>
 2272                 <ul class="continuationList">
 2273                   <li class="wrap">
 2274                     during a search, on the current file, in response to the <a class="command"
 2275                     href="#section8-2-1">Edit &gt; Edit file</a> and <a class="command"
 2276                     href="#section8-2-2">Edit &gt; Edit file, deferred</a> commands, or
 2277                   </li>
 2278                   <li class="wrap">
 2279                     after a search, by selecting a file from the results of a search that are
 2280                     listed in the <a href="#section7-3">result area</a>.
 2281                   </li>
 2282                 </ul>
 2283                 <div class="wrap">
 2284                   The pathname of the file to be edited can be included in the command line so
 2285                   that the file will be opened in the text editor.
 2286                 </div>
 2287               </dd>
 2288               <dd class="spaceAbove wrap">
 2289                 Within the command line, arguments must be separated with one or more spaces,
 2290                 and &apos;<code>%</code>&apos; (U+0025) acts as an escape character.
 2291                 &apos;<code>%f</code>&apos; is a placeholder for the pathname of the file that
 2292                 is to be edited.  All other characters that follow &apos;<code>%</code>&apos;
 2293                 are treated as themselves; thus, a literal space is represented by
 2294                 &apos;<code>%&nbsp;</code>&apos; (ie, U+0025, U+0020), and a literal
 2295                 &apos;<code>%</code>&apos; is represented by &apos;<code>%%</code>&apos;.
 2296               </dd>
 2297               <dd class="spaceAbove wrap">
 2298                 Pathnames in the command line may contain <a href="#sectionA">special
 2299                 constructs</a> for system properties, environment variables and the user&apos;s
 2300                 home directory.
 2301               </dd>
 2302             </dl>
 2303           </div>
 2304         </div>
 2305       </div>
 2306 
 2307       <div class="preferences">
 2308         <div>
 2309           <div class="sectionTitle" id="section8-5-1-f">File locations</div>
 2310         </div>
 2311 
 2312         <div>
 2313           <div id="cp-path-defaultSearchParameters">
 2314             <dl>
 2315               <dt>Default search parameters</dt>
 2316               <dd class="wrap">
 2317                 This is the pathname of the search-parameter file that will be loaded
 2318                 automatically when RegexSearch starts up.  The pathname may contain <a
 2319                 href="#sectionA">special constructs</a> for system properties, environment
 2320                 variables and the user&apos;s home directory.
 2321               </dd>
 2322             </dl>
 2323           </div>
 2324         </div>
 2325       </div>
 2326 
 2327       <div class="preferences">
 2328         <div>
 2329           <div class="sectionTitle" id="section8-5-1-g">Fonts</div>
 2330         </div>
 2331 
 2332         <div>
 2333           <div id="cp-font">
 2334             <dl>
 2335               <dd class="wrap">
 2336                 These are the fonts that are used in RegexSearch&apos;s display.  Remember that
 2337                 font names may be platform-dependent, so that a configuration that specifies
 2338                 font names may not work across platforms.
 2339               </dd>
 2340               <dd class="spaceAbove wrap">
 2341                 The <i>main</i> font is used for various components including labels (static
 2342                 text), menus, buttons and list boxes.
 2343               </dd>
 2344               <dd class="spaceAbove wrap">
 2345                 The <i>text field</i> font is used for text fields, spinners and some other text
 2346                 components.
 2347               </dd>
 2348               <dd class="spaceAbove wrap">
 2349                 The <i>combo box</i> font is used for drop-down lists and related components.
 2350               </dd>
 2351               <dd class="spaceAbove wrap">
 2352                 The <i>parameter editor</i> font is used for the <a href="#section7-5-3"><span
 2353                 class="component">Target</span> and <span class="component">Replacement</span>
 2354                 fields</a>.
 2355               </dd>
 2356               <dd class="spaceAbove wrap">
 2357                 The <i>text view</i> and <i>result area</i> fonts are used for the respective
 2358                 text areas.
 2359               </dd>
 2360               <dd class="spaceAbove wrap">
 2361                 The default values of all the font properties are those of the default fonts for
 2362                 the platform and look-and-feel.  A default font size is specified by leaving the
 2363                 <span class="component">Size</span> field empty (the minimum position on the
 2364                 spinner).  A default font is used if no font name is specified in
 2365                 RegexSearch&apos;s configuration or if the named font is not available.
 2366               </dd>
 2367             </dl>
 2368           </div>
 2369         </div>
 2370       </div>
 2371 
 2372       <p class="wrap">
 2373         Some of the configuration properties will take effect when the <span
 2374         class="component">Preferences</span> dialog is accepted (by closing it with <i>OK</i>);
 2375         other properties (eg, the look-and-feel and fonts) will not take effect until the next
 2376         time that RegexSearch is run.
 2377       </p>
 2378       <p class="wrap">
 2379         The <a href="#section5-2">configuration file</a> is normally saved automatically when
 2380         RegexSearch exits, if the configuration has changed.  The <span class="command">Save
 2381         configuration</span> command in the <span class="component">Preferences</span> dialog
 2382         can be used to save a configuration file explicitly.
 2383       </p>
 2384 
 2385     </div>
 2386 
 2387     <!--=====================================================================================-->
 2388 
 2389     <!-- Regular expressions -->
 2390 
 2391     <div class="section">
 2392       <h2 id="section9">9&nbsp; Regular expressions</h2>
 2393       <p class="tocLink">
 2394         [ <a href="#toc">Table of contents</a> ]
 2395       </p>
 2396 
 2397       <p class="wrap">
 2398         Within RegexSearch, the parsing and matching of regular expressions is performed by the
 2399         Java regex engine.  The purpose of this section is to present a summary of the syntax of
 2400         Java&apos;s regular expressions, which is similar to that of Perl and Python.  This
 2401         section is not intended to be a tutorial on the use of regular expressions; see the <a
 2402         href="#section9-6">references</a> at the end of this section for suggested sources of
 2403         further information.
 2404       </p>
 2405       <p class="wrap">
 2406         <strong>Note:</strong> There are several differences between the syntax of regular
 2407         expressions in Java and the syntax of regular expressions in Linux/UNIX tools such as
 2408         <i>sed</i> and <i>(g)awk</i>.
 2409       </p>
 2410       <p class="wrap">
 2411         In a search, the target pattern, replacement pattern and file are all composed of
 2412         Unicode characters.  RegexSearch converts files from bytes to 16-bit Unicode characters
 2413         according to the scheme described in <a href="#section8-4-1-3">How files are
 2414         processed</a>.  In particular, the line separators CR and CR+LF are converted to LF
 2415         before a file is searched.  Thereafter, by default, the only line separator recognised
 2416         during a search is the line feed character (U+000A) unless the <code>(?-d)</code> flag
 2417         appears in the target pattern.
 2418       </p>
 2419       <p class="wrap">
 2420         When selected, the <span class="component">Ignore case</span> check box in the control
 2421         dialog enables the default form of case-insensitive matching, which applies only to
 2422         characters in the US-ASCII character encoding.  To apply case-insensitive matching to
 2423         all Unicode characters, use the <code>(?u)</code> flag in the target pattern.
 2424       </p>
 2425       <p class="wrap">
 2426         Within a regular expression, all characters are treated as literal characters except for
 2427         twelve <i>metacharacters</i> &mdash; characters that have a special meaning and
 2428         don&apos;t behave normally in regular expressions.  The metacharacters are:
 2429       </p>
 2430       <p class="shaded">
 2431         &nbsp;&nbsp;$&nbsp;(&nbsp;)&nbsp;*&nbsp;+&nbsp;.&nbsp;?&nbsp;[&nbsp;\&nbsp;^&nbsp;{&nbsp;|
 2432       </p>
 2433       <p class="wrap">
 2434         A metacharacter can be <i>escaped</i> &mdash; that is, its special meaning can be
 2435         removed &mdash; by prefixing a backslash, &apos;<code>\</code>&apos;, to it.  An escaped
 2436         metacharacter represents its corresponding literal character; thus,
 2437         &apos;<code>\?</code>&apos; represents the character &apos;<code>?</code>&apos;, and
 2438         &apos;<code>\\</code>&apos; represents a literal backslash.
 2439       </p>
 2440       <p class="wrap">
 2441         Some metacharacters are used by theselves within regular expressions; others are used to
 2442         create special sequences called <i>metasymbols</i>.  (In the documentation for
 2443         <code>java.util.regex.Pattern</code>, metasymbols are referred to as <i>constructs</i>.)
 2444         For example, several alphanumeric characters become metasymbols when preceded by a
 2445         backslash.
 2446       </p>
 2447 
 2448       <h3 id="section9-1">9.1&nbsp; Simple metacharacters and structural metasymbols</h3>
 2449 
 2450       <table class="regex">
 2451         <tr>
 2452           <td class="shaded">.</td>
 2453           <td class="wrap">
 2454             By default, a dot matches any single character except a newline.  The
 2455             <code>(?s)</code> flag enables a mode in which a dot matches any character
 2456             <em>including</em> a newline.
 2457           </td>
 2458         </tr>
 2459         <tr>
 2460           <td class="shaded">^</td>
 2461           <td>
 2462             <div class="wrap">
 2463               Matches the beginning of a line.
 2464             </div>
 2465             <div class="wrap">
 2466               Example: <code>^#</code> matches a &apos;<code>#</code>&apos; character at the
 2467               beginning of a line.
 2468             </div>
 2469           </td>
 2470         </tr>
 2471         <tr>
 2472           <td class="shaded">$</td>
 2473           <td>
 2474             <div class="wrap">
 2475               Matches the end of a line or the end of the input string (in RegexSearch, the end
 2476               of a file).
 2477             </div>
 2478             <div class="wrap">
 2479               Example: <code>;$</code> matches a &apos;<code>;</code>&apos; character at the end
 2480               of a line or at the end of a file.
 2481             </div>
 2482           </td>
 2483         </tr>
 2484         <tr>
 2485           <td class="shaded">\</td>
 2486           <td>
 2487             The backslash has two roles:
 2488             <ol class="noTopBottomMargin">
 2489               <li>
 2490                 <div class="wrap">
 2491                   When it precedes a metacharacter (including itself), it <i>escapes</i> the
 2492                   metacharacter (ie, removes the special meaning of the metacharacter).
 2493                 </div>
 2494                 <div class="wrap">
 2495                   Example: <code>\*</code> matches a &apos;<code>*</code>&apos; character.
 2496                 </div>
 2497               </li>
 2498               <li>
 2499                 <div class="wrap">
 2500                   When it precedes some alphanumeric characters, it introduces a metasymbol.
 2501                   (Placing a backslash in front of an alphabetic character for which no
 2502                   metasymbol is defined will result in an error.)
 2503                 </div>
 2504                 <div class="wrap">
 2505                   Example: <code>\t</code> matches a tab character (U+0009).
 2506                 </div>
 2507               </li>
 2508             </ol>
 2509           </td>
 2510         </tr>
 2511         <tr>
 2512           <td class="shaded">|</td>
 2513           <td>
 2514             <div class="wrap">
 2515               The vertical bar separates alternatives.
 2516             </div>
 2517             <div class="wrap">
 2518               Example: <code>his|her|its</code> matches any one of the strings &quot;his&quot;,
 2519               &quot;her&quot; or &quot;its&quot;.
 2520             </div>
 2521           </td>
 2522         </tr>
 2523         <tr>
 2524           <td class="shaded">[&nbsp;]</td>
 2525           <td>
 2526             Matches one character from a <i>character class</i> &mdash; a set
 2527             of characters enclosed within the square brackets.  The set of
 2528             characters can be specified in a number of ways.  It may be:
 2529             <ul class="noTopBottomMargin">
 2530               <li>
 2531                 <div class="wrap">
 2532                   An enumeration of characters.
 2533                 </div>
 2534                 <div class="wrap">
 2535                   Example: <code>[abc]</code>.
 2536                 </div>
 2537               </li>
 2538               <li>
 2539                 <div class="wrap">
 2540                   One or more ranges of characters, in which a hyphen,
 2541                   &apos;<code>-</code>&apos;, separates the inclusive start and end of a range
 2542                   of contiguous characters.
 2543                 </div>
 2544                 <div class="wrap">
 2545                   Example: <code>[a-z]</code>, or <code>[A-Za-z]</code>.
 2546                 </div>
 2547               </li>
 2548               <li>
 2549                 <div class="wrap">
 2550                   A union.
 2551                 </div>
 2552                 <div class="wrap">
 2553                   Example: <code>[0-9[A-F]]</code>, which is equivalent to
 2554                   <code>[0-9A-F]</code>.
 2555                 </div>
 2556               </li>
 2557               <li>
 2558                 <div class="wrap">
 2559                   An intersection, in which the string &quot;&amp;&amp;&quot; separates sets of
 2560                   characters.
 2561                 </div>
 2562                 <div class="wrap">
 2563                   Example: <code>[a-e&amp;&amp;d-h]</code>, which is equivalent to
 2564                   <code>[de]</code>).
 2565                 </div>
 2566               </li>
 2567             </ul>
 2568             <div class="wrap">
 2569               If the first character within the square brackets is a circumflex,
 2570               &apos;<code>^</code>&apos;, the set of characters is negated; that is, the
 2571               character class matches one character that is <em>not</em> in the set of
 2572               characters that follows the &apos;<code>^</code>&apos;.
 2573             </div>
 2574             <div class="wrap">
 2575               Example: <code>[^0-9]</code> matches any character except a (Western) decimal
 2576               digit; <code>[a-z&amp;&amp;[^ij]]</code> is equivalent to <code>[a-hk-z]</code>.
 2577             </div>
 2578           </td>
 2579         </tr>
 2580         <tr>
 2581           <td class="shaded">(&nbsp;)</td>
 2582           <td>
 2583             <div class="wrap">
 2584               Encloses a <i>capturing group</i>.  The set of characters within the parentheses
 2585               is treated as a unit; eg, <code>^(foo|bar)</code> matches either &quot;foo&quot;
 2586               or &quot;bar&quot; at the beginning of a line.  The group is called
 2587               <i>capturing</i> because the text that it matched can be included later in the
 2588               target pattern or in the replacement by specifying the index of the group in a
 2589               metasymbol (see <code>\<i>n</i></code> in <a href="#section9-3">Alphanumeric
 2590               metasymbols</a>).
 2591             </div>
 2592             <div class="wrap">
 2593               A <i>cluster</i> &mdash; a non-capturing group &mdash; can be specified by
 2594               enclosing a set of characters between &apos;<code>(?:</code>&apos; and
 2595               &apos;<code>)</code>&apos; (eg, <code>(?:foo|bar)</code> matches either
 2596               &quot;foo&quot; or &quot;bar&quot; without capturing it).
 2597             </div>
 2598           </td>
 2599         </tr>
 2600       </table>
 2601 
 2602       <h3 id="section9-2">9.2&nbsp; Quantifiers</h3>
 2603 
 2604       <p class="wrap">
 2605         Quantifiers specify how many times the preceding character or group should match.  The
 2606         different types of quantifier are available in three flavours, which Java refers to as
 2607         <i>greedy</i>, <i>reluctant</i> and <i>possessive</i>.  (Greedy quantifiers are also
 2608         known as <i>maximal</i>, and reluctant quantifiers are also known as <i>lazy</i> or
 2609         <i>minimal</i>.)
 2610       </p>
 2611       <p class="wrap">
 2612         A greedy (maximal) quantifier starts by matching as much as possible of the input
 2613         string.  If this doesn&apos;t allow the whole pattern to be matched, the greedy
 2614         quantifier matches progressively less of the input string until either the whole pattern
 2615         is matched or the match fails.
 2616       </p>
 2617       <p class="wrap">
 2618         A reluctant (minimal) quantifier starts by matching as little as possible of the input
 2619         string.  If this doesn&apos;t allow the whole pattern to be matched, the reluctant
 2620         quantifier matches progressively more of the input string until either the whole pattern
 2621         is matched or the match fails.
 2622       </p>
 2623       <p class="wrap">
 2624         A possessive quantifier starts, like a greedy quantifier, by matching as much as
 2625         possible of the input string.  However, if this doesn&apos;t allow the whole pattern to
 2626         be matched, no backing-up is performed, and the match fails.
 2627       </p>
 2628 
 2629       <table class="regex">
 2630         <tr>
 2631           <th class="alignCentre" colspan="3">
 2632             Quantifiers
 2633           </th>
 2634           <th rowspan="2">
 2635             Meaning
 2636           </th>
 2637         </tr>
 2638         <tr>
 2639           <th>Greedy</th>
 2640           <th>Reluctant</th>
 2641           <th>Possessive</th>
 2642         </tr>
 2643         <tr>
 2644           <td class="shaded">*</td>
 2645           <td class="shaded">*?</td>
 2646           <td class="shaded">*+</td>
 2647           <td>Matches zero or more times</td>
 2648         </tr>
 2649         <tr>
 2650           <td class="shaded">+</td>
 2651           <td class="shaded">+?</td>
 2652           <td class="shaded">++</td>
 2653           <td>Matches one or more times</td>
 2654         </tr>
 2655         <tr>
 2656           <td class="shaded">?</td>
 2657           <td class="shaded">??</td>
 2658           <td class="shaded">?+</td>
 2659           <td>Matches once or not at all</td>
 2660         </tr>
 2661         <tr>
 2662           <td class="shaded">{<i>n</i>}</td>
 2663           <td class="shaded">{<i>n</i>}?</td>
 2664           <td class="shaded">{<i>n</i>}+</td>
 2665           <td>Matches exactly <i>n</i> times</td>
 2666         </tr>
 2667         <tr>
 2668           <td class="shaded">{<i>n</i>,}</td>
 2669           <td class="shaded">{<i>n</i>,}?</td>
 2670           <td class="shaded">{<i>n</i>,}+</td>
 2671           <td>Matches at least <i>n</i> times</td>
 2672         </tr>
 2673         <tr>
 2674           <td class="shaded">{<i>n</i>,<i>m</i>}</td>
 2675           <td class="shaded">{<i>n</i>,<i>m</i>}?</td>
 2676           <td class="shaded">{<i>n</i>,<i>m</i>}+</td>
 2677           <td>Matches at least <i>n</i> times but not more than <i>m</i> times</td>
 2678         </tr>
 2679       </table>
 2680 
 2681       <h3 id="section9-3">9.3&nbsp; Alphanumeric metasymbols</h3>
 2682 
 2683       <table class="regex">
 2684         <tr>
 2685           <td class="shaded">\0<i>n</i></td>
 2686           <td>
 2687             The character with octal value 0<i>n</i>, where <i>n</i> is in [0-7]
 2688           </td>
 2689         </tr>
 2690         <tr>
 2691           <td class="shaded">\0<i>nn</i></td>
 2692           <td>
 2693             The character with octal value 0<i>nn</i>, where <i>n</i> is in [0-7]
 2694           </td>
 2695         </tr>
 2696         <tr>
 2697           <td class="shaded">\0<i>mnn</i></td>
 2698           <td class="wrap">
 2699             The character with octal value 0<i>mnn</i>, where <i>m</i> is in [0-3] and <i>n</i>
 2700             is in [0-7]
 2701           </td>
 2702         </tr>
 2703         <tr>
 2704           <td class="shaded">\<i>n</i></td>
 2705           <td>
 2706             The sequence matched by the <i>n</i>th capturing group
 2707           </td>
 2708         </tr>
 2709         <tr>
 2710           <td class="shaded">\a</td>
 2711           <td>
 2712             The alert character (BEL), U+0007
 2713           </td>
 2714         </tr>
 2715         <tr>
 2716           <td class="shaded">\A</td>
 2717           <td>
 2718             The beginning of the input string (in RegexSearch, the beginning of a file)
 2719           </td>
 2720         </tr>
 2721         <tr>
 2722           <td class="shaded">\b</td>
 2723           <td>
 2724             A word boundary
 2725           </td>
 2726         </tr>
 2727         <tr>
 2728           <td class="shaded">\B</td>
 2729           <td>
 2730             Not a word boundary
 2731           </td>
 2732         </tr>
 2733         <tr>
 2734           <td class="shaded">\c<i>X</i></td>
 2735           <td>
 2736             The control character, Control-<i>X</i>
 2737           </td>
 2738         </tr>
 2739         <tr>
 2740           <td class="shaded">\d</td>
 2741           <td>
 2742             A digit, [0-9]
 2743           </td>
 2744         </tr>
 2745         <tr>
 2746           <td class="shaded">\D</td>
 2747           <td>
 2748             A non-digit, [^0-9]
 2749           </td>
 2750         </tr>
 2751         <tr>
 2752           <td class="shaded">\e</td>
 2753           <td>
 2754             The escape character (ESC), U+001B
 2755           </td>
 2756         </tr>
 2757         <tr>
 2758           <td class="shaded">\E</td>
 2759           <td>
 2760             End the quotation of metacharacters started by \Q
 2761           </td>
 2762         </tr>
 2763         <tr>
 2764           <td class="shaded">\f</td>
 2765           <td>
 2766             The form feed character (FF), U+000C
 2767           </td>
 2768         </tr>
 2769         <tr>
 2770           <td class="shaded">\n</td>
 2771           <td>
 2772             The line feed character (LF), U+000A
 2773           </td>
 2774         </tr>
 2775         <tr>
 2776           <td class="shaded">\p{<i>prop</i>}</td>
 2777           <td>
 2778             Any character in the character class named <i>prop</i>
 2779           </td>
 2780         </tr>
 2781         <tr>
 2782           <td class="shaded">\P{<i>prop</i>}</td>
 2783           <td>
 2784             Any character not in the character class named <i>prop</i>
 2785           </td>
 2786         </tr>
 2787         <tr>
 2788           <td class="shaded">\Q</td>
 2789           <td>
 2790             Quote (escape) metacharacters until \E
 2791           </td>
 2792         </tr>
 2793         <tr>
 2794           <td class="shaded">\r</td>
 2795           <td>
 2796             The carriage return character (CR), U+000D
 2797           </td>
 2798         </tr>
 2799         <tr>
 2800           <td class="shaded">\s</td>
 2801           <td>
 2802             A whitespace character, [ \t\n\x0B\f\r]
 2803           </td>
 2804         </tr>
 2805         <tr>
 2806           <td class="shaded">\S</td>
 2807           <td>
 2808             A non-whitespace character, [^\s]
 2809           </td>
 2810         </tr>
 2811         <tr>
 2812           <td class="shaded">\t</td>
 2813           <td>
 2814             The tab character (HT), U+0009
 2815           </td>
 2816         </tr>
 2817         <tr>
 2818           <td class="shaded">\u<i>nnnn</i></td>
 2819           <td class="wrap">
 2820             The Unicode character U+<i>nnnn</i>, where <i>n</i> is a hexdecimal digit character,
 2821             [0-9A-Fa-f]
 2822           </td>
 2823         </tr>
 2824         <tr>
 2825           <td class="shaded">\w</td>
 2826           <td>
 2827             A word character, [0-9A-Za-z_]
 2828           </td>
 2829         </tr>
 2830         <tr>
 2831           <td class="shaded">\W</td>
 2832           <td>
 2833             A non-word character, [^\w]
 2834           </td>
 2835         </tr>
 2836         <tr>
 2837           <td class="shaded">\x<i>nn</i></td>
 2838           <td>
 2839             The character with hexdecimal value 0x<i>nn</i>
 2840           </td>
 2841         </tr>
 2842         <tr>
 2843           <td class="shaded">\z</td>
 2844           <td>
 2845             The end of the input string (in RegexSearch, the end of a file)
 2846           </td>
 2847         </tr>
 2848         <tr>
 2849           <td class="shaded">\Z</td>
 2850           <td class="wrap">
 2851             The end of the input string (in RegexSearch, the end of a file), apart from a final
 2852             &apos;\n&apos;
 2853           </td>
 2854         </tr>
 2855       </table>
 2856 
 2857       <h3 id="section9-4">9.4&nbsp; Named character classes</h3>
 2858 
 2859       <p class="wrap">
 2860         Named character classes are metasymbols of the form <code>\p{<i>name</i>}</code> or
 2861         <code>\P{<i>name</i>}</code>.  There are three types of named character class: POSIX,
 2862         Unicode and Java.
 2863       </p>
 2864 
 2865       <h4 id="section9-4-1">9.4.1&nbsp; POSIX character classes</h4>
 2866 
 2867       <table class="regex">
 2868         <tr>
 2869           <td class="shaded">Lower</td>
 2870           <td>
 2871             A lowercase alphabetic character, [a-z]
 2872           </td>
 2873         </tr>
 2874         <tr>
 2875           <td class="shaded">Upper</td>
 2876           <td>
 2877             An uppercase alphabetic character, [A-Z]
 2878           </td>
 2879         </tr>
 2880         <tr>
 2881           <td class="shaded">ASCII</td>
 2882           <td>
 2883             An ASCII character, [\x00-\x7F]
 2884           </td>
 2885         </tr>
 2886         <tr>
 2887           <td class="shaded">Alpha</td>
 2888           <td>
 2889             An alphabetic character, [\p{Lower}\p{Upper}]
 2890           </td>
 2891         </tr>
 2892         <tr>
 2893           <td class="shaded">Digit</td>
 2894           <td>
 2895             A decimal digit character, [0-9]
 2896           </td>
 2897         </tr>
 2898         <tr>
 2899           <td class="shaded">Alnum</td>
 2900           <td>
 2901             An alphanumeric character, [\p{Alpha}\p{Digit}]
 2902           </td>
 2903         </tr>
 2904         <tr>
 2905           <td class="shaded">Punct</td>
 2906           <td>
 2907             Punctuation: one of !&quot;#$%&amp;&apos;()*+,-./:;&lt;=&gt;?@[\]^_`{|}~
 2908           </td>
 2909         </tr>
 2910         <tr>
 2911           <td class="shaded">Graph</td>
 2912           <td>
 2913             A visible character, [\p{Alnum}\p{Punct}]
 2914           </td>
 2915         </tr>
 2916         <tr>
 2917           <td class="shaded">Print</td>
 2918           <td>
 2919             A printable character, [\p{Graph}\x20]
 2920           </td>
 2921         </tr>
 2922         <tr>
 2923           <td class="shaded">Blank</td>
 2924           <td>
 2925             A space or a tab character, [ \t]
 2926           </td>
 2927         </tr>
 2928         <tr>
 2929           <td class="shaded">Cntrl</td>
 2930           <td>
 2931             A control character, [\x00-\x1F\x7F]
 2932           </td>
 2933         </tr>
 2934         <tr>
 2935           <td class="shaded">XDigit</td>
 2936           <td>
 2937             A hexadecimal digit character [0-9a-fA-F]
 2938           </td>
 2939         </tr>
 2940         <tr>
 2941           <td class="shaded">Space</td>
 2942           <td>
 2943             A whitespace character, [ \t\n\x0B\f\r]
 2944           </td>
 2945         </tr>
 2946       </table>
 2947 
 2948       <h4 id="section9-4-2">9.4.2&nbsp; Unicode character classes</h4>
 2949 
 2950       <p class="wrap">
 2951         The Unicode character classes are too numerous to list all of them here.  They include
 2952         Unicode character blocks (eg, Greek) and character categories (eg, uppercase letters).
 2953         When forming a metasymbol, <code>In</code> is prefixed to the name of a Unicode block
 2954         (eg, <code>\p{InGreek}</code> ), and <code>Is</code> is optionally prefixed to the name
 2955         of a Unicode category is (eg, <code>\p{Lu}</code> or <code>\p{IsLu}</code> ).
 2956       </p>
 2957       <p class="wrap">
 2958         The following table lists abbreviations for values in the Unicode General Category:
 2959       </p>
 2960 
 2961       <table class="regex">
 2962         <tr>
 2963           <td class="shaded">L</td>
 2964           <td>
 2965             Letter
 2966           </td>
 2967         </tr>
 2968         <tr>
 2969           <td class="shaded">Lu</td>
 2970           <td>
 2971             Letter, uppercase
 2972           </td>
 2973         </tr>
 2974         <tr>
 2975           <td class="shaded">Ll</td>
 2976           <td>
 2977             Letter, lowercase
 2978           </td>
 2979         </tr>
 2980         <tr>
 2981           <td class="shaded">Lt</td>
 2982           <td>
 2983             Letter, titlecase
 2984           </td>
 2985         </tr>
 2986         <tr>
 2987           <td class="shaded">Lm</td>
 2988           <td>
 2989             Letter, modifier
 2990           </td>
 2991         </tr>
 2992         <tr>
 2993           <td class="shaded">Lo</td>
 2994           <td>
 2995             Letter, other
 2996           </td>
 2997         </tr>
 2998         <tr>
 2999           <td class="shaded">M</td>
 3000           <td>
 3001             Mark
 3002           </td>
 3003         </tr>
 3004         <tr>
 3005           <td class="shaded">Mn</td>
 3006           <td>
 3007             Mark, non-spacing
 3008           </td>
 3009         </tr>
 3010         <tr>
 3011           <td class="shaded">Mc</td>
 3012           <td>
 3013             Mark, spacing combining
 3014           </td>
 3015         </tr>
 3016         <tr>
 3017           <td class="shaded">Me</td>
 3018           <td>
 3019             Mark, enclosing
 3020           </td>
 3021         </tr>
 3022         <tr>
 3023           <td class="shaded">N</td>
 3024           <td>
 3025             Number
 3026           </td>
 3027         </tr>
 3028         <tr>
 3029           <td class="shaded">Nd</td>
 3030           <td>
 3031             Number, decimal digit
 3032           </td>
 3033         </tr>
 3034         <tr>
 3035           <td class="shaded">Nl</td>
 3036           <td>
 3037             Number, letter
 3038           </td>
 3039         </tr>
 3040         <tr>
 3041           <td class="shaded">No</td>
 3042           <td>
 3043             Number, other
 3044           </td>
 3045         </tr>
 3046         <tr>
 3047           <td class="shaded">P</td>
 3048           <td>
 3049             Punctuation
 3050           </td>
 3051         </tr>
 3052         <tr>
 3053           <td class="shaded">Pc</td>
 3054           <td>
 3055             Punctuation, connector
 3056           </td>
 3057         </tr>
 3058         <tr>
 3059           <td class="shaded">Pd</td>
 3060           <td>
 3061             Punctuation, dash
 3062           </td>
 3063         </tr>
 3064         <tr>
 3065           <td class="shaded">Ps</td>
 3066           <td>
 3067             Punctuation, open
 3068           </td>
 3069         </tr>
 3070         <tr>
 3071           <td class="shaded">Pe</td>
 3072           <td>
 3073             Punctuation, close
 3074           </td>
 3075         </tr>
 3076         <tr>
 3077           <td class="shaded">Pi</td>
 3078           <td class="wrap">
 3079             Punctuation, initial quote (may behave like <code>Ps</code> or <code>Pe</code>
 3080             depending on usage)
 3081           </td>
 3082         </tr>
 3083         <tr>
 3084           <td class="shaded">Pf</td>
 3085           <td class="wrap">
 3086             Punctuation, final quote (may behave like <code>Ps</code> or <code>Pe</code>
 3087             depending on usage)
 3088           </td>
 3089         </tr>
 3090         <tr>
 3091           <td class="shaded">Po</td>
 3092           <td>
 3093             Punctuation, other
 3094           </td>
 3095         </tr>
 3096         <tr>
 3097           <td class="shaded">S</td>
 3098           <td>
 3099             Symbol
 3100           </td>
 3101         </tr>
 3102         <tr>
 3103           <td class="shaded">Sm</td>
 3104           <td>
 3105             Symbol, mathematical
 3106           </td>
 3107         </tr>
 3108         <tr>
 3109           <td class="shaded">Sc</td>
 3110           <td>
 3111             Symbol, currency
 3112           </td>
 3113         </tr>
 3114         <tr>
 3115           <td class="shaded">Sk</td>
 3116           <td>
 3117             Symbol, modifier
 3118           </td>
 3119         </tr>
 3120         <tr>
 3121           <td class="shaded">So</td>
 3122           <td>
 3123             Symbol, other
 3124           </td>
 3125         </tr>
 3126         <tr>
 3127           <td class="shaded">Z</td>
 3128           <td>
 3129             Separator
 3130           </td>
 3131         </tr>
 3132         <tr>
 3133           <td class="shaded">Zs</td>
 3134           <td>
 3135             Separator, space
 3136           </td>
 3137         </tr>
 3138         <tr>
 3139           <td class="shaded">Zl</td>
 3140           <td>
 3141             Separator, line
 3142           </td>
 3143         </tr>
 3144         <tr>
 3145           <td class="shaded">Zp</td>
 3146           <td>
 3147             Separator, paragraph
 3148           </td>
 3149         </tr>
 3150         <tr>
 3151           <td class="shaded">Cc</td>
 3152           <td>
 3153             Other, control
 3154           </td>
 3155         </tr>
 3156         <tr>
 3157           <td class="shaded">Cf</td>
 3158           <td>
 3159             Other, format
 3160           </td>
 3161         </tr>
 3162         <tr>
 3163           <td class="shaded">Cs</td>
 3164           <td>
 3165             Other, surrogate
 3166           </td>
 3167         </tr>
 3168         <tr>
 3169           <td class="shaded">Co</td>
 3170           <td>
 3171             Other, private use
 3172           </td>
 3173         </tr>
 3174         <tr>
 3175           <td class="shaded">Cn</td>
 3176           <td class="wrap">
 3177             Other, not assigned
 3178           </td>
 3179         </tr>
 3180       </table>
 3181 
 3182       <h4 id="section9-4-3">9.4.3&nbsp; Java character classes</h4>
 3183 
 3184       <p class="wrap">
 3185         The Java character classes will probably be of interest only to Java programmers.  The
 3186         name of the character class is formed by substituting &apos;<code>java</code>&apos; for
 3187         &apos;<code>is</code>&apos; in the name of a method of the <code><a class="external"
 3188         href="https://docs.oracle.com/javase/7/docs/api/java/lang/Character.html">java.lang.Character</a></code>
 3189         class that begins with &apos;<code>is</code>&apos;. For example, the character class
 3190         <code>javaLetterOrDigit</code> is equivalent to
 3191         <code>java.lang.Character.isLetterOrDigit()</code>.
 3192       </p>
 3193 
 3194       <h3 id="section9-5">9.5&nbsp; Extended sequences</h3>
 3195 
 3196       <p class="wrap">
 3197         Extended sequences are metasymbols of the form <code>(?...)</code>.  The modifiers,
 3198         <code>[dimsux]</code>, and their &quot;off&quot; versions (preceded by a minus sign) can
 3199         be concatenated within an extended sequence; for example, <code>(?iu-ms)</code> switches
 3200         on <code>i</code> and <code>u</code> and switches off <code>m</code> and <code>s</code>.
 3201       </p>
 3202 
 3203       <table class="regex">
 3204         <tr>
 3205           <td class="shaded">(?:&hellip;)</td>
 3206           <td>
 3207             Non-capturing group (<i>cluster</i>).
 3208           </td>
 3209         </tr>
 3210         <tr>
 3211           <td class="shaded">(?&gt;&hellip;)</td>
 3212           <td class="wrap">
 3213             Non-capturing group referred to in Perl as a <i>nonbacktracking subpattern</i>.
 3214           </td>
 3215         </tr>
 3216         <tr>
 3217           <td class="shaded"><div>(?d)</div><div>(?-d)</div></td>
 3218           <td>
 3219             <div class="wrap">
 3220               Enable/disable UNIX lines mode.
 3221             </div>
 3222             <div class="wrap">
 3223               If enabled, only the UNIX line separator (&apos;\n&apos;, U+000A) is recognised by
 3224               the metacharacters <code>.</code>, <code>^</code> and <code>$</code>; otherwise,
 3225               the following characters and character sequences are recognised as line
 3226               separators: &apos;\n&apos; (U+000A), &apos;\r&apos; (U+000D), &apos;\r\n&apos;
 3227               (U+000D, U+000A), U+0085, U+2028, U+2029.
 3228             </div>
 3229             <div class="wrap">
 3230               UNIX linesmode is enabled by default.
 3231             </div>
 3232           </td>
 3233         </tr>
 3234         <tr>
 3235           <td class="shaded"><div>(?i)</div><div>(?-i)</div></td>
 3236           <td>
 3237             <div class="wrap">
 3238               Enable/disable case-insensitive matching.
 3239             </div>
 3240             <div class="wrap">
 3241               Case sensitivity is initially denoted by the <i>ignore case</i> search parameter,
 3242               but it can be changed within the target pattern by means of this flag.  By
 3243               default, case-insensitive matching applies only to characters in the US-ASCII
 3244               character encoding, but this can be extended to all Unicode characters with the
 3245               <code>(?u)</code> flag.
 3246             </div>
 3247           </td>
 3248         </tr>
 3249         <tr>
 3250           <td class="shaded"><div>(?m)</div><div>(?-m)</div></td>
 3251           <td>
 3252             <div class="wrap">
 3253               Enable/disable multiline mode.
 3254             </div>
 3255             <div class="wrap">
 3256               In multiline mode, the metacharacters <code>^</code> and <code>$</code> match at
 3257               the beginning and end, respectively, of a line; otherwise, they match only at the
 3258               beginning and end of the input string (ie, the file).
 3259             </div>
 3260             <div class="wrap">
 3261               Multiline mode is enabled by default.
 3262             </div>
 3263           </td>
 3264         </tr>
 3265         <tr>
 3266           <td class="shaded"><div>(?s)</div><div>(?-s)</div></td>
 3267           <td>
 3268             <div class="wrap">
 3269               Enable/disable dotall mode.
 3270             </div>
 3271             <div class="wrap">
 3272               In dotall mode (known in Perl as <i>single-line mode</i>), the <code>.</code>
 3273               (dot) metacharacter matches any one character <i>including</i> a line separator;
 3274               otherwise, <code>.</code> matches any one character <i>except for</i> a line
 3275               separator.
 3276             </div>
 3277           </td>
 3278         </tr>
 3279         <tr>
 3280           <td class="shaded"><div>(?u)</div><div>(?-u)</div></td>
 3281           <td class="wrap">
 3282             By default, the case-insensitive matching that is control by the <i>ignore case</i>
 3283             search parameters and the <code>(?i)</code> flag applies only to characters in the
 3284             US-ASCII character encoding.  Using the <code>(?u)</code> flag, case-insensitive
 3285             matching can be extended to all Unicode characters.
 3286           </td>
 3287         </tr>
 3288         <tr>
 3289           <td class="shaded"><div>(?x)</div><div>(?-x)</div></td>
 3290           <td>
 3291             <div class="wrap">
 3292               Enable/disable comments mode.
 3293             </div>
 3294             <div class="wrap">
 3295               In comments mode, whitespace and comments in the target pattern are ignored.  A
 3296               comment starts with a &apos;<code>#</code>&apos; character and ends at the end of
 3297               the pattern.
 3298             </div>
 3299           </td>
 3300         </tr>
 3301         <tr>
 3302           <td class="shaded">(?=<i>pattern</i>)</td>
 3303           <td class="wrap">
 3304             Positive lookahead: a zero-width assertion that is true if <i>pattern</i>
 3305             immediately follows the assertion.
 3306           </td>
 3307         </tr>
 3308         <tr>
 3309           <td class="shaded">(?!<i>pattern</i>)</td>
 3310           <td class="wrap">
 3311             Negative lookahead: a zero-width assertion that is true if <i>pattern</i> does not
 3312             immediately follow the assertion.
 3313           </td>
 3314         </tr>
 3315         <tr>
 3316           <td class="shaded">(?&lt;=<i>pattern</i>)</td>
 3317           <td class="wrap">
 3318             Positive lookbehind: a zero-width assertion that is true if <i>pattern</i>
 3319             immediately precedes the assertion.
 3320           </td>
 3321         </tr>
 3322         <tr>
 3323           <td class="shaded">(?&lt;!<i>pattern</i>)</td>
 3324           <td class="wrap">
 3325             Negative lookbehind: a zero-width assertion that is true if <i>pattern</i> does not
 3326             immediately precede the assertion.
 3327           </td>
 3328         </tr>
 3329       </table>
 3330 
 3331       <h3 id="section9-6">9.6&nbsp; References</h3>
 3332 
 3333       <p class="wrap">
 3334         The following sources were used in writing this section:
 3335       </p>
 3336       <ul class="list">
 3337         <li class="wrap">
 3338           The Java documentation of the <code><a class="external"
 3339           href="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">java.util.regex.Pattern</a></code>
 3340           class.
 3341         </li>
 3342         <li class="wrap">
 3343           The section in the <a class="external"
 3344           href="https://docs.oracle.com/javase/tutorial/essential/regex/index.html">Java
 3345           Tutorial</a> on the use of regular expressions.
 3346         </li>
 3347         <li class="wrap">
 3348           Wall, Larry, et al, <i>Programming Perl</i> 3rd ed., O&apos;Reilly, 2000.  ISBN
 3349           0596000278.
 3350         </li>
 3351       </ul>
 3352       <p class="noBottomMargin wrap">
 3353         The Java documentation recommends the following book as providing a detailed treatment
 3354         of the use of regular expressions:
 3355       </p>
 3356       <p class="noTopMargin wrap">
 3357         &nbsp;&nbsp;Friedl, Jeffrey, <i>Mastering regular expressions</i> 3rd ed.,
 3358         O&apos;Reilly, 2006.  ISBN 0596528124.
 3359       </p>
 3360 
 3361     </div>
 3362 
 3363     <!--=====================================================================================-->
 3364 
 3365     <!-- Special constructs in pathnames -->
 3366 
 3367     <div class="section">
 3368       <h2 id="sectionA">Appendix A:&nbsp; Special constructs in pathnames</h2>
 3369       <p class="tocLink">
 3370         [ <a href="#toc">Table of contents</a> ]
 3371       </p>
 3372 
 3373       <p class="wrap">
 3374         Where indicated elsewhere in this document, pathname parameters and properties in
 3375         RegexSearch can contain special constructs for system properties, environment variables
 3376         and the user&apos;s home directory.  The special constructs are expanded when the
 3377         pathname is used.
 3378       </p>
 3379 
 3380       <dl class="basic">
 3381         <dt>System properties and environment variables</dt>
 3382         <dd class="wrap">
 3383           Java system properties (eg, the user&apos;s home directory, <code>user.home</code>)
 3384           and environment variables (eg, <code>PATH</code>) are referenced by enclosing them
 3385           between &apos;<code>${</code>&apos; and &apos;<code>}</code>&apos;; that is, they must
 3386           have the form <code>${&lt;<i>name</i>&gt;}</code>.  A Java system property takes
 3387           precedence over an environment variable with the same name.
 3388         </dd>
 3389         <dd class="wrap">
 3390           &bull; Example: <code>${user.home}/projects</code>
 3391         </dd>
 3392         <dd class="wrap">
 3393           &bull; Example: <code>${HOME}/projects</code>
 3394         </dd>
 3395         <dd class="wrap">
 3396           A Java system property can be specified by prefixing <code>sys.</code> to it.
 3397         </dd>
 3398         <dd class="wrap">
 3399           &bull; Example: <code>${sys.user.home}/projects</code>
 3400         </dd>
 3401         <dd class="wrap">
 3402           An environment variable can be specified by prefixing <code>env.</code> to it.
 3403         </dd>
 3404         <dd class="wrap">
 3405           &bull; Example: <code>${env.HOME}/projects</code>
 3406         </dd>
 3407 
 3408         <dt>User&apos;s home directory</dt>
 3409         <dd class="wrap">
 3410           A leading &apos;<code>~</code>&apos; in a pathname is expanded into the user&apos;s
 3411           home directory using the <code>user.home</code> system property, which is usually
 3412           equivalent to the environment variable <code>$HOME</code> on Linux/UNIX systems or
 3413           <code>%USERPROFILE%</code> on Windows systems.
 3414         </dd>
 3415         <dd class="wrap">
 3416           &bull; Example: <code>~/projects</code>
 3417         </dd>
 3418       </dl>
 3419 
 3420     </div>
 3421 
 3422     <!--=====================================================================================-->
 3423 
 3424     <!-- Configuration properties -->
 3425 
 3426     <div class="section">
 3427       <h2 id="sectionB">Appendix B:&nbsp; Configuration properties</h2>
 3428       <p class="tocLink">
 3429         [ <a href="#toc">Table of contents</a> ]
 3430       </p>
 3431 
 3432       <p class="wrap">
 3433         The table below lists the configuration properties of RegexSearch.  Apart from the <span
 3434         class="configProperty">app.configDir</span> property, which, for obvious reasons, cannot
 3435         be used within a configuration file, all properties can be used in the two configuration
 3436         locations: command-line properties and configuration file.
 3437       </p>
 3438       <p class="wrap">
 3439         When used in a <code>-D</code> command-line property, <code>app.</code> must be prefixed
 3440         to the property key (eg, <span
 3441         class="configProperty">app.general.mainWindowLocation</span>).
 3442       </p>
 3443       <p class="wrap">
 3444         The <i>&lt;index&gt;</i> of a indexed property must be a three-digit decimal-string
 3445         representation of the zero-based index of the property (eg, the third tab-width filter
 3446         would be <span class="configProperty">app.tabWidth.fileFilter.002</span>).
 3447       </p>
 3448       <p class="wrap">
 3449         When used in a configuration file, the components of the property keys become element
 3450         names in the XML document hierarchy.  (The <code>app</code> prefix of the property key
 3451         in command-line properties corresponds to the root element of the XML document.)  The
 3452         form of properties in a configuration file was changed in version 2.1 of RegexSearch.
 3453         Configuration files in the old format can be read, but files are written in the new
 3454         format.
 3455       </p>
 3456       <p class="wrap">
 3457         Any commas (&apos;<code>,</code>&apos;) or backslash characters
 3458         (&apos;<code>\</code>&apos;) in the name of a font must be escaped by prefixing a
 3459         &apos;<code>\</code>&apos; character to them.
 3460       </p>
 3461       <p class="noBottomMargin wrap">
 3462         In the table below, the initial character of an italicised component of a property value
 3463         denotes its data type according to the following convention:
 3464       </p>
 3465 
 3466       <table class="dataType">
 3467         <tr>
 3468           <td><i>i</i></td>
 3469           <td>integer</td>
 3470         </tr>
 3471         <tr>
 3472           <td><i>p</i></td>
 3473           <td>
 3474             platform-specific pathname, which may contain <a href="#sectionA">special
 3475             constructs</a>
 3476           </td>
 3477         </tr>
 3478         <tr>
 3479           <td><i>s</i></td>
 3480           <td>string</td>
 3481         </tr>
 3482         <tr>
 3483           <td><i>c</i></td>
 3484           <td>character</td>
 3485         </tr>
 3486       </table>
 3487 
 3488       <table class="configProperties">
 3489         <tr>
 3490           <th>Property key</th>
 3491           <th>Property value</th>
 3492         </tr>
 3493 
 3494         <tr>
 3495           <td>configDir</td>
 3496           <td class="paramValue"><i>pPathname</i></td>
 3497         </tr>
 3498 
 3499         <tr>
 3500           <td>appearance.lookAndFeel</td>
 3501           <td class="paramValue"><i>sName</i></td>
 3502         </tr>
 3503         <tr>
 3504           <td>appearance.parameterEditorSize</td>
 3505           <td class="paramValue">
 3506             <i>iNumColumns</i>, <i>iNumRows</i>
 3507           </td>
 3508         </tr>
 3509         <tr>
 3510           <td>appearance.resultAreaNumRows</td>
 3511           <td class="paramValue"><i>iNumRows</i></td>
 3512         </tr>
 3513         <tr>
 3514           <td>appearance.tabSurrogate</td>
 3515           <td class="paramValue"><i>sUnicode4</i></td>
 3516         </tr>
 3517         <tr>
 3518           <td>appearance.textAntialiasing</td>
 3519           <td class="paramValue">
 3520             default | none | normal | subpixelHRgb | subpixelHBgr | subpixelVRgb | subpixelVBgr
 3521           </td>
 3522         </tr>
 3523         <tr>
 3524           <td>appearance.textAreaColour.background</td>
 3525           <td class="paramValue">
 3526             <i>iRed</i>, <i>iGreen</i>, <i>iBlue</i>
 3527           </td>
 3528         </tr>
 3529         <tr>
 3530           <td>appearance.textAreaColour.highlightBackground</td>
 3531           <td class="paramValue">
 3532             <i>iRed</i>, <i>iGreen</i>, <i>iBlue</i>
 3533           </td>
 3534         </tr>
 3535         <tr>
 3536           <td>appearance.textAreaColour.highlightText</td>
 3537           <td class="paramValue">
 3538             <i>iRed</i>, <i>iGreen</i>, <i>iBlue</i>
 3539           </td>
 3540         </tr>
 3541         <tr>
 3542           <td>appearance.textAreaColour.text</td>
 3543           <td class="paramValue">
 3544             <i>iRed</i>, <i>iGreen</i>, <i>iBlue</i>
 3545           </td>
 3546         </tr>
 3547         <tr>
 3548           <td>appearance.textViewMaxNumColumns</td>
 3549           <td class="paramValue"><i>iNumColumns</i></td>
 3550         </tr>
 3551         <tr>
 3552           <td>appearance.textViewTextAntialiasing</td>
 3553           <td class="paramValue">
 3554             default | none | normal | subpixelHRgb | subpixelHBgr | subpixelVRgb | subpixelVBgr
 3555           </td>
 3556         </tr>
 3557         <tr>
 3558           <td>appearance.textViewViewableSize</td>
 3559           <td class="paramValue">
 3560             <i>iNumColumns</i>, <i>iNumRows</i>
 3561           </td>
 3562         </tr>
 3563 
 3564         <tr>
 3565           <td>editor.command</td>
 3566           <td class="paramValue"><i>sCommand</i></td>
 3567         </tr>
 3568 
 3569         <tr>
 3570           <td>font.comboBox</td>
 3571           <td class="paramValue">
 3572             <i>sName</i>, plain | bold | italic | boldItalic, <i>iSize</i>
 3573           </td>
 3574         </tr>
 3575         <tr>
 3576           <td>font.main</td>
 3577           <td class="paramValue">
 3578             <i>sName</i>, plain | bold | italic | boldItalic, <i>iSize</i>
 3579           </td>
 3580         </tr>
 3581         <tr>
 3582           <td>font.parameterEditor</td>
 3583           <td class="paramValue">
 3584             <i>sName</i>, plain | bold | italic | boldItalic, <i>iSize</i>
 3585           </td>
 3586         </tr>
 3587         <tr>
 3588           <td>font.resultArea</td>
 3589           <td class="paramValue">
 3590             <i>sName</i>, plain | bold | italic | boldItalic, <i>iSize</i>
 3591           </td>
 3592         </tr>
 3593         <tr>
 3594           <td>font.textField</td>
 3595           <td class="paramValue">
 3596             <i>sName</i>, plain | bold | italic | boldItalic, <i>iSize</i>
 3597           </td>
 3598         </tr>
 3599         <tr>
 3600           <td>font.textView</td>
 3601           <td class="paramValue">
 3602             <i>sName</i>, plain | bold | italic | boldItalic, <i>iSize</i>
 3603           </td>
 3604         </tr>
 3605 
 3606         <tr>
 3607           <td>general.characterEncoding</td>
 3608           <td class="paramValue"><i>sName</i></td>
 3609         </tr>
 3610         <tr>
 3611           <td>general.controlDialogLocation</td>
 3612           <td class="paramValue">
 3613             <i>iX</i>, <i>iY</i>
 3614           </td>
 3615         </tr>
 3616         <tr>
 3617           <td>general.copyResultsAsListFile</td>
 3618           <td class="paramValue">false | true</td>
 3619         </tr>
 3620         <tr>
 3621           <td>general.escapedMetacharacters</td>
 3622           <td class="paramValue"><i>sCharacters</i></td>
 3623         </tr>
 3624         <tr>
 3625           <td>general.ignoreFilenameCase</td>
 3626           <td class="paramValue">false | true</td>
 3627         </tr>
 3628         <tr>
 3629           <td>general.fileWritingMode</td>
 3630           <td class="paramValue">direct | useTempFile | useTempFilePreserveAttributes</td>
 3631         </tr>
 3632         <tr>
 3633           <td>general.hideControlDialogWhenSearching</td>
 3634           <td class="paramValue">false | true</td>
 3635         </tr>
 3636         <tr>
 3637           <td>general.mainWindowLocation</td>
 3638           <td class="paramValue">
 3639             <i>iX</i>, <i>iY</i>
 3640           </td>
 3641         </tr>
 3642         <tr>
 3643           <td>general.preserveLineSeparator</td>
 3644           <td class="paramValue">false | true</td>
 3645         </tr>
 3646         <tr>
 3647           <td>general.replacementEscapeCharacter</td>
 3648           <td class="paramValue"><i>cCharacter</i></td>
 3649         </tr>
 3650         <tr>
 3651           <td>general.selectTextOnFocusGained</td>
 3652           <td class="paramValue">false | true</td>
 3653         </tr>
 3654         <tr>
 3655           <td>general.showUnixPathnames</td>
 3656           <td class="paramValue">false | true</td>
 3657         </tr>
 3658 
 3659         <tr>
 3660           <td>path.defaultSearchParameters</td>
 3661           <td class="paramValue"><i>pPathname</i></td>
 3662         </tr>
 3663 
 3664         <tr>
 3665           <td>tabWidth.default</td>
 3666           <td class="paramValue"><i>iNumChars</i></td>
 3667         </tr>
 3668         <tr>
 3669           <td>tabWidth.fileFilter.<i>&lt;index&gt;</i></td>
 3670           <td class="paramValue">
 3671             <i>sPatterns</i> : <i>iNumChars</i>
 3672           </td>
 3673         </tr>
 3674         <tr>
 3675           <td>tabWidth.targetAndReplacement</td>
 3676           <td class="paramValue"><i>iNumChars</i></td>
 3677         </tr>
 3678 
 3679       </table>
 3680 
 3681     </div>
 3682 
 3683     <!--=====================================================================================-->
 3684 
 3685     <!-- Providing feedback about RegexSearch -->
 3686 
 3687     <div class="section">
 3688       <h2 id="sectionC">Appendix C:&nbsp; Providing feedback about RegexSearch</h2>
 3689       <p class="tocLink">
 3690         [ <a href="#toc">Table of contents</a> ]
 3691       </p>
 3692 
 3693       <p class="wrap">
 3694         The RegexSearch project is hosted by <a class="external"
 3695         href="https://sourceforge.net/">SourceForge</a>.  You can submit bug reports and
 3696         suggestions for improvements through the SourceForge website.  For current information
 3697         on how to do so, please see the <a class="external"
 3698         href="http://blankaspect.users.sourceforge.net/feedback.html">feedback page</a> for
 3699         Blank Aspect projects.
 3700       </p>
 3701       <p class="wrap">
 3702         When reporting a problem with RegexSearch, please try to include enough relevant
 3703         information to enable the problem to be reproduced.  You should include at least the
 3704         following information:
 3705       </p>
 3706       <ul class="list">
 3707         <li>the version number of RegexSearch,</li>
 3708         <li>the name and version number of the operating system,</li>
 3709         <li>the name and version number of the Java runtime environment,</li>
 3710         <li>a description of the problem.</li>
 3711       </ul>
 3712       <p class="wrap">
 3713         A Java stack trace, if one is available, would be helpful.
 3714       </p>
 3715 
 3716     </div>
 3717 
 3718     <!--=====================================================================================-->
 3719 
 3720     <!-- Footer -->
 3721 
 3722     <div id="lastModified">
 3723       <div>
 3724         <div>
 3725           Last modified: 2020-12-27
 3726         </div>
 3727         <div class="image">
 3728           <a class="hideHover" href="http://validator.w3.org/check?uri=referer">
 3729             <img alt="XHTML 1.1" src="images/valid-xhtml11.png"/>
 3730           </a>
 3731         </div>
 3732       </div>
 3733     </div>
 3734 
 3735   </body>
 3736 </html>