4.8. Documentation Constructions

Interscript supplies uses with various documentation constructions. These include standard constructions such as a title, multilevel document headings, page headings, table of contents, index, nestable enumerated, bulletted, and keyed lists, displays (long quotations), footnotes, and tables. For a full list of supported constructions see below.

The requirements here are to support a rich enough set of constructions, with a fine enough level of control of details, to do handle the bulk of work which would be required by a serious author, while at the same time providing the casual programmer simple enough tools to typeset basic program documentation.

In addition, Interscript supplies constructions specialised to literate programming. Naturally, there is a specialised construction for source code display, and some tables such as a list of files, and identifier index unique to literate programmed code. In addition, it is necessary to be able to typeset code fragments for 'examples of use', even though literate programming discourages this. (Give real examples!)

These requirements have to balanced against the efficiency of the translator, the ease of implementation of the constructions, and the availability of features in typesetting systems. How do you typeset diagrams in plain text? (With difficulty) What about diagrams, colour, pictures, and font control?