Tcl Source Code

How to edit/test tcl man pages
Login

Overview

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

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:

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:

File structure:

Some used markup:

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

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.