UNTITLED LOCAL UNTITLED
NAME
extract-sig -- generate SML
extract-info, merge-info -- generate intermediate files
html-gen, html-index, html-toc -- generate HTML
latex-gen, proof-latex -- generate LaTeX
filter-index, mk-mldoc-makefile -- miscellaneous ml-doc tools
SYNOPSIS
extract-sig [-config config-file] [-dir output-dir] mldoc-files
extract-info [-config config-file] [-dir output-dir] mldoc-files
merge-info [-config config-file] [-o output-file] info-files
html-index [-config config-file] [-dir output-dir] [-o output-file]
[-info path] [-cols num]
[-all | -sig | -struct | -exn | -type | -val]
html-toc [-config config-file] [-dir output-dir] [-o output-file]
[-info path] [-depth num]
html-gen [-config config-file] [-dir output-dir] [-info path-to-infofile]
[-wid num] mldoc-file
latex-gen [-config config-file] [-dir output-dir] [-doc] [-index]
[-info path-to-infofile] mldoc-file
proof-latex [-config config-file] [-dir output-dir] [-doc] [-index]
[-info path-to-infofile] mldoc-file
filter-index
mk-mldoc-makefile [-help] [-bin dir] [-html dir] [-info dir] [-latex dir]
[-proof dir] [-root file] mldoc-files
DESCRIPTION
ML-Doc is a system for producing reference manuals for SML libraries. It
can produce high quality documentation with extensive indexing, like the
published SML Basis Library reference manual, and also HTML for online
use.
ML-Doc is different to systems like javadoc that extract documentation
from source files. Rather, the documentation is the primary artifact--in
fact extract-sig can be used to create source files from documentation.
The mkdoc(1) utility, however, can produce first drafts from source
files. ML-Doc is most useful for documenting stable library interfaces.
ML-Doc files, marked by the extension .mldoc, are SGML documents conform-
ing to the ML-Doc document type definition.
This manual has four major sections besides the present one:
OPTIONS describes command line options and configuration
files.
USING ML-DOC describes how the toolset is used to produce docu-
mentation and includes subsections on HTML
Templates and Entities.
WRITING DOCUMENTATION describes the markup used within *.mldoc files.
SGML VS HTML/XML discusses some SGML features absent from HTML and
XML.
Generating SML
extract-sig -- Extracts SML signatures from *.mldoc documentation.
Generating intermediate files
extract-info -- Produces intermediate files summarising interfaces and
the section hierarchy.
merge-info -- Combines intermediate files into a single master info file.
Generating HTML
html-index -- Produces HTML index files from a master info file.
html-toc -- Transform a master info file and HTML template into a table
of contents.
html-gen -- Generate HTML output given template, master info, and mldoc
input files.
Generating LaTeX
latex-gen -- Produce LaTex for printing given master info and mldoc input
files.
proof-latex -- Produce LaTeX for proofing given master info and mldoc
input files.
Miscellaneous
filter-index -- Reads a list of index entries, one per line, from stan-
dard input, removes any duplicates, and writes the sorted entries to
standard output.
mk-mldoc-makefile -- Create a Makefile that ties all the other tools
together.
OPTIONS
Many command line options can also be specified in a configuration file,
using the names given in brackets.
-config config-file
Defaults to Config.cfg. Contains global and per-tool settings.
-cols num
(NumColumns) Number of columns in the index. Defaults to 3.
-debug (Debug) Currently unused.
-depth num
(Depth) Sections nested more deeply than this number will not be
listed in the table of contents. Defaults to 3.
-dir output-dir
(OutDir) Specifies where to write output files. The default is
different for each tool:
extract-sig Sigs
extract-info Info
html-index HTML
html-toc HTML
html-gen HTML
latex-gen Hardcopy
proof-latex Proof
-doc (Standalone) Currently unused.
-index Currently unused.
-info path
(MasterInfoFile) Locates the output of merge-info. Defaults to
Info/LaTeX.info for the hardcopy and proof tools, and
Info/HTML.info for the HTML tools.
-mldoc (MLDocDir) Names the subdirectory of the *.mldoc files. Defaults
to ML-Doc.
-o output-file
(OutFile) Specifies where to write output. For html-index the
default depends on the index generated:
all index-all.html
sig index-sig.html
struct index-struct.html
exn index-exn.html
type index-type.html
val index-val.html
Otherwise the name depends on the tool:
merge-info Info/Master.info
html-toc toc.html
-all | -sig | -struct | -exn | -type | -val
Specify which index to generate, defaulting to -all:
-all unified identifier index
-sig signatures
-struct structures
-exn exceptions
-type types
-val values
-wid num
(PreWid). Width of the output device. Currently unused. Defaults
to 60.
There are some additional options that can only be given in a configura-
tion file:
BaseURL Applies to the HTML grouping (described below). If the
RelativeLinks flag is true then intra-document links
will be relative, otherwise the value of BaseURL, if
present, is added as an HTML BASE tag.
Catalog Global option. Names the catalog file. Defaults to
CATALOG.
RelativeLinks Applies to the HTML grouping. See BaseURL above.
Defaults to false.
Root Applies to html-gen. Currently unused.
SGMLS Applies to the Tools grouping. Path to an SGML validat-
ing parser. Defaults to /usr/local/bin/nsgmls.
Template Applies to html-index, html-toc, and html-gen. Names
the template file.
TopLevelSection Applies to latex-gen and proof-latex. Defaults to
Chapter. Other permitted values are Part and Section.
Controls the generation of LaTeX sections.
A configuration file contains name/value pairs separated within and
between by white space. Single-line comments begin with a `#'. Groupings
are made by giving a name followed by contained options enclosed in
braces, { ... }. Values are either names, decimal or hexadecimal liter-
als, the latter prefixed with `0x', strings enclosed in double quotes, or
logical values (`TRUE' or `FALSE'). As a brief example:
# Catalog.cfg
Catalog "CATALOG"
HTML {
BaseURL "CML"
RelativeLinks TRUE
PreWid 70
}
mk-mldoc-makefile does not currently respect the configuration file,
instead it uses command line options, which differ somewhat from the
other tools:
-help Display a summary of options.
-bin dir
Specifies where the ML-Doc tool binaries are installed. Defaults
to /usr/local/bin.
-html dir
Output directory for HTML files. Defaults to HTML.
-info dir
Output directory for info files. Defaults to Info.
-latex dir
Output directory for LaTeX files. Defaults to Hardcopy.
-proof dir
Output directory for proof LaTeX files. Defaults to Proof.
-root file
If present, the generated Makefile will run LaTeX against the
given filename, which should not have a .tex extension.
USING ML-DOC
Directory structure
An ML-Doc project comprises a set of files and directories that, at a
minimum, will include:
CATALOG Typically links to Entities.sgml in the same directory
and the installed ML-Doc CATALOG file. See FILES.
Config.cfg Global and per-tool configuration options. See OPTIONS.
Entities.sgml Contains entities local to the project. These entities
are used for abbrevations and referencing external docu-
ments and files. See Entities.
ML-Doc/ The source *.mldoc SGML documentation.
index.template Template used by html-index.
page.template Template used by html-gen.
toc.template Template used by html-toc.
Running mk-mldoc-makefile adds:
Makefile Orchestrates the manifold programs to produce documenta-
tion.
The other tools place their output in additional subdirectories. Empty
subdirectories and any child directories therein must be created before
running the tools. The default names are:
HTML/ Output from the html-gen, html-toc, and html-index tools.
Hardcopy/ Output from latex-gen.
Info/ Output from extract-info, further augmented by
merge-info, to be used by the other tools.
Proof/ Output from proof-latex.
Sigs/ SML code created by extract-sig.
HTML Templates
Templates are HTML files containing special entities. The html-* tools
replace entities with details from *.mldoc and *.info files. Each tool
works from a distinct template named in the configuration file.
Tool name (in configuration file) Typical Template value
HTML-Gen page.template
HTML-Index index.template
HTML-TOC toc.template
The entities are:
&body; placeholder for document body
&filename; document filename without extension
&title; document title
&version; document version
&doc.date; document date in "month day, year" format
&doc.year; document year (4 digit format)
&doc.day; document day
&doc.month; document month (as a string)
&doc.monthnum; document month (as a number from 1-12)
&today.date; current date in "month day, year" format
&today.year; current year (4 digit format)
&today.day; current day
&today.month; current month (as a string)
&today.monthnum; current month (as a number from 1-12)
&base.url; URL of the root directory of the document
&parent.url; URL of the parent document
&root.url; URL of the document root
&index.url; URL of the document index
&toc.url; URL of the table of contents
Entities
Entities are used within ML-Doc to include mathematical and other spe-
cialised symbols, to abbreviate titles and other text, to reference
files, and to name certain output files. The latter three purposes are
served by including a customised Entities.sgml file within a project.
Specialised symbols include various mathematical symbols (described under
Mathematics), the HTML 2.0 standard entities, e.g. , ©, and
these SGML/LaTeX symbols:
< < <E; <=
> > >E; >=
&NEQ; != & &
&DQUOTE; " &BAR; |
&DASH; -
Abbreviations encourage consistency and facilitate certain types of
updates. These definitions, in an Entities.sgml file, are a good exam-
ple:
<!ENTITY SMLBASIS SDATA "SML Basis Library">
<!ENTITY SMLNJ SDATA "SML/NJ">
References, which will be expanded in the output text, may then be made
from *.mldoc files:
This feature requires the &SMLNJ; libraries.
Documentation will sometimes need to reference the ML-Doc descriptions of
other libraries; such as those of the SML Basis, SML/NJ, or Concurrent
ML. The reference tags described under References (e.g. SIGREF, AREF
and DOCREF) provide this facility via a DOCUMENT attribute whose value
must be an entity listed in Entities.sgml, a bracketing ampersand and
semicolon are not used for such values. The entity resolves to an iden-
tifying string, which is sought within the configuration file,
Config.cfg, to find an external document entry. As an example, consider
a constructor reference:
<CONREF DOCUMENT=SML-BASIS-DOC STRID="Option"/NONE/
The DOCUMENT attribute value, SML-BASIS-DOC, is defined in the project
entity file, Entities.sgml:
<!ENTITY SML-BASIS-DOC SDATA "SML-Basis-Doc">
The entity value, SML-Basis-Doc, in turn refers to an entry in the con-
figuration file:
...
SML-Basis-Doc {
InfoFile "/usr/local/smlnj/smlnj-lib/Doc/BasisInfo/HTML.info"
BaseURL "www.standardml.org/Basis"
RootURL "www.standardml.org/Basis/index.html"
}
...
This example refers to a master info file installed with SML/NJ and
directs hyperlinks to the online documentation.
Entities are also used within ML-Doc to specify values for the FILE
attribute, which specifies an input file for the (currently unsupported)
FIGURE tag, and names an output file for the SIGBODY tag. extract-sig
expands the given entity to name the source code it produces, e.g. given
an entity declaration:
<!ENTITY CML-SIG SDATA "cml-sig.sml">
The specifications in
<SIGBODY SIGID="CML" FILE=CML-SIG>
would be extracted to a file named cml-sig.sml.
General Use
A simplified sequence of steps for creating ML-Doc documentation:
1. Create and populate the basic directory structure, as per Directory
Structure.
2. Use mkdoc(1) to produce skeleton *.mldoc files. Add explanatory
text to each.
3. Add other *.mldoc files to link together into a continuous whole,
and to explain the various interfaces.
4. Create a Makefile with mk-mldoc-makefile, as shown under EXAMPLES.
5. Use the make targets to generate documentation.
HTML Default. Produce HTML pages.
Hardcopy Create LaTeX files for generating the final docu-
ment.
Proof Create LaTeX files for generating a review document.
clean Run the individual clean-html, clean-info,
clean-latex, and clean-proof targets to remove gen-
erated files.
6. LaTeX documentation requires further processing as described below.
7. Any changes to the library interface should be made against the
*.mldoc files, extract-sig is able to extract an updated SML ver-
sion.
LaTeX documents require a root file to specify the document class and
indexes. For example, if the first file is called intro.mldoc then
manual.tex might resemble:
\documentclass{mldoc-book}
\mldMakeTopicIndex\mldMakeIdIndex\mldMakeRaisesIndex
\newcommand{\kw}[1]{\textbf{#1}}
\begin{document}
\input{intro}
\mldPrintTopicIndex\mldPrintIdIndex\mldPrintRaisesIndex
\end{document}
The kw command formats identifiers. The mldoc class and style files must
be in a path searched by LaTeX. Updating the TEXINPUTS environment vari-
able is one way of ensuring this. E.g. under bash:
export TEXINPUTS=".:/usr/local/share/ml-doc/lib/LaTeX:".
The EXAMPLES section shows how to run the LaTeX tools.
WRITING DOCUMENTATION
This section essentially elaborates on the ml-doc.dtd file. An ML-Doc
file begins with the declaration:
<!DOCTYPE ML-DOC SYSTEM>
and contains header elements followed by one or more, potentially nested,
sections.
There are four types of header element. Only TITLE is mandatory. They
may be given in any order.
VERSION The version of the documentation, with attributes:
VERID e.g. `1.4'.
YEAR Year of release.
MONTH (optional) Month of release.
DAY (optional) Day of release.
E.g. <VERSION VERID="1.4" YEAR=2007 MONTH=8 DAY=12>
COPYRIGHT Identify a copyright holder with attributes:
OWNER The copyright owner.
YEAR Year of assertion.
E.g. <COPYRIGHT OWNER="Mega Corp" YEAR=2003>
Multiple COPYRIGHT elements may be present.
AUTHOR Identifies the document author, with attributes:
NAME Name of author.
EMAIL Email address of author.
YEAR Year written.
MONTH (optional) Month written.
DAY (optional) Day written.
E.g. <AUTHOR NAME="J. Doe" EMAIL="doej@mega.co"
YEAR=2006>
TITLE The document title. E.g. <TITLE>Superhash
Structure</TITLE>
Sections begin with a HEAD element, followed by zero or more paragraphs
(PP and FLOAT elements), and then zero or more nested sections, included
files and/or interfaces. The SECTION tag has three optional attributes:
LABEL A string used for making cross-references (from SECREF).
NONUMBER If present, the section will not be numbered in LaTeX
output.
NOTOC Excludes the section from the table of contents. Only
valid if NONUMBER is present.
HEAD and PP elements have no attributes. For FLOAT elements see GENERAL
MARKUP. E.g.
<SECTION>
<HEAD>General Markup</HEAD>
<PP>
Various tags provide...
<SECTION>
<HEAD>Formatting</HEAD>
<PP>
Tags available for inline...
</SECTION>
...
</SECTION>
Typically a separate *.mldoc file will be used for each major topic, such
as introductory or background text, and interface (signature, structure
or functor). A corresponding *.html file, for HTML output, and/or *.tex
file, for LaTeX output, is generated for each ML-Doc source file. A com-
plete document is constructed by including, with INCLFILE tags, individ-
ual files within a hierarchy of sections. Inclusions become hyperlinks
in HTML output and inserted pages in LaTeX output. An INCLFILE has a sin-
gle, mandatory FILE attribute specifying a relative or absolute file
path. The .mldoc extension is implied. E.g.
<INCLFILE FILE="lib/hash-sig">
SGML comments, e.g. <!-- check source code. -->, are ignored.
SML objects are described between INTERFACE tags which have optional
LABEL attributes for making cross-references. An INTERFACE element con-
tains, in order: a HEAD element (as per SECTION), an optional SEEALSO
element containing one or more references (see References), optional
paragraphs of introductory text, an object description, and optional
paragraphs of concluding text.
Object Descriptions
Object description elements may have a STATUS attribute, with value
REQUIRED, OPTIONAL, or PROPOSED. There are three types of element for
describing objects provided by a library:
SIGNATURE With mandatory SIGID attribute.
STRUCTURE With mandatory STRID attribute.
FUNCTOR With mandatory FCTID attribute.
Example outline of an interface:
<INTERFACE>
<HEAD>The <CD/Hash/ structure</HEAD>
<SEEALSO>
<STRREF DOCUMENT=SML-BASIS-DOC TOPID/Option/
<STRREF DOCUMENT=SML-BASIS-DOC TOPID/Time/
</SEEALSO>
<PP>
Optional text after synopsis.
<STRUCTURE STRID="CML">
...
</STRUCTURE>
<PP>
Optional final discussion.
</INTERFACE>
It is usually easier to generate object descriptions directly from SML
source files using mkdoc(1).
The SIGBODY element is central to describing objects. It must be
included in SIGNATUREs, may be included in STRUCTUREs and FUNCTORs, and
has two optional attributes:
SIGID Identifies the signature being described. It is used for
cross-referencing. When a SIGBODY is given within a
SIGNATURE, both may have identical SIGID values. Within a
STRUCTURE the SIGID attribute is usually the `signature
version' of the outer STRID. It is a succinct way of
describing both interface and implementation, e.g.
<STRUCTURE STRID="ControlSet">
<SIGBODY SIGID="CONTROL_SET" FILE=CONTROL-SET>
...
</SIGBODY>
</STRUCTURE>
FILE The mkdoc(1) utility uses the value of this attribute to
name extracted SML files. SIGID and FILE are typically
omitted on SIGBODYs used as functor arguments.
A SIGBODY contains one or more SPEC and/or SPECBREAK elements. The for-
mer is described under Specifications. The latter is used to form sub-
groups of related specifications, when marked with a NEWLINE attribute,
blank lines are placed in both extracted signatures and generated output.
A SIGNATURE contains a SIGBODY which may be followed by a series of
SIGINSTANCE elements that list structures implementing the signature,
each containing an ID, zero or more WHERETYPE elements, and optionally a
COMMENT. A WHERETYPE element states which signature types are instanti-
ated in an implementation, it consists of an optional TYPARAM binding,
the ID of the type, and a TY type constraint. The COMMENT, TYPARAM, and
TY elements are described below. The SIGINSTANCE tag has two optional
attributes:
STATUS Having a value of REQUIRED, OPTIONAL, or PROPOSED.
OPAQUE Indicates an opaque signature binding.
This example from the SML/NJ Library:
<SIGNATURE SIGID="ORD_MAP">
<SIGBODY SIGID="ORD_MAP" FILE=ORD-MAP>
...
<SIGINSTANCE OPAQUE><ID>IntBinaryMap
<WHERETYPE><ID>Key.ord_key<TY>Int.int
<COMMENT>
...
<SIGINSTANCE OPAQUE><ID>IntListMap
<WHERETYPE><ID>Key.ord_key<TY>Int.int
<COMMENT>
...
</SIGNATURE>
would yield a synopsis:
signature ORD_MAP
structure IntBinaryMap :> ORD_MAP
structure IntListMap :> ORD_MAP
A STRUCTURE contains either a full SIGBODY, as described above, or simply
the name of (ID), or reference to (SIGREF) a signature described else-
where. A name or reference may be followed by WHERETYPE type realisa-
tions. An OPAQUE element can be placed before the signature body, name
or reference, to signify an opaque binding, e.g.
<STRUCTURE STRID="Store">
<OPAQUE>
<SIGREF/ORD_SET/
<WHERETYPE><ID>Key.ord_key<TY>String.string
</STRUCTURE>
The contents of a FUNCTOR are identical to those of a STRUCTURE, except
that they must begin with an argument element, which takes one of two
forms:
short An argument name (ID) followed by the name of (ID), or
reference (SIGREF) to a signature.
general A SIGBODY element containing specifications, notably of
SUBSTRUCT and TYPE elements.
E.g. functor ListSetFn (ORD_KEY): ORD_SET could be written:
<FUNCTOR FCTID="ListSetFn">
<ID/K/<ID>ORD_KEY</ID> <!--argument-->
<ID>ORD_SET <!--result-->
</FUNCTOR>
The second ID could have been written as a SIGREF, the third could have
been given in full using SIGBODY.
Specifications
A SIGBODY comprises a list of SPEC elements, each containing either a
single substructure specification, or multiple specifications of the same
kind (though types and eqtypes may be mixed), and optionally followed by
a comment. The specification element types are:
INCLUDE An ID or SIGREF naming an included signature, optionally
followed by WHERETYPE realisations. E.g.
<SPEC><INCLUDE><SIGREF DOCUMENT=SML-BASIS-DOC/OS_IO/
SUBSTRUCT The contents are identical to those of STRUCTURE except
that the first contained element must be an ID naming the
substructure, e.g.
<SPEC><SUBSTRUCT>Key<SIGREF/ORD_KEY/</SUBSTRUCT>
SHARING An ID followed by one or more pairings of EQU and ID ele-
ments. The SHARING element may include a TYPE attribute.
E.g.
<SPEC>
<SHARING TYPE><ID>A.vector<EQU><ID>V.vector
<SHARING TYPE><ID>A.elem<EQU><ID>V.elem
...
EXN An ID and optional TY, e.g.
<EXN><ID>Fail<TY>string
or taking advantage of SGML short-hand (the ID tag is
optional):
<EXN>Fail<TY>string
TYPE / EQTYPE An optional TYPARAM, an ID, and an optional TY, e.g.
<TYPE><TYPARAM>'a<ID>queue
DATATYPE An optional TYPARAM, an ID, and a list of CONS elements,
each containing an ID followed by optional TY and COMMENT
elements, e.g.
<SPEC>
<DATATYPE><TYPARAM>'a<ID>option
<CONS>NONE
<CONS>SOME<TY>'a
</DATATYPE>
A DATATYPE element may be marked with a COMPACT attribute
that directs the output generators to place all of the
constructors on a single line if possible.
DATATYPEDEF An ID followed by another ID or a TYREF. Adds a datatype
replication, e.g.
<DATATYPEDEF><ID>access_mode</ID>
<TYREF STRID="OS.FileSys" DOCUMENT=SML-BASIS-DOC>
OS.FileSys.access_mode</TYREF>
</DATATYPEDEF>
VAL An ID followed by a TY and optionally a RAISES element
containing one or more EXNREFs, e.g.
<SPEC>
<VAL>fact<TY>int -> int
<RAISES><EXNREF/Domain/
<EXNREF/Overflow/
Comments
Comments may be included as the last item within a SIGINSTANCE, SPEC, or
CONS element. A COMMENT contains one or more paragraphs (PP), each
optionally preceded by a PROTOTY element that contains one or more PROTO
elements showing, in SML, how an object might be called or used with
argument names. To take an example from the SML Basis Library:
<SPEC>
<VAL>before<TY>('a * unit) -> 'a
<COMMENT>
<PROTOTY>
<PROTO>
<ARG/a/ before <ARG/b/
<PP>
returns <ARG/a/. It provides a notational shorthand for
evaluating <ARG/a/, then <ARG/b/, before returning the
value of <ARG/a/.
The specific argument names make it easier to write a description of what
the function does.
The final element within a PROTO can be EVALTO, which should contain SML
showing the result of evaluating the expression.
References
There are several ways to cross-reference:
SML objects Signatures, structures, functors, and their contents.
Further details follow this list.
External objects An IDREF element references an external non-SML identi-
fier. An optional KIND attribute describes what is
being referred to, e.g. a C function or a system call.
If the NOINDEX attribute is present the identifier
instance is not noted in an index. E.g. <IDREF
KIND="POSIX" NOINDEX/printf/
HTML anchors Cross-linking for HTML output. An ADEF with mandatory
TAG attribute defines an anchor name for a run of text.
AREF elements, also with TAG attributes, link back to
the matching name. Reference is made to anchors in
other documents by setting the DOCUMENT attribute to an
entity value, see Entities. E.g.
<ADEF TAG="FLUSHWARNING">Disaster results if a flush
is attempted after closing the pipe</ADEF>.
...
Heed the <AREF TAG="FLUSHWARNING">earlier</AREF> warning.
URLs A URL tag links to an external resource specified by an
HREF attribute. This tag is ignored when generating
LaTeX output.
External ML-Doc Reference is made to other ML-Doc documents with a
DOCREF element that specifies an entity with the
DOCUMENT attribute, e.g.
...features of the <DOCREF
DOCUMENT=SML-BASIS-DOC/SML Basis Library/...
Sections/floats Cross-references may be made to SECTIONs or FLOATs that
have LABEL attributes. The former using SECREF and the
latter with FLOATREF. Both require a LABEL attribute
of their own. Neither contain text, which comes
instead from the referenced object. E.g.
<SECTION LABEL="Files">
...
<SECTION LABEL="Storage">
<HEAD>Sockets</HEAD>
<PP>
The <SECREF LABEL="Files"> section describes...
Citations A CITE element refers to a bibliography entry. It is
not supported by the HTML generators. The value of the
KEY attribute is passed directly into LaTeX.
The remainder of this section discusses references to SML objects. These
references are included in the document index, if not marked with a
NOINDEX attribute, and become hyperlinks in HTML output, unless marked
with a NOLINK attribute. A DOCUMENT attribute is used to reference
another ML-Doc project.
The SML object reference tags are:
SIGREF Refer to a complete signature, e.g.
<SIGREF/MONO_ARRAY_SORT/
FCTREF Refer to a functor, e.g.
The <FCTREF NOLINK/ArrayQSortFn/ implements...
FCTARGREF Refer to the argument of a functor.
STRREF Refer to a structure or substructure.
EXNREF Refer to an exception, e.g.
<RAISES>
<EXNREF STRID="General" DOCUMENT=SML-BASIS-DOC/Size/
TYREF Refer to a type, e.g.
...constructor <TYREF SIGID="UREF">uref</TYREF> with...
CONREF Refer to a datatype constructor, e.g.
...then it returns <CONREF STRID="Option"/NONE/
VALREF Refer to a value, e.g <VALREF>randMin</VALREF>.
A context attribute should be given with the latter five tags when they
refer to a specification in another part of the module hierarchy. There
are four, mutually exclusive, possibilities:
SIGID For specifications in SIGNATUREs.
STRID For specifications in STRUCTUREs or SUBSTRUCTs.
FCTID For specifications in FUNCTORs.
TOPID For specifications available at the top-level without quali-
fication. No value is given.
Examples may be seen throughout this document. The partial path given in
the *ID attribute and the reference text are merged when there is overlap
between the rightmost components of the former and the leftmost compo-
nents of the latter. For example, in cases like:
<TYREF STRID="OS.FileSys">OS.FileSys.access_mode</TYREF>
An *ID attribute is not required when the reference is to another element
in the same SIGBODY.
Formatting
Tags available for inline formatting:
tag effect
EM emphasis
IT italics
BF bold
TT typewriter
CD code
ARG function argument
KW keyword
Program text may also be displayed, rather than inlined with the tag
CODE. Both CD and CODE tags may carry a LANG attribute having a value of
either "sml" or "c".
Tables
Tables are as in HTML but initial COL tags are mandatory:
<TABLE>
<COL ALIGN=LEFT PARBOX="5em"><COL ALIGN=CENTER><COL ALIGN=RIGHT>
<TR><TH>Colour<TH>Code<TH>Comment
<TR><TD>Red<TD><CD/#FF0000/<TD>Plain red
<TR><TD>Blue<TD><CD/#0000FF/<TD>Plain blue
</TABLE>
Table heading (TH) and cell (TD) elements have optional ALIGN and COLSPAN
attributes. Tables that span multiple pages should be marked LONG.
Floats
Source code and (non-LONG) tables may be floated:
<FLOAT LABEL="modlist" CAPALIGN=TOP>
<CAPTION>Module List
<TABLE>...</TABLE>
</FLOAT>
The LABEL attribute is obligatory and may be referenced from a FLOATREF.
Lists
There are three types of lists:
- itemized (bulleted items), e.g.
<ITEMIZE>
<ITEM>First item
<ITEM>Second item
</ITEMIZE>
- enumerated (numbered), e.g.
<ENUM>
<ITEM>First item
<ITEM>Second item
</ENUM>
- descriptive, e.g.
<DESCRIP>
<DTAG/first/<ITEM>text about first item
<DTAG/second/<ITEM>text about second item
</DESCRIP>
Miscellaneous Text Blocks
Paragraphs may be grouped based on intent:
EXAMPLE For extended examples.
QUESTION Presents a note on, or discussion of, open design issues.
IMPLNOTE Implementation notes, e.g. expected efficiency.
RATIONALE Explain the reasons behind design decisions.
SYSNOTE Comments specific to an architecture (named with the ARCH
attribute) or operating system (the OPSYS attribute).
As an example:
<PP>
<RATIONALE>
<PP>
These functions...
<PP>
An alternative...
</RATIONALE>
Regular Expressions
Regular expressions may be included within text (RE) or displayed on
their own line (REGEXP). Literal characters are tagged as GRAM.LIT and
displayed in typewriter font (other possible atoms are GRAM.NONTERM in
italics, GRAM.TERM in roman, and GRAM.KW in bold). E.g.
<RE><GRAM.LIT/i/<GRAM.LIT/f/</RE>
gives: if
Characters sets, displayed between square brackets, are built with
GRAM.CSET. Sets may include character atoms and ranges, e.g.
<REGEX><GRAM.CSET><GRAM.RANGE><GRAM.LIT/A/<GRAM.LIT/F/<GRAM.RANGE>
<GRAM.RANGE><GRAM.LIT/a/<GRAM.LIT/f/<GRAM.RANGE>
</GRAM.CSET></REGEX>
gives: [A-Fa-f]
Closures are expressed by grouping characters and specifying a count,
e.g.
<RE><GRAM.GRP ONE-OR-MORE><GRAM.LIT/a/<GRAM.LIT/b/</GRAM.GRP></RE>
gives: (ab)+
Possible counts are: ONE (the default), ZERO-OR-ONE, ZERO-OR-MORE,
ONE-OR-MORE.
Alternation, regular expressions separated by bars, is also possible,
e.g.
<RE><GRAM.ALT>
<GRAM.LIT/A/
<GRAM.GRP ZERO-OR-MORE><GRAM.LIT/B/</GRAM.GRP>
</GRAM.ALT></RE>
gives: A | B*
Mathematics
Some support is provided for type-setting mathematics. Formulas may be
placed in running text (MATH), displayed (on a separate line,
DISPLAYMATH) or made into a table of equations, e.g.
<EQNARRAY>
<EQN>x + y<EQNREL/=/2</EQN>
<EQN>y<EQNREL/>=/0</EQN>
</EQNARRAY>
gives:
x + y = 2
y >= 0
Other features:
subscripts <MATH>x<SUB/i+1/</MATH>
superscripts <MATH>x<SUP/2*3/</MATH>
modulo <MATH>x<MOD/y+z/</MATH>
displayed as: x (mod (y+z))
fractions <MATH><FRAC>1<OVER>2</FRAC></MATH>
absolute value <MATH><NORM>x + y</NORM></MATH>
ceiling <MATH><CEILING>x + y</CEILING></MATH>
floor <MATH><FLOOR>x + y</FLOOR></MATH>
sets <MATH><SET>x | x > 2</SET></MATH>
Argument variables, e.g. <ARG/lset/, may be included in formulas, as may
normal (roman) text, e.g.
<MTEXT/if not empty/
The predefined mathematical entities are:
&CUP; &CAP; &EXISTS; FORALL
&GREATER; &GREATEREQ; &IN; &LESS;
&LESSEQ; &NOTEQ; &NOTIN; &OMINUS;
&OPLUS; &OTIMES; &PI; &PLUSMINUS;
&MINUSPLUS; &INF;
Indexing
A hardcopy document contains up to three separate indexes:
topic General index (by topic)
id SML identifier index
raises Raised exception index
In HTML, separate indexes for signatures, structs, and types are possi-
ble.
Entries are extracted automatically from interface descriptions. They may
also be inserted into text manually with the INDEX tag, e.g.
This module handles <INDEX KEY="Error Reporting">error reporting.
creating an entry in the General Index, by default, with appropriate page
number:
Error Reporting, 14
The index--one of "topic, id" or "raises"--is specified with the WHICH
attribute. The SEE attribute replaces the page number with the given
text.
The key-view tag specifies alternate text or formatting for an index
entry. Extra sub-index tags can be added, with optional key-views, to
provide one or two extra levels of specificity, e.g.
This module handles <INDEX KEY="Error Reporting">
<KEY-VIEW><IT/Error Reporting/</KEY-VIEW>
<SUBINDEX KEY="Module">
</INDEX>error reporting.
Gives:
Error Reporting
Module, 14
Topics that span bodies of text are delimited with START and STOP
attributes, e.g.
<INDEX KEY="Displays" START> This chapter discusses display
characteristics of...
...which concludes our discussion.<INDEX KEY="Displays" STOP>
Could produce:
Displays, 19--25
SGML vs HTML/XML
Although the basics of editing ML-Doc will be familiar to most authors of
HTML and XML, SGML has some peculiarities that are designed to make edit-
ing `by hand' easier.
Many end-tags are optional, as in HTML, but unlike in XML, e.g.
<PP>
No explicit end-tag is given for this paragraph...
<PP>
...before moving into the next
The usual start and end-tags are acceptable:
<CD>'a</CD>
But null end-tags can also be used for the same effect:
<CD/'a/
Attribute names are often optional when an enumerated value is required,
i.e. instead of <GRAM.GRP COUNT=ONE> one can also write <GRAM.GRP ONE>.
some attribute values can be stated without a name, i.e. instead of:
<SPECBREAK NEWLINE=NEWLINE>
one can write:
<SPECBREAK NEWLINE>
Attribute values need not always be enclosed in double quotes.
These details are well described in Chapter 9 of SGML and HTML Explained
(refer SEE ALSO).
FILES
System-wide ML-Doc files and directories are stored at:
/usr/local/share/ml-doc
Notably:
lib/catalog Master catalog file.
lib/ml-doc.dtd DTD of ML-Doc language.
lib/entities.sgml Entity definitions (see
Entities).
lib/LaTeX/ LaTeX class and style files for
Hardcopy and Proof output.
EXAMPLES
After creating the directory structure (see Directory Structure), and
writing up the ML-Doc files (see WRITING DOCUMENTATION), create a
Makefile:
find ML-Doc -name '*.mldoc' -print | mk-mldoc-makefile
Then produce HTML documentation:
make
and/or LaTeX:
make Hardcopy
Creating/updating a signature file:
extract-sig ML-Doc/sync-var.mldoc
Processing LaTeX output:
latex manual
makeindex -o manual.ind manual.idx # topic index
makeindex -o manual.nnd manual.ndx # identifier index
makeindex -o manual.rnd manual.rdx # exception index
latex manual
BUGS
The utilities do not provide helpful error messages, usually just
uncaught exceptions.
The toolset does not seem, in totality, to handle sub-directories under
ML-Doc very well. Soft links provide a rudimentary work around.
The FIGURE tag is not implemented.
The GRAMMAR and GRAM.SEP tags are not supported.
Neither SUM, PROD, UNION, nor INTERSECT are implemented.
SUB and SUP do not work well together, i.e. squaring the ith x will not
be typeset properly:
<MATH>x<SUB/i/<SUP/2/</MATH>
It is not clear what MGROUP does. The contents are wrapped in brackets ()
in HTML output and invisible parentheses {} in LaTeX output.
The target added by the -root option of mk-mldoc-makefile does not run
makeindex(1).
It is not clear how to write mutually recursive DATATYPE or VAL specifi-
cations, nor is it clear what the REC attribute signifies .
The DOCREF tag is not supported. There is no way of referencing INTERFACE
elements (i.e. the LABEL attribute is redundant).
SEE ALSO
mkdoc(1), /usr/local/share/ml-doc/lib/ml-doc.dtd.
John H. Reppy, Concurrent Programming in ML, Cambridge University Press,
1999.
Emden R. Gansner and John H. Reppy, The Standard ML Basis Library,
Cambridge University Press, 2004.
Martin Bryan, SGML and HTML Explained, Addison Wesley Longman, 1997,
available online: http://www.is-thought.co.uk/book/home.htm.
AUTHORS
John H. Reppy <jhr@cs.uchicago.edu> wrote and maintains ML-Doc.
Andrew Appel <appel@princeton.edu> wrote the first version of latex-gen.
Lal George <lg@network-speed.com> wrote the proof-latex tool.
Timothy Bourke <tim@tbrk.org> wrote this man page for the FreeBSD port
based on documentation and source files from the distribution.
FreeBSD 6.2 August 2, 2007 FreeBSD 6.2