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