Abstract. In this part of the tuturial we describe SchemeDoc, which is a tool for production of interface documentation of Scheme libraries. 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 this document style in this part of the tutorial. |
![]() ![]() ![]() 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.1 SchemeDoc |
The file prog1 is a plain a normal Scheme program with a few simple define forms. A number of different kinds of comments are used, distinguished by the number of semicolons on 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 convensions:
Interface comments, sectional comments, and introductory comments are processed by SchemeDoc.
We can use SchemeDoc to process prog1.scm. This can be done by the following command (a call of a Scheme procedure):
(schemedoc "prog1.scm" "man/" "The program prog1" (list "Kurt Normark" "Aalborg University") "This is the demo program prog1")
Take a look at the manual entry of schemedoc (click the name to see the manual page of the schemedoc command)). The first parameter is the Scheme program to process, the next tells where to place the result, then comes the title, the author/affiliation, and the abstract.
In order to use the command, start a LAML session in your favorite Scheme System. I 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.
The schemedoc command reads the source files, extracts the two, three, and four semicolon comments and parts of the program, and via the Manual document style (see section 2.1 - not made yet) it presents this information as HTML on a web page.
Please take a careful look at the resulting manual page.
At this point in time, you should also take a look at the SchemeDoc Manual.
![]() ![]() ![]() 1.2 SchemeDoc internal tags |
In order to exercise finer control of the produced interface documentation SchemeDoc supports a number of special 'tags' in the Scheme comments. They are described in SECTION1 of the SchemeDoc manual. We summarize them here:
.title Some title .form (form-name par1 par2) .pre-condition Some Precondition .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
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/" "The program prog2" (list "Kurt Normark" "Aalborg University") "This is the demo program prog2")
![]() ![]() ![]() 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 parameter and context of the manual.
The LAML script prog3-script, stored in file prog3.laml in the man/ directory, produces laml/prog3.html.
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-o, via the Scheme procedure laml, or via the operating system command prompt using the laml command.
2.1 The Manual Document Style 2.2 Mixed use of the manual style and SchemeDoc |
![]() ![]() ![]() 2.1 The Manual Document Style |
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, together with SchemeDoc, as described in section 1.
The manual.scm is - of course made with use of the manual document style itself. In fact, it is made by authoring of a manual document (until section 6). Starting with section 7, the manual has been produced with SchemeDoc. We will see later in this tutorial how this combination can be provided for.
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 to the reference manual of the manual. (There are far too many manul manuals involved here...). Please also take a look at the HTML version of the processed manual. After loading laml.scm, and after using laml-style to load the manual sofware, we encounter the preamble part. In this section we define the title, author, and the abstract of the manual. We also set the manual name (somewhat redundantly). I recommend that this always is to be the proper name of the LAML file, in which the manual source resides.
Next comes the-manual section, in which we find manual-section and manual-page clauses. There are only few possible subclauses of a manual-section. A manual-page, however, may contain many different subclauses. Notice that most of these can be extracted by SchemeDoc from Scheme source programs. When we write a manual document, like manual-example we are on our own. We can use exactly those means of expressions we find important, and we can even write manuals for non-Scheme stuff.
Concretely, in the example manual, we document the interface of two imaginary functions f and g with title, calling form, description, parameters, precondition, cross-references, and more.
Notice the manual production, as done in the activation of the procedure make-manual in the manual-production section of the document.
![]() ![]() ![]() 2.2 Mixed use of the manual style and SchemeDoc |
As mentioned in section 2.1 we sometimes want to combine a manual style document with the manual contributions extracted from a Scheme source file, via the SchemeDoc tool. The example in mix-manual-example shows how to do this.
The first thing to notice is the scheme-doc-extraction section. Here we load the SchemeDoc tool software, and next we use the function extract-documentation-from-scheme-file to extract the document content of the Scheme file. The result is stored in doc-list.
In the manual-production section we pass two parameters to make-manual. The first, (append doc-list manual-page-list), is the list of documentation entries in manual format. The last is the HTML file in which to store the manual. - Unfortunately, the ordering of the manual entries is counter intuitive. All is reversed, and make-manual reverses the order. The doc-list entries end up in the rear end of the resulting manual.
You should take a look at the resulting 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 now have to write an LAML manual source file, bikes.laml of the bikes mirror functions. This is just hard work. We use the XML-in-LAML specific forms xml-in-laml-example-form and attribute-descriptions.
You should in particular notice the manual-production-and-merge section, in which we call the function manual-from-parsed-dtd. This generates a contribution to the manual, which is merged with our own contributions, using the function merge-manual-pages, as written in bikes.laml
Take a look at the resulting, generated manual. You should in particular notice how the explicitly written manual stuff from bikes.laml is merged with the information extracted from parsed-bikes-dtd.
![]() ![]() ![]() 4 Postscript We will in this final section say a few words about the future of the manual document style |
4.1 Postscript |
![]() ![]() ![]() 4.1 Postscript |
As mentioned in section 2.1, the LAML manual document style is one of the early document styles made for and in LAML. In our current development, we use XML-in-LAML to make XML compliant languages in LAML. There is a separate chapter of this tutorial about this, see the XML-in-LAML chapter.
In near future we hope to be able to reengineer the LAML manual style to use the XML-in-LAML conventions. This has already been done for LENO and the Course Plan language (which we eventually also include in this tuturial). In such a reengineering we keep the old software (to stay compatible with existing, old stuff), but we put on a new surface syntax.