|
|
|
|
General Information
Tutorials
Reference Manuals
Libraries
Translation Tasks
Tools
Administration
|
|
FunnelWeb
Producing Documentation
Specifying the TypesetterOne 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
The
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 The typesetter setting affects three things:
Typesetting Documentation with EliWithin the Eli-Implementation of FunnelWeb, the usage of a typesetter-directive is a precondition for the generation of a documentation in the same format.
StructureThe 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
FunnelWeb provides five levels of sections, ranging from the highest
level of 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 stringExperience 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
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 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 stringThe 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 PagebreakThe 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.
Producing a table of contentsThe table of contents pragma is a typesetting pragma with the following syntax.
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 spaceThe 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 documentThe 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"
|
