What's What in this TIP Formatter...

The formatter is divided into four sections whose responsibilities are relatively easy to describe.

tip.tcl

The code that runs the TIP formatter as a CGI script on my web-server. Should be relatively easy to localise to any server that supports CGI (and which has Tcl...)

parse.tcl

The code that performs basic parsing of the TIP format into paragraphs, understands the RFC822-like header, and provides support for iterating across the document set (foreachTIP) and obtaining the header info (and abstract section) of arbitrary TIP documents (getTIPDetails). Also includes a number of useful pre-defined regular expressions in global variables.

Also of note is the convert command which is great for people testing the formatting of their TIPs or developing a new formatter; if this file is run as a stand-alone Tcl script with an argument of the output file to generate (read the source for the format,) it intuits what file to convert from and format to generate and runs the converter for you.

tip*.tcl (various)

Formatters for individual output formats. Each should be contained within a reasonably obviously named file (e.g. tiphtml.tcl is the formatter for HTML) and should define a namespace within the global namespace with the same name as the root of the filename. Formatters should produce output by calling puts or puts -nonewline (with no channel parameter) and must define the following command:

• generateDocument headerAssocList bodyParagraphs

  Entry point to the formatter, which should take two parameters, an association list of header fields, and a list of paragraph descriptors for the body.

The easiest way of handling the document descriptors (IMHO) is to pass them one at a time to eval after the header has been generated. The currently defined document descriptors are:

• bulleting listLevel paragraphString

  First paragraph of a bulleted list at the given depth.

• continuation listLevel paragraphString

  Subsequent paragraphs of a list item (could be any of the three kinds of lists.) When not used in a list context, indicates that the paragraph is a quoted piece of text.

• description tagString listLevel paragraphString

  First paragraph of a descriptive list at the given depth, with tagString stating what is being described.

• enumeration tagString listLevel paragraphString

  First paragraph of a enumeration list at the given depth, with tagString giving the number of the item, or 1 to use the running item number for the current list.

• image imageDescription

  An image with caption (which can never be contained within a list.) The image reference can be separated from its caption using the regular expression in the global variable ImageRE. Though the image reference can be any URL, it should normally be a simple name without extension or path to allow for maximum portability.

• index indexType ?errorKind?

  A request to generate a list of the TIP documents in the archive of the specified kind. Implementations must support "medium" indices and should also support "short" and "long" indices too. If errorKind is given, a request for an undefined kind of index should cause an error to be thrown, and otherwise some kind of error paragraph should be inserted instead. It is assumed that indices are never contained within lists.

• ordinary paragraphString

  An ordinary paragraph, not contained within any lists.

• section title

  A section heading (which can never be contained within a list.) The first paragraph of a TIP document must be a section heading whose title is Abstract, and an ordinary paragraph should follow immediately after.

• separator

  A horizontal rule (which can never be contained within a list.)

• verbatim lineList

  A section of verbatim text. The argument gives a list of lines (without newline terminators) that form the body of the verbatim text. It is implementation defined whether verbatim text properly nests within lists or not.

imwidth.tcl

Utility for figuring out the width of an image file. Most of the code is cobbled from the Tcler's Wiki, which is a tremendous resource.