QEF home page

Chapter 2: QEF Documentation

The Guide's Table of Contents Previous Chapter Bottom Of Page Next Chapter

This chapter introduces the documentation available to the user online and via the web. The user is introduced to the many user documentation tools and databases available.


2.1) Sources of Q-Tree Documentation

Most of the documentation for the QEF toolkit is part of the toolkit itself. Every tool, every script, and every language provided in QEF has its own documentation. When you want to know more about a particular tool or convention, you can query the tool itself using the --x flag, check in the x_db and man databases for that tool or term (see xdbs and quete), or use the qef Info tool.

The Man Pages

Every program has a man page that can be found in the $QTREE/man directory. Adding $QTREE/man to your $MANPATH should allow you to access the QEF man pages using the normal man command.

The Reference Cards

Post-script and PDF forms of the qef Quick Reference Card are found in $QTREE/lib/refcard1.p{s,df}. They are also available in Appendix E and in the qef.gts.org web site page entitled "The QEF Quick Reference Card". This is a two page reference card that briefly lists the more important QEF commands and facilities.

The Appendix F: QEF Specialist's Reference Card is a set of lists of qvrs, qsg, and qef functions, keywords, scripts, and controls. In addition to Appendix F, it is also accessible via qef.gts.org's refcard2 page.

The reference cards are also available in the x-qmisc database and can be extracted using the commands:

    % x-qmisc refcard # the quick reference
    % x-qmisc refcard2 # the specialist's reference
The --x Convention All QEF tools support a --x (`x' for explain) flag which causes the program to print a synopsis, a short description, and the list of flags and arguments, as in:
    % qef -x
    qef [-x2cFkMntvX] [-A...] [-d dir] [-[DUGLl]...] [-P process]
	[-f file] [-T {012}] [-m <num>] [args ...]
    
    quod erat faciendum - that which was to be done
    
    -x		display this explanation
    -2		use qeffile2 instead of qeffile
    -c		suppress the ForbidQef check
    ...
The x--<cmd> Convention

QEF also supports an x--cmd convention. The command x--cmd is actually a link to the database program x_db in which the database base name defaults to cmd. You can get detailed help for tools that have such a database by prefacing the name with x--, as in:

    % x-qvrs
    x-qvrs : qvrs variables, facilities, and files eXplanatory D.B.
    
      qvrs-intro : brief description of qvrs
           files : the files of the qvrs system
      file-order : qvrs file search and ordering
          syntax : the syntax of qvrs input lines
       expansion : expansion of qvrs keyword arguments `@' strings
        keywords : qvrs command keywords
       functions : the built-in qvrs functions
       variables : lists of the classes of qvrs variables
     traits-vars : traits variables
      $Variables : the environment variables used in the Q-Tree
    
    See also: qvrs(x-qef) qvrs(1) x-qvrs x_db 

If any of the x--cmd commands is invoked without arguments or flags, it displays the first item in its database, which, by convention lists the major items in the database. Other variations are:

    % x-cmd -l # list the major items
    % x-cmd -L # list all items
    % x-cmd -a # output the major items
    % x-cmd -A # output all items
    % x-cmd -x # output abbreviated list of flags and options
    % x-cmd -X # output description of all flags and options
    % x-cmd key ... # output items for named keys
    % x-cmd -l key ... # list items for named keys 

The supported databases include:

x-qef

Information about qef itself

x-qefdirs

The multi-directory build script generator

x-qefeg

Example and prototype files

x-qefgui

The qef graphic user interface

x-qefpp

The qef pre-processor syntax, semantics, controls, and macros

x-qfsic

The File System Integrity Check package tools and error messages

x-qmisc

Miscellaneous QEF topics such as the tutorials, glossary, and FAQs. This database also contains a set of slides that may be used as introductory QEF seminar -- see seminar(x-qmisc).

x-qproc

The software process procedures for build managers and developers

x-qsg

The qsg tools, language, library scripts, and functions

x-qvrs

The qvrs tools, variables, language, and files.

In qefgui, the QEF graphical user interface, the cmd(N), cmd --x, and x--cmd mechanisms are all available and will appear as hyper-text links similar to those used in a web browser (such as the one you may be using now). The qef Info tool provides access to all of this information and all of the system manual pages. For an introduction to the qef Info Tool, see Chapter 5.6.
Note:Just as man page references consist of a name and a section number in parentheses (e.g., qef(1)), a reference to a x-- database topic in text or in the help files is followed by the database name in parentheses as in x_db(x-qef).

2.2) Xdbs, Quete, Mkquete, and the Quete Databases

Given the volume of the QEF documentation and for use by qefgui, two documentation search programs xdbs and quete are provided:
xdbs If xdbs is invoked without arguments, it simply lists the available x_db databases, as in:
    % xdbs
    ...
    qef     facilities and tools of the qef system
    qefdirs the syntax and use of qefdirs
    qefeg   prototype qef files
    qefgui  qefgui help items
    qefpp   qef pre-processor controls and macros
    qfsic   file system integrity package
    qmisc   Q-Tree miscellany
    qproc   the software process procedures
    qsg     qsg and its support library
    qvrs    qvrs variables and facilities
    ...

xdbs also provides flags to list all the items in the databases in various forms. Optional --p patterns ... can be specified to limit the list to those items that match the specified patterns as in:

    % xdbs -p mkquete
    mkquete(x-qef) produce manual section index (*tools)
    QueteUpd-Error(x-qefgui) mkquete execution error
quete quete is a specialized search tool that searches the title lines of all the x_db databases it can find and the quete/*.db databases of man page description lines and outputs the matched lines. For example:
    % quete mkquete # do search for terms mentioning mkquete
    mkquete(x-qef) produce manual section index (*tools)
    QueteUpd-Error(x-qefgui) mkquete execution error
    mkquete(1) ~ <qtree>/man mkquete - produce manual section index
Multiple patterns can be specified, in which case lines that match all the specified patterns. quete also supports the following flags that may be useful in queries:
    -Q      limit search to $QTREE manual sections
    -X      limit search to x_db databases
    -M      limit search to manual sections
    -N      do Not do dual case pattern matching
    -<num>  limit output to <num> items
    pattern ...	patterns matched against lines
Note:quete is a french noun for quest, search, collection, and beating about.
Building the quete database

The quete/*.db database mentioned above is built using mkquete. The list of quete databases can be retrieved using:

    % quete -L # list the quete databases
    /usr/tcl/man  G <qtree>/data/quete/tcl.db
    /usr/man  H <qtree>/data/quete/usr.man.db
    /usr/X11R6/man  G <qtree>/data/quete/X11.db
    /usr/tcl/man  C <qtree>/data/quete/tcl.db
    /usr/local/man  H <qtree>/data/quete/q101.db
    <qtree>/man  G <qtree>/data/quete/q100.db
    /usr/local/insure/man  G <qtree>/data/quete/q102.db
The letter following the directory name (e.g., `G') specifies the class or type of hosts served by the database file. Given that the <qtree>/data directory may be shared by many hosts on the network, there may be (actually there will be) differing man directories, although the name (e.g., /usr/man) may be the same. The type and its argument (not shown) are used to select the database file to be used when there are multiple files with the same directory name. The meanings of the types are as follows:
L
(local) the file quete.db in the directory itself is to be used, provided it exists
H
(host) the database applies to a specified host
C
(config) the database applies to hosts for the specific configuration name (e.g., Linux-2.0.34-i686) -- see system.
N
(sysnm) the database applies to hosts for the specific abbreviated system name (e.g., linux2) -- see sysnm.
G
(global) the database applies to all hosts not otherwise matched

The maintenance of the quete databases is described in Appendix B.5, however, you should be able to update or create entries using the command:

    % mkquete -u dir # create or update database for directory dir

c010.qh - 9.5 - 03/10/27 QEF Home The Guide's Table of Contents Previous Chapter Top Of Page Next Chapter