Processing math: 100%

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 (see §2.3). Any further documents described in catalogue files (§10) 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(see§8.2) 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 (see §8.2) 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 (see §8.2) 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 §8.2). 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 (see §8.2) 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 §8.2). 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

Notes on Specifying Documents

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 (see §B.1).
HTX_PATH
A colon-separated list of the library directories in which to search for hypertext documents see §2.3).
HTX_SERVER
The URL of the document server to be used for serving remote documents (see §6.1).
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 (see §B.3).