txt2man

txt2man(1)                                                          txt2man(1)



NAME
       txt2man - convert flat ASCII text to man page format

SYNOPSIS
       txt2man [-hpTX] [-t mytitle] [-P pname] [-r rel] [-s sect]
               [-v vol] [-I txt] [-B txt] [-d date] [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 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. 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.

       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.

       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 by a TAB. 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 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.

OPTIONS
       -h     The option -h displays help.

       -d date
              Set date in header. Defaults to current date.

       -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, usually 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).

ENVIRONMENT
       PAGER  name of paging command, usually more(1), or less(1). If not set
              falls back to more(1).

       SOURCE_DATE_EPOCH
              Unix timestamp that is used for date in header instead of
              current date.

EXAMPLES
       Try this command to format this text itself:

           $ txt2man -h 2>&1 | txt2man -T

       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:

           $ txt2man -d "15 May 2016" -t foo -r foo-1.1.0 -s 1 -v "show stars on screen" foo.txt > foo.1

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.

SEE ALSO
       man(1), mandoc(7), rman(1), groff(1), more(1), gxditview(1), troff(1).

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

AUTHOR
       Marc Vertes <mvertes@free.fr>



txt2man-1.6.0                   15 August 2016                      txt2man(1)