home | help 
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.	Alterna-
	    tively 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  fol-
	    lowed  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  func-
     tion  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.7.1			   2020-06-28			      txt2man(1)
home | help