1txt2man(1)                                                          txt2man(1)
2
3
4

NAME

6       txt2man - convert flat ASCII text to man page format
7

SYNOPSIS

9       txt2man [-hpTX] [-t mytitle] [-P pname] [-r rel] [-s sect]
10               [-v vol] [-I txt] [-B txt] [-d date] [ifile]
11

DESCRIPTION

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
19       txt2man  is  also  able  to  recognize and format sections, paragraphs,
20       lists (standard, numbered, description, nested), cross  references  and
21       literal display blocks.
22
23       If  input file ifile is omitted, standard input is used. Result is dis‐
24       played on standard output.
25
26       Here is how text patterns are recognized and processed:
27
28       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
35       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
41       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
46       Bullet list
47              Bullet list items are defined by the first word being "-" or "*"
48              or "o".
49
50       Enumerated list
51              The first word must be a number followed by a dot.
52
53       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
60       Cross references
61              A cross reference (another man page) is defined by a  word  fol‐
62              lowed by a number in parenthesis.
63
64       Special sections:
65
66       NAME   The  function  or  command name and short description are set in
67              this section.
68
69       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
78       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

OPTIONS

85       -h     The option -h displays help.
86
87       -d date
88              Set date in header. Defaults to current date.
89
90       -P pname
91              Set pname as project name in header. Default to uname -s.
92
93       -p     Probe title, section name and volume.
94
95       -t mytitle
96              Set mytitle as title of generated man page.
97
98       -r rel Set rel as project name and release.
99
100       -s sect
101              Set sect as section in heading, usually a value from 1 to 8.
102
103       -v vol Set vol as volume name, i.e. "Unix user 's manual".
104
105       -I txt Italicize txt in output. Can be specified more than once.
106
107       -B txt Emphasize (bold) txt in output. Can be specified more than once.
108
109       -T     Text result previewing using PAGER, usually more(1).
110
111       -X     X11 result previewing using gxditview(1).
112

ENVIRONMENT

114       PAGER  name of paging command, usually more(1), or less(1). If not  set
115              falls back to more(1).
116
117       SOURCE_DATE_EPOCH
118              Unix  timestamp  that is used for date in header instead of cur‐
119              rent date.
120

EXAMPLES

122       Try this command to format this text itself:
123
124           $ txt2man -h 2>&1 | txt2man -T
125
126       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
130           $ txt2man -d "15 May 2016" -t foo -r foo-1.1.0 -s 1 -v "show stars on screen" foo.txt > foo.1
131

HINTS

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

SEE ALSO

141       man(1), mandoc(7), rman(1), groff(1), more(1), gxditview(1), troff(1).
142

BUGS

144       •  Automatic  probe  (-p  option) works only if input is a regular file
145          (i.e.  not stdin).
146

AUTHOR

148       Marc Vertes <mvertes@free.fr>
149
150
151
152txt2man-1.7.1                    22 July 2023                       txt2man(1)
Impressum