1txt2man(1) txt2man(1)
2
6 txt2man - convert flat ASCII text to man page format
7
9 txt2man [-hpTX] [-t mytitle] [-P pname] [-r rel] [-s sect]
10 [-v vol] [-I txt] [-B txt] [-d date] [ifile]
11
13 txt2man converts the input text into nroff/troff standard man(7) macros
14 used to format Unix manual pages. Nice pages can be generated specially
15 for commands (section 1 or 8) or for C functions reference (sections 2,
16 3), with the ability to recognize and format command and function
17 names, flags, types and arguments.
18 txt2man is also able to recognize and format sections, paragraphs,
20 lists (standard, numbered, description, nested), cross references and
21 literal display blocks.
22 If input file ifile is omitted, standard input is used. Result is dis‐
24 played on standard output.
25 Here is how text patterns are recognized and processed:
27 Sections
29 These headers are defined by a line in upper case, starting col‐
30 umn 1. If there is one or more leading spaces, a sub-section
31 will be generated instead.
32 Paragraphs
34 They must be separated by a blank line, and left aligned.
35 Tag list
37 The item definition is separated from the item description by at
38 least 2 blank spaces, even before a new line, if definition is
39 too long. Definition will be emphasized by default.
40 Bullet list
42 Bullet list items are defined by the first word being "-" or "*"
43 or "o".
44 Enumerated list
46 The first word must be a number followed by a dot.
47 Literal display blocks
49 This paragraph type is used to display unmodified text, for
50 example source code. It must be separated by a blank line, and
51 be indented. It is primarily used to format unmodified source
52 code. It will be printed using fixed font whenever possible
53 (troff).
54 Cross references
56 A cross reference (another man page) is defined by a word fol‐
57 lowed by a number in parenthesis.
58 Special sections:
60 NAME The function or command name and short description are set in
62 this section.
63 SYNOPSIS
65 This section receives a special treatment to identify command
66 name, flags and arguments, and propagate corresponding
67 attributes later in the text. If a C like function is recognized
68 (word immediately followed by an open parenthesis), txt2man will
69 print function name in bold font, types in normal font, and
70 variables in italic font. The whole section will be printed
71 using a fixed font family (courier) whenever possible (troff).
72 It is a good practice to embed documentation into source code, by using
74 comments or constant text variables. txt2man allows to do that, keeping
75 the document source readable, usable even without further formatting
76 (i.e. for online help) and easy to write. The result is high quality
77 and standard complying document.
78
80 -h The option -h displays help.
81 -d date
83 Set date in header. Defaults to current date.
84 -P pname
86 Set pname as project name in header. Default to uname -s.
87 -p Probe title, section name and volume.
89 -t mytitle
91 Set mytitle as title of generated man page.
92 -r rel Set rel as project name and release.
94 -s sect
96 Set sect as section in heading, ususally a value from 1 to 8.
97 -v vol Set vol as volume name, i.e. "Unix user 's manual".
99 -I txt Italicize txt in output. Can be specified more than once.
101 -B txt Emphasize (bold) txt in output. Can be specified more than once.
103 -T Text result previewing using PAGER, usually more(1).
105 -X X11 result previewing using gxditview(1).
107
109 PAGER name of paging command, usually more(1), or less(1). If not set
110 falls back to more(1).
111
113 Try this command to format this text itself:
114 $ txt2man -h 2>&1 | txt2man -T
116
118 To obtain an overall good formating of output document, keep paragraphs
119 indented correctly. If you have unwanted bold sections, search for mul‐
120 tiple spaces between words, which are used to identify a tag list (term
121 followed by a description). Choose also carefully the name of command
122 line or function parameters, as they will be emphasized each time they
123 are encountered in the document.
124
126 man(1), mandoc(7), rman(1), groff(1), more(1), gxditview(1), troff(1).
127
129 · Automatic probe (-p option) works only if input is a regular file
130 (i.e. not stdin).
131
133 Marc Vertes <mvertes@free.fr>
134txt2man-1.5.6 16 March 2011 txt2man(1)