Date: Wed, 29 Aug 2007 20:40:59 +1000 (EST) From: Timothy Bourke <timbob@bigpond.com> To: FreeBSD-gnats-submit@FreeBSD.org Subject: ports/115932: New port: devel/ml-doc Message-ID: <200708291040.l7TAewqK009911@triptrop.cse.unsw.edu.au> Resent-Message-ID: <200708292310.l7TNA1Bx085420@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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@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@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@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@cs.uchicago.edu Xwrote and maintains ML-Doc. X.An Andrew Appel Aq appel@princeton.edu Xwrote the first version of X.Nm latex-gen . X.An Lal George Aq lg@network-speed.com Xwrote the X.Nm proof-latex Xtool. X.Pp X.An Timothy Bourke Aq timbob@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@research.att.com Xwrote Mkdoc. X.An Dan Wang Aq danwang@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@dirrm %%DATADIR%%/lib/LaTeX X@dirrm %%DATADIR%%/lib X@dirrm %%DATADIR%% END-of-ml-doc/pkg-plist exit --- newport ends here --- >Release-Note: >Audit-Trail: >Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200708291040.l7TAewqK009911>