.\" $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 /usr/local/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 /usr/local/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 .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 .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 "/usr/local/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 .Ed The specifications in .D1 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=".:/usr/local/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 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 .\" ** .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 .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 .\" ** .It Li TITLE The document title. E.g. .Li Superhash Structure .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
General Markup Various tags provide...
Formatting Tags available for inline...
...
.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 .\" .Pp SGML comments, e.g. .Li , 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 The Optional text after synopsis. ... Optional final discussion. .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 ... .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 ... IntBinaryMap Key.ord_keyInt.int ... IntListMap Key.ord_keyInt.int ... .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 Key.ord_keyString.string .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 ORD_KEY ORD_SET .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 Key .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 A.vectorV.vector A.elemV.elem ... .Ed .\" ** .It Li EXN An .Li ID and optional .Li TY , e.g. .Bd -literal -compact Failstring .Ed or taking advantage of SGML short-hand .Pq the Li ID No tag is optional : .Bd -literal -compact Failstring .Ed .\" ** .It Li TYPE No / Li EQTYPE An optional .Li TYPARAM , an .Li ID , and an optional .Li TY , e.g. .Bd -literal -compact 'aqueue .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 'aoption NONE SOME'a .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 access_mode OS.FileSys.access_mode .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 factint -> int before('a * unit) -> 'a returns Disaster results if a flush is attempted after closing the pipe. ... Heed the earlier 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 .Li ...
Sockets The 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 uref with... .Ed .\" ** .It Li CONREF Refer to a datatype constructor, e.g. .Bd -literal -compact .Li ...then it returns randMin . .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 OS.FileSys.access_mode 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
ColourCodeComment
RedPlain red
BluePlain blue
.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 Module List ...
 .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 First item Second item .Ed .It enumerated (numbered), e.g. .Bd -literal -compact First item Second item .Ed .It descriptive, e.g. .Bd -literal -compact text about first item text about second item .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 ... These functions... An alternative... .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 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 .Ed gives: .Li [A-Fa-f] .Pp Closures are expressed by grouping characters and specifying a count, e.g. .Dl 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 .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 x + y y=/0 .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 x + y" .It subscripts Ta Li x .It superscripts Ta Li x .It modulo Ta Li x .It Ta Em displayed as: Li x (mod (y+z)) .It fractions Ta Li 12 .It absolute value Ta Li x + y .It ceiling Ta Li x + y .It floor Ta Li x + y .It sets Ta Li x | x > 2 .El .Pp Argument variables, e.g. .Li 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 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 This chapter discusses display characteristics of... ...which concludes our discussion. .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 No explicit end-tag is given for this paragraph... ...before moving into the next .Ed .Pp The usual start and end-tags are acceptable: .Dl 'a But .Em null end-tags can also be used for the same effect: .Dl one can also write .Li . some attribute values can be stated without a name, i.e. instead of: .Dl one can write: .Dl .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 /usr/local/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 x .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 /usr/local/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.