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. Optionally, the Section name can be
32 preceded by a blank line. This is useful for a better visualiza‐
33 tion of the source text to be used to generate the manpage.
34 Paragraphs
36 They must be separated by a blank line, and left aligned. Al‐
37 ternatively two blank spaces can be used to produce the same re‐
38 sult. This option will provide a better visualization of the
39 source text to be used to generate the manpage.
40 Tag list
42 The item definition is separated from the item description by at
43 least 2 blank spaces, even before a new line, if definition is
44 too long. Definition will be emphasized by default.
45 Bullet list
47 Bullet list items are defined by the first word being "-" or "*"
48 or "o".
49 Enumerated list
51 The first word must be a number followed by a dot.
52 Literal display blocks
54 This paragraph type is used to display unmodified text, for ex‐
55 ample source code. It must be separated by a blank line and be
56 indented by a TAB. It is primarily used to format unmodified
57 source code. It will be printed using fixed font whenever possi‐
58 ble (troff).
59 Cross references
61 A cross reference (another man page) is defined by a word fol‐
62 lowed by a number in parenthesis.
63 Special sections:
65 NAME The function or command name and short description are set in
67 this section.
68 SYNOPSIS
70 This section receives a special treatment to identify command
71 name, flags and arguments, and propagate corresponding at‐
72 tributes later in the text. If a C like function is recognized
73 (word immediately followed by an open parenthesis), txt2man will
74 print function name in bold font, types in normal font, and
75 variables in italic font. The whole section will be printed us‐
76 ing a fixed font family (courier) whenever possible (troff).
77 It is a good practice to embed documentation into source code, by using
79 comments or constant text variables. txt2man allows one to do that,
80 keeping the document source readable, usable even without further for‐
81 matting (i.e. for online help) and easy to write. The result is high
82 quality and standard complying document.
83
85 -h The option -h displays help.
86 -d date
88 Set date in header. Defaults to current date.
89 -P pname
91 Set pname as project name in header. Default to uname -s.
92 -p Probe title, section name and volume.
94 -t mytitle
96 Set mytitle as title of generated man page.
97 -r rel Set rel as project name and release.
99 -s sect
101 Set sect as section in heading, usually a value from 1 to 8.
102 -v vol Set vol as volume name, i.e. "Unix user 's manual".
104 -I txt Italicize txt in output. Can be specified more than once.
106 -B txt Emphasize (bold) txt in output. Can be specified more than once.
108 -T Text result previewing using PAGER, usually more(1).
110 -X X11 result previewing using gxditview(1).
112
114 PAGER name of paging command, usually more(1), or less(1). If not set
115 falls back to more(1).
116 SOURCE_DATE_EPOCH
118 Unix timestamp that is used for date in header instead of cur‐
119 rent date.
120
122 Try this command to format this text itself:
123 $ txt2man -h 2>&1 | txt2man -T
125 The following command will generate a manpage level 1 to foo-1.1.0 pro‐
127 gram, from foo.txt file, used as source code to previously mentioned
128 manpage:
129 $ txt2man -d "15 May 2016" -t foo -r foo-1.1.0 -s 1 -v "show stars on screen" foo.txt > foo.1
131
133 To obtain an overall good formatting of output document, keep para‐
134 graphs indented correctly. If you have unwanted bold sections, search
135 for multiple spaces between words, which are used to identify a tag
136 list (term followed by a description). Choose also carefully the name
137 of command line or function parameters, as they will be emphasized each
138 time they are encountered in the document.
139
141 man(1), mandoc(7), rman(1), groff(1), more(1), gxditview(1), troff(1).
142
144 • Automatic probe (-p option) works only if input is a regular file
145 (i.e. not stdin).
146
148 Marc Vertes <mvertes@free.fr>
149txt2man-1.7.1 22 July 2023 txt2man(1)