\documentstyle{unixman} 

\filenamewidth 3.5 in
\def\met#1{{\it #1}}
\def\meta#1{{$<${\it #1}$>$}}
\gdef\[{\char'133}
\gdef\]{\char'135}

\begin{document} 

\version{1.1}{4th June 1991}
\header{unixman}{1L}[\LaTeX\ styles]

\section{NAME}

unixman -- \LaTeX\ document style produce Unix-style manual pages

\section{SYNOPSIS} 

{\tt
\bs documentstyle[unixman]\\
\bs begin\{document\}\\
\bs header\{\met{name}\}\{\met{section-number}\}[\met{section-name}]\\
\bs version\{\met{version-id}\}\{\met{date}\}

\bs section\{NAME\}

\hbox to 2cm{\hfil \vdots \hfil}

\bs end\{document\}
}

\section{DESCRIPTION} 

The \this\ document style produces documents conforming to the conventions
of the Unix manual, as embodied in the \command{troff}{1} ``man'' macros.
It uses the standard \LaTeX\ sectioning commands, and defines several
new commands and environments to make manual page formatting easier.
These include facilities for printing lists of command line flags and
doing rapid font switches, which tend to be common to reference manuals.

\subsection{Commands}

\begin{description}

\item[\bs version\{{\it version-id}\}\{{\it date}\}]
define the version number and date of modification of this manual entry.


\item[\bs header\{\I name \}\{\I section-number \}\[\I section-name \]]
define the name of the command and the section number in which it is
to appear. \I section-name is an optional argument used to override
the default name for \I section-number.

\item[\bs startpage\{{\it page-number}\}] 
start page numbering from {\it pagenumber}.

\item[\bs extrapagesfrom\{{\it page-number}\}] 
number all pages beyond {\it pagenumber} in the style {\it
pagenumber}a, {\it pagenumber}b and so on. For use when adding extra
pages to an existing manual. For instance, if you use
{\tt \bs extrapagesfrom\{260\}}, then instead of 260, 261, 262 you will 
get 260, 260a, 260b and so on.

\item[\bs file\{{\it file}\}] 
prints the name of a file in the default
font for such items\\
(e.g. {\tt \bs file\{/usr/lib\}} $\rightarrow$ \file{/usr/lib})

\item[\bs prog\{{\it program}\}] 
prints a program in the default font
for such items\\ 
(e.g. {\tt \bs prog\{awk\}} $\rightarrow$ \prog{awk}).

\item[\bs this] 
prints the name of this manual page, emboldened.

\item[\bs R, \bs B, \bs T, \bs I, \bs S]
print the next word in a \R roman, \B bold, \T typewriter, \I italic, and \S san-serif
font respectively. The word must be delimited by white space.

\item[\bs RB, \bs RI, \bs IB, \bs IR, \bs BI, \bs BR]
print the next two words in alternating fonts, where the two letters
specify the font according to the single word version described above.
The words must be delimited by whitespace.

\item[\bs tilde] 
prints a tilde (\tilde)

\item[\bs pipe]
prints a vertical bar (\pipe).

\item[\bs bs]
prints a backslash (\bs). Useful for manual pages about \LaTeX.

\item[\bs\<\ \R \& \bs\>] 
print left- and right- arrow brackets (\<\ \& \>).
These commands ignore following spaces completely.

\item[\bs \[\ \R and \bs \]]
print left and right square brackets (\[\ \& \]). Necessary in {\tt item} labels
within a list environment. 

\end{description}

\subsection{Environments}

The \this\ style defines several new environments to make the
formatting of manual pages easier and more consistent.

\subsubsection{Options}

The {\tt options} environment is intended for creating lists of
command line flags. Within it there are two special commands, {\tt \bs
opt} and {\tt \bs optarg}. The first is used to describe an flag that
has no arguments; the second is used in the case where there are
arguments.  With the {\tt optarg} command, you can use the command
{\tt \bs arg} to simply print the argument in the same style and
without retyping it.  An example -- the following \LaTeX\ specification:

\begin{example}
\begin{verbatim}
\begin{options}
\opt{-p} print top value on the stack
\optarg{-s}{x} put top of stack into register named \arg
\optarg{-I}{directory} add \arg to the list of directories searched.
\end{options}
\end{verbatim}
\end{example}

produces the following results

\begin{example}
\rm
\begin{options}
\opt{-p} print top value on the stack
\optarg{-s}{x} put top of stack into register named \arg
\optarg{-I}{directory} add \arg to the list of directories searched.
\end{options}
\end{example}

Note how the description is positioned when the argument associated
with an option flag is especially long (see PARAMETERS, below).

\subsubsection{Filelist}

The {\tt filelist} environment provides a simple means of formatting
lists of files for the standard FILES section of a manual page, or
elsewhere if desired.
 		       
\begin{example}
\bs begin\{filelist\}\\
\bs fileref\{\I filename\} \I description \ldots\\
\bs end\{filelist\}
\end{example}

{\tt \bs fileref} sets its argument in a default face. The description
part is optional, and its position in the case of very long filenames
follows the pattern for the `options' environment described above (see
PARAMETERS, below).

\subsubsection{Example}

The example environment provides an indented environment with a
typewriter font (Courier) as the default. If you wish to be able to
use all letters and symbols easily, you should use a verbatim
environment within an example.

\subsection{Parameters}

\begin{description}
\item[\bs filenamewidth] the width of a filename in a filelist that
when exceeded, causes the description (if present) to be wrapped to
the next line.  The default is 2.0 inches.

\item[\bs optionwidth] the width of an option in an options list that
when exceeded, causes the description (if present) to be wrapped to
the next line. The default is 0.5 inches

\item[\bs descriptionwidth] as {\tt \bs optionwidth}, but for
description environments, which are otherwise like the normal LaTeX
description environment. The default is 1.5 inches.

\item[\bs examplefont] the font to use in the 
{\tt example} environment. The defaut is typewriter (Courier).

\end{description}

\subsection{Conventions}

A typical manual page for a command  or  function  is
laid out as follows:

{\tt \bs header}\{TITLE\}\{1-8\}

The name of the  command  or  function  in  upper-case,
which  serves  as the title of the manual page. This is
followed by the number  of  the  section  in  which  it
appears.

{\tt \bs version}\{VERSION\}\{DATE\}

The version number and last modification of this manual page.

{\tt \bs section}\{NAME\}

{\tt name} (or comma-separated list of names) --  one-line summary

The name, or list of names, by  which  the  command  is
called,  followed by a dash and then a one-line summary
of the action performed. The summary should contain no
\LaTeX\ macros since it is used to contribute to the
`whatis' database.

{\tt \bs section}\{SYNOPSIS\}

{\bf Commands:}

The syntax of the command and  its  arguments,  as
typed  on  the  command line.  When in boldface, a
word must be typed exactly as  printed.   When  in
italics,  a  word can be replaced with an argument
that you supply.  References to bold or italicized
items  are not capitalized in other sections, even
when they begin a sentence.

Syntactic symbols appear in roman face:

\begin{description}
\item[\[\ \]] An argument, when surrounded by  brackets  is
                    optional.
\item[\pipe] Arguments separated by  a  vertical  bar  are
                    exclusive.   You  can  supply  only item from
                    such a list.
\item[\ldots] Arguments  followed  by  an  elipsis  can  be
                    repeated.   When  an elipsis follows a bracketed
                    set, the expression within the  brackets
                    can be repeated. 
\end{description}

{\bf Functions:}

If required, the data declaration, or \#include directive, is shown
first, followed by the function declaration.  Otherwise, the function
declaration is shown.

{\tt \bs section}\{DESCRIPTION\}

A narrative overview of the command or function's external behavior.
This includes how it interacts with files or data, and how it handles
the standard input, standard output and standard error.  Internals and
implementation details are normally omitted.  This section attempts to
provide a succinct overview in answer to the question, ``what does it
do?''

Literal text from the synopsis appears in boldface, as do literal
filenames and references to items that appear elsewhere in a reference
manual.  Arguments are italicized.

If a command interprets either subcommands or an input grammar, its
command interface or input grammar is normally described in a USAGE
section, which follows the OPTIONS section.  (The DESCRIPTION section
only describes the behavior of the command itself, not that of
subcommands.)

{\tt \bs section}\{OPTIONS\}

The list of options along with  a  description  of  how
each affects the command's operation. These should be
formatted within an {\tt options} environment.

{\tt \bs section}\{FILES\}

A list of files associated with the  command  or  function. 
These should be formatted within a {\tt filelist}
environment.

{\tt \bs section}\{SEE ALSO\}

A  comma-separated list of related  manual  pages,  followed
by references to other published materials.

{\tt \bs section}\{DIAGNOSTICS\}

A list of diagnostic messages  and  an  explanation  of
each.

{\tt \bs section}\{BUGS\}

A description of limitations, known defects, and possible
problems associated with the command or function.

\section{FILES}

\begin{filelist}
\fileref{/usr/local/lib/tex/macros/unixman.sty} The base style file
\fileref{/usr/local/lib/tex/macros/*.sty} other style options
\end{filelist}
   
\section{SEE ALSO} 

\command{man}{7}, \command{troff}{1}

{\it Formatting Documents, Chapter 3: the \T -man macro package}

\section{BUGS}

There is an \bs hoffset in the page dimensions whose function is not
clear.

There is a grotesque kludge used to get lists after section headings
spaced from the latter as if they were pure text, consisting of 
{\tt\bs vskip}'ing 14pt's back up the page. This is highly non-portable and
very bad style. Any better ideas~?

An \T verbatim environment immediately within another environment
other than \T example will not leave the normal amount of vertical space
before it. In fact, it leaves less than none at all.
\end{document}