troff reads text files (written using an instream formatting language, see [nroff]) and formats the text for typesetting or laser printing.
The most common modern implementation is [GNU] [groff].
The connection to Tcl is that the Tcl [man] pages - the only documentation that comes with the source - uses the *roff markup formatting language.
----
**Simple Tutorial on Writing a Tcl Manpage**
Firstly, always remember to look at other manual pages to see what sort of things belong! (And note that the purpose of this tutorial is writing a manual page that renders nicely and which Tcl can properly convert to nice HTML pages like you see on http://www.tcl.tk/man/ and not general manual page writing.)
***The Header***
Tcl manual pages start with:
===
.so man.macros
.TH ''name'' ''section'' ''version'' Tcl "Tcl Built-In Commands"
.BS
.SH NAME
''names'' \- ''description''
.SH SYNOPSIS
.nf
''summary of commands/functions''
.fi
.BE
===
The ''name'' is the name of the manual page.<
>
The ''section'' is (typically) '''n''' for commands (e.g. [lsearch]), '''3''' for [C] API functions (e.g. [Tcl_SetObjResult]), or '''1''' for programs/shells (e.g. [tclsh]).<
>
The ''version'' is the version of Tcl/extension where the page last had substantive changes.<
>
The ''names'' is a comma-separated list of all the commands or functions documented on the page, and must (along with the ''description'') be on a single line.<
>
The ''description'' is a very short description of what the commands/functions do (e.g. [lsearch]'s page says "See if a list contains a particular element"), and must be on a single line (along with the ''names'').<
>
The ''summary of commands/functions'' is what it says; check some examples for how to write them.
***Body Sections***
Sections start with a:
===
.SH "''title of section in caps''"
===
The quotes can be omitted if the title is a single word. If you want a subsection instead, use `.SS` instead of `.SH`
The following sections are normal for a Tcl manual page (and in this order):
NAME: Part of the header matter. Contents of section ''must'' follow idiomatic pattern since this is the part that [apropos] searches for.
SYNOPSIS: Part of the header matter. Quick summary for those people who never read very far into a page!
ARGUMENTS: Part of the header matter (not listed above). Table of C function argument descriptions; only for pages in section 3.
DESCRIPTION: General description of the command or function. Can be in quite a bit of depth, but the first paragraph should normally give the gist properly.
EXAMPLES: Idiomatic use of the command or function.
SEE ALSO: References to other manual pages (or books or papers or webpages or ...)
KEYWORDS: Comma-separated list of words people might look for the page under.
Other sections may be added between DESCRIPTION and EXAMPLES, and many pages omit the EXAMPLES still.
Note that [widget] manual pages have additional sections.
***Within a Section***
Paragraphs (normally) start with a `.PP` directive (`.LP` and `.P` are equivalent). You indent a section of paragraphs by putting `.RS` before them and `.RE` afterwards.
To do a bulleted list, start each item in the list with: <
>
`.IP \(bu 3`
To do a descriptive list item (like