%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Project:     Documentation Tools
%% Descr:       Latex -->  MAN-page (groff -man), LATEX documentation
%% Author:      Dr. Jürgen Vollmer, Juergen.Vollmer@acm.org
%% $Id: latex2man.tex,v 1.56 1998/01/14 07:56:55 vollmer Exp $
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass{article}
\usepackage[latin1]{inputenc}
\usepackage{babel}

%% do we have the `fancyheadings' package?
\IfFileExists{fancyheadings.sty}{
\usepackage[fancy]{latex2man}
}{
\usepackage[nofancy]{latex2man}
\message{package fancyheadings not present, discard it}
}

%% do we have the `rcsinfo' package?
\IfFileExists{rcsinfo.sty}{
\usepackage[nofancy]{rcsinfo}
\rcsInfo $Id: latex2man.tex,v 1.56 1998/01/14 07:56:55 vollmer Exp $
\setDate{\rcsInfoLongDate}
}{
\setDate{1998/01/14}    %%%% must be manually set
\message{package rcsinfo not present, discard it}
}

\setVersion{1.1}

\begin{document}

\begin{Name}{1}{latex2man}{Dr.~Jürgen Vollmer}{Documentation Tools}
  \Prog{Latex2man} is a tool to translate UNIX manual pages written with \LaTeX\ into a
  format understood by the UNIX \Cmd{man}{1}-command. Alternatively HTML code or TexInfo
  code can be produced too.
\end{Name}

\section{Synopsis}
%%%%%%%%%%%%%%%%%%

\Prog{latex2man} \oOptArg{-t}{transfile}
                 \oOpt{-H} \oOpt{-M} \oOpt{-T} \oOpt{-h} \oOpt{-V}
                 \Arg{infile}
                 \Arg{outfile}

\section{Description}
%%%%%%%%%%%%%%%%%%%%%
\Prog{Latex2man} reads the file \Arg{infile} and writes \Arg{outfile}. The input must be
a \LaTeX\ document using the \Prog{latex2man} \LaTeX\ package.  \Prog{Latex2man}
translates that document into the \Cmd{troff}{1} format using the \Opt{-man} macro
package.

Using the \Opt{-H} option, HTML code can be produced, instead of \Cmd{troff}{1}.

Using the \Opt{-T} option, TexInfo code can be produced, instead of \Cmd{troff}{1}.

\section{Options}
%%%%%%%%%%%%%%%%%
\begin{description}
\item[\OptArg{-t}{transfile}] Translation for user defined \LaTeX\ macros.
\item[\Opt{-M}] Produce output suitable for the \Cmd{man}{1} command (default).
\item[\Opt{-H}] Instead of producing output suitable for the \Cmd{man}{1} command, HTML
     code is produced (despite of the name of the command).
\item[\Opt{-T}] Instead of producing output suitable for the \Cmd{man}{1} command,
     TexInfo code is produced (despite of the name of the command).  The generated
     \File{.texi}-file may be processed with \Cmd{makeinfo}{1} (to produce an
     \File{.info}-file) which in turn may be installed using \Cmd{install-info}{1}. The
     Info tags \verb+@dircategory+ and \verb+@direntry+ are provided.
\item[\Opt{-h}] Show a help text.
\item[\Opt{-V}] Show version information.
\end{description}

\section{Files}
%%%%%%%%%%%%%%%

\begin{description}
\item[\File{latex2man.tex}] The \LaTeX\ file containing this Man-page.
\item[\File{latex2man.sty}] The \LaTeX\ package defining the environments and commands.
\item[\File{latex2man.trans}] File containing example translations of user defined
     \LaTeX\ macros.
\item[\File{fancyheadings.sty}] A \LaTeX\ package used to typeset head- and foot lines.
\item[\File{rcsinfo.sty}] A \LaTeX\ package used to extract and use of RCS version
     control information in \LaTeX\ documents.
\end{description}

\section{See Also}
%%%%%%%%%%%%%%%%%%

\LaTeX, TexInfo, \Cmd{troff}{1}, \Cmd{groff}{1}, \Cmd{makeinfo}{1}.

\section{\LaTeX\ commands}
%%%%%%%%%%%%%%%%%%%%%%%%%%

The \LaTeX\ package \texttt{latex2man} is used to write the Man-pages with \LaTeX.
Since we translate into other text formats, not all \LaTeX\ stuff can be translated.

\subsection{Package Options}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The \texttt{latex2man} package accepts the following options:

\begin{description}
\item[fancy] use the  \LaTeX\ package \texttt{fancyheadings} (default).
\item[nofancy] don't use the  \LaTeX\ package \texttt{fancyheadings}.
\end{description}

\subsection{Package Specific Environments}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The following environments are provided by the package:
\begin{description}
\item[\Bs begin\{Name\}\{chapter\}\{name\}\{author\}\{info\} ] The \texttt{Name}
     environment takes four arguments: 1.\ the Man-page chapter, 2.\ the name of the
     Man-page, 3.\ the author, 4.\ some short information about the tool. The
     \texttt{Name} environment must be the first environment in the document. Processing
     starts with this environment. Any text before this is ignored (exception:
     the \verb+setversion+ and \verb+setDate+ commands).
\item[\Bs begin\{Table\}\{columns\}] The \texttt{Table} environment takes one argument:
     the number of columns.
     For example:

     \verb+\begin{Table}{3}+            \\
     \verb+ Here & am  & I   \\\hline+  \\
     \verb+  A 1 & A 2 & A 3 \\+        \\
     \verb+  B 1 & B 2 & B 3 \\+        \\
     \verb+\end{Table}+

     will be typeset as:

     \begin{Table}{3}
       Here & am  & I   \\\hline
        A 1 & A 2 & A 3 \\
        B 1 & B 2 & B 3 \\
     \end{Table}

     \verb+\hline+ may be used. All entries are typeset left justified.
\end{description}

\subsection{Accepted \LaTeX\ Environments}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The following environments are accepted:
\begin{itemize}
\item \texttt{description}
\item \texttt{enumeration}
\item \texttt{itemize}
\end{itemize}

\subsection{Package Specific Macros}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The following commands are provided:
\begin{description}
\item[\Bs Opt\{option\}]   \verb+\Opt{-o}+ will be typeset as \Opt{-o}.
\item[\Bs Arg\{argument\}] \verb+\Arg{filename}+ will be typeset as \Arg{filename}.
\item[\Bs OptArg\{option\}\{argument\}] \verb+\OptArg{-o}{filename}+ will be typeset as
   \OptArg{-o}{filename}.
\item[\Bs oOpt\{option\}] Optional option, e.g.\ \verb+\oOpt{-o}+ will be typeset as
     \oOpt{-o}.
\item[\Bs oArg\{argument\}] Optional argument, e.g.\ \verb+\oArg{filename}+ will be
     typeset as \oArg{filename}.
\item[\Bs oOptArg\{option\}\{argument\}] Optional option with argument, e.g.\\
     \verb+\oOptArg{-o}{filename}+ will be typeset as \oOptArg{-o}{filename}.
\item[\Bs File\{filename\}] used to typeset filenames, e.g.\
     \verb+\File{filename}+ will be typeset as \File{filename}.
\item[\Bs Prog\{prog\}] used to typeset program names, e.g.\
     \verb+\Prog{latex2man}+ will be typeset as \Prog{latex2man}.
\item[\Bs Cmd\{command\}\{chapter\}] used to typeset references to other commands,
     e.g.\ \verb+\Cmd{latex2man}{1}+ will be typeset as \Cmd{latex2man}{1}.
\item[\Bs Bar] is typeset as \Bar.
\item[\Bs Bs] (BackSlash) is typeset as \Bs.
\item[\Bs Tilde] is typeset as a \Tilde.
\item[\Bs Dots] is typeset as \Dots
\item[\Bs setVersion\{..\}] set  \verb+..+ as version information.
\item[\Bs Version] returns the version information.
\item[\Bs setDate\{..\}] sets \verb+..+ as date information.
\item[\Bs Date] returns the date information.
\item[\Bs Email\{..\}] use to mark an Email address:\\
        \verb+\Email{Juergen.Vollmer@acm.org}+ is typeset as:\\
        \Email{Juergen.Vollmer@acm.org}.
\item[\Bs URL\{..\}] use to mark an URL:
        \verb+\URL{http://www.cocolab.de/vollmer}+ is typeset as
        \URL{http://www.cocolab.de/vollmer}.
\item[\Bs LatexManEnd] the input file is read and processed until reading end-of-file or
     \verb+\LatexManEnd+ (at the beginning of a line).  \LaTeX\ ignores this
     command.
\end{description}

\subsection{Accepted Macros from the ``rcsinfo'' Package}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{description}
\item[\Bs rcsInfo \$Id ...\$] if the \LaTeX\ package \File{rcsinfo} is used, this command
     is used to extract the date of the Man-page.
\item[\Bs rcsInfoLongDate] if the \LaTeX\ package \File{rcsinfo} is used, this command
     is used to typeset the date coded in the \verb+$Id ..$+ string.
\end{description}

\subsection{Accepted \LaTeX\ Macros}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The following standard \LaTeX\ commands are accepted:
\begin{description}
\item[\Bs section\{..\}] The \texttt{section} macro takes one argument: the name of the
     Man-page section.  Each Man-page consists of several sections. Usually there are the
     following sections in a Man-page: \emph{Name} (special handling as environment,
     c.f.\ above), \emph{Synopis}, \emph{Description}, \emph{Options}, \emph{Files},
     \emph{See Also}, \emph{Diagnostics}, \emph{Return Values}, \emph{Bugs},
     \emph{Author}, \emph{version}, etc.

     \emph{Synopsis} must be the first section after the \texttt{Name} environment.
\item[\Bs subsection\{..\}]
\item[\Bs emph\{..\}] \verb+\emph{example}+ is typeset as \emph{example}.
\item[\Bs textbf\{..\}] \verb+\textbf{example}+ is typeset as \textbf{example}.
\item[\Bs texttt\{..\}]\verb+\textt{example}+ is typeset as \texttt{example}.
\item[\Bs underline\{..\}]\verb+\underline{example}+ is typeset as \underline{example}.
\item[\Bs date\{..\}] uses \verb+..+ as date.
\item[\Bs verb+..+] but only + is allowed as delimiter
\item[\$$<$\$] is typeset as $<$.
\item[\$$>$\$] is typeset as $>$.
\item[\Bs \{] is typeset as \{.
\item[\Bs \}] is typeset as \}.
\item[\Bs \$] is typeset as \$.
\item[\Bs \_] is typeset as \_.
\item[\Bs \&] is typeset as \&.
\item[\Bs \#] is typeset as \#.
\item[\Bs \Bs] is typeset as a linebreak or marks the end of a column in the
     \texttt{Table} environment.
\item[\Bs ] (a \Bs\ followed by a blank) is typeset as a blank.
\item[\Tilde] is typeset as a blank.
\item[\Bs copyright] is typeset as \copyright.
\item[\Bs Circum] is typeset as \Circum.
\item[\Bs Lbr, \Bs Rbr] is typeset as \Lbr\ and \Rbr (these variants are needed only
     somtimes like in \verb+item[FooBar\LBr xx \Lbr]+. Usually \verb+[ ]+ will work.
\item[\Bs Percent] is typeset as \Percent.
\item[\Bs noindent]
\item[\Bs hline] inside a \texttt{Table} environment.
\item[\Bs item] inside a \texttt{itemize}, \texttt{enumerate}, or \texttt{description}
     environment.
\item[\Bs today] \today\ (see also the \texttt{rcsinfo} \LaTeX\ package).
\end{description}

\subsection{Translation of User Defined Macros}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The user macro translation file (given by the \oOptArg{-t}{transfile})
contains \Prog{Perl} commands specifying the translation of \LaTeX\ macros defined by the
user. These macros may have none, one or two arguments. The following code is expected:

\begin{itemize}
\item Comments start with a \# up to the end of the line.
\item  For a macro \verb+\foo+ with no arguments, the following code must be specified:\\
     \verb+$manMacro{'foo'}  = '...';+ \\
     \verb+$htmlMacro{'foo'} = '...';+ \\
     \verb+$texiMacro{'foo'} = '...';+ \\
     where \verb+...+ is the translation. The first assignment is used for translation
     into the Man-page format, the second is used for the translation into HTML code, the
     third is used for texInfo.

\item For a macro \verb+\foo{..}+ with one argument, the following code must be
     specified:\\
     \verb+$manMacro1a{'foo'}  = '...';+\\
     \verb+$manMacro1b{'foo'}  = '...';+

     \verb+$htmlMacro1a{'foo'} = '...';+\\
     \verb+$htmlMacro1b{'foo'} = '...';+

     \verb+$texiMacro1a{'foo'} = '...';+\\
     \verb+$texiMacro1b{'foo'} = '...';+

     where \verb+...+ is the translation. The \verb+1a+ code is used before the argument,
     while \verb+1b+ is typeset after the argument is set.

\item For a macro \verb+\foo{..}{..}+ with two arguments, the following code must be
     specified:\\
     \verb+$manMacro2a{'foo'}  = '...';+\\
     \verb+$manMacro2b{'foo'}  = '...';+\\
     \verb+$manMacro2c{'foo'}  = '...';+

     \verb+$htmlMacro2a{'foo'} = '...';+\\
     \verb+$htmlMacro2b{'foo'} = '...';+\\
     \verb+$htmlMacro2c{'foo'} = '...';+

     \verb+$texiMacro2a{'foo'} = '...';+\\
     \verb+$texiMacro2b{'foo'} = '...';+\\
     \verb+$texiMacro2c{'foo'} = '...';+

     where \verb+...+ is the translation. The \verb+2a+ code is used before the first
     argument, \verb+2b+ between the two arguments and \verb+2c+ is typeset after the
     second argument is set.
\item The file \File{latex2man.trans} contains some example code.
\end{itemize}

\subsection{General Remarks}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{enumerate}
\item Empty lines are typeset as paragraph separators.
\item The arguments of the \LaTeX\ commands must not be split over several lines.
\item Do not nest calls to macros or environments.
\item Except the mentioned environment and macros, the usage of other \LaTeX\
     environments or macros are not translated. Their usage will cause garbage in the
     output.
\end{enumerate}

\section{Version}
%%%%%%%%%%%%%%%%%

Version: \Version\ of \Date.

\section{Copyright}
%%%%%%%%%%%%%%%%%%%

\noindent
Copyright \copyright\ 1998, Jürgen Vollmer.\\
This is \emph{PostCardWare}, which means
\begin{itemize}
\item You may use this software without a fee, as it is, and at your own risk.
\item You may distribute this software only without any changes and complete
     (i.e. with this copyright notice and the following files
     \File{latex2man.sty} \File{latex2man}, \File{latex2man.tex}, \File{latex2man.trans},
     \File{Makefile}, \File{README}, and \File{INSTALL}).
\item You may not sell this software.
\item If you have bug fixes, enhancements, new ideas, etc. send them to me.
\item If you find this software useful, send me a postcard.
\end{itemize}

\section{Author}
%%%%%%%%%%%%%%%%

\noindent
Dr.~Jürgen Vollmer                      \\
Viktoriastraße 15                       \\
D-76133 Karlsruhe                       \\
Email: \Email{Juergen.Vollmer@acm.org}  \\
WWW: \URL{http://www.cocolab.de/vollmer}.
\LatexManEnd

\end{document}
