Target documents
----------------
There are four documents that can be made:
 1.  The Administrators' Guide
 2.  The Users' Guide
 3.  The Command Reference
 4.  The Reference Manual (which consists of all the above)

Systemwide convenience macros
-----------------------------
\Prog{progname}
  Any executable program

\Cmd{command}{section}
  Commands from man pages.  E.g., talk(1) ==> \Cmd{talk}{1}

\Sinful{sinfulstring}
  Don't put in the wakka's (i.e., < and >) --- they will be put in 
  automatically. E.g., \Sinful{perdita.cs.wisc.edu}

\Condor{command}
  A condor *executable* (i.e., will be typeset with \Prog).  Also removes the 
  pain of typing in an escaped underscore (underscore is special in TeX).  
  Thus, type \Condor{q} for condor_q.

\condor{file}
  A condor *non-executable* --- does the same as \Condor{} above, but is not
  typeset as a \Prog{}.  Mostly useful for things like config file names, e.g., 
  \condor{config} and \condor{config.local}
 
\File{filename}
  Any file of importance. E.g., \File{/etc/passwd} and \File{\condor{config}}

Other macros for punctuation (such as | [ ] \ etc.) also available.  See 
condor-macros.tex



Writing man pages
-----------------
The following four points are *required* to be observed for *every* man page.

1.  A man page is written in a ManPage environment, which is delimited by
    \begin{ManPage} and \end{ManPage}.  The \begin{ManPage} requires three
	arguments:  the name of the command being documented, the section it
	belongs to (i.e., 1 for user commands, 8 for admin, etc.) and a short
	(1--5 line) description of the function of the command.  E.g.,

	\begin{ManPage}{\condor{q}}{1}{Displays the request queue.}
	...
	\end{ManPage}


2.	Inside the environment, the first part is the synopsis.  This is demarked
    by \Synopsis immediately followed by a \SynProg{progname}.  The contents
    of this section are the options allowed.  E.g.

	\begin{ManPage}{\condor{q}}{1}{Displays the request queue}
		\Synopsis \SynProg{\Condor{q}}	
			\oOpt{-global} \oOptArg{-submittor}{submittor} \oOpt{-help} 
			\oOptArg{-name}{name} \oOptArg{-constraint}{expression} 
			\oOpt{-long} \oArg{cluster} \oArg{cluster.process} \oArg{owner}
		...
	\end{ManPage}

	The macros which should be used for this purpose are:
		\Opt{option}		- A required option (e.g., -foo)
		\Arg{argument}		- A required argument (e.g., inputfile)
		\OptArg{opt}{arg} 	- Reqd. option with an argument (e.g., -o a.out)
		\oOpt{option}		- An optional option (e.g., [-global])
		\oArg{option}		- An optional argument (e.g., [cluster])
		\oOptArg{opt}{arg}	- Optional option with argument (e.g., [-o a.out])

	"Required option" and "optional option" are a little meaningless, but the 
	intentions are clear, so I'll leave it at that.


3.	Following the synopsis is a description, which is a normal LaTeX paragraph
	that is commenced with a \Description.

	\begin{ManPage}{\Condor{q}}{1}{Displays the request queue}
		\Synopsis \SynProg{\Condor{q}}	
			\oOpt{-global} \oOptArg{-submittor}{submittor} \oOpt{-help} 
			\oOptArg{-name}{name} \oOptArg{-constraint}{expression} 
			\oOpt{-long} \oArg{cluster} \oArg{cluster.process} \oArg{owner}
		
		\Description
		\Condor{q} displays information about jobs in the local condor job 
		queue.  If a \Arg{cluster} and a \Arg{process} are both specified, 
		\Condor{q} displays information about the specified process. If a 
		\Arg{cluster} is specified without a \Arg{process}, \Condor{q} displays 
		information about ...

	\end{ManPage}

	To differentiate the concept "cluster" from the argument "cluster", and for
    consistancy, please use \Arg, \Opt, \Condor, et al. in the entire man page.
	However, do not use the \oXXX variants (i.e., optional variants); just use
	/XXX even if the argument is optional.  (This ensures that the text is
    typeset as -name instead of [-name], which doesn't make sense in running 
	text.)


4.	Following the description is a detailed description of the options and
	their efficacy.  This is performed in an option table.  Each item in the
	option table is a pair (option,description) which describes the option of
	interest.  Again, do not use the \oXXX variants.

    \begin{ManPage}{\Condor{q}}{1}{Displays the request queue}
        \Synopsis \SynProg{\Condor{q}}
            \oOpt{-global} \oOptArg{-submittor}{submittor} \oOpt{-help}
            \oOptArg{-name}{name} \oOptArg{-constraint}{expression}
            \oOpt{-long} \oArg{cluster} \oArg{cluster.process} \oArg{owner}
        
        \Description
        	\Condor{q} displays information about jobs in the local condor job 
        	queue.  If a \Arg{cluster} and a \Arg{process} are both specified, 
        	\Condor{q} displays information about the specified process. If a 
        	\Arg{cluster} is specified without a \Arg{process}, \Condor{q} 
			displays information about ...

		\begin{Options}
			\OptItem{\Opt{-help}} {Get a brief description of the supported 
				options}
	
			\OptItem{\Opt{-long}} {Get verbose output}

			\OptItem{\OptArg{-name}{name}} {Get the request queue of the
				schedd named \Arg{name}}.
			...

		\end{Options}

    \end{ManPage}


In addition to the previous four required parts, a given man page may also
contain several optional parts.  Each optional part is one or more normal
LaTeX paragraphs preceded by one of \Examples, \SeeAlso, \Files and \GenRem 
(for general remarks).  [NOTE:  \Files and \File{filename} are different
creatures!!]
