findme  -  Search for documents by keyword and display a list of those found

Description:

This command performs keyword searching of locally available (or locally catalogued) documents and displays a list of those found using a WWW browser. This list includes hyper-links to the parts of each document that were matched.

Invocation:

findme [switches] [keyword] [doclist]

Parameters

keyword

The string of characters to be searched for. This is treated as a single string (not as multiple keywords) and should be quoted if it contains special characters or white space. Pattern matching characters, as used in "sed" or "grep" regular expressions, may be included.

If this parameter is omitted, then all documents searched will be matched. This provides a convenient way of listing all the documents available.

doclist

An optional space-separated list of the documents to be searched. If this is omitted, then the complete set of hypertext documents will be searched, as found on the HTX_PATH search path. Any further documents described in catalogue files will also be included.

Any ".htx" extension on document names is ignored.

Switches

-b

Requests that a "brief" list be produced of the documents found. This means that only document names and titles will appear and references to individual pages will be omitted. By default, individual pages will be listed if the search has included them and they match the search criteria.

-c

Indicates that case is significant when searching for the keyword. By default, differences in case are ignored.

-f

Indicates that a full search should be performed, involving searching document names, titles, page headings and lines of text. This option is shorthand for the switches -n, -t, -h and -l used together.

-h

Indicates that a search for the keyword is to be performed on all the page headings within each document.This provides a convenient compromise between speed of execution and full search coverage, and generally produces an acceptable amount of output. By default, a search on page headings is performed if the keyword cannot be found in any document title. Page headings may only be searched in local hypertext (".htx") documents.

-html

Indicates that the list of documents found by this command should not be displayed using a WWW browser. Instead, the results are simply written to standard output as a list in HTML format (without a surrounding HTML document). This provides an interface for other software that will display the results itself.

Note that the URLs used for hyper-links in this output list will be suitable only for local use by a WWW browser running on the same machine as the findme command. They may not be suitable, for instance, for embedding in an HTML document that will be interpreted by a remote WWW browser.

-l

Indicates that a search for the keyword is to be performed on all lines of text within each document (note that this will include all HTML tags, URLs, etc.). This provides the fullest possible form of keyword search, but may take some time to complete and could generate a large volume of output. By default, a search of document lines is only performed if the keyword cannot be found in any document title or page heading. Line-oriented searching can only be performed on local hypertext (".htx") documents.

-m

Indicates that the output list is to contain information on which search criteria were matched and how many matches were found. By default, this information is omitted.

-n

Indicates that a search for the keyword is to be performed on the name of each document. Searching of document names is not performed by default.

-q

Indicates that the search should progress in "quiet" mode without producing messages about its progress. By default, messages about the progress of the search are written to the controlling terminal.

-s

Indicates that the output list is to be sorted so that the most significant matches appear first and the least significant last. In assessing this, matches to the document name are given the highest significance, then matches to titles, page headings and finally lines of textual content (see §). An alphabetical sort on document title and page heading is used to resolve any remaining ambiguity over output order. By default, a simple alphabetical sort on document title and page heading is used alone.

-t

Indicates that a search for the keyword is to be performed on the title of each document. This provides a quick but effective form of search for major topics and gives at most one entry in the output list for each document matched. By default, title matching is performed first, and a search of page headings (and eventually lines of textual content) is performed only if this initial search fails to match any documents (see §). Using -t prevents these subsequent searches from happening automatically.

-w

Indicates that the keyword supplied must match an entire word (i.e. a string delimited by characters which are not underscores or alphanumerics, or delimited by the beginning or end of the text, or by a newline). By default, the specified string of characters is matched wherever it occurs, so long as it does not span multiple lines of text.

-warn

Indicates that any warning messages issued by the WWW browser (e.g. when it is started up) are to be suppressed. By default, these warnings are written to standard error along with any other warning or error messages.

Exit Status

The exit status from this command is set equal to the number of documents matched by the search. Thus a non-zero exit status indicates success, while a zero status indicates failure to find any document. Note that this is the reverse of the convention normally adopted by UNIX commands.

Notes On Searching

• If none of the switches -n, -t, -h or -l is used, the keyword given will first be searched for in the title of each document. If this fails to produce a match, it will next be searched for in the page headings of each document. If this also fails to produce a match, a final search of the lines of text within each document will be made.

• If one or more of the switches -n, -t, -h or -l is used, the automatic sequence of searches described above will not occur. Instead, only those document components specified by these switches (name, title, page header and lines of text, respectively) will be searched. This will be done in a single pass through all documents.

• To obtain the fullest possible (but slowest) search, use the -f option. This is equivalent to using all of the switches -n, -t, -h and -l together.

Notes on Specifying Documents

• If no documents are specified, then all directories on the HTX_PATH search path will be inspected for hypertext (".htx") documents and all those found will be searched. In addition, if any directory on the search path contains a catalogue file, the documents it describes will also be included in any search of document names or titles (but not of page headings or lines of text).

• If one or more document names are supplied, then the search will be restricted to the specified documents only. If these document names are supplied without directory information, then they will be located by following the HTX_PATH search path and then by reading the contents of any catalogue files, if necessary. If document names are supplied with explicit directory information, then they must refer to local hypertext documents and no search will be made to locate them.

• If documents with the same name are found both locally in hypertext form and in one or more catalogue files, then the hypertext version takes precedence. If a document with the same name appears more than once in the list given for the doclist parameter, then the first occurrence takes precedence, except that the first occurrence of a name with explicit directory information always takes precedence over the same document specified without directory information.

Examples:

findme

Finds all available documents.

findme guide

Finds all documents with the string "guide" in them. This is done by first searching their titles, then (if that fails) by searching all their page headings, then (if that also fails) by searching all of their lines of text.

findme -t guide

Finds all documents with the string "guide" in their title. Only titles are searched.

findme -n sun

Finds all documents whose names contain the string "sun".

findme -w star

Finds documents that contain "star" as a word on its own.

findme -c GnS

Finds documents that contain the string "GnS" with the correct capitalisation.

findme -l -b unix

Searches all lines of text in all documents for the string "unix" and displays a brief listing of the results, so that only the relevant document names and titles are shown.

findme -h DAT_ sun92

Finds a document called "sun92" and searches its page headings (only) for the string "DAT_". Each page which matches is listed.

findme -t -h '?$' docs/.htx

Searches the titles and page headings of all hypertext documents stored in directory docs and lists those which end in a question mark ("?$" is a regular expression specifying that there should be a question mark at the end of a line).

findme -h -html -q "$keyword" pkg_manual >>/tmp/results$$

This command might be used to provide a command lookup facility for a software package. It searches all the page headings in the document called "pkg_manual" for the command stored in the keyword variable and appends the resulting list (in HTML format) to a scratch file in which an HTML page of results is being constructed. Messages about the progress of the search are suppressed with the -q switch.

Environment Variables Used

HTX_BROWSER

The command which will be used to invoke the WWW browser.

HTX_PATH

A colon-separated list of the library directories in which to search for hypertext documents.

HTX_SERVER

The URL of the document server to be used for serving remote documents.

HTX_TMP

The name of the directory in which to create temporary communication files. If this variable is not set or is null, then $HOME/.htxtmp is used instead.