LATEX2MAN
Documentation Tools
Dr. Jürgen Vollmer
1998/01/14
Version 1.1
Latex2man
is a tool to translate UNIX manual pages written with LaTeX into a
format understood by the UNIX man(1)-command.
Alternatively HTML code or TexInfo
code can be produced too.
Table of Contents
Synopsis
latex2man
[ -ttransfile ]
[ -H ]
[ -M ]
[ -T ]
[ -h ]
[ -V ]
infile
outfile
Description
Latex2man
reads the file infile
and writes outfile.
The input must be
a LaTeX document using the latex2man
LaTeX package. Latex2man
translates that document into the troff(1)
format using the -man
macro
package.
Using the -H
option, HTML code can be produced, instead of troff(1).
Using the -T
option, TexInfo code can be produced, instead of troff(1).
Options
- -ttransfile
- Translation for user defined LaTeX macros.
- -M
- Produce output suitable for the man(1)
command (default).
- -H
- Instead of producing output suitable for the man(1)
command, HTML
code is produced (despite of the name of the command).
- -T
- Instead of producing output suitable for the man(1)
command,
TexInfo code is produced (despite of the name of the command). The generated
.texi-file
may be processed with makeinfo(1)
(to produce an
.info-file)
which in turn may be installed using install-info(1).
The
Info tags @dircategory and @direntry are provided.
- -h
- Show a help text.
- -V
- Show version information.
Files
- latex2man.tex
- The LaTeX file containing this Man-page.
- latex2man.sty
- The LaTeX package defining the environments and commands.
- latex2man.trans
- File containing example translations of user defined
LaTeX macros.
- fancyheadings.sty
- A LaTeX package used to typeset head- and foot lines.
- rcsinfo.sty
- A LaTeX package used to extract and use of RCS version
control information in LaTeX documents.
See Also
LaTeX,TexInfo, troff(1),
groff(1),
makeinfo(1).
LaTeX commands
The LaTeX package latex2man
is used to write the Man-pages with LaTeX.
Since we translate into other text formats, not all LaTeX stuff can be translated.
Package Options
The latex2man
package accepts the following options:
- fancy
- use the LaTeX package fancyheadings
(default).
- nofancy
- don't use the LaTeX package fancyheadings.
Package Specific Environments
The following environments are provided by the package:
- \begin{Name}{chapter}{name}{author}{info}
- The 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
Name
environment must be the first environment in the document. Processing
starts with this environment. Any text before this is ignored (exception:
the setversion and setDate commands).
- \begin{Table}{columns}
- The Table
environment takes one argument:
the number of columns.
For example:
\begin{Table}{3}
Here & am & I \\\hline
A 1 & A 2 & A 3 \\
B 1 & B 2 & B 3 \\
\end{Table}
will be typeset as:
| Here |
am |
I |
| A 1 |
A 2 |
A 3 |
| B 1 |
B 2 |
B 3 |
\hline may be used. All entries are typeset left justified.
Accepted LaTeX Environments
The following environments are accepted:
-
description
-
enumeration
-
itemize
Package Specific Macros
The following commands are provided:
- \Opt{option}
- \Opt{-o} will be typeset as -o.
- \Arg{argument}
- \Arg{filename} will be typeset as filename.
- \OptArg{option}{argument}
- \OptArg{-o}{filename} will be typeset as
-ofilename.
- \oOpt{option}
- Optional option, e.g. \oOpt{-o} will be typeset as
[ -o ].
- \oArg{argument}
- Optional argument, e.g. \oArg{filename} will be
typeset as [ filename ].
- \oOptArg{option}{argument}
- Optional option with argument, e.g.
\oOptArg{-o}{filename} will be typeset as [ -ofilename ].
- \File{filename}
- used to typeset filenames, e.g.
\File{filename} will be typeset as filename.
- \Prog{prog}
- used to typeset program names, e.g.
\Prog{latex2man} will be typeset as latex2man.
- \Cmd{command}{chapter}
- used to typeset references to other commands,
e.g. \Cmd{latex2man}{1} will be typeset as latex2man(1).
- \Bar
- is typeset as |.
- \Bs
- (BackSlash) is typeset as \.
- \Tilde
- is typeset as a ~.
- \Dots
- is typeset as ...
- \setVersion{..}
- set .. as version information.
- \Version
- returns the version information.
- \setDate{..}
- sets .. as date information.
- \Date
- returns the date information.
- \Email{..}
- use to mark an Email address:
\Email{Juergen.Vollmer@acm.org} is typeset as:
Juergen.Vollmer@acm.org.
- \URL{..}
- use to mark an URL:
\URL{http://www.cocolab.de/vollmer} is typeset as
http://www.cocolab.de/vollmer.
- \LatexManEnd
- the input file is read and processed until reading end-of-file or
\LatexManEnd (at the beginning of a line). LaTeX ignores this
command.
Accepted Macros from the ``rcsinfo'' Package
- \rcsInfo $Id ...$
- if the LaTeX package rcsinfo
is used, this command
is used to extract the date of the Man-page.
- \rcsInfoLongDate
- if the LaTeX package rcsinfo
is used, this command
is used to typeset the date coded in the $Id ..$ string.
Accepted LaTeX Macros
The following standard LaTeX commands are accepted:
- \section{..}
- The 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: Name
(special handling as environment,
c.f. above), Synopis,
Description,
Options,
Files,
See Also,
Diagnostics,
Return Values,
Bugs,
Author,
version,
etc.
Synopsis
must be the first section after the Name
environment.
- \subsection{..}
-
- \emph{..}
- \emph{example} is typeset as example.
- \textbf{..}
- \textbf{example} is typeset as example.
- \texttt{..}
- \textt{example} is typeset as example.
- \underline{..}
- \underline{example} is typeset as example.
- \date{..}
- uses .. as date.
- \verb+..+
- but only + is allowed as delimiter
- $<$
- is typeset as <.
- $>$
- is typeset as >.
- \{
- is typeset as {.
- \}
- is typeset as }.
- \$
- is typeset as $.
- \_
- is typeset as _.
- \&
- is typeset as &.
- \#
- is typeset as #.
- \\
- is typeset as a linebreak or marks the end of a column in the
Table
environment.
- \
- (a \ followed by a blank) is typeset as a blank.
- ~
- is typeset as a blank.
- \copyright
- is typeset as ©.
- \Circum
- is typeset as ^.
- \Lbr, \Rbr
- is typeset as [ and ](these variants are needed only
somtimes like in item[FooBar\LBr xx \Lbr]. Usually [ ] will work.
- \Percent
- is typeset as %.
- \noindent
-
- \hline
- inside a Table
environment.
- \item
- inside a itemize,
enumerate,
or description
environment.
- \today
- 14 January 1998 (see also the rcsinfo
LaTeX package).
Translation of User Defined Macros
The user macro translation file (given by the [ -ttransfile ])
contains 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:
-
Comments start with a # up to the end of the line.
-
For a macro \foo with no arguments, the following code must be specified:
$manMacro{'foo'} = '...';
$htmlMacro{'foo'} = '...';
$texiMacro{'foo'} = '...';
where ... 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.
-
For a macro \foo{..} with one argument, the following code must be
specified:
$manMacro1a{'foo'} = '...';
$manMacro1b{'foo'} = '...';
$htmlMacro1a{'foo'} = '...';
$htmlMacro1b{'foo'} = '...';
$texiMacro1a{'foo'} = '...';
$texiMacro1b{'foo'} = '...';
where ... is the translation. The 1a code is used before the argument,
while 1b is typeset after the argument is set.
-
For a macro \foo{..}{..} with two arguments, the following code must be
specified:
$manMacro2a{'foo'} = '...';
$manMacro2b{'foo'} = '...';
$manMacro2c{'foo'} = '...';
$htmlMacro2a{'foo'} = '...';
$htmlMacro2b{'foo'} = '...';
$htmlMacro2c{'foo'} = '...';
$texiMacro2a{'foo'} = '...';
$texiMacro2b{'foo'} = '...';
$texiMacro2c{'foo'} = '...';
where ... is the translation. The 2a code is used before the first
argument, 2b between the two arguments and 2c is typeset after the
second argument is set.
-
The file latex2man.trans
contains some example code.
General Remarks
-
Empty lines are typeset as paragraph separators.
-
The arguments of the LaTeX commands must not be split over several lines.
-
Do not nest calls to macros or environments.
-
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.
Version
Version: 1.1 of 1998/01/14.
Copyright
Copyright © 1998, Jürgen Vollmer.
This is PostCardWare,
which means
-
You may use this software without a fee, as it is, and at your own risk.
-
You may distribute this software only without any changes and complete
(i.e. with this copyright notice and the following files
latex2man.sty
latex2man,
latex2man.tex,
latex2man.trans,
Makefile,
README,
and INSTALL).
-
You may not sell this software.
-
If you have bug fixes, enhancements, new ideas, etc. send them to me.
-
If you find this software useful, send me a postcard.
Author
Dr. Jürgen Vollmer
Viktoriastraße 15
D-76133 Karlsruhe
Email: Juergen.Vollmer@acm.org
WWW: http://www.cocolab.de/vollmer.