# Producing Documentation

## Specifying the Typesetter

One of the design goals of FunnelWeb was to provide a typesetter independent literate programming system. By this is meant that it be possible to create FunnelWeb input files that do not contain typesetter-specific commands.

The difficulty with providing typesetter-independent typesetting is that each desired typesetting feature must be recreated in a typesetter-independent FunnelWeb typesetting construct that FunnelWeb can translate into whatever typesetting language is being targeted by Weave. Taken to the extreme, this would result in FunnelWeb providing the full syntactic and semantic power of TeX, but with a more generic, FunnelWeb-specific syntax. This was unfeasible in the time available, and undesirable as well.

The compromise struck in the FunnelWeb design is to provide a set of primitive typesetter-independent typesetting features that are implemented by FunnelWeb. These are the typesetter directives. If the user is prepared to restrict to these directives, then the user's FunnelWeb document will be both target-language and typesetter independent. However, if the user wishes to use the more sophisticated features of the target typesetting system, the user can specify the typesetter in a typesetter pragma and then place typesetter commands in the free text of the FunnelWeb document where they will be passed verbatim to the documentation file. The choice of the trade-off between typesetter independence and typesetting power is left to the user.

The typesetter pragma allows the user to specify whether the input file is supposed to be typesetter-independent, or whether it contains commands in a particular typesetter language. The pragma has the following syntax.

pragma_typesetter ::=
ps typesetter' s =' s
(none' / tex' / latex' / html' / texinfo' /
latex2html').

s ::= { '}+ .

ps ::= (@p' / @P')  ' .


The six forms of the pragma look like this.

@p typesetter = none
@p typesetter = tex
@p typesetter = latex
@p typesetter = html
@p typesetter = texinfo
@p typesetter = latex2html


A source file can contain more than one typesetter pragma, but they must all specify the same value. The default is none, in which case FunnelWeb assumes that the documentation file is to be typeset with TeX but that the user has not included any explicit TeX markup. If the typesetter setting is not none, FunnelWeb assumes that the free text may contain explicit markup for the specified typesetter.

The typesetter setting affects three things:

Handling of free text
If the typesetter setting is not none, FunnelWeb writes the free text directly to the documentation file without changing it in any way. This means that if (say) \centerline appears in the input file, it will copied directly to the documentation file. If the typesetter is none, Weave intercepts any characters or sequences that might have a special meaning to TeX and replaces them with TeX commands to typeset the sequences so that they will appear as they do in the input. For example, if $ (the TeX mathematics mode character) appears in the input file, it will be be written to the documentation file as \$.

Handling of macro text
Text within macros and literal strings always appears in the documentation exactly as it does in the FunnelWeb source. Weave intercepts any characters or sequences that might have a special meaning to the specified typesetter and replaces them with commands to typeset that material as it appears in the input.

Boilerplate
If the typesetter setting is none or tex, the documentation file will begin with a collection of TeX macros implementing FunnelWeb constructs and commands to protect TeX markup. A FunnelWeb file using either of these settings need have no explicit markup whatsoever. No such boilerplate is included for any other typesetter settings. Thus any markup required by the specified typesetter must appear explicitly in the FunnelWeb file. (For example, if the typesetter setting is latex then the FunnelWeb file must contain an explicit \documentclass command.)

## Typesetting Documentation with Eli

Within the Eli-Implementation of FunnelWeb, the usage of a typesetter-directive is a precondition for the generation of a documentation in the same format.

@p typesetter = none
@p typesetter = tex
@p typesetter = latex
@p typesetter = latex2html
When these or no typesetter-directive is used, the derivation :fwTex can be used to obtain a .tex'-type file. A file of this type can be converted into a .dvi'-file by application of the :dvi-derivation or into a .ps'-file by application of the :ps-derivation. Of course you need a TeX implementation to use these derivations.

The user must supply an appropriate LaTeX preamble, \begin{document} and \end{document} as part of the document text when using either latex or latex2html. This means that it is possible to combine the outputs from several :fwTex derivations into a single document by using appropriate LaTeX \input commands.

The preamble must include the LaTeX command \usepackage{alltt} for either latex or latex2html, and latex2html also requires \usepackage{html}.

Pragmas latex and latex2html normally translate the FunnelWeb section directives into LaTeX sectioning commands as follows:

@A \section
@B \subsection
@C \subsubsection
@D \paragraph
@E \subparagraph

If the +chapter parameter is passed to the :fwTex derivation, however, the translation is:

@A \chapter
@B \section
@C \subsection
@D \subsubsection
@E \paragraph

@p typesetter = texinfo
When these directive is used, the derivation :fwTexinfo can be used to obtain a .tnf'-type file. Since .tnf'-files are valid TeX-files, all the derivations for .tex-files are also valid for .tnf-files. Additionally, .tnf-type files can be converted into info-files which can be shown with the Eli-Info-Browser by application of the :display-derivation.

@p typesetter = html
When these directive is used, the derivation :fwHtml can be used to obtain a .html'-type file. This file can be extracted from Eli and can be loaded into your favorite html-browser.

## Structure

The section directive provides a way for the user to structure the program and documentation into a hierarchical tree structure, just as in most large documents. A section construct consists of a case-insensitive identifying letter, which determines the absolute level of the section in the document, and an optional section name, which has exactly the same syntax as a macro name.

section ::= @' levelchar [name] .

levelchar ::= A' / B' / C' / D' / E' /
a' / b' / c' / d' / e' .

name ::= @<' name_text @>' .

name_text ::= {ordinary_char / text_special} .


The section construct is not quite "inline" as it must appear only at the start of a line. However, unlike the @i, @p, and @t constructs, it does not consume the remainder of the line (although it would be silly to place anything on the same line anyway).

FunnelWeb provides five levels of sections, ranging from the highest level of A to the lowest level of E. FunnelWeb input files need not contain any sections at all, but if they do, the first section must be at level A, and following sections must not skip hierarchical levels (e.g. an @D cannot follow an @B). FunnelWeb generates an error if a level is skipped.

All section must have names associated with them, but for convenience, the section name is optional if the section contains one or more macro definitions (ie. at least one macro definition appears between the section construct in question and the next section construct in the input file.). In this case, the section inherits the name of the first macro defined in the section. This feature streamlines the input file, avoiding duplicate name inconsistencies.

Any sequence of printable characters can be used in the section name, even the target typesetter's escape sequence (eg. in TeX, \).

The following example demonstrates the section construct.

@A@<Life Simulation@>

This is the main simulation module for planet earth, simulated
down to the molecular level.  This is a REALLY big program.  I
mean really big.  I mean, if you thought the X-Windows source
code was big, you're in for a shock...

@B We start by looking at the code for six legged stick
insects as they form a good example of a typical
object-oriented animal implementation.

@\$@<Six Legged Stick Insects@>@{@-
slsi.creep; slsi.crawl; slsi.creep;@}


In the above example, the name for the level A section is provided explicitly, while the name for the level B section will be inherited from the macro name.

## Marking Text

### Typesetting a literal string

Experience has shown that one of the most common typesetting requirements is that of being able to typeset small program fragments in the middle of the documenting free text. Typically there is a frequent need to refer to program identifiers, and it assists the reader to have such identifiers typeset in the same manner as the program text in the macro definition.

To specify that some text be typeset in tt font, enclose the text in curly brace special sequences as follows.

literal ::= @{' ordinary_text @}' .


As in macro names, section names, and macro bodies, the text contained within the literal construct is protected by FunnelWeb from any non-literal interpretation by the typesetter and the user is free to enclose any text covered by the definition ordinary_text. FunnelWeb guarantees that, no matter what the text is, it will be typeset in tt font exactly as it appears. However, the text will be filled and justified into a paragraph as usual.

Here is an example of the use of the construct:

@C The @{WOMBAT@} (Waste Of Money, Brains, And Time)
function calls the @{kangaroo@} input function which has
been known to cause keybounce.  This keybounce can be
dampened using the @{wet_sloth@} subsystem.


### Emphasising a string

The emphasis directive is very similar to the literal directive except that it causes its argument to be typeset in an emphasised manner (eg. italics). Like the literal directive, the emphasis directive protects its text argument.

emphasise ::= @/' ordinary_text @/' .


Example:

@C What you @/really@/ need, of course, is a @/great@/,
@/big@/, network with packets just flying
@/everywhere@/.  This section implements an interface to
such a @/humungeous@/ network.


## Formatting

### Forcing a Pagebreak

The new page pragma is a typesetting pragma with the following syntax.

ftd_newpage ::= @t ' new_page' .


Its only form looks like this.

@t new_page


Its sole effect is to cause a "skip to a new page" command to be inserted into the documentation file. The new page command is such that if the typesetter is already at the top of a page, it will skip to the top of the next page.

ftd_toc ::= @t ' table_of_contents' .


Its only form looks like this.

@t table_of_contents


Its sole effect is to instruct FunnelWeb to insert a table of contents at this point in the printed documentation. This pragma does not skip to the top of a new page first.

### Inserting blank vertical space

The vertical skip pragma is a typesetting pragma that instructs Weave to insert a specified amount of vertical space into the documentation. The pragma has the following syntax.

ftd_vskip ::= @t ' vskip'  ' number  mm'.


For example:

@t vskip 26 mm


### Specifying the title of your document

The title pragma is a typesetting pragma with the following syntax.

ftd_title ::= ts title' s font s alignment text .

font ::= normalfont' / titlefont' / smalltitlefont' .

alignment ::= left' / centre' / right' .

text ::= "' {printable_char} "' .


Its effect is to instruct Weave to insert a single line into the printed documentation containing the specified text set in the specified font and aligned in the specified manner. The double quotes delimiting the text are for show only; if you want to put a double quote in the string, you don't need to double them.

Here is an example of the pragma.

@t title smalltitlefont centre "How to Flip a Bit"