ports/115932: New port: devel/ml-doc
Timothy Bourke
timbob at bigpond.com
Wed Aug 29 23:10:02 UTC 2007
>Number: 115932
>Category: ports
>Synopsis: New port: devel/ml-doc
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-ports-bugs
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Wed Aug 29 23:10:00 GMT 2007
>Closed-Date:
>Last-Modified:
>Originator: Timothy Bourke
>Release: FreeBSD 6.1-RELEASE-p6 i386 (uname -s -r -m)
>Organization:
n/a
>Environment:
>Description:
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
>How-To-Repeat:
>Fix:
--- newport begins here ---
# This is a shell archive. Save it in a file, remove anything before
# this line, and then unpack it by entering "sh file". Note, it may
# create directories; files and directories will be owned by you and
# have default permissions.
#
# This archive contains:
#
# ml-doc
# ml-doc/Makefile
# ml-doc/pkg-descr
# ml-doc/distinfo
# ml-doc/files
# ml-doc/files/patch-config-install-sml-wrapper_sh.in
# ml-doc/files/patch-configure
# ml-doc/files/lib-Makefile
# ml-doc/files/patch-tools-lib-latex-text_to_latex.sml
# ml-doc/files/patch-tools-html-gen-do_spec.sml
# ml-doc/files/ml-doc.1.in
# ml-doc/files/mkdoc.1.in
# ml-doc/files/patch-Makefile.in
# ml-doc/pkg-plist
#
echo c - ml-doc
mkdir -p ml-doc > /dev/null 2>&1
echo x - ml-doc/Makefile
sed 's/^X//' >ml-doc/Makefile << 'END-of-ml-doc/Makefile'
X# New ports collection makefile for: ml-doc
X# Date created: 21 Aug 2007
X# Whom: Timothy Bourke <timbob at bigpond.com>
X#
X# $FreeBSD$
X#
X
XPORTNAME= ml-doc
XPORTVERSION= 2.0
XCATEGORIES= devel
XMASTER_SITES= http://people.cs.uchicago.edu/~jhr/tools/downloads/ \
X http://www.cse.unsw.edu.au/~tbourke/distfiles/
XDISTNAME= ${PORTNAME}
XEXTRACT_SUFX= .tgz
X
XMAINTAINER= timbob at bigpond.com
XCOMMENT= Produces documentation from SML signatures
X
XBUILD_DEPENDS= smlnj-devel>=110.65:${PORTSDIR}/lang/sml-nj-devel \
X nsgmls:${PORTSDIR}/textproc/jade
XRUN_DEPENDS= nsgmls:${PORTSDIR}/textproc/jade
X
XGNU_CONFIGURE= yes
XCONFIGURE_ENV+= SMLNJ_DEVEL=yes
XALL_TARGET= build
XMAKE_ENV+= DATADIR=${DATADIR} SMLNJ_DEVEL=yes
X
XSUB_FILES= ml-doc.1 mkdoc.1
XMAN1= ml-doc.1 mkdoc.1
XMLINKS= ml-doc.1 extract-sig.1 ml-doc.1 extract-info.1 \
X ml-doc.1 merge-info.1 ml-doc.1 html-gen.1 \
X ml-doc.1 html-index.1 ml-doc.1 html-toc.1 \
X ml-doc.1 latex-gen.1 ml-doc.1 proof-latex.1 \
X ml-doc.1 filter-index.1 ml-doc.1 mk-mldoc-makefile.1
X
XOPTIONS= LATEX "Install LaTeX if necessary (needed for pdf output)" OFF
X
X.include <bsd.port.pre.mk>
X
X.if defined(WITH_LATEX)
XRUN_DEPENDS+= latex:${PORTSDIR}/print/teTeX
X.endif
X
Xpost-extract:
X @${CP} ${FILESDIR}/lib-Makefile ${WRKSRC}/lib/Makefile
X
Xpost-install:
X @${INSTALL_MAN} ${WRKDIR}/ml-doc.1 ${MAN1PREFIX}/man/man1
X @${INSTALL_MAN} ${WRKDIR}/mkdoc.1 ${MAN1PREFIX}/man/man1
X
X.include <bsd.port.post.mk>
END-of-ml-doc/Makefile
echo x - ml-doc/pkg-descr
sed 's/^X//' >ml-doc/pkg-descr << 'END-of-ml-doc/pkg-descr'
XML-Doc is a system for documenting the interfaces of SML libraries. It can
Xproduce both HTML and LaTeX output.
X
XWWW: http://people.cs.uchicago.edu/~jhr/tools/ml-doc.html
END-of-ml-doc/pkg-descr
echo x - ml-doc/distinfo
sed 's/^X//' >ml-doc/distinfo << 'END-of-ml-doc/distinfo'
XMD5 (ml-doc.tgz) = 2ca9d9e9632ddc9de2880b2a40db0b54
XSHA256 (ml-doc.tgz) = bb296dd03474bbc365e31ec1958d8ba08e35801a9c0a60a600d8d4a54c369493
XSIZE (ml-doc.tgz) = 371727
END-of-ml-doc/distinfo
echo c - ml-doc/files
mkdir -p ml-doc/files > /dev/null 2>&1
echo x - ml-doc/files/patch-config-install-sml-wrapper_sh.in
sed 's/^X//' >ml-doc/files/patch-config-install-sml-wrapper_sh.in << 'END-of-ml-doc/files/patch-config-install-sml-wrapper_sh.in'
X--- config/install-sml-wrapper_sh.in.orig Thu May 10 23:24:11 2007
X+++ config/install-sml-wrapper_sh.in Sun Jul 22 16:49:42 2007
X@@ -9,9 +9,10 @@
X #
X # install-sml-wrapper.sh <program-name> <install-dir>
X
X-INSTALL="@INSTALL@"
X-INSTALL_DATA="@INSTALL_DATA@"
X+INSTALL="$BSD_INSTALL_PROGRAM"
X+INSTALL_DATA="$BSD_INSTALL_DATA"
X HEAP_SUFFIX="@SMLNJ_HEAP_SUFFIX@"
X+HEAP2EXEC=/usr/local/bin/heap2exec
X
X if test $# -ne 2 ; then
X echo "usage: install-sml-wrapper.sh <program-name> <install-dir>"
X@@ -22,29 +23,17 @@
X TARGET=`basename $SRC`
X HEAP_IMAGE=$SRC.$HEAP_SUFFIX
X INSTALL_DIR=$2
X-INSTALL_HEAP_DIR=$INSTALL_DIR/.heap
X-INSTALL_HEAP_IMAGE=$INSTALL_HEAP_DIR/$TARGET.$HEAP_SUFFIX
X
X if test ! -f $HEAP_IMAGE ; then
X echo "heap image $HEAP_IMAGE not found"
X exit 1
X fi
X
X-# create the wrapper script
X-#
X-cat > $TARGET <<XXXX
X-#!/bin/sh
X-#
X-exec @SMLNJ_CMD@ @SMLcmdname=\$0 @SMLload=$INSTALL_HEAP_IMAGE \$@
X-XXXX
X+$HEAP2EXEC $HEAP_IMAGE $TARGET
X
X #install the script and heap image
X #
X $INSTALL $TARGET $INSTALL_DIR/$TARGET || exit 1
X-if test ! -d $INSTALL_HEAP_DIR ; then
X- mkdir $INSTALL_HEAP_DIR || exit 1
X-fi
X-$INSTALL_DATA $HEAP_IMAGE $INSTALL_HEAP_IMAGE || exit 1
X
X # remove the local copy of the script
X rm -f $TARGET
END-of-ml-doc/files/patch-config-install-sml-wrapper_sh.in
echo x - ml-doc/files/patch-configure
sed 's/^X//' >ml-doc/files/patch-configure << 'END-of-ml-doc/files/patch-configure'
X--- configure.orig Mon Jun 18 16:28:59 2007
X+++ configure Wed Aug 22 14:15:02 2007
X@@ -1374,7 +1374,7 @@
X
X
X if test z$SMLNJ_CMD = z ; then
X- for ac_prog in sml-cm sml
X+ for ac_prog in sml
X do
X # Extract the first word of "$ac_prog", so it can be a program name with args.
X set dummy $ac_prog; ac_word=$2
X@@ -1471,8 +1471,8 @@
X then
X USING_NEW_CM="TRUE"
X else
X- { { echo "$as_me:$LINENO: error: installation requires version 110.55+ of SML/NJ" >&5
X-echo "$as_me: error: installation requires version 110.55+ of SML/NJ" >&2;}
X+ { { echo "$as_me:$LINENO: error: installation requires version 110.61+ of SML/NJ" >&5
X+echo "$as_me: error: installation requires version 110.61+ of SML/NJ" >&2;}
X { (exit 1); exit 1; }; }
X fi
X
X@@ -1538,10 +1538,10 @@
X hppa*:hpux9*) SMLNJ_ARCH=hppa; SMLNJ_OPSYS=hpux9;;
X hppa*:hpux10*) SMLNJ_ARCH=hppa; SMLNJ_OPSYS=hpux;;
X i386:darwin*) SMLNJ_ARCH=x86; SMLNJ_OPSYS=darwin;;
X- i386:freebsd*) SMLNJ_ARCH=x86; SMLNJ_OPSYS=freebsd;;
X- i486:freebsd*) SMLNJ_ARCH=x86; SMLNJ_OPSYS=freebsd;;
X- i586:freebsd*) SMLNJ_ARCH=x86; SMLNJ_OPSYS=freebsd;;
X- i686:freebsd*) SMLNJ_ARCH=x86; SMLNJ_OPSYS=freebsd;;
X+ i386:freebsd*) SMLNJ_ARCH=x86; SMLNJ_OPSYS=bsd;;
X+ i486:freebsd*) SMLNJ_ARCH=x86; SMLNJ_OPSYS=bsd;;
X+ i586:freebsd*) SMLNJ_ARCH=x86; SMLNJ_OPSYS=bsd;;
X+ i686:freebsd*) SMLNJ_ARCH=x86; SMLNJ_OPSYS=bsd;;
X i386:linux*) SMLNJ_ARCH=x86; SMLNJ_OPSYS=linux;;
X i486:linux*) SMLNJ_ARCH=x86; SMLNJ_OPSYS=linux;;
X i586:linux*) SMLNJ_ARCH=x86; SMLNJ_OPSYS=linux;;
END-of-ml-doc/files/patch-configure
echo x - ml-doc/files/lib-Makefile
sed 's/^X//' >ml-doc/files/lib-Makefile << 'END-of-ml-doc/files/lib-Makefile'
X# Makefile for installing ML-Doc shared data.
X#
X
XLIBDIR = ${DATADIR}/lib
XTEXDIR = ${DATADIR}/lib/LaTeX
XINSTALL_DATA= ${BSD_INSTALL_DATA}
X
XTARGETS= HTMLsym.ent \
X catalog \
X dummy-filemap.sgml \
X element-list \
X entities.sgml \
X iso-lat1.ent \
X ml-doc-info.dtd \
X ml-doc.decl \
X ml-doc.dtd
X
XTEXTARGETS= mldoc-book.cls \
X mldoc-code.sty \
X mldoc.sty \
X proofMLDoc.sty
X
Xinstall:
X if [ ! -d $(LIBDIR) ]; then \
X mkdir -p $(LIBDIR); \
X fi
X for file in $(TARGETS); do \
X $(INSTALL_DATA) $$file $(LIBDIR)/$$file || exit $$?; \
X done
X
X if [ ! -d $(TEXDIR) ]; then \
X mkdir $(TEXDIR); \
X fi
X for file in $(TEXTARGETS); do \
X $(INSTALL_DATA) LaTeX/$$file $(TEXDIR)/$$file || exit $$?; \
X done
X
END-of-ml-doc/files/lib-Makefile
echo x - ml-doc/files/patch-tools-lib-latex-text_to_latex.sml
sed 's/^X//' >ml-doc/files/patch-tools-lib-latex-text_to_latex.sml << 'END-of-ml-doc/files/patch-tools-lib-latex-text_to_latex.sml'
X--- tools/lib/latex/text-to-latex.sml.orig Tue Jul 24 14:14:47 2007
X+++ tools/lib/latex/text-to-latex.sml Tue Jul 24 14:15:03 2007
X@@ -538,7 +538,7 @@
X trans(last, arg, colAlign)
X | transCell (last, Flt.TD arg, colAlign) =
X trans(last, arg, colAlign)
X- fun doCells ([cell], [colAlign]) =
X+ fun doCells ([cell], colAlign::_) =
X ignore (transCell(true, cell, colAlign))
X | doCells (cell::r1, colAlign::r2) = let
X val nCols = transCell(false, cell, colAlign)
END-of-ml-doc/files/patch-tools-lib-latex-text_to_latex.sml
echo x - ml-doc/files/patch-tools-html-gen-do_spec.sml
sed 's/^X//' >ml-doc/files/patch-tools-html-gen-do_spec.sml << 'END-of-ml-doc/files/patch-tools-html-gen-do_spec.sml'
X--- tools/html-gen/do-spec.sml.orig Sun Aug 5 20:42:32 2007
X+++ tools/html-gen/do-spec.sml Sun Aug 5 20:43:41 2007
X@@ -82,7 +82,7 @@
X of (body, NONE) => HTML.CODE(T.codeToHTML ctx body)
X | (body, SOME result) => HTML.TextList[
X HTML.CODE(T.codeToHTML ctx body),
X- HTML.EM(HTML.PCDATA "evaluates to"),
X+ HTML.EM(HTML.PCDATA " evaluates to "),
X HTML.CODE result
X ]
X (* end case *)
END-of-ml-doc/files/patch-tools-html-gen-do_spec.sml
echo x - ml-doc/files/ml-doc.1.in
sed 's/^X//' >ml-doc/files/ml-doc.1.in << 'END-of-ml-doc/files/ml-doc.1.in'
X.\" $Id$
X.\"
X.\" The tools and formats described by this document are:
X.\" COPYRIGHT (c) 2000 Bell Labs, Lucent Technologies.
X.\" COPYRIGHT (c) 2003-2004 John Reppy (http://www.cs.uchicago.edu/~jhr)
X.\"
X.\" The document itself is licensed:
X.\" Copyright (C) 2007 Timothy Bourke. All Rights Reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\" notices, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\" notice, this list of conditions and the following disclaimer in the
X.\" documentation and/or other materials provided with the distribution.
X.\" 3. No names are removed from the AUTHORS section.
X.\"
X.\" THIS DOCUMENTATION IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.Dd August 2, 2007
X.Os FreeBSD 6.2
X.Dt ML-Doc 1
X.\" ----------------------------------------
X.Sh NAME
X.\"
X.Nm extract-sig
X.Nd generate SML
X.br
X.Nm extract-info , merge-info
X.Nd generate intermediate files
X.br
X.Nm html-gen , html-index , html-toc
X.Nd generate HTML
X.br
X.Nm latex-gen , proof-latex
X.Nd generate LaTeX
X.br
X.Nm filter-index , mk-mldoc-makefile
X.Nd miscellaneous ml-doc tools
X.\"
X.\" ----------------------------------------
X.Sh SYNOPSIS
X.Nm extract-sig
X.Op Fl config Ar config-file
X.Op Fl dir Ar output-dir
X.Ar mldoc-files
X.\"
X.Nm extract-info
X.Op Fl config Ar config-file
X.Op Fl dir Ar output-dir
X.Ar mldoc-files
X.\"
X.Nm merge-info
X.Op Fl config Ar config-file
X.Op Fl o Ar output-file
X.Ar info-files
X.\"
X.Nm html-index
X.Op Fl config Ar config-file
X.Op Fl dir Ar output-dir
X.Op Fl o Ar output-file
X.Op Fl info Ar path
X.Op Fl cols Ar num
X.Op Fl all | Fl sig | Fl struct | Fl exn | Fl type | Fl val
X.\"
X.Nm html-toc
X.Op Fl config Ar config-file
X.Op Fl dir Ar output-dir
X.Op Fl o Ar output-file
X.Op Fl info Ar path
X.Op Fl depth Ar num
X.\"
X.Nm html-gen
X.Op Fl config Ar config-file
X.Op Fl dir Ar output-dir
X.Op Fl info Ar path-to-infofile
X.Op Fl wid Ar num
X.Ar mldoc-file
X.\"
X.Nm latex-gen
X.Op Fl config Ar config-file
X.Op Fl dir Ar output-dir
X.Op Fl doc
X.Op Fl index
X.Op Fl info Ar path-to-infofile
X.Ar mldoc-file
X.\"
X.Nm proof-latex
X.Op Fl config Ar config-file
X.Op Fl dir Ar output-dir
X.Op Fl doc
X.Op Fl index
X.Op Fl info Ar path-to-infofile
X.Ar mldoc-file
X.\"
X.Nm filter-index
X.\"
X.Nm mk-mldoc-makefile
X.Op Fl help
X.Op Fl bin Ar dir
X.Op Fl html Ar dir
X.Op Fl info Ar dir
X.Op Fl latex Ar dir
X.Op Fl proof Ar dir
X.Op Fl root Ar file
X.Ar mldoc-files
X.Sh DESCRIPTION
X.ML-Doc
Xis a system for producing reference manuals for SML libraries. It can
Xproduce high quality documentation with extensive indexing, like the
Xpublished SML Basis Library reference manual, and also HTML for online use.
X.Pp
X.ML-Doc
Xis different to systems like javadoc that extract documentation from source
Xfiles.
XRather, the documentation
X.Em is
Xthe primary artifact\(emin fact
X.Nm extract-sig
Xcan be used to create source files from documentation. The
X.Xr mkdoc 1
Xutility, however, can produce first drafts from source files.
X.ML-Doc
Xis most useful for documenting stable library interfaces.
X.Pp
X.ML-Doc
Xfiles, marked by the extension
X.Pa .mldoc ,
Xare SGML documents conforming to the
X.ML-Doc
Xdocument type definition.
X.Pp
XThis manual has four major sections besides the present one:
X.Bl -tag -compact -width ".Sx WRITING DOCUMENTATION"
X.It Sx OPTIONS
Xdescribes command line options and configuration files.
X.It Sx USING ML-DOC
Xdescribes how the toolset is used to produce documentation and includes
Xsubsections on
X.Sx HTML Templates
Xand
X.Sx Entities .
X.It Sx WRITING DOCUMENTATION
Xdescribes the markup used within
X.Pa *.mldoc
Xfiles.
X.It Sx SGML VS HTML/XML
Xdiscusses some SGML features absent from HTML and XML.
X.El
X.\"
X.Ss Generating SML
X.Nm extract-sig
X.Nd Extracts SML signatures from
X.Pa *.mldoc
Xdocumentation.
X.Pp
X.\"
X.Ss Generating intermediate files
X.Nm extract-info
X.Nd Produces intermediate files summarising interfaces and
Xthe section hierarchy.
X.Pp
X.Nm merge-info
X.Nd Combines intermediate files into a single master info file.
X.Pp
X.\"
X.Ss Generating HTML
X.Nm html-index
X.Nd Produces HTML index files from a master info file.
X.Pp
X.Nm html-toc
X.Nd Transform a master info file and HTML template into a table of contents.
X.Pp
X.Nm html-gen
X.Nd Generate HTML output given template, master info, and mldoc input files.
X.Pp
X.\"
X.Ss Generating LaTeX
X.Nm latex-gen
X.Nd Produce LaTex for printing given master info and mldoc input files.
X.Pp
X.Nm proof-latex
X.Nd Produce LaTeX for proofing given master info and mldoc input files.
X.Pp
X.\"
X.Ss Miscellaneous
X.Nm filter-index
X.Nd Reads a list of index entries, one per line, from standard input,
Xremoves any duplicates, and writes the sorted entries to standard output.
X.Pp
X.Nm mk-mldoc-makefile
X.Nd Create a Makefile that ties all the other tools together.
X.\"
X.\"
X.\" ----------------------------------------
X.Sh OPTIONS
XMany command line options can also be specified in a configuration file,
Xusing the names given in brackets.
X.Pp
X.Bl -tag -width indent
X.\" config
X.It Fl config Ar config-file
XDefaults to
X.Pa Config.cfg .
XContains global and per-tool settings.
X.\" cols/NumColumns
X.It Fl cols Ar num
X.Pq Li NumColumns
XNumber of columns in the index. Defaults to 3.
X.\" debug/Debug
X.It Fl debug
X.Pq Li Debug
XCurrently unused.
X.\" depth/Depth
X.It Fl depth Ar num
X.Pq Li Depth
XSections nested more deeply than this number will not be listed in the
Xtable of contents.
XDefaults to 3.
X.\" dir/OutDir
X.It Fl dir Ar output-dir
X.Pq Li OutDir
XSpecifies where to write output files.
XThe default is different for each tool:
X.Bl -column -compact -offset indent ".Nm extract-sig" "Hardcopy"
X.It Nm extract-sig Ta Pa Sigs
X.It Nm extract-info Ta Pa Info
X.It Nm html-index Ta Pa HTML
X.It Nm html-toc Ta Pa HTML
X.It Nm html-gen Ta Pa HTML
X.It Nm latex-gen Ta Pa Hardcopy
X.It Nm proof-latex Ta Pa Proof
X.El
X.\" doc/Standalone
X.It Fl doc
X.Pq Li Standalone
XCurrently unused.
X.\" index
X.It Fl index
XCurrently unused.
X.\" info/MasterInfoFile
X.It Fl info Ar path
X.Pq Li MasterInfoFile
XLocates the output of
X.Nm merge-info .
XDefaults to
X.Pa Info/LaTeX.info
Xfor the hardcopy and proof tools, and
X.Pa Info/HTML.info
Xfor the HTML tools.
X.\" mldoc/MLDocDir
X.It Fl mldoc
X.Pq Li MLDocDir
XNames the subdirectory of the
X.Pa *.mldoc
Xfiles. Defaults to
X.Li ML-Doc .
X.\" o/OutFile
X.It Fl o Ar output-file
X.Pq Li OutFile
XSpecifies where to write output.
XFor
X.Nm html-index
Xthe default depends on the index generated:
X.Bl -column -compact -offset indent "struct" ".Pa index-struct.html"
X.It all Ta Pa index-all.html
X.It sig Ta Pa index-sig.html
X.It struct Ta Pa index-struct.html
X.It exn Ta Pa index-exn.html
X.It type Ta Pa index-type.html
X.It val Ta Pa index-val.html
X.El
XOtherwise the name depends on the tool:
X.Bl -column -compact -offset indent ".Nm merge-info" ".Pa Info/Master.info"
X.It Nm merge-info Ta Pa Info/Master.info
X.It Nm html-toc Ta Pa toc.html
X.El
X.\" all, sig, struct, exn, type, val
X.It Fl all | Fl sig | Fl struct | Fl exn | Fl type | Fl val
XSpecify which index to generate, defaulting to
X.Fl all :
X.Bl -column -compact -offset indent ".Fl struct" "unified identifier index"
X.It Fl all Ta unified identifier index
X.It Fl sig Ta signatures
X.It Fl struct Ta structures
X.It Fl exn Ta exceptions
X.It Fl type Ta types
X.It Fl val Ta values
X.El
X.\" wid/PreWid
X.It Fl wid Ar num
X.Pq Li PreWid .
XWidth of the output device. Currently unused. Defaults to 60.
X.El
X.Pp
XThere are some additional options that can only be given in a configuration
Xfile:
X.Bl -tag -compact -width ".Sy TopLevelSection"
X.\" **
X.It Sy BaseURL
XApplies to the
X.Li HTML
Xgrouping
X.Pq described below .
XIf the RelativeLinks flag is true then intra-document links will be
Xrelative,
Xotherwise the value of BaseURL, if present, is added as an HTML
X.Li BASE
Xtag.
X.\" **
X.It Sy Catalog
XGlobal option. Names the catalog file. Defaults to
X.Pa CATALOG .
X.\" **
X.It Sy RelativeLinks
XApplies to the
X.Li HTML
Xgrouping.
XSee BaseURL above.
XDefaults to false.
X.\" **
X.It Sy Root
XApplies to
X.Nm html-gen .
XCurrently unused.
X.\" **
X.It Sy SGMLS
XApplies to the
X.Li Tools
Xgrouping. Path to an SGML validating parser. Defaults to
X.Pa %%PREFIX%%/bin/nsgmls .
X.\" **
X.It Sy Template
XApplies to
X.Nm html-index , html-toc ,
Xand
X.Nm html-gen .
XNames the template file.
X.\" **
X.It Sy TopLevelSection
XApplies to
X.Nm latex-gen
Xand
X.Nm proof-latex .
XDefaults to
X.Li Chapter .
XOther permitted values are
X.Li Part
Xand
X.Li Section .
XControls the generation of LaTeX sections.
X.El
X.Pp
XA configuration file contains name/value pairs separated within and between
Xby white space. Single-line comments begin with a
X.Ql # .
XGroupings are made by giving a name followed by contained options
Xenclosed in braces,
X.Li "{ ... }" .
XValues are either names, decimal or hexadecimal literals, the latter
Xprefixed with
X.Ql 0x ,
Xstrings enclosed in double quotes, or logical values
X.Po
X.Ql TRUE
Xor
X.Ql FALSE
X.Pc .
XAs a brief example:
X.Bd -literal -offset indent
X# Catalog.cfg
XCatalog "CATALOG"
X
XHTML {
X BaseURL "CML"
X RelativeLinks TRUE
X PreWid 70
X}
X.Ed
X.Pp
X.Nm mk-mldoc-makefile
Xdoes not currently respect the configuration file, instead it uses
Xcommand line options, which differ somewhat from the other tools:
X.Bl -tag -width indent
X.\" **
X.It Fl help
XDisplay a summary of options.
X.\" **
X.It Fl bin Ar dir
XSpecifies where the ML-Doc tool binaries are installed. Defaults to
X.Pa %%PREFIX%%/bin .
X.\" **
X.It Fl html Ar dir
XOutput directory for HTML files. Defaults to
X.Pa HTML .
X.\" **
X.It Fl info Ar dir
XOutput directory for info files. Defaults to
X.Pa Info .
X.\" **
X.It Fl latex Ar dir
XOutput directory for LaTeX files.
XDefaults to
X.Pa Hardcopy .
X.\" **
X.It Fl proof Ar dir
XOutput directory for proof LaTeX files. Defaults to
X.Pa Proof .
X.\" **
X.It Fl root Ar file
XIf present, the generated Makefile will run LaTeX against the given
Xfilename, which should not have a
X.Li .tex
Xextension.
X.El
X.\"
X.\" ----------------------------------------
X.Sh USING ML-DOC
X.\"
X.Ss Directory structure
XAn
X.ML-Doc
X.Em project
Xcomprises a set of files and directories that, at a minimum, will include:
X.Bl -tag -width ".Pa index.template"
X.\" **
X.It Pa CATALOG
XTypically links to
X.Pa Entities.sgml
Xin the same directory and the installed
X.ML-Doc
X.Pa CATALOG
Xfile.
XSee
X.Xr FILES .
X.\" **
X.It Pa Config.cfg
XGlobal and per-tool configuration options.
XSee
X.Xr OPTIONS .
X.\" **
X.It Pa Entities.sgml
XContains entities local to the project. These entities are used for
Xabbrevations and referencing external documents and files.
XSee
X.Xr Entities .
X.\" **
X.It Pa ML-Doc/
XThe source
X.Pa *.mldoc
XSGML documentation.
X.\" **
X.It Pa index.template
XTemplate used by
X.Nm html-index .
X.\" **
X.It Pa page.template
XTemplate used by
X.Nm html-gen .
X.\" **
X.It Pa toc.template
XTemplate used by
X.Nm html-toc .
X.El
X.Pp
XRunning
X.Nm mk-mldoc-makefile
Xadds:
X.Bl -tag -width ".Pa index.template"
X.\" **
X.It Pa Makefile
XOrchestrates the manifold programs to produce documentation.
X.El
X.Pp
XThe other tools place their output in additional subdirectories.
XEmpty subdirectories and any child directories therein
Xmust be created before running the tools.
XThe default names are:
X.Bl -tag -width ".Pa index.template"
X.\" **
X.It Pa HTML/
XOutput from the
X.Nm html-gen , html-toc ,
Xand
X.Nm html-index
Xtools.
X.\" **
X.It Pa Hardcopy/
XOutput from
X.Nm latex-gen .
X.\" **
X.It Pa Info/
XOutput from
X.Nm extract-info ,
Xfurther augmented by
X.Nm merge-info ,
Xto be used by the other tools.
X.\" **
X.It Pa Proof/
XOutput from
X.Nm proof-latex .
X.\" **
X.It Pa Sigs/
XSML code created by
X.Nm extract-sig .
X.El
X.\"
X.Ss HTML Templates
XTemplates are HTML files containing special entities. The
X.Nm html-*
Xtools replace entities with details from
X.Pa *.mldoc
Xand
X.Pa *.info
Xfiles.
XEach tool works from a distinct template named in the configuration
Xfile.
X.Bl -column -offset indent ".Sy Tool name (in configuration file)" \
X ".Sy Typical Template value"
X.It Sy Tool name (in configuration file) Ta Sy Typical Template value
X.It HTML-Gen Ta Pa page.template
X.It HTML-Index Ta Pa index.template
X.It HTML-TOC Ta Pa toc.template
X.El
X.Pp
XThe entities are:
X.Bl -tag -compact -offset indent -width ".Li &today.monthnum;"
X.\" **
X.It Li &body;
Xplaceholder for document body
X.\" **
X.It Li &filename;
Xdocument filename without extension
X.\" **
X.It Li &title;
Xdocument title
X.\" **
X.It Li &version;
Xdocument version
X.\" **
X.It Li &doc.date;
Xdocument date in
X.Qq month day, year
Xformat
X.\" **
X.It Li &doc.year;
Xdocument year
X.Pq 4 digit format
X.\" **
X.It Li &doc.day;
Xdocument day
X.\" **
X.It Li &doc.month;
Xdocument month
X.Pq as a string
X.\" **
X.It Li &doc.monthnum;
Xdocument month
X.Pq as a number from 1-12
X.\" **
X.It Li &today.date;
Xcurrent date in
X.Qq month day, year
Xformat
X.\" **
X.It Li &today.year;
Xcurrent year
X.Pq 4 digit format
X.\" **
X.It Li &today.day;
Xcurrent day
X.\" **
X.It Li &today.month;
Xcurrent month
X.Pq as a string
X.\" **
X.It Li &today.monthnum;
Xcurrent month
X.Pq as a number from 1-12
X.\" **
X.It Li &base.url;
XURL of the root directory of the document
X.\" **
X.It Li &parent.url;
XURL of the parent document
X.\" **
X.It Li &root.url;
XURL of the document root
X.\" **
X.It Li &index.url;
XURL of the document index
X.\" **
X.It Li &toc.url;
XURL of the table of contents
X.El
X.\"
X.Ss Entities
XEntities are used within
X.ML-Doc
Xto include mathematical and other
Xspecialised symbols, to abbreviate titles and other text, to reference
Xfiles, and to name certain output files.
XThe latter three purposes are served by including a customised
X.Pa Entities.sgml
Xfile within a project.
X.Pp
XSpecialised symbols include various mathematical symbols
X.Pq described under Sx Mathematics ,
Xthe HTML 2.0 standard entities, e.g.
X.Li , © ,
Xand these SGML/LaTeX symbols:
X.Bl -column -offset indent -compact "&DQUOTE;" "MMMMMMMMM" "&DQUOTE;" "MMM"
X.It Li < Ta Li < Ta Li <E; Ta Li <=
X.It Li > Ta Li > Ta Li >E; Ta Li >=
X.It Li &NEQ; Ta Li != Ta Li & Ta Li &
X.It Li &DQUOTE; Ta Li \(dq Ta Li &BAR; Ta Li |
X.It Li &DASH; Ta Li -
X.El
X.Pp
XAbbreviations encourage consistency and facilitate certain types of updates.
XThese definitions, in an
X.Pa Entities.sgml
Xfile, are a good example:
X.Bd -literal -offset indent -compact
X<!ENTITY SMLBASIS SDATA "SML Basis Library">
X<!ENTITY SMLNJ SDATA "SML/NJ">
X.Ed
XReferences, which will be expanded in the output text, may then be made from
X.Pa *.mldoc
Xfiles:
X.D1 This feature requires the &SMLNJ; libraries.
X.Pp
XDocumentation will sometimes need to reference the
X.ML-Doc
Xdescriptions of other libraries; such as those of the SML Basis, SML/NJ, or
XConcurrent ML.
XThe reference tags described under
X.Sx References
X.Po
Xe.g.
X.Li SIGREF , AREF
Xand
X.Li DOCREF
X.Pc
Xprovide this facility via a
X.Li DOCUMENT
Xattribute whose value must be an entity listed in
X.Pa Entities.sgml ,
Xa bracketing ampersand and semicolon are not used for such values.
XThe entity resolves to an identifying string, which is sought within the
Xconfiguration file,
X.Pa Config.cfg ,
Xto find an
X.Em external document entry .
XAs an example, consider a constructor reference:
X.Dl <CONREF DOCUMENT=SML-BASIS-DOC STRID="Option"/NONE/
XThe
X.Li DOCUMENT
Xattribute value,
X.Li SML-BASIS-DOC ,
Xis defined in the project entity file,
X.Pa Entities.sgml :
X.Bd -literal -offset indent -compact
X<!ENTITY SML-BASIS-DOC SDATA "SML-Basis-Doc">
X.Ed
XThe entity value,
X.Li SML-Basis-Doc,
Xin turn refers to an entry in the configuration file:
X.Bd -literal -offset indent -compact
X.Li ...
XSML-Basis-Doc {
X InfoFile "%%PREFIX%%/smlnj/smlnj-lib/Doc/BasisInfo/HTML.info"
X BaseURL "www.standardml.org/Basis"
X RootURL "www.standardml.org/Basis/index.html"
X}
X.Li ...
X.Ed
XThis example refers to a master info file installed with SML/NJ and directs
Xhyperlinks to the online documentation.
X.Pp
XEntities are also used within
X.ML-Doc
Xto specify values for the
X.Li FILE
Xattribute, which specifies an input file for the
X.Pq currently unsupported
X.Li FIGURE
Xtag, and names an output file for the
X.Li SIGBODY
Xtag.
X.Nm extract-sig
Xexpands the given entity to name the source code it produces, e.g. given an
Xentity declaration:
X.Bd -literal -compact -offset indent
X<!ENTITY CML-SIG SDATA "cml-sig.sml">
X.Ed
XThe specifications in
X.D1 <SIGBODY SIGID="CML" FILE=CML-SIG>
Xwould be extracted to a file named
X.Pa cml-sig.sml .
X.\"
X.Ss General Use
XA simplified sequence of steps for creating
X.ML-Doc
Xdocumentation:
X.Bl -enum
X.\" **
X.It
XCreate and populate the basic directory structure, as per
X.Sx Directory Structure .
X.\" **
X.It
XUse
X.Xr mkdoc 1
Xto produce skeleton
X.Pa *.mldoc
Xfiles.
XAdd explanatory text to each.
X.\" **
X.It
XAdd other
X.Pa *.mldoc
Xfiles to link together into a continuous whole, and to explain the various interfaces.
X.\" **
X.It
XCreate a
X.Pa Makefile
Xwith
X.Nm mk-mldoc-makefile ,
Xas shown under
X.Sx EXAMPLES .
X.\" **
X.It
XUse the make targets to generate documentation.
X.Bl -tag -offset indent -width ".Li Hardcopy"
X.It Li HTML
XDefault. Produce HTML pages.
X.It Li Hardcopy
XCreate LaTeX files for generating the final document.
X.It Li Proof
XCreate LaTeX files for generating a review document.
X.It Li clean
XRun the individual
X.Li clean-html , clean-info , clean-latex ,
Xand
X.Li clean-proof
Xtargets to remove generated files.
X.El
X.\" **
X.It
XLaTeX documentation requires further processing as described below.
X.\" **
X.It
XAny changes to the library interface should be made against the
X.Pa *.mldoc
Xfiles,
X.Nm extract-sig
Xis able to extract an updated SML version.
X.El
X.Pp
XLaTeX documents require a
X.Em root file
Xto specify the document class and indexes.
XFor example, if the first file is called
X.Pa intro.mldoc
Xthen
X.Pa manual.tex
Xmight resemble:
X.Bd -literal -offset indent
X\\documentclass{mldoc-book}
X\\mldMakeTopicIndex\\mldMakeIdIndex\\mldMakeRaisesIndex
X\\newcommand{\\kw}[1]{\\textbf{#1}}
X
X\\begin{document}
X \\input{intro}
X \\mldPrintTopicIndex\\mldPrintIdIndex\\mldPrintRaisesIndex
X\\end{document}
X.Ed
XThe
X.Li kw
Xcommand formats identifiers.
XThe mldoc class and style files must be in a path searched by LaTeX.
XUpdating the
X.Ev TEXINPUTS
Xenvironment variable is one way of ensuring this. E.g. under bash:
X.Dl export TEXINPUTS=".:%%PREFIX%%/share/ml-doc/lib/LaTeX:" .
XThe
X.Sx EXAMPLES
Xsection shows how to run the LaTeX tools.
X.\"
X.\" ----------------------------------------
X.Sh WRITING DOCUMENTATION
X.Pp
XThis section essentially elaborates on the
X.Pa ml-doc.dtd
Xfile.
XAn
X.ML-Doc
Xfile begins with the declaration:
X.Dl <!DOCTYPE ML-DOC SYSTEM>
Xand contains header elements followed by one or more, potentially nested,
Xsections.
X.Pp
XThere are four types of header element. Only
X.Li TITLE
Xis mandatory.
XThey may be given in any order.
X.Bl -tag -offset indent -width ".Li COPYRIGHT"
X.\" **
X.It Li VERSION
XThe version of the documentation, with attributes:
X.Bl -tag -offset indent -width ".Li MONTH" -compact
X.It Li VERID
Xe.g.
X.Ql 1.4 .
X.It Li YEAR
XYear of release.
X.It Li MONTH
X.Pq optional
XMonth of release.
X.It Li DAY
X.Pq optional
XDay of release.
X.El
XE.g.
X.Li <VERSION VERID="1.4" YEAR=2007 MONTH=8 DAY=12>
X.\" **
X.It Li COPYRIGHT
XIdentify a copyright holder with attributes:
X.Bl -tag -offset indent -width ".Li OWNER" -compact
X.It Li OWNER
XThe copyright owner.
X.It Li YEAR
XYear of assertion.
X.El
XE.g.
X.Li <COPYRIGHT OWNER="Mega Corp" YEAR=2003>
X.br
XMultiple
X.Li COPYRIGHT
Xelements may be present.
X.\" **
X.It Li AUTHOR
XIdentifies the document author, with attributes:
X.Bl -tag -offset indent -width ".Li MONTH" -compact
X.It Li NAME
XName of author.
X.It Li EMAIL
XEmail address of author.
X.It Li YEAR
XYear written.
X.It Li MONTH
X.Pq optional
XMonth written.
X.It Li DAY
X.Pq optional
XDay written.
X.El
XE.g.
X.Li <AUTHOR NAME="J. Doe" EMAIL="doej at mega.co" YEAR=2006>
X.\" **
X.It Li TITLE
XThe document title. E.g.
X.Li <TITLE>Superhash Structure</TITLE>
X.El
X.Pp
XSections begin with a
X.Li HEAD
Xelement, followed by zero or more paragraphs
X.Pq Li PP No and Li FLOAT No elements ,
Xand then zero or more nested sections, included files and/or interfaces.
XThe
X.Li SECTION
Xtag has three optional attributes:
X.Bl -tag -offset indent -width ".Li NONUMBER" -compact
X.It Li LABEL
XA string used for making cross-references
X.Pq from Li SECREF .
X.It Li NONUMBER
XIf present, the section will not be numbered in LaTeX output.
X.It Li NOTOC
XExcludes the section from the table of contents.
XOnly valid if
X.Li NONUMBER
Xis present.
X.El
X.Li HEAD
Xand
X.Li PP
Xelements have no attributes. For
X.Li FLOAT
Xelements see
X.Sx GENERAL MARKUP .
XE.g.
X.Bd -literal -offset indent -compact
X<SECTION>
X <HEAD>General Markup</HEAD>
X <PP>
X Various tags provide...
X <SECTION>
X <HEAD>Formatting</HEAD>
X <PP>
X Tags available for inline...
X </SECTION>
X ...
X</SECTION>
X.Ed
X.\"
X.Pp
XTypically a separate
X.Pa *.mldoc
Xfile will be used for each major topic, such as introductory or background
Xtext, and interface (signature, structure or functor).
XA corresponding
X.Pa *.html
Xfile, for HTML output, and/or
X.Pa *.tex
Xfile, for LaTeX output, is generated for each
X.ML-Doc
Xsource file.
XA complete document is constructed by including, with
X.Li INCLFILE
Xtags, individual files within a hierarchy of sections.
XInclusions become hyperlinks in HTML output and inserted pages in LaTeX
Xoutput. An
X.Li INCLFILE
Xhas a single, mandatory
X.Li FILE
Xattribute specifying a relative or absolute file path. The
X.Li .mldoc
Xextension is implied. E.g.
X.Dl <INCLFILE FILE="lib/hash-sig">
X.\"
X.Pp
XSGML comments, e.g.
X.Li <!-- check source code. --> ,
Xare ignored.
X.\"
X.Pp
XSML objects are described between
X.Li INTERFACE
Xtags which have optional
X.Li LABEL
Xattributes for making cross-references. An
X.Li INTERFACE
Xelement contains, in order:
Xa
X.Li HEAD
Xelement
X.Pq as per Li SECTION ,
Xan optional
X.Li SEEALSO
Xelement containing one or more references
X.Pq see Sx References ,
Xoptional paragraphs of introductory text,
Xan
X.Em object description ,
Xand optional paragraphs of concluding text.
X.\"
X.Ss Object Descriptions
XObject description elements may have a
X.Li STATUS
Xattribute, with value
X.Li REQUIRED ,
X.Li OPTIONAL ,
Xor
X.Li PROPOSED .
XThere are three types of element for describing objects provided by a
Xlibrary:
X.Bl -tag -offset indent -compact -width ".Li SIGNATURE"
X.\" **
X.It Li SIGNATURE
XWith mandatory
X.Li SIGID
Xattribute.
X.\" **
X.It Li STRUCTURE
XWith mandatory
X.Li STRID
Xattribute.
X.\" **
X.It Li FUNCTOR
XWith mandatory
X.Li FCTID
Xattribute.
X.El
X.Pp
XExample outline of an interface:
X.Bd -literal -offset indent -compact
X<INTERFACE>
X <HEAD>The <CD/Hash/ structure</HEAD>
X <SEEALSO>
X <STRREF DOCUMENT=SML-BASIS-DOC TOPID/Option/
X <STRREF DOCUMENT=SML-BASIS-DOC TOPID/Time/
X </SEEALSO>
X
X <PP>
X Optional text after synopsis.
X
X <STRUCTURE STRID="CML">
X ...
X </STRUCTURE>
X
X <PP>
X Optional final discussion.
X</INTERFACE>
X.Ed
XIt is usually easier to generate object descriptions directly from SML
Xsource files using
X.Xr mkdoc 1 .
X.Pp
XThe
X.Li SIGBODY
Xelement is central to describing objects.
XIt must be included in
X.Li SIGNATURE Ns No s,
Xmay be included in
X.Li STRUCTURE Ns No s
Xand
X.Li FUNCTOR Ns No s,
Xand has two optional attributes:
X.Bl -tag -offset indent -width ".Li SIGID" -compact
X.\" SIGBODY: SIGID Attribute
X.It Li SIGID
XIdentifies the signature being described. It is used for cross-referencing.
XWhen a
X.Li SIGBODY
Xis given within a
X.Li SIGNATURE ,
Xboth may have identical
X.Li SIGID
Xvalues. Within a
X.Li STRUCTURE
Xthe
X.Li SIGID
Xattribute is usually the
X.Sq signature version
Xof the outer
X.Li STRID .
XIt is a succinct way of describing both interface and implementation, e.g.
X.Bd -literal -offset indent -compact
X<STRUCTURE STRID="ControlSet">
X <SIGBODY SIGID="CONTROL_SET" FILE=CONTROL-SET>
X ...
X </SIGBODY>
X</STRUCTURE>
X.Ed
X.\" SIGBODY: FILE Attribute
X.It Li FILE
XThe
X.Xr mkdoc 1
Xutility uses the value of this attribute to name extracted SML files.
X.Li SIGID
Xand
X.Li FILE
Xare typically omitted on
X.Li SIGBODY Ns No s
Xused as functor arguments.
X.El
XA
X.Li SIGBODY
Xcontains one or more
X.Li SPEC
Xand/or
X.Li SPECBREAK
Xelements.
XThe former is described under
X.Sx Specifications .
XThe latter is used to form sub-groups of related specifications, when
Xmarked with a
X.Li NEWLINE
Xattribute, blank lines are placed in both extracted signatures and
Xgenerated output.
X.Pp
X.\" Object description: SIGNATURE
XA
X.Li SIGNATURE
Xcontains a
X.Li SIGBODY
Xwhich may be followed by a series of
X.Li SIGINSTANCE
Xelements that list structures implementing the signature, each containing an
X.Li ID ,
Xzero or more
X.Li WHERETYPE
Xelements, and optionally a
X.Li COMMENT .
XA
X.Li WHERETYPE
Xelement states which signature types are instantiated in an implementation,
Xit consists of an optional
X.Li TYPARAM
Xbinding, the
X.Li ID
Xof the type, and a
X.Li TY
Xtype constraint. The
X.Li COMMENT , TYPARAM ,
Xand
X.Li TY
Xelements are described below. The
X.Li SIGINSTANCE
Xtag has two optional attributes:
X.Bl -tag -offset indent -width ".Li OPAQUE" -compact
X.It Li STATUS
XHaving a value of
X.Li REQUIRED ,
X.Li OPTIONAL ,
Xor
X.Li PROPOSED .
X.It Li OPAQUE
XIndicates an opaque signature binding.
X.El
XThis example from the SML/NJ Library:
X.Bd -literal -offset indent -compact
X<SIGNATURE SIGID="ORD_MAP">
X <SIGBODY SIGID="ORD_MAP" FILE=ORD-MAP>
X ...
X <SIGINSTANCE OPAQUE><ID>IntBinaryMap
X <WHERETYPE><ID>Key.ord_key<TY>Int.int
X <COMMENT>
X ...
X <SIGINSTANCE OPAQUE><ID>IntListMap
X <WHERETYPE><ID>Key.ord_key<TY>Int.int
X <COMMENT>
X ...
X</SIGNATURE>
X.Ed
Xwould yield a synopsis:
X.Bd -unfilled -offset indent -compact
Xsignature ORD_MAP
Xstructure IntBinaryMap :> ORD_MAP
Xstructure IntListMap :> ORD_MAP
X.Ed
X.Pp
X.\" Object description: STRUCTURE
XA
X.Li STRUCTURE
Xcontains either a full
X.Li SIGBODY ,
Xas described above,
Xor simply the name of
X.Pq Li ID ,
Xor reference to
X.Pq Li SIGREF
Xa signature described elsewhere.
XA name or reference may be followed by
X.Li WHERETYPE
Xtype realisations.
XAn
X.Li OPAQUE
Xelement can be placed before the signature body, name or reference, to
Xsignify an opaque binding, e.g.
X.Bd -literal -offset indent -compact
X<STRUCTURE STRID="Store">
X <OPAQUE>
X <SIGREF/ORD_SET/
X <WHERETYPE><ID>Key.ord_key<TY>String.string
X</STRUCTURE>
X.Ed
X.Pp
XThe contents of a
X.Li FUNCTOR
Xare identical to those of a
X.Li STRUCTURE ,
Xexcept that they must begin with an argument element, which takes one of two
Xforms:
X.Bl -tag -offset indent -compact -width "general"
X.It short
XAn argument name
X.Pq Li ID
Xfollowed by the name of
X.Pq Li ID ,
Xor reference
X.Pq Li SIGREF
Xto a signature.
X.It general
XA
X.Li SIGBODY
Xelement containing specifications, notably of
X.Li SUBSTRUCT
Xand
X.Li TYPE
Xelements.
X.El
XE.g.
X.Li functor ListSetFn (ORD_KEY) : ORD_SET
Xcould be written:
X.Bd -literal -compact -offset indent
X<FUNCTOR FCTID="ListSetFn">
X <ID/K/<ID>ORD_KEY</ID> <!--argument-->
X <ID>ORD_SET <!--result-->
X</FUNCTOR>
X.Ed
XThe second
X.Li ID
Xcould have been written as a
X.Li SIGREF ,
Xthe third could have been given in full using
X.Li SIGBODY .
X.\"
X.Ss Specifications
XA
X.Li SIGBODY
Xcomprises a list of
X.Li SPEC
Xelements, each containing either a single substructure specification, or
Xmultiple specifications of the same kind
X.Pq though types and eqtypes may be mixed ,
Xand optionally followed by a comment.
XThe specification element types are:
X.Bl -tag -width ".Li TYPE No / Li EQTYPE"
X.\" **
X.It Li INCLUDE
XAn
X.Li ID
Xor
X.Li SIGREF
Xnaming an included signature, optionally followed by
X.Li WHERETYPE
Xrealisations.
XE.g.
X.Bd -literal -compact
X<SPEC><INCLUDE><SIGREF DOCUMENT=SML-BASIS-DOC/OS_IO/
X.Ed
X.\" **
X.It Li SUBSTRUCT
XThe contents are identical to those of
X.Li STRUCTURE
Xexcept that the first contained element must be an
X.Li ID
Xnaming the substructure, e.g.
X.Bd -literal -compact
X<SPEC><SUBSTRUCT>Key<SIGREF/ORD_KEY/</SUBSTRUCT>
X.Ed
X.\" **
X.It Li SHARING
XAn
X.Li ID
Xfollowed by one or more pairings of
X.Li EQU
Xand
X.Li ID
Xelements. The
X.Li SHARING
Xelement may include a
X.Li TYPE
Xattribute. E.g.
X.Bd -literal -compact
X<SPEC>
X <SHARING TYPE><ID>A.vector<EQU><ID>V.vector
X <SHARING TYPE><ID>A.elem<EQU><ID>V.elem
X ...
X.Ed
X.\" **
X.It Li EXN
XAn
X.Li ID
Xand optional
X.Li TY ,
Xe.g.
X.Bd -literal -compact
X<EXN><ID>Fail<TY>string
X.Ed
Xor taking advantage of SGML short-hand
X.Pq the Li ID No tag is optional :
X.Bd -literal -compact
X<EXN>Fail<TY>string
X.Ed
X.\" **
X.It Li TYPE No / Li EQTYPE
XAn optional
X.Li TYPARAM ,
Xan
X.Li ID ,
Xand an optional
X.Li TY ,
Xe.g.
X.Bd -literal -compact
X<TYPE><TYPARAM>'a<ID>queue
X.Ed
X.\" **
X.It Li DATATYPE
XAn optional
X.Li TYPARAM ,
Xan
X.Li ID ,
Xand a list of
X.Li CONS
Xelements, each containing an
X.Li ID
Xfollowed by optional
X.Li TY
Xand
X.Li COMMENT
Xelements, e.g.
X.Bd -literal -compact
X<SPEC>
X <DATATYPE><TYPARAM>'a<ID>option
X <CONS>NONE
X <CONS>SOME<TY>'a
X </DATATYPE>
X.Ed
XA
X.Li DATATYPE
Xelement may be marked with a
X.Li COMPACT
Xattribute that directs the output generators to place all of the
Xconstructors on a single line if possible.
X.\" **
X.It Li DATATYPEDEF
XAn
X.Li ID
Xfollowed by another
X.Li ID
Xor a
X.Li TYREF .
XAdds a datatype replication, e.g.
X.Bd -literal -compact
X<DATATYPEDEF><ID>access_mode</ID>
X <TYREF STRID="OS.FileSys" DOCUMENT=SML-BASIS-DOC>
X OS.FileSys.access_mode</TYREF>
X</DATATYPEDEF>
X.Ed
X.\" **
X.It Li VAL
XAn
X.Li ID
Xfollowed by a
X.Li TY
Xand optionally a
X.Li RAISES
Xelement containing one or more
X.Li EXNREF Ns No s, e.g.
X.Bd -literal -compact
X<SPEC>
X <VAL>fact<TY>int -> int
X <RAISES><EXNREF/Domain/
X <EXNREF/Overflow/
X.Ed
X.El
X.Ss Comments
XComments may be included as the last item within a
X.Li SIGINSTANCE , SPEC ,
Xor
X.Li CONS
Xelement. A
X.Li COMMENT
Xcontains one or more paragraphs
X.Pq Li PP ,
Xeach optionally preceded by a
X.Li PROTOTY
Xelement that contains one or more
X.Li PROTO
Xelements showing, in SML, how an object might be called or used with
Xargument names.
XTo take an example from the SML Basis Library:
X.Bd -literal -offset indent -compact
X<SPEC>
X <VAL>before<TY>('a * unit) -> 'a
X <COMMENT>
X <PROTOTY>
X <PROTO>
X <ARG/a/ before <ARG/b/
X <PP>
X returns <ARG/a/. It provides a notational shorthand for
X evaluating <ARG/a/, then <ARG/b/, before returning the
X value of <ARG/a/.
X.Ed
XThe specific argument names make it easier to write a description of what
Xthe function does.
X.Pp
XThe final element within a
X.Li PROTO
Xcan be
X.Li EVALTO ,
Xwhich should contain SML showing the result of evaluating the
Xexpression.
X.\"
X.Ss References
XThere are several ways to cross-reference:
X.Bl -tag -width "External objects"
X.\" **
X.It SML objects
XSignatures, structures, functors, and their contents. Further details
Xfollow this list.
X.\" **
X.It External objects
XAn
X.Li IDREF
Xelement references an external non-SML identifier.
XAn optional
X.Li KIND
Xattribute describes what is being referred to, e.g. a C function or a system
Xcall.
XIf the
X.Li NOINDEX
Xattribute is present the identifier instance is not noted in an index.
XE.g.
X.Li <IDREF KIND="POSIX" NOINDEX/printf/
X.\" **
X.It HTML anchors
XCross-linking for HTML output. An
X.Li ADEF
Xwith mandatory
X.Li TAG
Xattribute defines an anchor name for a run of text.
X.Li AREF
Xelements, also with
X.Li TAG
Xattributes, link back to the matching name.
XReference is made to anchors in other documents by setting
Xthe
X.Li DOCUMENT
Xattribute to an entity value, see
X.Xr Entities .
XE.g.
X.Bd -literal -compact
X<ADEF TAG="FLUSHWARNING">Disaster results if a flush
Xis attempted after closing the pipe</ADEF>.
X ...
XHeed the <AREF TAG="FLUSHWARNING">earlier</AREF> warning.
X.Ed
X.\" **
X.It URLs
XA
X.Li URL
Xtag links to an external resource specified by an
X.Li HREF
Xattribute. This tag is ignored when generating LaTeX output.
X.\" **
X.It External ML-Doc
XReference is made to other ML-Doc documents with a
X.Li DOCREF
Xelement that specifies an entity with the
X.Li DOCUMENT
Xattribute, e.g.
X.Bd -literal -compact
X ...features of the <DOCREF
X DOCUMENT=SML-BASIS-DOC/SML Basis Library/...
X.Ed
X.\" **
X.It Sections/floats
XCross-references may be made to
X.Li SECTION Ns No s
Xor
X.Li FLOAT Ns No s
Xthat have
X.Li LABEL
Xattributes. The former using
X.Li SECREF
Xand the latter with
X.Li FLOATREF .
XBoth require a
X.Li LABEL
Xattribute of their own.
XNeither contain text, which comes instead from the referenced object.
XE.g.
X.Bd -literal -compact
X<SECTION LABEL="Files">
X.Li ...
X<SECTION LABEL="Storage">
X <HEAD>Sockets</HEAD>
X <PP>
X The <SECREF LABEL="Files"> section describes...
X.Ed
X.\" **
X.It Citations
XA
X.Li CITE
Xelement refers to a bibliography entry.
XIt is not supported by the HTML generators.
XThe value of the
X.Li KEY
Xattribute is passed directly into LaTeX.
X.El
X.Pp
XThe remainder of this section discusses references to SML objects.
XThese references are included in the document index, if not marked with a
X.Li NOINDEX
Xattribute, and become hyperlinks in HTML output, unless marked with a
X.Li NOLINK
Xattribute.
XA
X.Li DOCUMENT
Xattribute is used to reference another ML-Doc project.
X.Pp
XThe SML object reference tags are:
X.Bl -tag -offset indent -compact -width ".Li FCTARGREF"
X.\" **
X.It Li SIGREF
XRefer to a complete signature, e.g.
X.Li <SIGREF/MONO_ARRAY_SORT/
X.\" **
X.It Li FCTREF
XRefer to a functor, e.g.
X.Bd -literal -compact
XThe <FCTREF NOLINK/ArrayQSortFn/ implements...
X.Ed
X.\" **
X.It Li FCTARGREF
XRefer to the argument of a functor.
X.\" **
X.It Li STRREF
XRefer to a structure or substructure.
X.\" **
X.It Li EXNREF
XRefer to an exception, e.g.
X.Bd -literal -compact
X<RAISES>
X <EXNREF STRID="General" DOCUMENT=SML-BASIS-DOC/Size/
X.Ed
X.\" **
X.It Li TYREF
XRefer to a type, e.g.
X.Bd -literal -compact
X.Li ...constructor <TYREF SIGID="UREF">uref</TYREF> with...
X.Ed
X.\" **
X.It Li CONREF
XRefer to a datatype constructor, e.g.
X.Bd -literal -compact
X.Li ...then it returns <CONREF STRID="Option"/NONE/
X.Ed
X.\" **
X.It Li VALREF
XRefer to a value, e.g
X.Li <VALREF>randMin</VALREF> .
X.El
X.Pp
XA context attribute should be given with the latter five tags when they
Xrefer to a specification in another part of the module hierarchy.
XThere are four, mutually exclusive, possibilities:
X.Bl -tag -offset indent -compact -width ".Li FCTID"
X.It Li SIGID
XFor specifications in
X.Li SIGNATURE Ns No s.
X.It Li STRID
XFor specifications in
X.Li STRUCTURE Ns No s
Xor
X.Li SUBSTRUCT Ns No s.
X.It Li FCTID
XFor specifications in
X.Li FUNCTOR Ns No s.
X.It Li TOPID
XFor specifications available at the top-level without qualification. No value is given.
X.El
XExamples may be seen throughout this document.
XThe partial path given in the
X.Li *ID
Xattribute and the reference text are merged when there is overlap between
Xthe rightmost components of the former and the leftmost components of the
Xlatter. For example, in cases like:
X.Dl <TYREF STRID="OS.FileSys">OS.FileSys.access_mode</TYREF>
XAn
X.Li *ID
Xattribute is not required when the reference is to another element in the
Xsame
X.Li SIGBODY .
X.\"
X.Ss Formatting
XTags available for inline formatting:
X.Bl -column -compact -offset indent "ARG" "function argument"
X.It Sy tag Ta Sy effect
X.It Li EM Ta emphasis
X.It Li IT Ta italics
X.It Li BF Ta bold
X.It Li TT Ta typewriter
X.It Li CD Ta code
X.It Li ARG Ta function argument
X.It Li KW Ta keyword
X.El
XProgram text may also be displayed, rather than inlined with the tag
X.Li CODE .
XBoth
X.Li CD
Xand
X.Li CODE
Xtags may carry a
X.Li LANG
Xattribute having a value of either
X.Qq sml
Xor
X.Qq c .
X.\"
X.Ss Tables
XTables are as in HTML but initial
X.Li COL
Xtags are mandatory:
X.Bd -literal -offset indent -compact
X<TABLE>
X <COL ALIGN=LEFT PARBOX="5em"><COL ALIGN=CENTER><COL ALIGN=RIGHT>
X <TR><TH>Colour<TH>Code<TH>Comment
X <TR><TD>Red<TD><CD/#FF0000/<TD>Plain red
X <TR><TD>Blue<TD><CD/#0000FF/<TD>Plain blue
X</TABLE>
X.Ed
XTable heading
X.Pq Li TH
Xand cell
X.Pq Li TD
Xelements have optional
X.Li ALIGN
Xand
X.Li COLSPAN
Xattributes. Tables that span multiple pages should be marked
X.Li LONG .
X.\"
X.Ss Floats
XSource code and
X.Pq non- Ns Li LONG
Xtables may be floated:
X.Bd -literal -offset indent -compact
X<FLOAT LABEL="modlist" CAPALIGN=TOP>
X <CAPTION>Module List
X <TABLE>...</TABLE>
X</FLOAT>
X.Ed
XThe
X.Li LABEL
Xattribute is obligatory and may be referenced from a
X.Li FLOATREF .
X.\"
X.Ss Lists
XThere are three types of lists:
X.Bl -bullet -compact
X.It
Xitemized (bulleted items), e.g.
X.Bd -literal -compact
X<ITEMIZE>
X <ITEM>First item
X <ITEM>Second item
X</ITEMIZE>
X
X.Ed
X.It
Xenumerated (numbered), e.g.
X.Bd -literal -compact
X<ENUM>
X <ITEM>First item
X <ITEM>Second item
X</ENUM>
X
X.Ed
X.It
Xdescriptive, e.g.
X.Bd -literal -compact
X<DESCRIP>
X <DTAG/first/<ITEM>text about first item
X <DTAG/second/<ITEM>text about second item
X</DESCRIP>
X.Ed
X.El
X.\"
X.Ss Miscellaneous Text Blocks
XParagraphs may be grouped based on intent:
X.Bl -tag -width ".Li RATIONALEMM"
X.It EXAMPLE
XFor extended examples.
X.It QUESTION
XPresents a note on, or discussion of, open design issues.
X.It IMPLNOTE
XImplementation notes, e.g. expected efficiency.
X.It RATIONALE
XExplain the reasons behind design decisions.
X.It SYSNOTE
XComments specific to an architecture
X.Pq named with the Li ARCH No attribute
Xor operating system
X.Pq the Li OPSYS No attribute .
X.El
XAs an example:
X.Bd -literal -offset indent -compact
X<PP>
X...
X<RATIONALE>
X <PP>
X These functions...
X <PP>
X An alternative...
X</RATIONALE>
X.Ed
X.\"
X.Ss Regular Expressions
XRegular expressions may be included within text
X.Pq Li RE
Xor displayed on their own line
X.Pq Li REGEXP .
XLiteral characters are tagged as
X.Li GRAM.LIT
Xand displayed in typewriter font (other possible atoms are
X.Li GRAM.NONTERM
Xin italics,
X.Li GRAM.TERM
Xin roman, and
X.Li GRAM.KW
Xin bold).
XE.g.
X.Dl <RE><GRAM.LIT/i/<GRAM.LIT/f/</RE>
Xgives:
X.Li if
X.Pp
XCharacters sets, displayed between square brackets, are built with
X.Li GRAM.CSET .
XSets may include character atoms and ranges, e.g.
X.Bd -literal -compact -offset indent
X<REGEX><GRAM.CSET><GRAM.RANGE><GRAM.LIT/A/<GRAM.LIT/F/<GRAM.RANGE>
X <GRAM.RANGE><GRAM.LIT/a/<GRAM.LIT/f/<GRAM.RANGE>
X </GRAM.CSET></REGEX>
X.Ed
Xgives:
X.Li [A-Fa-f]
X.Pp
XClosures are expressed by grouping characters and specifying a count, e.g.
X.Dl <RE><GRAM.GRP ONE-OR-MORE><GRAM.LIT/a/<GRAM.LIT/b/</GRAM.GRP></RE>
Xgives:
X.Li (ab)+
X.Pp
XPossible counts are:
X.Li ONE
X(the default),
X.Li ZERO-OR-ONE ,
X.Li ZERO-OR-MORE ,
X.Li ONE-OR-MORE .
X.Pp
XAlternation, regular expressions separated by bars, is also possible, e.g.
X.Bd -literal -offset indent -compact
X<RE><GRAM.ALT>
X <GRAM.LIT/A/
X <GRAM.GRP ZERO-OR-MORE><GRAM.LIT/B/</GRAM.GRP>
X </GRAM.ALT></RE>
X.Ed
Xgives:
X.Li A | B*
X.\"
X.Ss Mathematics
XSome support is provided for type-setting mathematics. Formulas may be
Xplaced in running text
X.Pq Li MATH ,
Xdisplayed (on a separate line,
X.Li DISPLAYMATH Ns
X) or made into a table of equations, e.g.
X.Bd -literal -offset indent -compact
X<EQNARRAY>
X <EQN>x + y<EQNREL/=/2</EQN>
X <EQN>y<EQNREL/>=/0</EQN>
X</EQNARRAY>
X.Ed
Xgives:
X.Bl -column -compact -offset indent "x + y" ">=" "2"
X.It x + y Ta = Ta 2
X.It y Ta >= Ta 0
X.El
X.Pp
XOther features:
X.Bl -column -compact -offset indent "absolute value" ".Li <MATH><CEILING>x + y</CEILING></MATH>"
X.It subscripts Ta Li <MATH>x<SUB/i+1/</MATH>
X.It superscripts Ta Li <MATH>x<SUP/2*3/</MATH>
X.It modulo Ta Li <MATH>x<MOD/y+z/</MATH>
X.It Ta Em displayed as: Li x (mod (y+z))
X.It fractions Ta Li <MATH><FRAC>1<OVER>2</FRAC></MATH>
X.It absolute value Ta Li <MATH><NORM>x + y</NORM></MATH>
X.It ceiling Ta Li <MATH><CEILING>x + y</CEILING></MATH>
X.It floor Ta Li <MATH><FLOOR>x + y</FLOOR></MATH>
X.It sets Ta Li <MATH><SET>x | x > 2</SET></MATH>
X.El
X.Pp
XArgument variables, e.g.
X.Li <ARG/lset/ ,
Xmay be included in formulas, as may
Xnormal (roman) text, e.g.
X.Dl <MTEXT/if not empty/
X.Pp
XThe predefined mathematical entities are:
X.Bl -column -offset indent -compact \
X ".Li &MINUSPLUS;" ".Li &GREATEREQ;" ".Li &EXISTS;" ".Li &PLUSMINUS;"
X.It Li &CUP; Ta Li &CAP; Ta Li &EXISTS; Ta Li FORALL
X.It Li &GREATER; Ta Li &GREATEREQ; Ta Li &IN; Ta Li &LESS;
X.It Li &LESSEQ; Ta Li &NOTEQ; Ta Li &NOTIN; Ta Li &OMINUS;
X.It Li &OPLUS; Ta Li &OTIMES; Ta Li &PI; Ta Li &PLUSMINUS;
X.It Li &MINUSPLUS; Ta Li &INF;
X.El
X.\"
X.Ss Indexing
XA hardcopy document contains up to three separate indexes:
X.Bl -tag -width "raises" -compact -offset indent
X.It topic
XGeneral index (by topic)
X.It id
XSML identifier index
X.It raises
XRaised exception index
X.El
XIn HTML, separate indexes for signatures, structs, and types are possible.
X.Pp
XEntries are extracted automatically from interface descriptions. They may
Xalso be inserted into text manually with the
X.Li INDEX
Xtag, e.g.
X.Dl This module handles <INDEX KEY="Error Reporting">error reporting.
Xcreating an entry in the General Index, by default, with
Xappropriate page number:
X.Bd -literal -compact -offset indent
XError Reporting, 14
X.Ed
X.Pp
XThe index\(emone of
X.Qq topic , id
Xor
X.Qq raises Ns
X\(emis specified with the
X.Li WHICH
Xattribute. The
X.Li SEE
Xattribute replaces the page number with the given text.
X.Pp
XThe key-view tag specifies alternate text or formatting for an index entry.
XExtra sub-index tags can be added, with optional key-views, to provide one
Xor two extra levels of specificity, e.g.
X.Bd -literal -offset indent -compact
XThis module handles <INDEX KEY="Error Reporting">
X <KEY-VIEW><IT/Error Reporting/</KEY-VIEW>
X <SUBINDEX KEY="Module">
X</INDEX>error reporting.
X.Ed
XGives:
X.Bd -literal -compact -offset indent
X.Em Error Reporting
X Module, 14
X.Ed
X.Pp
XTopics that span bodies of text are delimited with
X.Li START
Xand
X.Li STOP
Xattributes, e.g.
X.Bd -literal -offset indent -compact
X<INDEX KEY="Displays" START> This chapter discusses display
Xcharacteristics of...
X ...which concludes our discussion.<INDEX KEY="Displays" STOP>
X.Ed
XCould produce:
X.Bd -literal -offset indent -compact
XDisplays, 19\(em25
X.Ed
X.\" ----------------------------------------
X.Sh SGML vs HTML/XML
XAlthough the basics of editing
X.ML-Doc
Xwill be familiar to most authors of HTML and XML, SGML has some peculiarities
Xthat are designed to make editing
X.Sq by hand
Xeasier.
X.Pp
XMany end-tags are optional, as in HTML, but unlike in XML, e.g.
X.Bd -literal -offset indent -compact
X<PP>
XNo explicit end-tag is given for this paragraph...
X<PP>
X ...before moving into the next
X.Ed
X.Pp
XThe usual start and end-tags are acceptable:
X.Dl <CD>'a</CD>
XBut
X.Em null end-tags
Xcan also be used for the same effect:
X.Dl <CD/'a/
X.Pp
XAttribute names are often optional when an enumerated value is required,
Xi.e. instead of
X.Li <GRAM.GRP COUNT=ONE>
Xone can also write
X.Li <GRAM.GRP ONE> .
Xsome attribute values can be stated without a name, i.e. instead of:
X.Dl <SPECBREAK NEWLINE=NEWLINE>
Xone can write:
X.Dl <SPECBREAK NEWLINE>
X.Pp
XAttribute values need not always be enclosed in double quotes.
X.Pp
XThese details are well described in Chapter 9 of
X.Em SGML and HTML Explained
X.Pq refer Sx SEE ALSO .
X.\"
X.\" ----------------------------------------
X.Sh FILES
XSystem-wide
X.ML-Doc
Xfiles and directories are stored at:
X.Dl %%PREFIX%%/share/ml-doc
XNotably:
X.Bl -tag -compact -offset indent
X.It Pa lib/catalog
XMaster catalog file.
X.It Pa lib/ml-doc.dtd
XDTD of
X.ML-Doc
Xlanguage.
X.It Pa lib/entities.sgml
XEntity definitions
X.Pq see Xr Entities .
X.It Pa lib/LaTeX/
XLaTeX class and style files for Hardcopy and Proof output.
X.El
X.\"
X.\" ----------------------------------------
X.Sh EXAMPLES
XAfter creating the directory structure
X.Pq see Sx Directory Structure ,
Xand writing up the ML-Doc files
X.Pq see Sx WRITING DOCUMENTATION ,
Xcreate a
X.Pa Makefile :
X.Dl find ML-Doc -name '*.mldoc' -print | mk-mldoc-makefile
X.Pp
XThen produce HTML documentation:
X.Dl make
Xand/or LaTeX:
X.Dl make Hardcopy
X.Pp
XCreating/updating a signature file:
X.Dl extract-sig ML-Doc/sync-var.mldoc
X.Pp
XProcessing LaTeX output:
X.Bd -literal -offset indent -compact
Xlatex manual
Xmakeindex -o manual.ind manual.idx # topic index
Xmakeindex -o manual.nnd manual.ndx # identifier index
Xmakeindex -o manual.rnd manual.rdx # exception index
Xlatex manual
X.Ed
X.\" ----------------------------------------
X.Sh BUGS
XThe utilities do not provide helpful error messages, usually
Xjust uncaught exceptions.
X.Pp
XThe toolset does not seem, in totality, to handle sub-directories under
X.Pa ML-Doc
Xvery well. Soft links provide a rudimentary work around.
X.Pp
XThe
X.Li FIGURE
Xtag is not implemented.
X.Pp
XThe
X.Li GRAMMAR
Xand
X.Li GRAM.SEP
Xtags are not supported.
X.Pp
XNeither
X.Li SUM , PROD , UNION ,
Xnor
X.Li INTERSECT
Xare implemented.
X.Pp
X.Li SUB
Xand
X.Li SUP
Xdo not work well together, i.e. squaring the ith x will not be typeset
Xproperly:
X.Dl <MATH>x<SUB/i/<SUP/2/</MATH>
X.Pp
XIt is not clear what
X.Li MGROUP
Xdoes. The contents are wrapped in brackets () in
XHTML output and invisible parentheses {} in LaTeX output.
X.Pp
XThe target added by the
X.Fl root
Xoption of
X.Nm mk-mldoc-makefile
Xdoes not run
X.Xr makeindex 1 .
X.Pp
XIt is not clear how to write mutually recursive
X.Li DATATYPE
Xor
X.Li VAL
Xspecifications, nor is it clear what the
X.Li REC
Xattribute signifies .
X.Pp
XThe
X.Li DOCREF
Xtag is not supported. There is no way of referencing
X.Li INTERFACE
Xelements
X.Pq i.e. the Li LABEL No attribute is redundant .
X.\" ----------------------------------------
X.Sh SEE ALSO
X.Xr mkdoc 1 ,
X.Pa %%PREFIX%%/share/ml-doc/lib/ml-doc.dtd .
X.Rs
X.%A "John H. Reppy"
X.%B "Concurrent Programming in ML"
X.%D 1999
X.%I Cambridge University Press
X.Re
X.Rs
X.%A "Emden R. Gansner"
X.%A "John H. Reppy"
X.%B "The Standard ML Basis Library"
X.%D 2004
X.%I Cambridge University Press
X.Re
X.Rs
X.%A "Martin Bryan"
X.%B "SGML and HTML Explained"
X.%D 1997
X.%I "Addison Wesley Longman"
X.%O available online: http://www.is-thought.co.uk/book/home.htm
X.Re
X.\" ----------------------------------------
X.Sh AUTHORS
X.An John H. Reppy Aq jhr at cs.uchicago.edu
Xwrote and maintains ML-Doc.
X.An Andrew Appel Aq appel at princeton.edu
Xwrote the first version of
X.Nm latex-gen .
X.An Lal George Aq lg at network-speed.com
Xwrote the
X.Nm proof-latex
Xtool.
X.Pp
X.An Timothy Bourke Aq timbob at bigpond.com
Xwrote this man page for the FreeBSD port based on documentation and source
Xfiles from the distribution.
END-of-ml-doc/files/ml-doc.1.in
echo x - ml-doc/files/mkdoc.1.in
sed 's/^X//' >ml-doc/files/mkdoc.1.in << 'END-of-ml-doc/files/mkdoc.1.in'
X.\" $Id$
X.\"
X.\" The tool described by this document is:
X.\" COPYRIGHT (c) 2007 The Fellowship of SML/NJ (http://smlnj.org)
X.\" All rights reserved.
X.\"
X.Dd August 2, 2007
X.Os FreeBSD 6.2
X.Dt mkdoc 1
X.\" ----------------------------------------
X.Sh NAME
X.\"
X.Nm mkdoc
X.Nd Turn SML signatures into rudimentary ML-Doc files.
X.\"
X.\" ----------------------------------------
X.Sh SYNOPSIS
X.Nm mk-doc
X.Op Fl a | Fl b | Fl \&?
X.Op Fl o Ar output-file
X.Op Fl c Ar copyright
X.Op Fl s | Sy +s Ar strid
X.Op Fl f | Sy +f Ar fctid Ar arg-id Ar arg-sig
X.Op Fl i | Sy +i Ar struct
X.Ar sml-file ...
X.\"
X.\" ----------------------------------------
X.Sh DESCRIPTION
X.Nm
Xtransforms an SML source file into SGML text for further processing by
X.Xr ml-doc 1 .
XThe output file contains the required basic structure.
XFurther editing is required to produce useful documentation.
XComments from the SML source can be included in the output
X.Po
Xthe
X.Fl a
Xand
X.Fl b
Xoptions
X.Pc as SGML comments.
X.\"
X.\" ----------------------------------------
X.Sh OPTIONS
X.Bl -tag -width indent
X.\"
X.It Fl \&?
XDisplay a summary of options.
X.\"
X.It Fl a
XCopy comments written
X.Em after
Xa specification.
X.\"
X.It Fl b
XCopy comments written
X.Em before
Xa specification.
X.\"
X.It Fl o Ar outfile
XSpecify an output file to use instead of standard output.
X.\"
X.It Fl c Ar copyright
XInsert the given copyright string into the output.
X.\"
X.It Fl s/ Ns Sy +s Ar strid
XInstead of placing the generated
X.Li SIGBODY
Xwithin
X.Li SIGNATURE
Xtags, the file must contain a single signature, use
X.Li STRUCTURE
Xtags with the specified
X.Li STRID .
XBind opaquely if
X.Sy +s
Xis given.
X.\"
X.It Fl f/ Ns Sy +f Ar fctid Ar arg-id Ar arg-sig
XAs per
X.Fl s/ Ns Sy +s ,
Xbut wrap the result in
X.Li FUNCTOR
Xtags, with
X.Ar fct
Xas
X.Li FCTID ,
X.Ar arg-id
Xas the functor argument
X.Li ID ,
Xand
X.Ar arg-sig
Xas its signature
X.Li ID .
X.\"
X.It Fl i/ Ns Sy +i Ar struct
XAttach, for each
X.Sy -/+i
Xoption given, a
X.Li SIGINSTANCE ,
Xpossibly with an
X.Li OPAQUE
Xattribute, onto the output.
X.\" ----------------------------------------
X.Sh EXAMPLES
X.Bd -literal -compact
Xmkdoc +i IntBinaryMap +i IntListMap Util/ord-map-sig.sml
Xmkdoc -f SplayMapFn K ORD_KEY Util/ord-map-sig.sml
X.Ed
X.\" ----------------------------------------
X.Sh BUGS
XError messages are usually just uncaught exceptions.
X.\" ----------------------------------------
X.Sh SEE ALSO
X.Xr ml-doc 1 .
X.\" ----------------------------------------
X.Sh AUTHORS
X.An Emden Gansner Aq erg at research.att.com
Xwrote Mkdoc.
X.An Dan Wang Aq danwang at cs.princeton.edu
Xadded the comment extraction feature.
END-of-ml-doc/files/mkdoc.1.in
echo x - ml-doc/files/patch-Makefile.in
sed 's/^X//' >ml-doc/files/patch-Makefile.in << 'END-of-ml-doc/files/patch-Makefile.in'
X--- Makefile.in.orig Sun Jul 22 17:30:59 2007
X+++ Makefile.in Sun Jul 22 17:31:39 2007
X@@ -11,6 +11,7 @@
X PREFIX = @prefix@
X CONFIGDIR = @top_srcdir@/config
X SRCDIR = @top_srcdir@/tools
X+LIBDIR= @top_srcdir@/lib
X BINDIR = @mldoc_bindir@
X HEAPDIR = @heapdir@
X
X@@ -38,6 +39,7 @@
X for dir in $(TARGETS); do \
X (cd $(SRCDIR)/$$dir && $(MAKE) install) || exit $$?; \
X done
X+ (cd $(LIBDIR) && $(MAKE) install) || exit $$?;
X
X clean:
X for dir in $(TARGETS); do \
END-of-ml-doc/files/patch-Makefile.in
echo x - ml-doc/pkg-plist
sed 's/^X//' >ml-doc/pkg-plist << 'END-of-ml-doc/pkg-plist'
Xbin/extract-sig
Xbin/extract-info
Xbin/filter-index
Xbin/html-gen
Xbin/html-index
Xbin/html-toc
Xbin/latex-gen
Xbin/merge-info
Xbin/mkdoc
Xbin/mk-mldoc-makefile
Xbin/proof-latex
X%%DATADIR%%/lib/HTMLsym.ent
X%%DATADIR%%/lib/catalog
X%%DATADIR%%/lib/dummy-filemap.sgml
X%%DATADIR%%/lib/element-list
X%%DATADIR%%/lib/entities.sgml
X%%DATADIR%%/lib/iso-lat1.ent
X%%DATADIR%%/lib/ml-doc-info.dtd
X%%DATADIR%%/lib/ml-doc.decl
X%%DATADIR%%/lib/ml-doc.dtd
X%%DATADIR%%/lib/LaTeX/mldoc-book.cls
X%%DATADIR%%/lib/LaTeX/mldoc-code.sty
X%%DATADIR%%/lib/LaTeX/mldoc.sty
X%%DATADIR%%/lib/LaTeX/proofMLDoc.sty
X at dirrm %%DATADIR%%/lib/LaTeX
X at dirrm %%DATADIR%%/lib
X at dirrm %%DATADIR%%
END-of-ml-doc/pkg-plist
exit
--- newport ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-ports-bugs
mailing list