Table of Contents
txt2man - convert flat ASCII text to man page format
txt2man [-hpTX] [-t mytitle] [-P pname] [-r rel] [-s sect]
[-v vol] [-I txt] [-B txt] [ifile]
txt2man converts the input text into nroff/troff standard man(7)
macros used to format Unix manual pages. Nice pages can be generated specially
for commands (section 1 or 8) or for C functions reference (sections 2,
3), with the ability to recognize and format command and function names,
flags, types and arguments.
txt2man is also able to recognize and format
sections, paragraphs, lists (standard, numbered, description, nested),
cross references and literal display blocks.
If input file ifile is omitted,
standard input is used. Result is displayed on standard output.
Here is how
text patterns are recognized and processed:
- Sections
- These headers are
defined by a line in upper case, starting column 1. If there is one or more
leading spaces, a sub-section will be generated instead.
- Paragraphs
- They
must be separated by a blank line, and left aligned.
- Tag list
- The item
definition is separated from the item description by at least 2 blank spaces,
even before a new line, if definition is too long. Definition will be emphasized
by default.
- Bullet list
- Bullet list items are defined by the first word
being "-" or "*" or "o".
- Enumerated list
- The first word must be a number
followed by a dot.
- Literal display blocks
- This paragraph type is used to
display unmodified text, for example source code. It must be separated by
a blank line, and be indented. It is primarily used to format unmodified
source code. It will be printed using fixed font whenever possible (troff).
- Cross references
- A cross reference (another man page) is defined by a
word followed by a number in parenthesis.
Special sections:
- NAME
- The function
or command name and short description are set in this section.
- SYNOPSIS
- This section receives a special treatment to identify command name, flags
and arguments, and propagate corresponding attributes later in the text.
If a C like function is recognized (word immediately followed by an open
parenthesis), txt2man will print function name in bold font, types in normal
font, and variables in italic font. The whole section will be printed using
a fixed font family (courier) whenever possible (troff).
It is a good practice
to embed documentation into source code, by using comments or constant
text variables. txt2man allows to do that, keeping the document source readable,
usable even without further formatting (i.e. for online help) and easy to
write. The result is high quality and standard complying document.
-
-h
- The option -h displays help.
- -P pname
- Set pname as project name in header.
Default to uname -s.
- -p
- Probe title, section name and volume.
- -t mytitle
- Set
mytitle as title of generated man page.
- -r rel
- Set rel as project name and
release.
- -s sect
- Set sect as section in heading, ususally a value from 1
to 8.
- -v vol
- Set vol as volume name, i.e. "Unix user 's manual".
- -I txt
- Italicize
txt in output. Can be specified more than once.
- -B txt
- Emphasize (bold) txt
in output. Can be specified more than once.
- -T
- Text result previewing using
PAGER, usually more(1)
.
- -X
- X11 result previewing using gxditview(1)
.
-
PAGER
- name of paging command, usually more(1)
, or less(1)
. If not set falls
back to more(1)
.
Try this command to format this text itself:
$ txt2man -h 2>&1 | txt2man -T
To obtain an overall good formating of output document, keep paragraphs
indented correctly. If you have unwanted bold sections, search for multiple
spaces between words, which are used to identify a tag list (term followed
by a description). Choose also carefully the name of command line or function
parameters, as they will be emphasized each time they are encountered in
the document.
man(1)
, mandoc(7)
, rman(1)
, groff(1)
, more(1)
, gxditview(1)
,
troff(1)
.
- Automatic probe (-p option) works only if input is a regular
file (i.e. not stdin).
Marc Vertes <mvertes@free.fr>
Table of Contents