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.

----
**Producing a Print-Quality Version of a Tcl Manpage**
======
set filename [file normalize .../path/to/namespace.n];  # namespace.n for example purposes only
cd [file dirname $filename]
exec groff -Tpdf -man [file tail $filename] >output.pdf
======

Note that you only need to be in the same directory if you are using the documentation in the Tcl/Tk source checkouts. It's not necessary with the official source distributions as those have references to external files resolved during the build of the distribution.
----
**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.<<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.

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: <<br>>
`.IP \(bu 3`

To do a descriptive list item (like <DT><DD> in [HTML]) do this: <<br>>
`.TP` <<br>>
''one line text that is the "name" of the item'' <<br>>
`.` <<br>>
''rest of paragraph describing the item''

The dot on a line by its own is optional, but makes things much more readable for you.

To do a table, start with `.DS`, finish with `.DE`, use a single line per row, and use real tab characters to separate the columns. (You might also need to use a `.ta` directive after the .DS to make things look right, but this is best tuned if you've got nroff or groff to hand!)

***Within a paragraph***
You can make a sequence of letters '''bold''' (used for literal parts of commands) by wrapping in `\fB`...`\fR` sequences, and you can make a sequence of letters ''italic'' (used for varying parts of commands) by wrapping in `\fI`...`\fR` sequences. Put a literal backslash in by using `\e` and any dash that isn't an inter-word hyphen (such as just used there) should be written as `\-` so that it is of a better length. (There are other hyphens available for advanced users; consult your *roff format documentation for details.)

Put a sequence of characters in (appropriate) quotes using the `.QW` directive, like this:
===
This is some text with some
.QW "quoted bits"
in the middle.
===
which renders like:
    :   This is some text with some “quoted bits” in the middle.

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