troff

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 https://www.tcl-lang.org/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 <DT><DD> in HTML) do this:
.TP
one line text that is the "name" of the item
.
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.