The advantages of literate programming (embedding documentation in the source code) are that the documentation is available both in the source code and in the online or printed documents, and that chances are greater that updates to the source code and the documentation are synchronized.
Some structuring conventions are required to embed all the documentation information within the comments of the source code. They are relatively simple and are detailed below.
All lines up to and including the first blank line are put into an HTML comment. This makes it easy to omit the source file copyright notice from the documentation. The first blank line must not be within a comment.
The portions of the file that are not in comments will be placed within preformatted (<PRE>) sections, obeying line breaks and indentation. Any characters that have special significance to HTML will be quoted.
The portions of the file that are in comments will be treated differently depending on the position of the comment. There are three cases:
PROCEDURE P(VAR (*OUT*) x: INTEGER);
PROCEDURE LineTo(path: T; READONLY p: Point.T); (* Extend "path" with a linear segment that starts at its current point and ends at "p". *)
It is recommended that these slanted comments be kept brief; additional details can be provided in longer type 3 comments.
Sometimes you want a portion of a comment to be treated verbatim, like program text, for example, when including an example program. Therefore, any line that starts with "| " (vertical bar followed by space) is treated like program text, typesetting it verbatim in typewriter font.
Comments of type 2 and 3 may contain HTML tags, for example to annotate section headings or emphasize text. A title and level 1 header are supplied using the interface name.
Lines in type-three comments that begin with "| " are treated just like program text with one exception: you can slip in words in roman font by enclosing them in back-quotes.
| ELSIF s `was generated by` LineTo THEN