LAML SchemeDoc

Kurt Nørmark ©     normark@cs.aau.dk
Department of Computer Science, Aalborg University

Abstract.

In this part of the tutorial we describe LAML SchemeDoc, which is a tool for production of interface documentation of Scheme libraries. The tool can also be use to document and XML DTDs. SchemeDoc is similar of similar nature as Javadoc tool for Java and Doxygen.

As for the other LAML tutorials, a separate directory with SchemeDoc and Manual examples is available.

There is a strong connection between SchemeDoc, LAML, and Emacs. The most convenient way to work with SchemeDoc goes via Emacs. As of version 32, we have we described how to profit from SchemeDoc WITHOUT using Emacs. There exists separate guides for use of SchemeDoc from a Scheme interpreter, or from an operating system command prompt.

 

1     SchemeDoc
We start with an introduction and discussion of the SchemeDoc tool.
1.1     SchemeDoc
1.2     SchemeDoc internal tags
1.3     Using SchemeDoc from a LAML script
1.4     Scheme Source linking
 


1.1     SchemeDoc

The file prog1 is a very simple Scheme program with a few define forms. (Red, blue and green names are clickable in this tutorial. Try click on the red name now!) A number of comment blocks are used. A comment block is a sequence of comment lines. Recall that a comment line in a Scheme program starts with a semicolon and runs to the end of the line. Some comment blocks are considered as documentation comments. The SchemeDoc tool uses the following commenting conventions

  1. Comments started with a single semicolon are not taken into account by SchemeDoc.

  2. Comments started with a double semicolon in front of a define form are definition comment. A definition comment is intended to define the calling or application conventions of an abstraction.

  3. Comments started with a triple semicolon are sectional comments. A sectional comment serves as an introduction to a number of related definitions, which come after the sectional comment.

  4. A four semicolon comment serves the role as an introduction or an abstract to the Scheme source file - the introductory comment. There should only be one introductory comment, and it should be found at the very beginning of the Scheme source file.

The commenting conventions described above are relative to the so-called multi-semicolon commenting style. LAML SchemeDoc also supports a documentation-mark commenting style. Please consult the details of both commeting styles in the SchemeDoc reference manual.

Definition 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 in different ways. If you are an Emacs use, the easiest way is to use the Scheme > SchemeDoc > Run SchemeDoc menu item for activation of SchemeDoc on the Scheme source file. The last five lines of the initial ;;;; comment are setup parameters to SchemeDoc. The last one, .source-destination-delta, request that the HTML files are located in a man subdirectory. you are supposed to create the directory man yourself before you run SchemeDoc.

As an alternative processing technique, you can use the schemedoc procedure from a LAML enabled Scheme read-eval-print loop:

   
 (schemedoc "prog1.scm")

In order to process prog1 it may be attractive to pass the full and absolute file path to the schemedoc procedure, such as:

   
 (schemedoc "/user/normark/scheme/examples/tutorial/schemedoc/")

The manual title and the manual author are given by 'dot initiated tags' in prog1. In addition we provide values of a number of SchemeDoc processing attributes (processing parameters to SchemeDoc). These are .laml-resource... .source-destination-path. They correspond to a (rather limited) subset the manual-front-matters attributes. Please consult the description of these. The internal dot-initiated tag lines and the introductory text can appear in any order. Normally, internal tagging is line oriented. It is, however, possible to have multi-lined internal tagging by ending the line with a line continuation character (normally a backslash).

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 SchemeDoc which commenting style to use ( multi-semicolon or documentation-mark ).

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. Alternatively, provide a full and absolute file path to your Scheme source file.

The schemedoc command reads a Scheme source file, extracts the documentation comments and relevant parts of the Scheme program, and it presents this information as an XHTML file. It may be convenient to use native XHTML markup in definition 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 description of Documentation Comments and the Internal Tags in the first two sections of the manual.


1.2     SchemeDoc internal tags

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 all described in the section about Internal SchemeDoc tags of the SchemeDoc Reference Manual. We summarize the possible internal tags in definition comments (2 semicolon comments) here:

   
.form (form-name par1 par2)
.pre-condition Some Precondition
.post-condition Some Postcondition
.parameter par-name parameter description
.returns Return value description
.example some example
.reference "category" "anchor" "url"
.internal-references "category" "ref1" "ref2" ...
.misc Miscelaneous information
.comment Internal comment

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)

In addition, the following processing tags are available for use in introdoctory comments:

   
.laml-resource                 true/false
.css-prestylesheet             compact/normal
.css-stylesheet                original/fancy
.css-stylesheet-copying        true/false
.keep-syntactical-comment-file true/false
.source-destination-delta      relative-path
.scheme-source-linking         true/false

The program prog2 extends prog1, and it illustrates a number of the special SchemeDoc tags in definition comments. You should study the resulting manual page.

Like prog1, we produced prog2 with the interactive LAML command in a Scheme prompt:

   
 (schemedoc "prog2.scm")

We could, as well just activate SchemeDoc from Emacs as explained above. In prog2 and the resulting manual page you should in particular notice the use of the scheme-source-linking attribute. With use of this attribute, SchemeDoc generates an HTML version of the Scheme source program, and it provides links from the SchemeDoc manual to this source file. Try follow the "See also Scheme source files" links.

We illustrate additional SchemeDoc details in prog4 and in the corresponding, generated HTML file. These are the use of .affiliation in the introductory comment, use of .section-id in sectional comments. Notice that we do not in prog4 provide the processing options like in prog1 and prog2. In this example we use 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.


1.3     Using SchemeDoc from a LAML script

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 parameters and the 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.sdoc in the man/ directory, produces laml/prog3.html. Files with extension sdoc are supposed to contain SchemeDoc stuff. Notice that the manual-front-matters attributes in prog3-script take precedence over the similar internal tags found in the introductory comment of the Scheme source file prog3.

Using the Emacs command M-x make-laml-schemedoc-manual it is easy to make a LAML script like prog3-script. The Emacs command make-laml-schemedoc-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 the script prog3-script. There are many ways to so: a 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. I always process laml scripts from Emacs via C-c C-o with hygienic emacs keybindings (or C-o in case the orginal keybindings are used.) The keybinding policy is controlled at LAML installation time via the file laml-config/configuration.

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. In the concrete example these informations are taken from the internal tags of the introductory comment in the Scheme source file, prog3.

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 SchemeDoc XML language. The SchemeDoc document style is up for discussion and explanation later in this tutorial.


1.4     Scheme Source linking

prog5 and in particular the LAML script that generates the manual, shows how to generate a SchemeDoc manual with Scheme source linking. The generated SchemeDoc manual is here. The Scheme source file, in turn, is able to refer to a number of other SchemeDoc manuals.

You should in particular notice the scheme-source-linking-manual clause in the LAML script and in the generated manual. The "See also Scheme source" clauses give access to the Scheme source file. Within the Scheme source files all colored names are anchored links. Notice in particular the slightly green names, which give access to entries in the fundamental LAML library and in the general LAML library. The green links are made via use of the scheme-source-linking-manual clauses mentioned above.

Notice also the brown names in the Scheme source files, which link to details in the Scheme R4RS or R5RS manual.

The function laml-library-source-linking in the LAML fundamental library returns a number of scheme-source-linking-manual clauses, which provide for source linking to a collection of LAML libraries. Simply insert a call of laml-library-source-linking in a manual-front-matters element.

The Scheme source files are produced by the Scheme Elucidator, which also has been used to make this tutorial.

2     The SchemeDoc Document Style
We have described the SchemeDoc tool above. SchemeDoc extracts information from Scheme source programs. The extracted information is rendered HTML files. The SchemeDoc document style can be used to produce highly structured reference manuals for collection of Scheme procedures and functions.
2.1     The Manual Document Style
 


2.1     The Manual Document Style

The original SchemeDoc document style (once called the 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 is made with use of the SchemeDoc document style itself. From the parsed XML manual DTD it is possible to create a SchemeDoc manual very easily. (See below for details). We have augmented the DTD-derived information with element and attribute descriptions to obtain The SchemeDoc Reference Manual.

We will now show how to use the LAML SchemeDoc 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 only real good in example in the LAML distribution is the documentation of the so-called LAML compatibility file. 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 manual-example we document the interface of two imaginary functions f and g with form, description, precondition, postcondition, parameters, returns, and more.

3     Making a manual of XML-in-LAML functions

In this section we will see how to make a LAML SchemeDoc 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.

3.1     Making a manual of XML-in-LAML functions
 


3.1     Making a manual of XML-in-LAML functions

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 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-schemedoc-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. If you want more information, you should consider the academic paper Scheme Program Documentation Tools. Half of that paper is about Schemedoc.