In this part of the tutorial we describe SchemeDoc, which is a tool for production of interface documentation of Scheme libraries and XML DTDs. SchemeDoc is similar to the well-known Javadoc tool for Java. SchemeDoc produces information which is processed by the Manual document style for the purpose of web presentation. We also discuss the LAML manual documentation style in this part of the tutorial.
From LAML version 22, the LAML manual document style conforms to XML-in-LAML. It means that the manual format is defined by an XML DTD. Also, the LAML manuals now rely on XHTML and Cascading Stylesheets for manual presentation. It means that many presentation details can be controlled by CSS stylesheets.
As for the other LAML tutorials, a separate directory with SchemeDoc and Manual examples is available.
The file prog1 is very simple Scheme program with a few define forms. A number of different kinds of comments are used, distinguished by the number of semicolons at the beginning of the lines. Recall that a comment in a Scheme program starts with a semicolon and runs to the end of the line. The SchemeDoc tool uses the following comment convensions:
Interface comments, sectional comments, and introductory comments are processed by SchemeDoc.
We can use SchemeDoc to process prog1. The resulting manual is here. The processing can be done by the following Scheme procedure call:
(schemedoc "prog1.scm" "man/")
The manual title and the manual author are given by 'dot initiated tags' in prog1, which must come after the abstract text. I.e., the title and author line must be the last two lines of the introductory comment.
Take a look at the manual entry of schemedoc (click the name to see the manual page of the schemedoc command). The first required parameter is the Scheme program to process, and the next (optional) tells in which directory to place the result (relative to the location of the source file). If we only pass a single parameter, "prog1.scm", to the schemedoc procedure, the HTML documentation file will be a sibling file to the Scheme source file.
In order to call the schemedoc procedure, start an LAML session in your favorite Scheme System. I most often use PLT MzScheme from Emacs. In this setting, just say M-x run-laml-interactively. This starts an interactive Scheme session (Inferior Lisp process in Emacs jargon) and it loads a number of useful LAML libraries. Use (laml-cd "dir") and (laml-pwd) to navigate the file system in a Unix-like fashion.
The schemedoc command reads the source file, extracts the two, three, and four semicolon comments and parts of the program, and via the Manual document style (see section 2) it presents this information as XHTML. It may be convenient to use native XHTML markup in interface comments, sectional comments, and introductory comments. Notice however, that the use of such textual HTML markup is not validated in the context of the target XHTML document, as generated by the LAML manual document style. In other words, if you use HTML markup in documentation comments in your Scheme program, you are on your own with respect to validation of the resulting manual. I recommend that you only use very simple markup in documentation comments.
At this point in time, you can also take a look at the SchemeDoc Reference Manual. You should pay special attention to the SchemeDoc commenting conventions in section 1 of the manual.
In order to exercise finer control of the produced interface documentation, SchemeDoc supports a number of special 'internal tags' in the Scheme comments. They are described in the section SchemeDoc Reference Manual SchemeDoc tags in Scheme source files of the SchemeDoc Reference Manual. We summarize the possible internal tags in interface comments (2 semicolons) here:
.title Some title .form (form-name par1 par2) .pre-condition Some Precondition .post-condition Some Postcondition .description Some Description .parameter par-name parameter description .example some example .reference "category" "anchor" "url" .internal-references "category" "ref1" "ref2" ... .misc Miscelaneous information .comment Internal comment .returns Return value description
In a sectional comment (3 semicolons) the following internal tag can be used to give a section id:
.section-id some-id
Finally, in a introductory comment (4 semicolons) the following tags are possible:
.title Manual title .author Manual author(s) .affiliation Affiliation of the manual author(s)
The program prog2 extends prog1, and it illustrates a number of the special SchemeDoc tags. You should study the resulting manual page.
Like prog1, we produced prog2 with the interactive LAML command in a Scheme prompt:
(schemedoc "prog2.scm" "man/")
We illustrate additional SchemeDoc details in prog4. These are the use of . affiliation in the introductory comment, use of . section-id in sectional comments, and use of the escaping character, which is the dollar character. The escaping character is necessary if you need to start a comment with a '.'. If this is not the case, you can probably forget about it. The resulting manual page is here.
As we have seen above, it is possible to activate SchemeDoc from an interactive LAML command called schemedoc. In some situations it is more convenient to define a LAML script which defines the parameter and context of the manual. This is what we have done for all the LAML manual pages in the LAML distribution.
The LAML script prog3-script, stored in file prog3.laml in the man/ directory, produces laml/prog3.html. Using the Emacs command M-x make-laml-manual it is easy to make a LAML script like prog3-script. The Emacs command make-laml-manual is also found in the Tools > SchemeDoc menu in Emacs.
With this setup, there is no need for issuing an interactive LAML command. Just process prog3.laml in prog3-script the usual way: From the LAML menu in Emacs, via the Emacs keyboard shortcut C-c C-o, via the Scheme procedure laml, or via the operating system command prompt using the laml command.
A few words about prog3-script. First, it allows the setting of both the title, author, affiliation, and abstract by subforms (manual-title "..."), (manual-author "..."), (manual-affiliation "...") and (manual-abstract "...") of the manual-front-matters form. Second, the attributes of the manual-front-matters make it possible to set a number of processing options via the attributes. Notice in particular the CSS stylesheet settings.
The manual, manual-front-matters and manual-from-scheme-file forms in prog3-script are mirror functions of XML elements in the Manual XML language. The LAML manual document style is up for discussion and explanation in the following section.
The original manual document style is one of the oldest LAML document styles. It is also one of the most important, because all the LAML software is documented by use of it, as described in section 1. From LAML version 22, the LAML manual document style has been reengineered as a mirror of an XML manual language. The original LAML manual facility is now obsolete.
The reference manual of SchemeDoc is made with use of the manual document style itself. From the parsed XML manual DTD it is possible to create a LAML manual very easily. (See below for details). We have augmented the DTD-derived information with element and attribute descriptions to obtain The SchemeDoc Rerence manual.
We will now show how to use the LAML Manual language to write software manuals from scratch, and without use of automatically extracted information from a Scheme source file. It should be noticed that we do not very often write manuals in this way. The SchemeDoc approach illustrated above, and exercised widely with JavaDoc, Doxygen and similar tools, is much easier to deal with, and it usually gives much more accurate manuals.
The first example of a manual is called manual-example. Please click on it to bring it up in the rightmost frame of the elucidator. Also notice that you can actually navigate from the example manual (in the frame which probably is located to the right) to the reference manual. (The slightly green names are all links!) Please also take a look at the HTML version of the processed manual.
After the manual-front-matters element comes a number of manual-section and manual-page elements. As described above, a manual-section is an introduction to the following manual pages. A manual-page describes the characteristica of a single abstraction (function, variable, etc).
Concretely, in the example manual manual-example we document the interface of two imaginary functions f and g with form, description, precondition, postcondition, parameters, returns, and more.
In this section we will see how to make a LAML reference manual of a set of mirror functions, which are generated from an XML DTD. In particular, we shall see how to make good use of the information in the DTD in the reference manual.
In another part of the tutorial - in the the XML-in-LAML chapter we explain how to make a mirror of an XML language in Scheme. This is the so-called XML-in-LAML framework. It is often relevant to make a reference manual of the Scheme mirror functions produced in this way. The manual document style supports this. In this section, we will give an example.
We will make a manual of the example bikes DTD from the XML-in-LAML chapter. When such a DTD is parsed, an internal Lisp representation is generated. The file with this representation contains a lot of useful information, which can be merged with manually writen explanations.
If you wish, you can bring the DTD up in the right frame of this elucidator by clicking here.
You can also take a look at the derived, internal Lisp representation parsed-bikes-dtd file of the bikes DTD.
We are now about to document the bikes XML DTD. This is done in two steps. In step one we make a naked manual of the bikes XML language, which only contains the information in the the DTD. The generation of the naked manual spins off a template of a fulfledged manual, which we refine in step two.
In step one we make the naked XML documentation, by means of the script bikes.laml. A script like this can easily be made by the Emacs command M-x make-laml-manual. This script holds the title and author information in the top part, and a reference to XML DTD in the manual-from-xml-dtd element below. Notice the attribute make-dtd-manual-template, which has the value true. The precesence of this particular attribute causes the creation of manual-template.laml when bikes.laml is processed.
As the second step, we now transfer the title, author, and front-matters attributes of bikes.laml to manual-template.laml. We also fill in the the information in the description and attribute-description clauses. Hereby we get augmented-bikes.laml which process with LAML in one of the usual ways. You should consult the augmented bikes XML DTD manual to see the result of our efforts. At the end of augmented-bikes.laml notice the use of merged-manual-from-xml-dtd instead of manual-from-xml-dtd in bikes.laml .
This ends the description of SchemeDoc and LAML manuals.