Manual Reference Pages - txt2man (1)
NAME
txt2man - [DEVELOPER] convert flat ASCII text to manpage format
CONTENTS
Synopsis
Description
Options
Environment
Example
Hints
See Also
Bugs
Author
SYNOPSIS
txt2man [-hpTxX] [-t mytitle] [-P pname] [-r rel] [-s sect] [-v vol] [-I txt] [-B txt] [ifile]
DESCRIPTION
txt2man converts the input text into nroff/troff standard man(7) macros used to format Unix manual pages. Nice pages can be generated; particularly for commands (section 1 or 8) or for C functions (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 an input file ifile is omitted, standard input is used. The 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 in column 1. If there is one or more leading spaces, a sub-section will be generated instead. NOTE that a section resets the indent; so an uppercase line is ALWAYS the beginning of a section and will reset being in fixed space mode. Paragraphs They must be separated by a blank line, and consistently left aligned (all lines must have the same left margin). Tag list The item definition is separated from the item description by at least 2 blank spaces, even before a new line, if the 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" or "+". 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 will be printed using a fixed font whenever possible (troff). So that means you put a blank line above a code block and that there has to have been at least one previous line in the section to set the default indent and that the code must be indented relative to that line:
SECTION BEGINNING
Line to set the default paragraph indent
code starts indented with a blank line
| Cross references | |||||||
|
A cross reference (another manpage) is defined by a word
followed by a number in parenthesis.
Special sections:
| |||||||
OPTIONS
-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 manpage. -r rel Set rel as project name and release. -s sect Set sect as section in heading, usually a value from 1 to 8. -v vol Set vol as volume name, i.e. "Unix user ’s manual". -I txt Italicize text in output. Can be specified more than once. -B txt Emphasize (bold) text in output. Can be specified more than once. -T Text result previewing using PAGER, usually more(1). -X X11 result previewing using gxditview(1). -x Basic example input file
ENVIRONMENT
PAGER name of paging command, usually more(1), or less(1). If not set falls back to more(1).
EXAMPLE
Try this command to format this text itself:
$ txt2man -h 2>&1 | txt2man -T
HINTS
To obtain an overall good formatting of the 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). Also choose carefully the name of command line or function parameters, as they will be emphasized each time they are encountered in the document.
SEE ALSO
man(1), mandoc(7), rman(1), groff(1), more(1), gxditview(1), troff(1).
BUGS
o Automatic probe (-p option) works only if input is a regular file (i.e. not stdin). o Something wrong when use ellipsis ("...") o SYNOPSIS command [value(s)]causes problems with ().
o SYNOPSIS name ( a, b, c, d ) causes problems with (). Remove spaces and it is OK.
AUTHOR
Marc Vertes <mvertes@free.fr>
| txt2man (1) | March 11, 2021 |
