.\" Text automatically generated by txt2man
.TH txt2man 1 "20 August 2021" "txt2man-1.7.1" ""
.SH NAME
\fBtxt2man \fP- convert flat ASCII text to man page format
.SH SYNOPSIS
.nf
.fam C
\fBtxt2man\fP [\fB-hpTX\fP] [\fB-t\fP \fImytitle\fP] [\fB-P\fP \fIpname\fP] [\fB-r\fP \fIrel\fP] [\fB-s\fP \fIsect\fP]
        [\fB-v\fP \fIvol\fP] [\fB-I\fP \fItxt\fP] [\fB-B\fP \fItxt\fP] [\fB-d\fP \fIdate\fP] [\fIifile\fP]
.fam T
.fi
.fam T
.fi
.SH DESCRIPTION
\fBtxt2man\fP converts the input text into nroff/troff standard \fBman\fP(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.
.PP
\fBtxt2man\fP is also able to recognize and format sections, paragraphs,
lists (standard, numbered, description, nested), cross references and
literal display blocks.
.PP
If input file \fIifile\fP is omitted, standard input is used. Result is
displayed on standard output.
.PP
Here is how text patterns are recognized and processed:
.TP
.B
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. Optionally, the
Section name can be preceded by a blank line. This is useful
for a better visualization of the source text to be used to
generate the manpage.
.TP
.B
Paragraphs
They must be separated by a blank line, and left aligned.
Alternatively two blank spaces can be used to produce the
same result. This option will provide a better visualization
of the source text to be used to generate the manpage.
.TP
.B
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.
.TP
.B
Bullet list
Bullet list items are defined by the first word being "-"
or "*" or "o".
.TP
.B
Enumerated list
The first word must be a number followed by a dot.
.TP
.B
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 by a TAB. It is primarily used to format
unmodified source code. It will be printed using fixed font
whenever possible (troff).
.TP
.B
Cross references
A cross reference (another man page) is defined by a word
followed by a number in parenthesis.
.PP
Special sections:
.TP
.B
NAME
The function or command name and short description are set in
this section.
.TP
.B
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), \fBtxt2man\fP 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).
.PP
It is a good practice to embed documentation into source code, by using
comments or constant text variables. \fBtxt2man\fP allows one 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.
.SH OPTIONS
.TP
.B
\fB-h\fP
The option \fB-h\fP displays help.
.TP
.B
\fB-d\fP \fIdate\fP
Set \fIdate\fP in header. Defaults to current \fIdate\fP.
.TP
.B
\fB-P\fP \fIpname\fP
Set \fIpname\fP as project name in header. Default to uname \fB-s\fP.
.TP
.B
\fB-p\fP
Probe title, section name and volume.
.TP
.B
\fB-t\fP \fImytitle\fP
Set \fImytitle\fP as title of generated man page.
.TP
.B
\fB-r\fP \fIrel\fP
Set \fIrel\fP as project name and release.
.TP
.B
\fB-s\fP \fIsect\fP
Set \fIsect\fP as section in heading, usually a value from 1 to 8.
.TP
.B
\fB-v\fP \fIvol\fP
Set \fIvol\fP as volume name, i.e. "Unix user 's manual".
.TP
.B
\fB-I\fP \fItxt\fP
Italicize \fItxt\fP in output. Can be specified more than once.
.TP
.B
\fB-B\fP \fItxt\fP
Emphasize (bold) \fItxt\fP in output. Can be specified more than once.
.TP
.B
\fB-T\fP
Text result previewing using PAGER, usually \fBmore\fP(1).
.TP
.B
\fB-X\fP
X11 result previewing using \fBgxditview\fP(1).
.SH ENVIRONMENT
.TP
.B
PAGER
name of paging command, usually \fBmore\fP(1), or \fBless\fP(1). If not set
falls back to \fBmore\fP(1).
.TP
.B
SOURCE_DATE_EPOCH
Unix timestamp that is used for \fIdate\fP in header instead
of current \fIdate\fP.
.SH EXAMPLES
Try this command to format this text itself:
.PP
.nf
.fam C
    $ txt2man -h 2>&1 | txt2man -T

.fam T
.fi
The following command will generate a manpage level 1 to foo-1.1.0 program,
from foo.txt file, used as source code to previously mentioned manpage:
.PP
.nf
.fam C
    $ txt2man -d "15 May 2016" -t foo -r foo-1.1.0 -s 1 -v "show stars on screen" foo.txt > foo.1
.fam T
.fi
.SH HINTS
To obtain an overall good formatting 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.
.SH SEE ALSO
\fBman\fP(1), \fBmandoc\fP(7), \fBrman\fP(1), \fBgroff\fP(1), \fBmore\fP(1), \fBgxditview\fP(1), \fBtroff\fP(1).
.SH BUGS
.IP \(bu 3
Automatic probe (\fB-p\fP option) works only if input is a regular file (i.e.
not stdin).
.SH AUTHOR
Marc Vertes <mvertes@free.fr>