From 5add2428204d8d6ff589a9679141d288cf421152 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 13 Nov 2008 17:43:59 +0000 Subject: new support script latex2man git-svn-id: svn://tug.org/texlive/trunk@11289 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/doc/support/latex2man/latex2man.tex | 758 +++++++++++++++++++++ 1 file changed, 758 insertions(+) create mode 100644 Master/texmf-dist/doc/support/latex2man/latex2man.tex (limited to 'Master/texmf-dist/doc/support/latex2man/latex2man.tex') diff --git a/Master/texmf-dist/doc/support/latex2man/latex2man.tex b/Master/texmf-dist/doc/support/latex2man/latex2man.tex new file mode 100644 index 00000000000..b4d02ad8f83 --- /dev/null +++ b/Master/texmf-dist/doc/support/latex2man/latex2man.tex @@ -0,0 +1,758 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Project: Documentation Tools +%% Descr: Latex --> MAN-page (groff -man), LATEX documentation +%% Author: Dr. Jürgen Vollmer, Juergen.Vollmer@informatik-vollmer.de +%% $Id: latex2man.tex,v 1.187 2008/11/11 07:21:18 vollmer Exp $ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% Latex2man is a tool to translate UNIX manual pages written with LaTeX into a +%% format understood by the UNIX man(1)-command. +%% Alternatively HTML or TexInfo code can be produced too. +%% Output of parts of the text may be supressed using the conditional text +%% feature. +%% +%% There is LaTeX package (latex2man.sty) used for writing the Man-page +%% and a PERL script (latex2man) doing the actual translation. +%% +%% Copyright (C) 1998, Dr. Juergen Vollmer +%% Viktoriastrasse 15, D-76133 Karlsruhe, Germany +%% Juergen.Vollmer@informatik-vollmer.de +%% License: +%% This program can be redistributed and/or modified under the terms +%% of the LaTeX Project Public License Distributed from CTAN +%% archives in directory macros/latex/base/lppl.txt; either +%% version 1 of the License, or any later version. +%% +%% If you find this software useful, please send me a postcard. +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\documentclass[english]{article} +\usepackage[latin1]{inputenc} +\usepackage{babel} +\usepackage{verbatim} + +%% do we have the `hyperref package? +\IfFileExists{hyperref.sty}{ + \usepackage[bookmarksopen,bookmarksnumbered]{hyperref} +}{} + +%% do we have the `fancyhdr' package? +\IfFileExists{fancyhdr.sty}{ +\usepackage[fancyhdr]{latex2man} +}{ +%% do we have the `fancyheadings' package? +\IfFileExists{fancyheadings.sty}{ +\usepackage[fancy]{latex2man} +}{ +\usepackage[nofancy]{latex2man} +\message{no fancyhdr or fancyheadings package present, discard it} +}} + +%% do we have the `rcsinfo' package? +\IfFileExists{rcsinfo.sty}{ +\usepackage[nofancy]{rcsinfo} +\rcsInfo $Id: latex2man.tex,v 1.187 2008/11/11 07:21:18 vollmer Exp $ +\setDate{\rcsInfoLongDate} +}{ +\setDate{2008/11/11} %%%% must be manually set, if rcsinfo is not present +\message{package rcsinfo not present, discard it} +} + +\setVersionWord{Version:} %%% that's the default, no need to set it. +\setVersion{1.23} + +\begin{document} + +\begin{Name}{1}{latex2man}{Dr.~J{\"u}rgen Vollmer}{Documentation Tools}{\LaTeX2man\\--\\ A Documentation Tool} + + \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, TexInfo, or \LaTeX\ code can be produced too. + Output of parts of the text may be suppressed using the conditional text + feature (for this, LaTeX generation may be used). +\end{Name} + +\section{Synopsis} +%%%%%%%%%%%%%%%%%% + +\Prog{latex2man} \oOptArg{-t}{transfile} + \oOpt{-HMTL} \oOpt{-h} \oOpt{-V} \oOptArg{-C}{name} \TEXIbr + \oOptArg{-a}{char} + \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}. + +Using the \Opt{-M} option, \Cmd{troff}{1} input is produced. + +Using the \Opt{-L} option, \LaTeX\ ouput can be produced, instead of +\Cmd{troff}{1}. + + +\section{Options} +%%%%%%%%%%%%%%%%% +\begin{Description}[\OptArg{-t}{transfile}]\setlength{\itemsep}{0cm} +\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 the name of the command). +\item[\Opt{-T}] Instead of producing output suitable for the \Cmd{man}{1} + command, TexInfo code is produced (despite 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{-L}] The \LaTeX\ source is written to the \Arg{outfile}. This is + useful in conjunction with the \OptArg{-C}{name} option. +\item[\OptArg{-C}{name}] Output the conditional text for \Arg{name}. If more + than one name should be given use quotes: \OptArg{-C}{'name1 name2 ...'}\\ + The following names are defined automatically: + \begin{itemize} + \item \Opt{-H} defines \texttt{HTML} + \item \Opt{-T} defines \texttt{TEXI} + \item \Opt{-M} defines \texttt{MAN} + \item \Opt{-L} defines \texttt{LATEX} + \end{itemize} + \item[\OptArg{-a}{char}] Is used only in conjunction with -T.\\ + Background:\\ + TexInfo ignores all blanks before the first word on a new line. In order + to produce some additional space before that word (using \Bs SP) some + character has to be printed before the additional space. By default this + is a . (dot). The \Arg{char} specifies an alternative for that first + character. Giving a blank to + \Opt{-a} supresses the indentation of a line.\\ + Note: only for the first \Bs SP of a series that \Arg{char} is printed. +\item[\Opt{-h}] Show a help text. +\item[\Opt{-V}] Show version information. +\end{Description} + +\section{Files} +%%%%%%%%%%%%%%% + +\begin{Description}\setlength{\itemsep}{0cm} +\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.cfg}] The configuration file for \Prog{Latex2man} + \LaTeX-package. +\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{fancyhdr.sty}] A \LaTeX\ package used to typeset head- and foot + lines. +\item[\File{rcsinfo.sty}] A \LaTeX\ package used to extract and use 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}\setlength{\itemsep}{0cm} +\item[fancy] use the \LaTeX\ package \texttt{fancyheadings}. +\item[fancyhdr] use the \LaTeX\ package \texttt{fancyhdr}. +\item[nofancy] neither the \LaTeX\ package \texttt{fancyheadings} nor + \texttt{fancyhdr} are used. +\end{description} + +The default option may be specified in the file \texttt{latex2man.cfg}. + +\subsection{Package Specific Environments} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +The following environments are provided by the package: +\begin{description}\setlength{\itemsep}{0cm} +\item[\Bs begin\{Name\}\{chapter\}\{name\}\{author\}\{info\}\{title\} ] The + \texttt{Name} environment takes five arguments: 1.\ the Man-page chapter, + 2.\ the name of the Man-page, 3.\ the author, 4.\ some short information + about the tool printed in the footline of the Man-page, and 5.\ a text + which is used as title, for HTML and \LaTeX\ (it's ignored for output of + the Man-page or TeXinfo. 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). (Note: all arguments of \Bs begin\{Name\} must + be written on one line). +\item[\Bs begin\{Table\}\Lbr width\Rbr\{columns\}] The \texttt{Table} + environment takes two arguments: the first optional one specifies + a width of the last column, the second one gives the number of columns. + For example: + + \verb+\begin{Table}[2cm]{3}+ \\ + \verb+ Here & am & I \\\hline+ \\ + \verb+ A 1 & A 2 & A 3 1 2 3 4 5 A 3 1 2 3 4 5 \\+ \\ + \verb+ B 1 & B 2 & B 3 \\+ \\ + \verb+\end{Table}+ + + will be typeset as: + + \begin{Table}[2cm]{3} + Here & am & I \\\hline + A 1 & A 2 & A 3 1 2 3 4 5 A 3 1 2 3 4 5\\ + B 1 & B 2 & B 3 \\ + \end{Table} + + If no optional \emph{width} argument is given, all entries are + typeset left justified. + The \emph{width} is a length measured absolutly in \emph{cm}. + Processing with \LaTeX\ a \verb+p{width}+ column is typeset + as last column. The translation to \Cmd{troff}{1} commands + results in a \texttt{lw(width)} column specification. Translating + to HTML and TexInfo ignores the \emph{width} parameter. + + \verb+\hline+ may be used. + + If the Man-page is formatted with \Cmd{troff}{1} and tables are used, the + \Cmd{tbl}{1} preprocessor should be called, usually by giving + a \Opt{-t} to the call of \Cmd{troff}{1}. When viewing the generated + manula page using \Cmd{man}{1}, \Cmd{tbl}{1} is called automatically. +\item[\Bs begin\{Description\}] is the same as \Bs begin\{description\} +\item[\Bs begin\{Description\}\Lbr label\Rbr] is similar to + \Bs begin\{description\}, but the item labels have at minimum the size + of the (optional) word \emph{label}. The difference is visible only + in the DVI and PDF-output, not in the troff, TexInfo or HTML output. + \begin{description} + \item[a] \Bar a \verb+\begin{description}+ + \item[ab] \Bar ab + \item[abc] \Bar abc + \end{description} + \begin{Description} + \item[a] \Bar a \verb+\begin{Description}+ + \item[ab] \Bar ab + \item[abc]\Bar abc + \end{Description} + \begin{Description}[ab] + \item[a] \Bar a \verb+\begin{Description}[aa]+ + \item[ab] \Bar ab + \item[abc] \Bar abc + \end{Description} +\end{description} + +\subsection{Accepted \LaTeX\ Environments} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +The following environments are accepted: +\begin{itemize}\setlength{\itemsep}{0cm} +\item \texttt{description} +\item \texttt{enumerate} +\item \texttt{itemize} +\item \texttt{verbatim} +\item \texttt{center} +\end{itemize} + +They may be nested: +\begin{itemize} +\item Itemize and nested center: + \begin{center} + A centered line.\\ + Another centered line. + \end{center} +\item Another item an nested enumerate + \begin{enumerate} + \item a + \item b + \end{enumerate} +\end{itemize} + + +\subsection{Package Specific Macros} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +The following commands are provided: +\begin{description}\setlength{\itemsep}{0cm} +\item[\Bs Opt\{option\}] Option: \verb+\Opt{-o}+ will be typeset as \Opt{-o}. +\item[\Bs Arg\{argument\}] Argument: \verb+\Arg{filename}+ will be typeset as + \Arg{filename}. +\item[\Bs OptArg\{option\}\{argument\}] Option with Argument:\\ + \verb+\OptArg{-o}{filename}+ will be typeset as \OptArg{-o}{filename}. +\item[\Bs OptoArg\{option\}\{argument\}] Option with optional Argument:\\ + \verb+\OptoArg{-o}{filename}+ will be + typeset as \OptoArg{-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 oOptoArg\{option\}\{argument\}] Optional option with optional + argument, e.g.\ + \verb+\oOptoArg{-o}{filename}+ will be typeset as \oOptoArg{-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 Bullet] us typeset as \Bullet. +\item[\Bs setVersion\{..\}] set \verb+..+ as version information. +\item[\Bs setVersionWord\{..\}] set \verb+..+ for the word \emph{Version:} in + the footline. The default is \verb+\setVersionWord{Version:}+. +\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@informatik-vollmer.de}+ is typeset as:\\ + \Email{Juergen.Vollmer@informatik-vollmer.de}. +\item[\Bs URL\{..\}] use to mark an URL: + \verb+\URL{http://www.foo.de/\Tilde vollmer}+ is typeset as + \URL{http://www.foo.de/\Tilde 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. +\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 LBr, \Bs RBr] is typeset as \LBr\ and \RBr\ (these variants are + needed when using \{ or \} as arguments to macros. +\item[\Bs Circum] is typeset as \Circum. +\item[\Bs Percent] is typeset as \Percent. +\item[\Bs TEXbr] If processed with \LaTeX\ causes a linebreak (i.e.\ is + equivalent to \Bs\Bs). In the output of \Prog{latex2man} this macro is + ignored. +\item[\Bs TEXIbr] If TexInfo output is generated, causes a linebreak (i.e.\ is + equivalent to \Bs\Bs), otherwise ignored. +\item[\Bs MANbr] If Man-Page output is generated, causes a linebreak (i.e.\ is + equivalent to \Bs\Bs), otherwise ignored. +\item[\Bs HTMLbr] If HTML output is generated, causes a linebreak (i.e.\ is + equivalent to \Bs\Bs), otherwise ignored. +\item[\Bs medskip] An empty line. +\item[\Bs SP] Produces some extra space, works also at the beginning of lines. + The code of the second line looks like: + \texttt{\Bs SP abc \Bs SP\Bs SP xx\Bs\Bs}:\\ + abc \SP\SP\SP xx\\ + \SP abc \SP\SP xx\\ + \SP\SP abc \SP xx + + Note: Due to some ``problems'' with TexInfo, the lines starting with + \texttt{\Bs SP} have a leading . (dot) in the TexInfo output, + see \OptArg{-a}{char}. +\end{description} + +\subsection{Accepted Macros from the rcsinfo Package} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{description}\setlength{\itemsep}{0cm} +\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}\setlength{\itemsep}{0cm} +\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{Synopsis}, + \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. + + Note: Do not use \LaTeX-macros in section names. +\item[\Bs subsection\{..\}] works as well as +\item[\Bs subsubsection\{..\}] those. +\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 of underline}. +\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[\$$<=$\$] is typeset as $<=$. +\item[\$$>=$\$] is typeset as $>=$. +\item[\$$=$\$] is typeset as $=$. +\item[\$$<>$\$] is typeset as $<>$. +\item[\$\Bs ge\$] is typeset as $\ge$. +\item[\$\Bs le\$] is typeset as $\le$. +\item[\$\Bs leftarrow\$] is typeset as $\leftarrow$. +\item[\$\Bs Leftarrow\$] is typeset as $\Leftarrow$. +\item[\$\Bs rightarrow\$] is typeset as $\rightarrow$. +\item[\$\Bs Rightarrow\$] is typeset as $\Rightarrow$. +\item[\Bs \{] is typeset as \{. +\item[\Bs \}] is typeset as \}. +\item[\Bs \$] is typeset as \$. +\item[\Bs \Dollar] is typeset as \Dollar, should be used inside macro + arguments. +\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 smaller blank -\,- (between the two -) +\item[\Bs -] is used to mark hyphenation in a word. +\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, + although it cannot be used at the beginning of a line to make indentation + (see the \texttt{\Bs SP} command). +\item[\Tilde] is typeset as a blank. +\item[\Bs copyright] is typeset as \copyright. +\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). +\item[\Bs ss,\Bs"a, ...] \Bs ss = \ss, \Bs"a = \"a, \Bs"o = \"o, \Bs"u = \"u, + \Bs"A = \"A, \Bs"O = \"O, \Bs"U = \"U. It is allowed to surround these + macros in \{ and \} in all places, even inside other macros, e.g. + \begin{verbatim} + \textbf{\"a\"o\"u\"A\"O\"U\ss} + \textbf{\"a}{\"o}{\"u}{\"A}{\"O}{\"U}{\ss}} + \textbf{äöüÄÖÜß} + \end{verbatim} + + \textbf{\"a\"o\"u\"A\"O\"U\ss {\"a}{\"o}{\"u}{\"A}{\"O}{\"U}{\ss} äöüÄÖÜß} + + If these letters are used in their LATIN-1 8-bit coding, they are + translated into the equivalent letter of the desired output format. + E.g. \texttt{Ä} becomes \texttt{\Ä}; in HTML and \texttt{@"A} + in texinfo. +\end{description} + +\subsection{Conditional Text} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\Prog{latex2man} preprocesses the \LaTeX\ input to allow text to be used +conditionally. A special sort of \LaTeX\ comment is used for that purpose. +\begin{itemize}\setlength{\itemsep}{0cm} +\item \Percent@\Percent\ IF \emph{condition} \Percent@\Percent +\item \Percent@\Percent\ ELSE \Percent@\Percent +\item \Percent@\Percent\ END-IF \Percent@\Percent +\end{itemize} + +A line must contain only such a comment and nothing else. \emph{condition} is +a boolean expression containing ``names'' and operators. The names given with +the \OptArg{-C}{name} option have the value ``true'', while all other names +occuring in the expression are assumed to be ``false''. If the evaluation of +the boolean expression results in the value ``true'', the text in the +``then''-part is used and the text in the optional ``else''-part is skipped +(and vice versa). The \texttt{IF/ELSE/END-IF} may be nested. As boolean +operators the following are allowed: + +\begin{Table}{2} +\Bar\Bar & boolean or \\ +\&\& & boolean and \\ +! & negation +\end{Table} + +( and ) for grouping are allowed. + +\noindent +For example:\\ +\Percent@\Percent\ IF abc \Percent@\Percent\\ +\verb+ +abc set\\ +\verb+ +\Percent@\Percent\ IF xyz \Percent@\Percent\\ +\verb+ +xyz set\\ +\verb+ +\Percent@\Percent\ ELSE \Percent@\Percent\\ +\verb+ +xyz NOT set\\ +\verb+ +\Percent@\Percent\ END-IF \Percent@\Percent\\ +\Percent@\Percent\ ELSE \Percent@\Percent\\ +\verb+ +abc NOT set\\ +\verb+ +\Percent@\Percent\ IF xyz \Bar\Bar\ !XYZ \Percent@\Percent\\ +\verb+ +xyz OR !XYZ set\\ +\verb+ +\Percent@\Percent\ ELSE \Percent@\Percent\\ +\verb+ +xyz OR !XYZ NOT set\\ +\verb+ +\Percent@\Percent\ END-IF \Percent@\Percent\\ +\Percent@\Percent\ END-IF \Percent@\Percent + +\noindent +Run this manual page through \Prog{latex2man} with e.g.\ +\OptArg{-C}{'abc XYZ'} and have a look to the generated output. +(If simply running the \LaTeX-document\ through \LaTeX, all lines are shown in the +.dvi file).\\ +%@% IF abc %@% + abc set\\ + %@% IF xyz %@% + xyz set\\ + %@% ELSE %@% + xyz NOT set\\ + %@% END-IF %@% +%@% ELSE %@% + abc NOT set\\ + %@% IF xyz || !XYZ %@% + xyz OR !XYZ set\\ + %@% ELSE %@% + xyz OR !XYZ NOT set + %@% END-IF %@% +%@% END-IF %@% + +\noindent +To check the conditional text feature, when \Prog{latex2man} is called with +\begin{description} +\item[\OptArg{-C}{HTML}] the lines 1a, 2b, 3b, and 4b; +\item[\OptArg{-C}{TEXI}] the lines 1b, 2a, 3b, and 4b; +\item[\OptArg{-C}{MAN}] the lines 1b, 2b, 3a, and 4b; +\item[\OptArg{-C}{LATEX}] the lines 1b, 2b, 3b, and 4a; +\item[calling \LaTeX\ without preprocessing] all lines +\end{description} +should be shown: + +%@% IF HTML %@% +1a. This text occurs only when viewing the HTML output. + +%@% ELSE %@% +1b. The HTML conditional was not set. + +%@% END-IF %@% + +%@% IF TEXI %@% +2a. This text occurs only when viewing the TEXI output + +%@% ELSE %@% +2b. The TEXI conditional was not set. + +%@% END-IF %@% + +%@% IF MAN %@% +3a. This text occurs only when viewing the MAN output + +%@% ELSE %@% +3b. The MAN conditional was not set. + +%@% END-IF %@% + +%@% IF LATEX %@% +4a. This text occurs only when viewing the LATEX output + +%@% ELSE %@% +4b. The LATEX conditional was not set. + +%@% END-IF %@% + +\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}\setlength{\itemsep}{0cm} +\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: + \begin{description}\setlength{\itemsep}{0cm} + \item[Translation to Man-Pages]\TEXbr + \verb+$manMacro{'foo'} = '...';+ + \item[Translation to HTML]\TEXbr + \verb+$htmlMacro{'foo'} = '...';+ + \item[Translation to TexInfo]\TEXbr + \verb+$texiMacro{'foo'} = '...';+ + \end{description} + + where \verb+...+ is the translation. + +\item For a macro \verb+\foo{..}+ with one argument, the following code must be + specified: + \begin{description}\setlength{\itemsep}{0cm} + \item[Translation to Man-Pages]\TEXbr + \verb+$manMacro1a{'foo'} = '...';+\\ + \verb+$manMacro1b{'foo'} = '...';+ + \item[Translation to HTML]\TEXbr + \verb+$htmlMacro1a{'foo'} = '...';+\\ + \verb+$htmlMacro1b{'foo'} = '...';+ + + \item[Translation to TexInfo]\TEXbr + \verb+$texiMacro1a{'foo'} = '...';+\\ + \verb+$texiMacro1b{'foo'} = '...';+ + \end{description} + + 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: + \begin{description}\setlength{\itemsep}{0cm} + \item[Translation to Man-Pages]\TEXbr + \verb+$manMacro2a{'foo'} = '...';+\\ + \verb+$manMacro2b{'foo'} = '...';+\\ + \verb+$manMacro2c{'foo'} = '...';+ + \item[Translation to HTML]\TEXbr + \verb+$htmlMacro2a{'foo'} = '...';+\\ + \verb+$htmlMacro2b{'foo'} = '...';+\\ + \verb+$htmlMacro2c{'foo'} = '...';+ + \item[Translation to TexInfo]\TEXbr + \verb+$texiMacro2a{'foo'} = '...';+\\ + \verb+$texiMacro2b{'foo'} = '...';+\\ + \verb+$texiMacro2c{'foo'} = '...';+ + \end{description} + + 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{Verbatim Environment} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{verbatim} +This + {is} + \texttt{a} + $test$ + _of_ +verbatim + and no @* TexInfo command +\end{verbatim} + +\subsection{Subsection works} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +This is a \verb+\subsection+. + +\subsubsection{Subsubsection works} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +This is a \verb+\subsubsection+. + +\subsubsection{Subsubsection still works} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +This is another \verb+\subsubsection+. + + +\subsection{General Remarks} +%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{enumerate}\setlength{\itemsep}{0cm} +\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. +\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. +\item \Prog{latex2man} requires Perl version $>=$ 5.0004\_03. +\item If you want to install the system with the distributed \File{Makefile}, + you need GNU-\Prog{make}. If you don't have it, you should execute the + steps shown in the \File{Makefile} manually. +\end{enumerate} + +\subsection{Some Bug Fix Tests} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% TODO: HTML: a blank line after \begin{description} should not emit a

+\begin{description} +\item[Leading . and '] +%%%%%%%%%%%%%%%%%%%%%% +Now leading . and ' in generation troff output should work propperly, +since a \verb+\&+ is added. Therfore the \verb+\Dot+ macro has been deleted.\\ +Thanks to \Email{Frank.Schilder@Mathematik.Tu-Ilmenau.De}.\\ +Testcase 1: +\begin{description} +\item['\Bs n'] ... +\end{description} +Testcase 2:\\ +\File{.foobar} +Testcase 3:\\ +\Dots + +abc \Dots abc . efg ' 123 + +\item[\% in verbatim] A \% in a \Bs verb and verbatim-environment was not + emitted correctly. Thanks to Aleksey Nogin \Email{nogin@cs.caltech.edu} + for the bug report and bug fix. + +\verb+ % abc+ + +\begin{verbatim} + % abc % +\end{verbatim} + +but ignore comments following this: % this should be ignored + +\end{description} + +\section{Requirements} +%%%%%%%%%%%%%%%%%%%%%% + +\begin{description}\setlength{\itemsep}{0cm} +\item[Perl] \Prog{latex2man} requires Perl version $>=$ 5.0004\_03. +\item[Make] If you want to install the system with the distributed + \File{Makefile}, you need GNU-\Prog{make}. If you don't have it, you + should execute the steps shown in the \File{Makefile} manually. +\item[\LaTeX] \LaTeX 2e is required. +\end{description} + +\section{Changes} +%@% IF LATEX %@% +{\small\verbatiminput{CHANGES}} +%@% ELSE %@% +Please check the file \URL{latex2man-CHANGES} for the list of changes. +%@% END-IF %@% + +\section{Version} +%%%%%%%%%%%%%%%%% + +Version: \Version\ of \Date. + +\section{License and Copyright} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{description} +\item[Copyright] \copyright\ 1998, Dr.~Jürgen Vollmer, Viktoriastraße 15, + D-76133 Karlsruhe, Germany, \Email{Juergen.Vollmer@informatik-vollmer.de} + + + The actual version of \Prog{Latex2man} may be found on my homepage\\ + \URL{http://www.informatik-vollmer.de/software/latex2man.html}. + +\item[License] This program can be redistributed and/or modified under the + terms of the LaTeX Project Public License Distributed from CTAN archives + in directory \File{macros/latex/base/lppl.txt}; either version 1 of the + License, or any later version. + +\item[Misc] If you find this software useful, please send me a postcard from + the place where you are living. +\end{description} + +\section{Author} +%%%%%%%%%%%%%%%% + +\noindent +Dr.~Jürgen Vollmer \\ +Viktoriastraße 15 \\ +D-76133 Karlsruhe \\ +Email: \Email{Juergen.Vollmer@informatik-vollmer.de} \\ +WWW: \URL{http://www.informatik-vollmer.de}. + +\LatexManEnd + +\end{document} -- cgit v1.2.3