Overview

The man source pages are in groff format. They may be transformed to two distribution formats:

man pages: transform using groff man -Tutf8
html output: using the file tools/tcltk-man2html.tcl

The html output is used, to build the htmlhelp target of the makefile.vc build system.

Producing output for reading

Printed output

If you want printed output, you'll get something very good from the -Tpdf, -Tps or -Tdvi options to groff (depending on the version installed). While it isn't a primary target for us these days, it's what Tcl's documentation was always supposed to look like.

Plain text output

The best quality text output is with the -Tutf8 option to groff, though -Tascii also works; the ideal option depends on your system encoding. (The man command will use one of those.) The result is usually best piped straight into less.

Output for the web

Use the make html in the unix directory, which will build documentation trees for Tcl, Tk and all installed contrib packages. Assume you need an up-to-date version of Tcl installed on your local platform to run this.

The process may be started manually using:

tclsh tools/tcltk-man-html.tcl
  --help              print this help, then exit
  --version           print version number, then exit
  --srcdir=DIR        find tcl and tk source below DIR
  --htmldir=DIR       put generated HTML in DIR
  --tcl               build tcl help
  --tk                build tk help
  --useversion=ver    version of tcl/tk to search for
  --verbose=0/1       whether to print longer messages

Remark, that there is only one folder for tcl and tk. Tk must be in a folder beside tcl and the folder must be named "tk" + the value of "--version". Any DIR in the options should be in TCL notation with / as path separator.

Editing the documentation

2015-06-18 Donal K. Fellows posted on the core list the following text:

Editor

I use emacs but you can use anything you want I suppose. Probably best to not use MS Word; Notepad would be a better choice. :-)

99% of what you might ever want to do when just editing docs can be done without putting a lot of effort into rendering; that's what I usually do.

Special characters.

I have found that when trying to introduce some "fancy characters" (like å or ø) in the documentation the final html result fails to reproduce those correctly.

According to the groff_char man page (find the reference below) we see that:

    In the actual version, groff provides only 8-bit characters for
    direct input and named entities for further glyphs.  On ASCII
    platforms, input character codes in the range 0 to 127 (decimal)
    represent the usual 7-bit ASCII characters, while codes between 127
    and 255 are interpreted as the corresponding characters in the latin1
    (ISO-8859-1) code set by default.

This means we can introduce some "fancy chars" like:

å as \N'229' (or by virtue of having a named glyph for this: \[oa])
ø as \N'248' (or by virtue of having a named glyph for this: \[/o])

Check the groff_char man page for yours!

Check formatting

I check the formatting with 'groff -Tutf8 -man' and with 'make html' ( make html-tcl HTML_INSTALL_DIR=~/test/html) in the unix build tree (which doesn't use groff's -Thtml output mode because that sucks, or at least did a few years ago when I last had time to try it, and which requires an installed tclsh8.6). There's a release of groff for cygwin apparently (according to Google) so it ought to be usable for you.

Tcl's groff subset

The main thing to beware of is that we actually use a small subset of the full power of groff, augmented with a few of our own macros (defined and "documented" in man.macros). Please avoid using anything too exotic unless you update the HTML generator to support it. Because of this, ‘make html’ is actually the check to use; it's pretty strict about diagnostics.

I don't bother with the winhelp converter these days; the HTML is better (as in “more recently maintained”) and everyone has a reader for the format it produces.

Some additional resources:

Mentioned file: man.macros
Gnu roff: https://www.gnu.org/software/groff/
GNU roff manual: https://www.gnu.org/software/groff/manual/groff.html
Groff help: http://man7.org/linux/man-pages/man7/groff_man.7.html
Groff char help: http://man7.org/linux/man-pages/man7/groff_char.7.html

File structure:

Commands like .xx always at the beginning of a line.
Comands like \xx may be within the text.

Some used markup:

.SH "Text": Section header. Text included in html TOC.
.SS "Text": Subsection header. Text included in html TOC. Text must be in capital letters to be found by links.
.TP : Paragraph label, start of indented text, text included in html TOC. The paragraph label occupies the next source line. It is often followed by a line with a single . on it (which does nothing, but makes the nroff code easier to read).
\fBText\fR : Bold font
\fIText\fR : Italic font (\fR (for Roman font) must always follow)
.RS : Indent paragraph 3 to right start
.RE : Indent end
.PP : New line and reset font, margin and indent to default values
.fn, .fi : switch automatic line break off/on

We add the following markup ourselves (i.e., these are rules defined in the man.macros file):

.BS : Box Start. Puts this part in a box in some versions. (HTML version could do with updating to support this)
.BE : Box End.
.VS "Text": Mark as new version, "Text" describes version (marks as a change in some renderings, but not the HTML version at the moment)
.VE "Text": End of mark (the text is just a reminder)
.CS : Source code examples
.CE : Source code example end
.QW "Text": Quoted Word, puts the Text in magic quotes when rendered on systems that support that (such as html).
.PQ "Text": Parenthesized Quoted word; puts the Text in parentheses and magic quotes. Gets the spacing right which .QW doesn't in this case.

Cross references within the file

There is some magic about cross referencing. The following creates a link to a section header:

.SS "LINK TARGET"
...
See section \fBLINK TARGET\fR.

This linking only happens if the text after ".SS" is in capital caracters.

Tcl Source Code