1LATEX2MAN(1) Documentation Tools LATEX2MAN(1)
2
6 Latex2man is a tool to translate UNIX manual pages written with LaTeX‐
7 into a format understood by the UNIX man(1)-command. Alternatively
8 HTML, TexInfo, or LaTeX code can be produced too. Output of parts of
9 the text may be suppressed using the conditional text feature (for
10 this, LaTeX generation may be used).
11
13 latex2man [-ttransfile] [-cCSSfile] [-HMTL] [-h] [-V] [-Cname] [-achar]
14 infile outfile
15
17 Latex2man reads the file infile and writes outfile. The input must be
18 a LaTeX document using the latex2man LaTeXpackage. Latex2man trans‐
19 lates that document into the troff(1) format using the -man macro pack‐
20 age.
21 Using the -H option, HTML code can be produced, instead of troff(1).
23 With this option you can, optionally, specify a CSSfile as an argument.
24 CSS (Cascading Style Sheets) allows you to control the appearance of
25 the resulting HTML page. See below for the names of CSS classes that
26 are included in the HTML tags as attributes.
27 Using the -T option, TexInfo code can be produced, instead of troff(1).
29 Using the -M option, troff(1) input is produced.
31 Using the -L option, LaTeX ouput can be produced, instead of troff(1).
33
35 -ttransfile
36 Translation for user defined LaTeX macros.
37 -cCSSfile
39 If you use the -H you can also specify a file that contains CSS
40 style sheets. The link to the CSS file is inserted into the gen‐
41 eratedHTML output using the specified CSSfile filename.
42 -M
44 Produce output suitable for the man(1) command (default).
45 -H
47 Instead of producing output suitable for the man(1) command,
48 HTML code is produced (despite the name of the command).
49 -T
51 Instead of producing output suitable for the man(1) command,
52 TexInfo code is produced (despite the name of the command). The
53 generated .texi-file may be processed with makeinfo(1) (to pro‐
54 duce an .info-file) which in turn may be installed using
55 install-info(1). The Info tags @dircategory and @direntry are
56 provided.
57 -L
59 The LaTeX source is written to the outfile. This is useful in
60 conjunction with the -Cname option.
61 -Cname
63 Output the conditional text for name. If more than one name
64 should be given use quotes: -C'name1 name2 ...'
65 The following names are defined automatically:
66 * -H defines HTML
68 * -T defines TEXI
70 * -M defines MAN
72 * -L defines LATEX
74 -achar
76 Is used only in conjunction with -T.
77 Background:
78 TexInfo ignores all blanks before the first word on a new line.
79 In order to produce some additional space before that word
80 (using \SP) some character has to be printed before the addi‐
81 tional space. By default this is a . (dot). The char specifies
82 an alternative for that first character. Giving a blank to -a
83 supresses the indentation of a line.
84 Note: only for the first \SP of a series that char is printed.
85 -h
87 Show a help text.
88 -V
90 Show version information.
91
93 latex2man.tex
94 The LaTeX file containing this Man-page.
95 latex2man.inc
97 A file read with \input{..} .
98 latex2man.sty
100 The LaTeX package defining the environments and commands.
101 latex2man.cfg
103 The configuration file for Latex2man LaTeX-package.
104 latex2man.css
106 File containing example CSS definitions.
107 latex2man.trans
109 File containing example translations of user defined LaTeX
110 macros.
111 fancyheadings.sty
113 A LaTeX package used to typeset head- and foot lines.
114 fancyhdr.sty
116 A LaTeX package used to typeset head- and foot lines.
117 rcsinfo.sty
119 A LaTeX package used to extract and use RCS version control
120 information in LaTeX documents.
121 latex2man.pdf
123 The PDF version of this document.
124
126 LaTeX,TexInfo, troff(1), groff(1), makeinfo(1).
127
129 The LaTeX package latex2man is used to write the Man-pages with
130 LaTeX.Since we translate into other text formats, not all LaTeX stuff
131 can be translated.
132 PACKAGE OPTIONS
134 The latex2man package accepts the following options:
135 fancy use the LaTeX package fancyheadings.
137 fancyhdr
139 use the LaTeX package fancyhdr.
140 nofancy
142 neither the LaTeX package fancyheadings nor fancyhdr are used.
143 The default option may be specified in the file latex2man.cfg.
145 PACKAGE SPECIFIC ENVIRONMENTS
147 The following environments are provided by the package:
148 \begin{Name}{chapter}{name}{author}{info}{title}
150 The Name environment takes five arguments: 1. the Man-page
151 chapter, 2. the name of the Man-page, 3. the author, 4. some
152 short information about the tool printed in the footline of the
153 Man-page, and 5. a text which is used as title, for HTML and
154 LaTeX (it's ignored for output of the Man-page or TeXinfo. The
155 Name environment must be the first environment in the document.
156 Processing starts with this environment. Any text before this is
157 ignored (exception: the setVersion and setDate commands). (Note:
158 all arguments of \begin{Name} must be written on one line).
159 \begin{Table}[width]{columns}
161 The Table environment takes two arguments: the first optional
162 one specifies a width of the last column, the second one gives
163 the number of columns. For example:
164 \begin{Table}[2cm]{3}
166 Here & am & I \\\hline
167 A 1 & A 2 & A 3 1 2 3 4 5 A 3 1 2 3 4 5 \\
168 B 1 & B 2 & B 3 \\
169 \end{Table}
170 will be typeset as:
172 Here am I
174 ──────────────────────
175 A 1 A 2 A 3 1 2
176 3 4 5 A
177 3 1 2 3
178 4 5
179 B 1 B 2 B 3
180 If no optional width argument is given, all entries are typeset left
182 justified. The width is a length measured absolutly in cm. Processing
183 with LaTeX a p{width} column is typeset as last column. The translation
184 to troff(1) commands results in a lw(width) column specification.
185 Translating to HTML and TexInfo ignores the width parameter.
186 \hline may be used.
188 If the Man-page is formatted with troff(1) and tables are used, the
190 tbl(1) preprocessor should be called, usually by giving a -t to the
191 call of troff(1). When viewing the generated manula page using man(1),
192 tbl(1) is called automatically.
193 \begin{Description}
195 is the same as \begin{description}
196 \begin{Description}[label]
198 is similar to \begin{description}, but the item labels have at
199 minimum the size of the (optional) word label. The difference
200 is visible only in the DVI and PDF-output, not in the troff,
201 TexInfo or HTML output.
202 a |a \begin{description}
204 ab |ab
206 abc |abc
208 a |a \begin{Description}
210 ab |ab
212 abc |abc
214 a |a \begin{Description}[aa]
216 ab |ab
218 abc |abc
220 ACCEPTED LaTeX ENVIRONMENTS
222 The following environments are accepted:
223 * description
225 * enumerate
227 * itemize
229 * verbatim
231 * center
233 They may be nested:
235 * Itemize and nested center:
237 A centered line.
238 Another centered line.
239 * Another item an nested enumerate
242 1. a
244 2. b
246 PACKAGE SPECIFIC MACROS
248 The following commands are provided:
249 \Opt{option}
251 Option: \Opt{-o} will be typeset as -o.
252 \Arg{argument}
254 Argument: \Arg{filename} will be typeset as filename.
255 \OptArg{option}{argument}
257 Option with Argument:
258 \OptArg{-o}{filename} will be typeset as -ofilename.
259 \OptoArg{option}{argument}
261 Option with optional Argument:
262 \OptoArg{-o}{filename} will be typeset as -o[filename].
263 \oOpt{option}
265 Optional option, e.g. \oOpt{-o} will be typeset as [-o].
266 \oArg{argument}
268 Optional argument, e.g. \oArg{filename} will be typeset as
269 [filename].
270 \oOptArg{option}{argument}
272 Optional option with argument, e.g.
273 \oOptArg{-o}{filename} will be typeset as [-ofilename].
274 \oOptoArg{option}{argument}
276 Optional option with optional argument, e.g.
277 \oOptoArg{-o}{filename} will be typeset as [-o[filename]].
278 \File{filename}
280 used to typeset filenames, e.g. \File{filename} will be typeset
281 as filename.
282 \Prog{prog}
284 used to typeset program names, e.g. \Prog{latex2man} will be
285 typeset as latex2man.
286 \Cmd{command}{chapter}
288 used to typeset references to other commands, e.g.
289 \Cmd{latex2man}{1} will be typeset as latex2man(1).
290 \Bar is typeset as |.
292 \Bs (BackSlash) is typeset as \.
294 \Tilde is typeset as a ~.
296 \Dots is typeset as ...
298 \Bullet
301 us typeset as *.
302 \setVersion{..}
304 set .. as version information.
305 \setVersionWord{..}
307 set .. for the word Version: in the footline.
308 The default is \setVersionWord{Version:}.
309 \Version
311 returns the version information.
312 \setDate{..}
314 sets .. as date information.
315 \Date returns the date information.
317 \Email{..}
319 use to mark an Email address:
320 \Email{Juergen.Vollmer@informatik-vollmer.de} is typeset as:
321 Juergen.Vollmer@informatik-vollmer.de.
322 \URL{..}
324 use to mark an URL: \URL{http://www.foo.de/\Tilde vollmer} is
325 typeset as
326 http://www.foo.de/~vollmer.
327 \LatexManEnd
329 the input file is read and processed until reading end-of-file
330 or
331 \LatexManEnd (at the beginning of a line). LaTeXignores this
332 command.
333 \Lbr, \Rbr
335 is typeset as [ and ] (these variants are needed only somtimes
336 like in
337 \item[FooBar\LBr xx \Lbr]. Usually [ ] will work.
338 \LBr, \RBr
340 is typeset as { and } (these variants are needed when using { or
341 } as arguments to macros.
342 \Circum
344 is typeset as ^.
345 \Percent
347 is typeset as %.
348 \TEXbr If processed with LaTeX causes a linebreak (i.e. is equivalent
350 to \\).In the output of latex2man this macro is ignored.
351 \TEXIbr
353 If TexInfo output is generated, causes a linebreak (i.e. is
354 equivalent to \\),otherwise ignored.
355 \MANbr If Man-Page output is generated, causes a linebreak (i.e. is
357 equivalent to \\),otherwise ignored.
358 \HTMLbr
360 If HTML output is generated, causes a linebreak (i.e. is equiv‐
361 alent to \\),otherwise ignored.
362 \medskip
364 An empty line.
365 \SP Produces some extra space, works also at the beginning of lines.
367 The code of the second line looks like: \SP abc \SP\SP xx\\:
368 abc xx
369 abc xx
370 abc xx
371 Note: Due to some ``problems'' with TexInfo, the lines starting with
373 \SP have a leading . (dot) in the TexInfo output, see -achar.
374 ACCEPTED MACROS FROM THE RCSINFO PACKAGE
376 \rcsInfo $Id ...$
377 if the LaTeX package rcsinfo is used, this command is used to
378 extract the date of the Man-page.
379 \rcsInfoLongDate
381 if the LaTeX package rcsinfo is used, this command is used to
382 typeset the date coded in the $Id ..$ string.
383 ACCEPTED LaTeX MACROS
385 The following standard LaTeX commands are accepted:
386 \section{..}
388 The section macro takes one argument: the name of the Man-page
389 section. Each Man-page consists of several sections. Usually
390 there are the following sections in a Man-page: Name (special
391 handling as environment, c.f. above), Synopsis, Description,
392 Options, Files, See Also, Diagnostics, Return Values, Bugs,
393 Author, version, etc.
394 Synopsis must be the first section after the Name environment.
396 Note: Do not use LaTeX-macrosin section names.
398 \subsection{..}
400 works as well as
401 \subsubsection{..}
403 those.
404 \emph{..}
406 \emph{example} is typeset as example.
407 \textbf{..}
409 \textbf{example} is typeset as example.
410 \texttt{..}
412 \texttt{example} is typeset as example.
413 \underline{..}
415 \underline{example} is typeset as example of underline .
416 \date{..}
418 uses .. as date.
419 \verb+..+
421 but only + is allowed as delimiter.
422 $<$ is typeset as <.
424 $>$ is typeset as >.
426 $<=$ is typeset as <=.
428 $>=$ is typeset as >=.
430 $=$ is typeset as =.
432 $<>$ is typeset as <>.
434 $\ge$ is typeset as $>=$.
436 $\le$ is typeset as $<=$.
438 $\leftarrow$
440 is typeset as $<--$.
441 $\Leftarrow$
443 is typeset as $<==$.
444 $\rightarrow$
446 is typeset as $-->$.
447 $\Rightarrow$
449 is typeset as $==>$.
450 \{ is typeset as {.
452 \} is typeset as }.
454 \$ is typeset as $.
456 \$ is typeset as $,should be used inside macro
458 arguments.
459 \_ is typeset as _.
461 \& is typeset as &.
463 \# is typeset as #.
465 \% is typeset as %.
467 \, is typeset as smaller blank - - (between the two -)
469 \- is used to mark hyphenation in a word.
471 \\ is typeset as a linebreak or marks the end of a column in the
473 Table environment.
474 \ (a \ followed by a blank) is typeset as a blank,
476 although it cannot be used at the beginning of a line to make
477 indentation (see the \SP command).
478 ~ is typeset as a blank.
480 \copyright
482 is typeset as (C).
483 \noindent
485 \hline inside a Table environment.
487 \item inside a itemize, enumerate, or description environment.
489 \today 25 November 2018(see also the rcsinfo LaTeXpackage).
491 \ss,\"a, ...
493 \ss = ß, \"a= ä, \"o= ö, \"u= ü, \"A= Ä, \"O= Ö, \"U= Ü. It is
494 allowed to surround these macros in { and } in all places, even
495 inside other macros, e.g.
496 \textbf{\"a\"o\"u\"A\"O\"U\ss}
497 \textbf{\"a}{\"o}{\"u}{\"A}{\"O}{\"U}{\ss}}
498 \textbf{äöüÄÖÜß}
499 äöüÄÖÜß äöüÄÖÜß äöüÄÖÜß
502 If these letters are used in their LATIN-1 8-bit coding, they are
504 translated into the equivalent letter of the desired output format.
505 E.g. Ä becomes Ä in HTML and @"A in texinfo.
506 \input{..}
508 Read and process the given filename.
509 Please note: the name of the LaTeX-macrosand its arguments must be con‐
511 tained in one line.
512 CONDITIONAL TEXT
514 latex2man preprocesses the LaTeX input to allow text to be used condi‐
515 tionally. A special sort of LaTeX comment is used for that purpose.
516 * %@% IF condition %@%
518 * %@% ELSE %@%
520 * %@% END-IF %@%
522 A line must contain only such a comment and nothing else. condition is
524 a boolean expression containing ``names'' and operators. The names
525 given with the -Cname option have the value ``true'', while all other
526 names occuring in the expression are assumed to be ``false''. If the
527 evaluation of the boolean expression results in the value ``true'', the
528 text in the ``then''-part is used and the text in the optional
529 ``else''-part is skipped (and vice versa). The IF/ELSE/END-IF may be
530 nested. As boolean operators the following are allowed:
531 ( and ) for grouping are allowed.
533 For example:
535 %@% IF abc %@%
536 abc set
537 %@% IF xyz %@%
538 xyz set
539 %@% ELSE %@%
540 xyz NOT set
541 %@% END-IF %@%
542 %@% ELSE %@%
543 abc NOT set
544 %@% IF xyz || !XYZ %@%
545 xyz OR !XYZ set
546 %@% ELSE %@%
547 xyz OR !XYZ NOT set
548 %@% END-IF %@%
549 %@% END-IF %@%
550 Run this manual page through latex2man with e.g. -C'abc XYZ' and have
552 a look to the generated output. (If simply running the LaTeX-document
553 through LaTeX,all lines are shown in the .dvi file).
554 abc NOT set
555 xyz OR !XYZ set
556 To check the conditional text feature, when latex2man is called with
558 -CHTML
560 the lines 1a, 2b, 3b, and 4b;
561 -CTEXI
563 the lines 1b, 2a, 3b, and 4b;
564 -CMAN
566 the lines 1b, 2b, 3a, and 4b;
567 -CLATEX
569 the lines 1b, 2b, 3b, and 4a;
570 calling LaTeX without preprocessing
572 all lines
573 should be shown:
575 1b. The HTML conditional was not set.
577 2b. The TEXI conditional was not set.
579 3a. This text occurs only when viewing the MAN output
581 4b. The LATEX conditional was not set.
583 TRANSLATION OF USER DEFINED MACROS
585 The user macro translation file (given by the [-ttransfile]) contains
586 Perl commands specifying the translation of LaTeX macros defined by the
587 user. These macros may have none, one or two arguments. The following
588 code is expected:
589 * Comments start with a # up to the end of the line.
591 * For a macro \foo with no arguments, the following code must be
593 specified:
594 Translation to Man-Pages
596 $manMacro{'foo'} = '...';
597 Translation to HTML
599 $htmlMacro{'foo'} = '...';
600 Translation to TexInfo
602 $texiMacro{'foo'} = '...';
603 where ... is the translation.
605 * For a macro \foo{..} with one argument, the following code must
607 be specified:
608 Translation to Man-Pages
610 $manMacro1a{'foo'} = '...';
611 $manMacro1b{'foo'} = '...';
612 Translation to HTML
614 $htmlMacro1a{'foo'} = '...';
615 $htmlMacro1b{'foo'} = '...';
616 Translation to TexInfo
618 $texiMacro1a{'foo'} = '...';
619 $texiMacro1b{'foo'} = '...';
620 where ... is the translation. The 1a code is used before the
622 argument, while 1b is typeset after the argument is set.
623 * For a macro \foo{..}{..} with two arguments, the following code
625 must be specified:
626 Translation to Man-Pages
628 $manMacro2a{'foo'} = '...';
629 $manMacro2b{'foo'} = '...';
630 $manMacro2c{'foo'} = '...';
631 Translation to HTML
633 $htmlMacro2a{'foo'} = '...';
634 $htmlMacro2b{'foo'} = '...';
635 $htmlMacro2c{'foo'} = '...';
636 Translation to TexInfo
638 $texiMacro2a{'foo'} = '...';
639 $texiMacro2b{'foo'} = '...';
640 $texiMacro2c{'foo'} = '...';
641 where ... is the translation. The 2a code is used before the
643 first argument, 2b between the two arguments and 2c is typeset
644 after the second argument is set.
645 * The file latex2man.trans contains some example code.
647 VERBATIM ENVIRONMENT
649 This
650 {is}
651 \texttt{a}
652 $test$
653 _of_
654 verbatim
655 <this is no HTML tag> and no @* TexInfo command
656 SUBSECTION WORKS
659 This is a \subsection.
660 Subsubsection works
662 This is a \subsubsection.
663 Subsubsection still works
665 This is another \subsubsection.
666 GENERAL REMARKS
668 1. Empty lines are typeset as paragraph separators.
669 2. The arguments of the LaTeX commands must not be split over sev‐
671 eral lines.
672 3. Do not nest calls to macros.
674 4. Except the mentioned environment and macros, the usage of other
676 LaTeX environments or macros are not translated. Their usage
677 will cause garbage in the output.
678 5. latex2man requires Perl version >= 5.0004_03.
680 6. If you want to install the system with the distributed Makefile,
682 you need GNU-make. If you don't have it, you should execute the
683 steps shown in the Makefile manually.
684
686 The table below shows the names of CSS classes that will be included in
687 the HTML tags as attributes. You can specify the CSS style properties
688 in the CSSfile for these classes:
689 HTML tag Class Style applies to
691 body the body of the HTML page
692 h1 titlehead the title at the top of the HTML
693 page specified as an argument to
694 the Name environment
695 h4 authorhead the author at the top of the HTML
696 page specified as an argument to
697 the Name environment
698 h4 datehead the date at the top of the HTML
699 page
700 h4 versionhead the man page version at the top
701 of the HTML page specified as an
702 argument to the setVersion macro
703 h2 sectionname a section title specified as an
704 argument to the section macro
705 h4 subsectionname a subsection title specified as
706 an argument to the subsection
707 macro
708 h5 subsubsectionname a subsubsection title specified
709 as an argument to the subsubsec‐
710 tion macro
711 font progname a program name specified as an
712 argument to the Prog macro
713 font filename a file name specified as an argu‐
714 ment to the File macro
715 font commandname a command name specified as an
716 argument to the Cmd macro
717 font textstyle all text that is not an argument
718 to some LaTeX or latex2man macro
719 font optstyle a name of an option specified as
720 an argument to the Opt, oOpt,
721 OptArg, oOptArg or oOptoArg
722 macros
723 font argstyle a name of an argument specified
724 as an argument to the Arg, oArg,
725 OptArg, oOptArg or oOptoArg
726 macros
727 a, font urlstyle a URL specified as an argument to
728 the URL macro
729 a, font urlstyle.link subclass of urlstyle class
730 a, font urlstyle.visited subclass of urlstyle class
731 a, font urlstyle.hover subclass of urlstyle class
732 a, font emailstyle an email specified as an argument
733 to the Email macro
734 a, font emailstyle.link subclass of emailstyle class
735 a, font emailstyle.visited subclass of emailstyle class
736 a, font emailstyle.hover subclass of emailstyle class
737 table tablestyle a table specified as a Table
738 environment
739 tr rowstyle a row of a table specified as a
740 Table environment
741 td cellstyle a cell of a table specified as a
742 Table environment
743
745 Leading . and '
746 Now leading . and ' in generation troff output should work prop‐
747 perly, since a \& is added. Therfore the \Dot macro has been
748 deleted.
749 Thanks to Frank.Schilder@Mathematik.Tu-Ilmenau.De.
750 Testcase 1:
751 '\n' ...
753 Testcase 2:
755 .foobar Testcase 3:
756 ...
757 abc ... abc . efg ' 123
759 %in verbatim
761 A % in a \verb and verbatim-environment was not emitted cor‐
762 rectly. Thanks to Aleksey Nogin nogin@cs.caltech.edu for the bug
763 report and bug fix.
764 % abc
766 % abc %
768 but ignore comments following this:
771
773 Perl latex2man requires Perl version >= 5.0004_03.
774 Make If you want to install the system with the distributed Makefile,
776 you need GNU-make. If you don't have it, you should execute the
777 steps shown in the Makefile manually.
778 LaTeX LaTeX2e is required.
780
782 Please check the file latex2man-CHANGES for the list of changes and
783 acknowledgment to people contributing bugfixes or enhancements.
784
786 Version: 1.29 of 2018/11/25.
787
789 Copyright
790 (C)1998, Dr. Jürgen Vollmer, Am Rennbuckel 21, D-76185 Karls‐
791 ruhe, Germany,
792 Juergen.Vollmer@informatik-vollmer.de
793 The most recent version of Latex2man may be found on my homepage
795 http://www.informatik-vollmer.de/software/latex2man.html.
796 License
798 This program can be redistributed and/or modified under the
799 terms of the LaTeX Project Public License Distributed from CTAN
800 archives in directory macros/latex/base/lppl.txt; either version
801 1 of the License, or any later version.
802 Misc If you find this software useful, please send me a postcard from
804 the place where you are living.
805
807 Dr. Jürgen Vollmer
808 Am Rennbuckel 21
809 D-76185 Karlsruhe
810 Email: Juergen.Vollmer@informatik-vollmer.de
811 WWW: http://www.informatik-vollmer.de.
812Documentation Tools 2018/11/25 LATEX2MAN(1)