diff options
author | Karl Berry <karl@freefriends.org> | 2008-11-13 17:43:59 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2008-11-13 17:43:59 +0000 |
commit | 5add2428204d8d6ff589a9679141d288cf421152 (patch) | |
tree | fcc87e4b9c091a2c4d62ea40401b79db218f7e16 /Master/texmf-dist/doc/support/latex2man/latex2man.txt | |
parent | 6ff046c12b6896c6b7ace34d964ace11ef5059ed (diff) |
new support script latex2man
git-svn-id: svn://tug.org/texlive/trunk@11289 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/latex2man/latex2man.txt')
-rw-r--r-- | Master/texmf-dist/doc/support/latex2man/latex2man.txt | 758 |
1 files changed, 758 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/latex2man/latex2man.txt b/Master/texmf-dist/doc/support/latex2man/latex2man.txt new file mode 100644 index 00000000000..2ded2fa1000 --- /dev/null +++ b/Master/texmf-dist/doc/support/latex2man/latex2man.txt @@ -0,0 +1,758 @@ +LATEX2MAN(1) Documentation Tools LATEX2MAN(1) + + + +NAME + Latex2man is a tool to translate UNIX manual pages written with LaTeX- + into a format understood by the UNIX 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). + + +SYNOPSIS + latex2man [-ttransfile] [-HMTL] [-h] [-V] [-Cname] [-achar] infile out- + file + + +DESCRIPTION + Latex2man reads the file infile and writes outfile. The input must be + a LaTeX document using the latex2man LaTeXpackage. Latex2man trans- + lates that document into the troff(1) format using the -man macro pack- + age. + + 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). + + Using the -M option, troff(1) input is produced. + + Using the -L option, LaTeX ouput 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 the name of the command). + + -T Instead of producing output suitable for the man(1) command, + TexInfo code is produced (despite the name of the command). The + generated .texi-file may be processed with makeinfo(1) (to pro- + duce an .info-file) which in turn may be installed using + install-info(1). The Info tags @dircategory and @direntry are + provided. + + -L The LaTeX source is written to the outfile. This is useful in + conjunction with the -Cname option. + + -Cname Output the conditional text for name. If more than one name + should be given use quotes: -C'name1 name2 ...' + The following names are defined automatically: + + * -H defines HTML + + * -T defines TEXI + + * -M defines MAN + + * -L defines LATEX + + + -achar 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 \SP) some character has to be printed before the addi- + tional space. By default this is a . (dot). The char specifies + an alternative for that first character. Giving a blank to -a + supresses the indentation of a line. + Note: only for the first \SP of a series that char is printed. + + -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.cfg + The configuration file for Latex2man LaTeX-package. + + latex2man.trans + File containing example translations of user defined LaTeX + macros. + + fancyheadings.sty + A LaTeX package used to typeset head- and foot lines. + + fancyhdr.sty + A LaTeX package used to typeset head- and foot lines. + + rcsinfo.sty + A LaTeX package used to extract and use 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. + + fancyhdr + use the LaTeX package fancyhdr. + + nofancy + neither the LaTeX package fancyheadings nor fancyhdr are used. + + The default option may be specified in the file latex2man.cfg. + + + PACKAGE SPECIFIC ENVIRONMENTS + The following environments are provided by the package: + + \begin{Name}{chapter}{name}{author}{info}{title} + The 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 + 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). (Note: + all arguments of \begin{Name} must be written on one line). + + \begin{Table}[width]{columns} + The 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: + + \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} + + will be typeset as: + + + Here am I + ---------------------- + A 1 A 2 A 3 1 2 + 3 4 5 A + 3 1 2 3 + 4 5 + B 1 B 2 B 3 + + If no optional width argument is given, all entries are typeset left + justified. The width is a length measured absolutly in cm. Processing + with LaTeX a p{width} column is typeset as last column. The translation + to troff(1) commands results in a lw(width) column specification. + Translating to HTML and TexInfo ignores the width parameter. + + \hline may be used. + + If the Man-page is formatted with troff(1) and tables are used, the + tbl(1) preprocessor should be called, usually by giving a -t to the + call of troff(1). When viewing the generated manula page using man(1), + tbl(1) is called automatically. + + \begin{Description} + is the same as \begin{description} + + \begin{Description}[label] + is similar to \begin{description}, but the item labels have at + minimum the size of the (optional) word label. The difference + is visible only in the DVI and PDF-output, not in the troff, + TexInfo or HTML output. + + a |a \begin{description} + + ab |ab + + abc |abc + + + a |a \begin{Description} + + ab |ab + + abc |abc + + + a |a \begin{Description}[aa] + + ab |ab + + abc |abc + + + + ACCEPTED LaTeX ENVIRONMENTS + The following environments are accepted: + + * description + + * enumerate + + * itemize + + * verbatim + + * center + + They may be nested: + + * Itemize and nested center: + A centered line. + Another centered line. + + + * Another item an nested enumerate + + 1. a + + 2. b + + + + PACKAGE SPECIFIC MACROS + The following commands are provided: + + \Opt{option} + Option: \Opt{-o} will be typeset as -o. + + \Arg{argument} + Argument: \Arg{filename} will be typeset as filename. + + \OptArg{option}{argument} + Option with Argument: + \OptArg{-o}{filename} will be typeset as -ofilename. + + \OptoArg{option}{argument} + Option with optional Argument: + \OptoArg{-o}{filename} will be typeset as -o[filename]. + + \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]. + + \oOptoArg{option}{argument} + Optional option with optional argument, e.g. \oOp- + toArg{-o}{filename} will be typeset as [-o[filename]]. + + \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 ... + + + \Bullet + us typeset as *. + + \setVersion{..} + set .. as version information. + + \setVersionWord{..} + set .. for the word Version: in the footline. The default is + \setVersionWord{Version:}. + + \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@informatik-vollmer.de} is typeset as: + Juergen.Vollmer@informatik-vollmer.de. + + \URL{..} + use to mark an URL: \URL{http://www.foo.de/\Tilde vollmer} is + typeset as http://www.foo.de/~vollmer. + + \LatexManEnd + the input file is read and processed until reading end-of-file + or \LatexManEnd (at the beginning of a line). LaTeXignores this + command. + + \Lbr, \Rbr + is typeset as [ and ] (these variants are needed only somtimes + like in item[FooBar\LBr xx \Lbr]. Usually [ ] will work. + + \LBr, \RBr + is typeset as { and } (these variants are needed when using { or + } as arguments to macros. + + \Circum + is typeset as ^. + + \Percent + is typeset as %. + + \TEXbr If processed with LaTeX causes a linebreak (i.e. is equivalent + to \\).In the output of latex2man this macro is ignored. + + \TEXIbr + If TexInfo output is generated, causes a linebreak (i.e. is + equivalent to \\),otherwise ignored. + + \MANbr If Man-Page output is generated, causes a linebreak (i.e. is + equivalent to \\),otherwise ignored. + + \HTMLbr + If HTML output is generated, causes a linebreak (i.e. is equiv- + alent to \\),otherwise ignored. + + \medskip + An empty line. + + \SP Produces some extra space, works also at the beginning of lines. + The code of the second line looks like: \SP abc \SP\SP xx\\: + abc xx + abc xx + abc xx + + Note: Due to some ``problems'' with TexInfo, the lines starting with + \SP have a leading . (dot) in the TexInfo output, see -achar. + + + 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), Synopsis, Description, + Options, Files, See Also, Diagnostics, Return Values, Bugs, + Author, version, etc. + + Synopsis must be the first section after the Name environment. + + Note: Do not use LaTeX-macrosin section names. + + \subsection{..} + works as well as + + \subsubsection{..} + those. + + \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 of underline . + + \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 <>. + + $\ge$ is typeset as $>=$. + + $\le$ is typeset as $<=$. + + $\leftarrow$ + is typeset as $<--$. + + $\Leftarrow$ + is typeset as $<==$. + + $\rightarrow$ + is typeset as $-->$. + + $\Rightarrow$ + is typeset as $==>$. + + \{ is typeset as {. + + \} is typeset as }. + + \$ is typeset as $. + + \$ is typeset as $,should be used inside macro + arguments. + + \_ is typeset as _. + + \& is typeset as &. + + \# is typeset as #. + + \% is typeset as %. + + \, is typeset as smaller blank - - (between the two -) + + \- is used to mark hyphenation in a word. + + \\ 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, + although it cannot be used at the beginning of a line to make + indentation (see the \SP command). + + ~ is typeset as a blank. + + \copyright + is typeset as (C). + + \noindent + + \hline inside a Table environment. + + \item inside a itemize, enumerate, or description environment. + + \today 11 November 2008(see also the rcsinfo LaTeXpackage). + + \ss,\"a, ... + \ss = ß, \"a= ä, \"o= ö, \"u= ü, \"A= Ä, \"O= Ö, \"U= Ü. It is + allowed to surround these macros in { and } in all places, even + inside other macros, e.g. + \textbf{\"a\"o\"u\"A\"O\"U\ss} + \textbf{\"a}{\"o}{\"u}{\"A}{\"O}{\"U}{\ss}} + \textbf{äöüÄÖÜß} + + + äöüÄÖÜß äöüÄÖÜß äöüÄÖÜß + + 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. Ä becomes Ä in HTML and @"A in texinfo. + + + CONDITIONAL TEXT + latex2man preprocesses the LaTeX input to allow text to be used condi- + tionally. A special sort of LaTeX comment is used for that purpose. + + * %@% IF condition %@% + + * %@% ELSE %@% + + * %@% END-IF %@% + + A line must contain only such a comment and nothing else. condition is + a boolean expression containing ``names'' and operators. The names + given with the -Cname 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 IF/ELSE/END-IF may be + nested. As boolean operators the following are allowed: + + + + ( and ) for grouping are allowed. + + For example: + %@% 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 %@% + + Run this manual page through latex2man with e.g. -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). + abc NOT set + xyz OR !XYZ set + + To check the conditional text feature, when latex2man is called with + + -CHTML the lines 1a, 2b, 3b, and 4b; + + -CTEXI the lines 1b, 2a, 3b, and 4b; + + -CMAN the lines 1b, 2b, 3a, and 4b; + + -CLATEX + the lines 1b, 2b, 3b, and 4a; + + calling LaTeX without preprocessing + all lines + + should be shown: + + 1b. The HTML conditional was not set. + + 2b. The TEXI conditional was not set. + + 3a. This text occurs only when viewing the MAN output + + 4b. The LATEX conditional was not set. + + + 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: + + Translation to Man-Pages + $manMacro{'foo'} = '...'; + + Translation to HTML + $htmlMacro{'foo'} = '...'; + + Translation to TexInfo + $texiMacro{'foo'} = '...'; + + where ... is the translation. + + + * For a macro \foo{..} with one argument, the following code must + be specified: + + Translation to Man-Pages + $manMacro1a{'foo'} = '...'; + $manMacro1b{'foo'} = '...'; + + Translation to HTML + $htmlMacro1a{'foo'} = '...'; + $htmlMacro1b{'foo'} = '...'; + + + Translation to TexInfo + $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: + + Translation to Man-Pages + $manMacro2a{'foo'} = '...'; + $manMacro2b{'foo'} = '...'; + $manMacro2c{'foo'} = '...'; + + Translation to HTML + $htmlMacro2a{'foo'} = '...'; + $htmlMacro2b{'foo'} = '...'; + $htmlMacro2c{'foo'} = '...'; + + Translation to TexInfo + $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. + + + VERBATIM ENVIRONMENT + This + {is} + \texttt{a} + $test$ + _of_ + verbatim + <this is no HTML tag> and no @* TexInfo command + + + + SUBSECTION WORKS + This is a \subsection. + + + Subsubsection works + This is a \subsubsection. + + + Subsubsection still works + This is another \subsubsection. + + + GENERAL REMARKS + 1. Empty lines are typeset as paragraph separators. + + 2. The arguments of the LaTeX commands must not be split over sev- + eral lines. + + 3. Do not nest calls to macros. + + 4. 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. + + 5. latex2man requires Perl version >= 5.0004_03. + + 6. If you want to install the system with the distributed Makefile, + you need GNU-make. If you don't have it, you should execute the + steps shown in the Makefile manually. + + + SOME BUG FIX TESTS + Leading . and ' + Now leading . and ' in generation troff output should work prop- + perly, since a \& is added. Therfore the \Dot macro has been + deleted. + Thanks to Frank.Schilder@Mathematik.Tu-Ilmenau.De. + Testcase 1: + + '\n' ... + + Testcase 2: + .foobar Testcase 3: + ... + + abc ... abc . efg ' 123 + + + %in verbatim + A % in a \verb and verbatim-environment was not emitted cor- + rectly. Thanks to Aleksey Nogin nogin@cs.caltech.edu for the bug + report and bug fix. + + % abc + + % abc % + + + but ignore comments following this: + + +REQUIREMENTS + Perl latex2man requires Perl version >= 5.0004_03. + + Make If you want to install the system with the distributed Makefile, + you need GNU-make. If you don't have it, you should execute the + steps shown in the Makefile manually. + + LaTeX LaTeX2e is required. + + +CHANGES + Please check the file latex2man-CHANGES for the list of changes. + + +VERSION + Version: 1.23 of 2008/11/11. + + +LICENSE AND COPYRIGHT + Copyright + (C)1998, Dr. Jürgen Vollmer, Viktoriastraße 15, D-76133 Karl- + sruhe, Germany, Juergen.Vollmer@informatik-vollmer.de + + The actual version of Latex2man may be found on my homepage + http://www.informatik-vollmer.de/software/latex2man.html. + + + 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. + + + Misc If you find this software useful, please send me a postcard from + the place where you are living. + + +AUTHOR + Dr. Jürgen Vollmer + Viktoriastraße 15 + D-76133 Karlsruhe + Email: Juergen.Vollmer@informatik-vollmer.de + WWW: http://www.informatik-vollmer.de. + + + + +Documentation Tools 2008/11/11 LATEX2MAN(1) |