FAQ

NAME

SYNOPSIS

DESCRIPTION

Faq Searches for answers to Frequently Asked Questions

Faq reads a loosely formatted faq file and extracts a set of questions. An faq file contains comments (as indicated by # or ; at the start of a line), questions (as shown by Q: at the start of a line), and answers which follow the question section. Any text preceeding the first question is taken to be a description of the FAQ file itself.

If a number is specified, that particular question and answer pair are shown. If one or more keywords are listed, the set of questions is scanned for matching text. Questions that meet the criteria are shown. This is used to limit the number of questions to select from.

The following options may be used with faq.

-h, -?, --help

List all the available options.

-f[file], --faq[=file]

Manually specify the FAQ file to use. If this option is omitted, FAQ will seek out a faq file in the current directory, then all directories specified by the environment variable FAQPATH, then the user's home directory via the HOME environment variable, and then all directories in the PATH. If the option is specified without an argument, then faq will report the filename that is currently being used. This is useful when faq gives an unexpected result. Note that to specify an optional value to a single-character parameter, it must directly follow the parametere with no whitespace; in the case of a long-parameter, an equalsign is needed. A - may be used to represent stdin in the place of a regular filename.

-F[file], --Faq[=file], --FAQ[=file]

Exactly like -f and --faq, but if faq has to search for the faq file then the search attempts are shown.

-d, --describe

Display the faq file's description. Any text that appears before the first question is considered descriptive text.

-l, --list

List all the questions in the faq. You may also use ? as the sole argument.

-L, --list-all

Not only will all the questions, but all the answers will be shown as well.

-c, --count

Provide a numeric summary of all the answers and questions shown. This option can be used to obtain the number of questions in the file as well as the number of questions that match the search criteria.

-a, --all

Same as -dLc

-i, --ignore-case

Normally searches through the questions are case-sensitive. This switch ignores case.

-x, --extended-regex

Uses extended regular expressions as explained by egrep.

-q, --quiet

Hushes the output of question lists and answers (it does not supress the counts or description). This option is primarily useful with the -c option and some keywords; it will show how many questions exist for a given set of keywords. Additionally, it may be used with -v to surpress faq descriptions.

-v, --version

Print the version number of faq to standard out before displaying FAQ contents. The version number should be included in all bug reports (see below). The compile date, time, compiler used, and version control information is also presented.

Entering -v will cause faq to display the faq description, but with faq's version information preceeding it. Using the -q option will silence the description, producing terse output.

INTRODUCTION

Nobody likes to read documentation. As such, new users constantly bombbard administrators, news groups, and techincal support with the same old questions.

In order to answer these questions once in for all, a knowledge base is built called a FAQ, which stands for Frequently Asked Questions.

Supposedly, the unfamiliar users will turn to the FAQ, providing they know where it is, and read it. Only then will a question be asked.

Unforuntately FAQ files can get rather large. Thus, users don't read them.

faq attempts to solve the problem by doing the dirty work of casual browsing for a subset applicable questions. The user may then select which question they'd like an answer to and only that answer is shown.

The faq application also saves the faq author mundane work by keeping track of the question numbers dynamically. Questions can be inserted anywhere and faq will adjust the numbering scheme. This save a lot of editing and organization. Additionally, faq can be set up to look in a common area for faq files if none are found in the local directory. As such, it can compliment the system help facilities.

faq is not meant to be a substitute for well written documentation, man or info page, or an elaborate hypertext system. It is a quick and dirty command line interface.  

EXAMPLE FAQ

# This is a comment

; This is another kind of comment

This is the description to the faq. It can be as long as we want and include multiple blank lines in the middle.

Q: What makes a question?

A question is a single line that starts with Q: or q: and has a question following. Eveything following up to the next question or end-of-file is the answer to the question.

Q: Is this another question?

Yes it is.

BEHAVIOR

Trailing spaces and tabs are removed from the output stream.

Special directives, comments, questions, etc. must start in column 1.

Control characters and HTML may be used in the faq file and will be extracted as is.  

REGULAR EXPRESSIONS

Searching is done with regular expressions, each regular expression listed on the command line as an argument is checked against the question list. If any question matches any regular expression, it is displayed (without the answer).

This is used to reduce the number of questions down to a manageable amount. Answers may then be obtained by invoking faq with the numerical number of the question.  

SEARCH ORDER

faq will ignore anything that is not a file or has an execute bit set; this prevents it from accidently opening executables and scripts. You may manually specify such files, but faq will not automatically select them during its searching.  

ENVIRONMENT

If faq can not find an appropiate input source in the current directory, then it looks in the directories specified by the FAQPATH environment variable. Directories are separated by colons. If no file is found after that, the PATH is searched.  

USAGE EXAMPLES

  Show the description for the current faq.

faq - dns named bind

  Show all questions that pertain to either DNS, named, or bind.

faq -l

  List all the questions

faq -c

  Show how many questions are in the FAQ.

faq -qc print

  Show how many questions are in the FAQ with the word print them.

faq -vq

  Show the version information without the FAQ file's internal description.

SEE ALSO

DIAGNOSTICS

If faq is successful, the exit status is 0. If there are any problems in accessing the faq file or with the user supplied options, then a non-zero exit status is returned.  

COPYING

The latest release should be available from ftp://ftp.wwco.com/pub/wwco/ and from http://wls.wwco.com/  

AUTHOR

HISTORY

This version for Linux is a super-set of that version.  

BUGS

There are no known bugs at this time, although the code could use some minor optimizations.

Email bug reports to wls@wls.wwco.com. Be sure to include the word ``faq'' somewhere in the ``Subject:'' field.

Index

NAME

SYNOPSIS

DESCRIPTION

INTRODUCTION

EXAMPLE FAQ

BEHAVIOR

REGULAR EXPRESSIONS

SEARCH ORDER

ENVIRONMENT

USAGE EXAMPLES

SEE ALSO

DIAGNOSTICS

COPYING

AUTHOR

HISTORY

BUGS

Return to MindPrint or go back to the Software Archives containing Wizard Workshop and Company distributions.