The LAML SchemeDoc Homepage
Current downloadable version of LAML SchemeDoc: 38, November 14, 2011
Recent news related to SchemeDoc:
32.30: The SchemeDoc tutorial has been revised. Several issues have been dealt with. It should now be fully up-to-date.
33.00: Cleaner rendering of Scheme source programs via the Scheme Elucidator.
33.00: Added support of -/ prefix of .schemedoc-dependencies.
SchemeDoc is a tool for extraction of interface documentation (API documentation) from a Scheme source file. As such, SchemeDoc is a member of the familiy of interface documentation extraction tools, such as JavaDoc and Doxygen. The documentation extracted by SchemeDoc is presented as HTML files with use of CSS stylesheets. SchemeDoc is implemented in Scheme with use of the LAML libraries. I use SchemeDoc to document the LAML libraries and tools (see the Manual column of the referred table).
It is now possible to download SchemeDoc separately (2.6 Mbyte). SchemeDoc is subset of LAML. If you have downloaded LAML already, you also have SchemeDoc.
In the same way as LAML, SchemeDoc works on both Windows, Linux, and Unix. Personally, I use it with MzScheme and Guile, but it is designed to be applicable with all R4RS/R5RS Scheme systems that implement as set of LAML compatibility functions. SchemeDoc will not work together with R6RS. See additional details on supported Scheme systems.
Getting started
SchemeDoc (and the underlying LAML system) works very well together with Emacs (via Emacs menus and Emacs keyboard shortcuts), but it is also possible to use SchemeDoc without the support of Emacs.
In order to get started, we provide the following step-wise tutorials for novice users who do not want to use Emacs. The tutorial is good for SchemeDoc version 32.1 or newer.
SchemeDoc features:
Two different kinds of documentation comments. SchemeDoc supports two different
styles of documentation comments in Scheme source programs. The multi-semicolon style relies on two, three and four semicolon comments in a Scheme source file. The documentation-mark style relies on a special mark (one or more '!' characters) on the first comment line. Consult
example 1 and
example 2 below for concrete illustrations of the two styles.
Processing options in top-level documentation comment
The most important processing options can be specified in the top-level Scheme comment (also called the abstract comment).
Documentation from multiple Scheme source files may be collected in a single SchemeDoc page.
It is possible to generate a single SchemeDoc web page from information, which is extracted from several Scheme source pages. This works as if all the source files have been concatenated in place of the first source file. Example 10 shows how to do it.
Access to Scheme source files. As an option of SchemeDoc, it is possible to link from the interface documentation to a nice HTML rendering of the actual Scheme source file. The HTML version of the Scheme source file is created by the
Scheme Elucidator 2. As of version 33, the rendering of the Scheme source files do not contain documentation comments. This simplifies the source programs considerably.
Access to R5RS and R4RS Scheme Reports
SchemeDoc comes with indexed versions of R4RS and R5RS. Scheme source files, as generated by SchemeDoc, can link to one of these reports In this way, allmost all non-local, applied names in a Scheme source program can be bound to their most relevant documentation.
Multiple modes of activation SchemeDoc can be activated from a Scheme interpreter, from an operating system prompt (when used with MzScheme on Unix), via an Emacs command issued on the Scheme source file, or from a LAML script that holds processing options (and in some situations also manual contents). LAML scripts are writtten in a
SchemeDoc XML language. See additional details
below.
Documentation of XML DTDs LAML relies on XML DTDs. A given XML DTD can - element for element - by represented as 'mirror functions' in Scheme. These function integrate full validation of the generated documents. SchemeDoc makes it possible to make both naked and augmented manuals of XML DTDS that have been parsed with the
LAML DTD parser. Naked manuals do only contain the information in the DTD. Augmented manuals holds additional information supplied by the author. It is, however, possible to specify a cross reference generation function, which in a systematic way, can produce URLs to useful, external resources (see the
manual-front-matters attributes
element-cross-reference-url-fn and
element-cross-reference-anchor-text ). SchemeDoc can generate an XML-in-LAML template which serves as a starting point of the augmented manual.
Writing an API manual from scratch SchemeDoc is controlled by an
XML language. In normal use, the XML language is only used for setting of processing options. However, the XML language allows you to write all your API documentation from scratch, instead of extracting it from a Scheme source file or from an XML DTD.
Indexing of several SchemeDocs A number of SchemeDoc manuals can be indexed in a convenient multi-framed browser. The browser may integrate direct access to each named function and syntax of the Scheme Report (either R4RS or R5RS). The full LAML distribution contains indexed versions of both R4RS and R5RS.
The LAML & Scheme browser is made with use of the SchemeDoc Index facility.
From version 30, the attribute informative-name of the element manual-index-contribution has been made optional. If no such attribute is supplied, the name of the manual entry is taken from the title of the underlying manual file. Integrated with the Scheme Elucidator The
Scheme Elucidator is a sophisticated tool for generation of internal documentation of Scheme programs. As already noticed, SchemeDoc relies on the Scheme Elucidator for generation of thoroughly linked HTML renderings of Scheme source programs. In the other direction, the Scheme Elucidator can integrate SchemeDoc documentation instead of linking to the underlying source programs.
Emacs support It is easy to use SchemeDoc from Emacs. The Emacs Tools menu has a section of SchemeDoc submenu items that helps you construct SchemeDoc scripts. When you are in Scheme mode, the Scheme menu has a SchemeDoc section that provides relevant documentation comment templates. In addition, there is a menu item for activation of SchemeDoc on the Scheme source file. LAML scripts can be processed via commands in the LAML menu.
From a Scheme source file, it is possible to get direct access to SchemeDoc documentation via the Emacs command display-schemedoc-information. (This is quite similar to Emacs' own help system on Emacs Lisp, and it is bound to the same keys: C-h f). There is also direct access to documentation of all R5RS functions in that way. You can control the set of SchemeDoc files that are taken into consideration by using the tag .schemedoc-dependencies in one of the introductory comments of the Scheme source file. (See example 1 and 2 below for how it can be done). The .schemedoc-dependencies internal tag enumerates a number of relative or absolute file paths to SchemeDoc resources (in terms of -.manlsp files, but it is not necessary to supply the extension). The prefix '-/' is expanded to the file path prefix of the LAML software directory. Depending on the major and minor mode of the Emacs buffer, a number of default SchemeDoc resources will be available. The Emacs command reset-schemedoc-information refreshes the SchemeDoc information of the current buffer, and it informs you about the SchemeDoc resources that are taken into consideration.
Internal SchemeDoc format SchemeDoc generates an
auxiliary file with extension manlsp, which contains all the manual information in a list structure. The SchemeDoc index tool uses the information in the manlsp files. Other Lisp tools are also likely to make good use of this information.
Custom tags in SchemeDoc comments (introduced in version 30)
You can use your own tags in SchemeDoc comments (within Scheme source files), and you can arrange that SchemeDoc takes these custom tags into consideration when it produces the documentation files.
Details.
Examples
SchemeDoc Resources
The two already mentioned Getting started tutorials (without use of Emacs):
More examples A number of additional examples from the LAML example directory.
SchemeDoc Usage
SchemeDoc can be activated in several different ways, here ordered after the amount of control that can be exercised:
Via a LAML script
From a LAML script written in the SchemeDoc XML-in-LAML language, such as the scripts shown in the third column of the table from above. Such script files should have file extension sdoc.
Personally, I maintain a LAML script for each SchemeDoc manual I produce. This gives the best possible control of your SchemeDoc manuals.
The script can be executed from the operating system command prompt, from Emacs, or from within Schme interpreter (in which LAML stuff has been loaded).
From Emacs with LAML support. In a buffer in Scheme mode use
M-x schemedoc or the Emacs menu entry
Scheme > SchemeDoc > Run SchemeDoc.
Be sure to include a top-level comment (also known as an abstract comment) in your Scheme source file (can be inserted via the menu entry
Scheme > SchemeDoc > Insert Abstract Comment).
A neighbor menu entry offers SchemeDoc help.
From a Unix or Linux shell From an Unix og Linux shell the
schemedoc command can be activated on a Scheme source file:
schemedoc file.scm
The shell script accepts no options, but processing options can be given in the initial comment of the Scheme source program. Using this mode of activation it is not possible to link to the underlying Scheme source program.
Similar Work
It is worth noticing that there a several different and unrelated approaches to documentation of the interface of Scheme libraries. There is even another system called SchemeDoc. Here is a list of similar systems (and the Scheme system to which they belong):
For more details see the MISC part of the Scheme FAQ or section 3.5 of my paper Scheme Program Documentation tools.
If you are aware of other similar systems, please tell me.
Generated: Friday, July 6, 2012, 14:49:40