Chapter 2: QEF Documentation

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.

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.

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.

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

x

    % 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
    ...

QEF also supports an xcmd convention. The command xcmd 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 xcmd 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:

Information about qef itself

The multi-directory build script generator

Example and prototype files

The qef graphic user interface

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

The File System Integrity Check package tools and error messages

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).

The software process procedures for build managers and developers

The qsg tools, language, library scripts, and functions

The qvrs tools, variables, language, and files.

In qefgui, the QEF graphical user interface, the cmd(N), cmd x, and xcmd 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).

    % 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 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

    -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

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

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