Using TXT_FIND in a form || Using TXT_FIND in <ISINDEX> searchable indices

### Searching files using TXT_Find

TXT_Find looks for "search strings" within "paragraphs", and uses "meta commands" and "target specific" instructions to structure the search.

By default, a paragraph is defined as being all text between blank lines. Alternatively, one can define paragraphs as single lines, or as delimited by any arbitrary character sequence.

A search string is comprised of "targets" There are two kinds of targets: `subwords` and `phrases.`
Each space delimited entry in the search string is treated as a seperate `subword`, except..
for `phrases`, which are delimited by parenthesis; for example: (xx yy zz)
.... and phrases must be matched precisely.

### Search algorithims.

TXT_Find has two modes: SIMPLE and LOGICAL.

##### Simple mode with highlighting.

     Two meta-commands and 4 "target specific"  instructions are recognized.
            Meta-commands are signified by  *&  or *\ at the beginning
            of the search string.
                 *&   means "find paragraphs that match ALL targets in
                    the search string"
                 *\  means "find paragraphs that match NONE of the targets in
                     the search string"
         If there are no meta-commands, the following target specific
         commands are recognized.
              &   means "paragraphs MUST have this target"
              |   means "accept paragraph if it has this target"
                  Note that | is the default (assumed if no target specific
                  command entered).
              \ means "paragraph must NOT have this target"
              % means "accept paragraph if it does NOT have this target"

        Summarizing: to be a "found" paragraph:
          Test 1a) Any (of several) | targets must be present,    or
               1b) All of the % targets must be missing
             If pass test 1a and 1b, then
               2a) None of the \ can be present, and
               2b) All of the & must be present
         If present, all & and | targets will be highlighted.
         Note that if there are no % targets specified, test 1b is ignored.

##### Logical expression mode without highlighting

The user enters REXX-like logical expression using the following operators:
- & : AND operator
- | : OR operator
- \ : NOT operator
- @ : XOR operator
- ( ) : to group expressions.

> A sequence of words without any operators is treated as a phrase -- to treat each word as a seperate subword, put ( ) around each one. Basically, when using this mode, be liberal in your use of ( ).

### TXT_Find Options

TXT_Find supports a number of options. These options are easily set in DOSEARH.HTM, or by modifying the ALIASE(es) that invoke TXT_Find.

Technically speaking, the options appear in an option list, with each option seperated by an & character.....

- if the GET method was used, the option list is placed after a ? character in the request selector .
- If the POST methed was used, the option list is placed in the body of the request.

The option list should have the structure:
option_name=option_value&option_Nam2=option_value2&...

The TXT_Find options are:

           DELIM : The paragraph delimiter.
                       " "  or 0 = blank lines   (the default)
                       "$"      = Each line is a paragraph
                       other     = User specified delimiter
           LINE  : Maximum number of lines to display of each "found" paragraph.
                     If 0, no lines displayed (a summary will be displayed)
                     Default is to display all lines.
           NUM   : 1=Display the line or paragraph number,
                   0=Don't (default=YES)
           BAR   : 1= Seperate each paragraph/line by a horizontal bar,
                   0=Don't (default=YES)
           EXPERT: 1= Use "logical expression mode",
                   0=Use simple mode (Default=NO)
           FILE  :  FILE=filename
                    A selector pointing to the file(s) to search (either relative
                    to the data directory, or in a virtual directory).  You can
                    include as many FILE options as desired (each entry will be
                    searched in turn).
                    Furthermore, * and ? wildcards can be used.
                    However, the ~ replacement is not attempted.
           SEARCH: The search string
           CASE  : If 1, then search is case sensitive (default is NO)
          HIGHLIGHT: If 1, then underline matches (the default). If 0, do not
                     underline matches.

#### Examples

##### Simple mode examples

`( The best car)`
  Finds paragraphs containing the phrase `the best car`
`car truck motorcycle`
  Finds paragraphs that contain one (or more) of `car, truck` or `motorcycle`
`dog cat & store (pet pig)`
  Finds paragraphs that contain one (or more) of `dog, cat` or the phrase `pet pig`; and that also contain `store`
`*& computer price memory`
  Finds paragraphs that contain `computer, price`, and `memory` (must have all of them, but can be in any order)

##### Logical mode examples

`The best car`
  Finds paragraphs containing the phrase `the best car`
`car | truck | motorcycle`
  Finds paragraphs that contain one (or more) of `car, truck` or `motorcycle`
`( (dog & cat) | (pet pig) ) & stores`
  Finds paragraphs that contain `stores`, and that contain either both `dog` and `cat`, or the phrase `pet pig`

### Using TXT_Find.CMD

The TxtFind2.HTM HTML document uses a form to invoke TXT_Find -- you can use it to search any file on this site (to which you have access privileges). It also provides an easy means for setting a number of TXT_Find options.

If you are familiar with HTML FORMS, you can customize (and rename) TxtFind2.HTM. In particular, to facilitate searches (say, of a specific document) many of the FORM elements can be set to be "hidden".

Lastly, as demonstrated by CONGRESS.HTM, you can use TXT_Find (in combination with an appropriate realm-definition, in your ATTRIBS.CFG file) to implement an ISINDEX type of searchable index.