Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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 dis-
       played on standard output.

       Here is how text	patterns are recognized	and processed:

       Sections
	      These headers are	defined	by a line in upper case, starting col-
	      umn  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 visualiza-
	      tion of the source text to be used to generate the manpage.

       Paragraphs
	      They must	be separated by	a blank	line, and left	aligned.   Al-
	      ternatively two blank spaces can be used to produce the same re-
	      sult. 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  ex-
	      ample  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	possi-
	      ble (troff).

       Cross references
	      A	cross reference	(another man page) is defined by a  word  fol-
	      lowed 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 at-
	      tributes 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 us-
	      ing 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  for-
       matting	(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 cur-
	      rent 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 pro-
       gram,  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	 para-
       graphs  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
       o  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.0			08 August 2020			    txt2man(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT | EXAMPLES | HINTS | SEE ALSO | BUGS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=txt2man&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help