path: root/devel/ml-doc/files/ml-doc.1.in

.\" $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 &LT; Ta Li < Ta Li &LTE; Ta Li <=
.It Li &GT; Ta Li > Ta Li &GTE; Ta Li >=
.It Li &NEQ; Ta Li != Ta Li &AMP; 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 ,
first edit the
.Pa CATALOG
file:
.Bd -literal -offset indent -compact
ENTITY    %document-entities    "Entities.sgml"
CATALOG                         "%%PREFIX%%/share/ml-doc/lib/catalog"
.Ed
Then, 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.