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!

***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.<<br>>
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]).<<br>>
The ''version'' is the version of Tcl/extension where the page last had substantive changes.<<br>>
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.<<br>>
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'').<<br>>
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.

----
!!!!!!
%| [Category Word and Text Processing] |%
!!!!!!