path: root/man/mdoc-assemble.1

.\" 
.\" mdoc assemble manual page.
.\" (C) 2008 Novell, Inc.
.\" Author:
.\"   Jonathan Pryor (jpryor@novell.com)
.\"
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.TH "mdoc-assemble" 1
.SH NAME
mdoc assemble \- Compile documentation for use in \fBmonodoc\fR(1)
.SH SYNOPSIS
.B mdoc assemble
[OPTIONS]+
PATHS+
.SH DESCRIPTION
\fBmdoc assemble\fR creates \fI.tree\fR and \fI.zip\fR files from \fIPATHS\fR
for use in the \fBmonodoc\fR(1) documentation browser.
.PP
The input files must have a supported \fIformat\fR, specified with the
\fI--format\fR option.
.PP
The \fI.tree\fR and \fI.zip\fR files are copied into \fBmonodoc\fR's 
\fIsources\fR directory, alongside a \fI.source\fR file which is used by 
\fBmonodoc\fR(1) to specify where the documentation should be displayed.
.PP
The \fI.source\fR file has the following format:
.nf

  <?xml version="1.0"?>
  <monodoc>
    <node label="LABEL" name="PATH" parent="PARENT">
      <node label="LABEL2" name="PATH2" />
      <!-- ... -->
    </node>
    <source provider="PROVIDER" basefile="BASEFILE" path="PATH" />
    <!-- other <source/> elements -->
  </monodoc>

.fi
The \fI/monodoc/node\fR node is an optional node that specifies where in the
monodoc tree the documentation should be displayed, and \fI//node\fR elements
may be nested to any depth to create trees.  \fI//node/@label\fR is the label
that will be displayed within the monodoc tree.
.PP
\fI//node/@name\fR is the name of the monodoc tree node, and may be used as 
the value of the \fI/monodoc/source/@path\fR value.
.PP
\fI//node/@parent\fR is the node name to use as the parent node.  
\fI$MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml\fR contains a list of such 
names, and this can be any \fI//node/@name\fR value.  If the 
\fI//node/@parent\fR value isn't found, then it's inserted under the
"Various" tree node.
.PP
The \fI/monodoc/source/@provider\fR attribute specifies which format provider
should be used when reading the \fI.tree\fR and \fI.zip\fR files; this
\fImust\fR correspond to one of the \fI--format\fR values.
.PP
The \fI/monodoc/source/@basefile\fR attribute specifies the filename prefix 
for the documentation files.  This must be the same prefix as used with the 
\fI\-\-out\fR parameter.  There should be \fIno\fR filename extension on this 
value.
.PP
The \fI/monodoc/source/@path\fR attribute specifies the parent node in 
\fBmonodoc\fR(1)'s tree view where the documentation will be inserted.
See the \fI$MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml\fR
file for a list of \fIPATH\fR values (the \fI//node/@name\fR values), or it
may be a \fI//node/@name\fR value in the same \fI.source\fR file.
.PP
Once the \fIBASEFILE.source\fR has been written, the documentation can be
installed so that \fBmonodoc\fR(1) will display the documentation with the
command:
.nf

  cp BASEFILE.source BASEFILE.tree BASEFILE.zip \\
    `pkg-config monodoc --variable=sourcesdir`

.fi
.SH OPTIONS
.TP
\fB\-f\fR, \fB\-\-format\fR=\fIFORMAT\fR
Specifies the documentation format used within \fIPATHS\fR.  Valid
\fIFORMAT\fR values include:
\fIecma\fR,
\fIecmaspec\fR,
\fIerror\fR,
\fIhb\fR,
\fIman\fR,
\fIsimple\fR, and
\fIxhtml\fR.
.Sp
See the \fIFORMATS\fR section below for more information about these formats.
.Sp
The default format (if none is specifed) is \fIecma\fR.
.Sp
The \fI\-\-format\fR option may be interleaved with \fIPATHS\fR to
change the format used for the remaining parameters (until the next
\fI\-\-format\fR option is seen), e.g.:
.nf

  mdoc assemble -o PREFIX A B --format=man C D --format=xhtml E

.fi
will assemble directories \fIA\fR and \fIB\fR with the \fIecma\fR format,
files \fIC\fR and \fID\fR with the \fIman\fR formt, and directory
\fIE\fR with the \fIxhtml\fR format.
.TP
\fB\-o\fR, \fB\-\-out\fR=\fIPREFIX\fR
Specify the output file prefix.  \fBmdoc assemble\fR creates the files
\fIPREFIX.zip\fR and \fIPREFIX.tree\fR.
.TP
\fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR
Display a help message and exit.
.SH "FORMATS"
The following documentation formats are supported:
.SS ecma
The \fIMono ECMA Documentation Format\fR, an XML documentation format with one 
file per type.
.PP
See the \fBmdoc\fR(5) man page for more information.
.SS ecmaspec
The \fIMono ECMA Specification Documentation Format\fR.
This is not the format you're looking for; it is the format used to represent 
the ECMA-334 (C#) standard within \fBmonodoc\fR(1).  It is not used to display 
class library documentation; for class library documentation, use the
.B ecma
format.
.SS error
The \fIError Documentation Format\fR is used to present detailed error 
messages, and is used in \fBmonodoc\fR(1)'s "C# Compiler Error Reference"
tree.  
.PP
In this format, \fIPATHS\fR is a configuration file, containing the XML:
.nf

    <ErrorProviderConfig>
        <FilesPath>../../mcs/errors</FilesPath>
        <Match>cs????*.cs</Match>
        <ErrorNumSubstringStart>2</ErrorNumSubstringStart>
        <ErrorNumSubstringLength>4</ErrorNumSubstringLength>
        <FriendlyFormatString>CS{0:0###}</FriendlyFormatString>
    </ErrorProviderConfig>

.fi
The elements mean:
.TP
.I /ErrorProviderConfig/FilesPath
Specifies where to look for files.
.TP
.I /ErrorProviderConfig/Match
Specifies the filename pattern to look for within the
\fI/ErrorProviderConfig/FilesPath\fR directory.
.TP
.I /ErrorProviderConfig/ErrorNumSubstringStart
Specifies where within the filename the error number starts.
.TP
.I /ErrorProviderConfig/ErrorNumSubstringLength
Specifies how many characters after
\fI/ErrorProviderConfig/ErrorNumSubstringStart\fR to use for the error number.
.TP
.I /ErrorProviderConfig/FriendlyFormatString
Specifies the formatting/display of the node in the \fBmonodoc\fR(1) tree.
.PP
For each file found, it is converted to HTML with C# syntax coloring applied.
.SS simple
The \fISimple Documentation Format\fR file format recursively adds all files
and directories underneath \fIPATHS\fR.  When displayed, HTML files are
displayed as-is.  Text files are converted into HTML by translating each 
newline into an HTML \fI<br>\fR element.  No other file type is supported.
.SS man
The \fIMan Page Documentation Format\fR displays groff man pages.  (This is
\fInot\fR a full groff parser, and only handles the man page constructs used
within the mono man pages.)
.PP
\fIPATHS\fR is a set of XML files containing:
.nf

  <?xml version="1.0"?>
  <manpages>
    <manpage name="NAME" page="FILE" />
  </manpages>

.fi
There may be multiple \fI//manpage\fR elements within the root \fI/manpage\fR
element.
.PP
The \fI/manpages/manpage/@name\fR attribute contains the display name for the
tree view node, which is also the URL of the man page when using
\fBmonodoc\fR(1)'s \fILookup URL\fR command (before prefixing with a
\fIman:\fR prefix).  Thus, if \fI/manpages/manpage/@name\fR contains
\fImono(1)\fR, then \fIman:mono(1)\fR can be used in the \fILookup URL\fR
command to view the \fImono(1)\fR man page.
.PP
The \fI/manpages/manpage/@page\fR attribute is the filename that contains the
man page.  If this file does not exist, then \fI/manpages/manpage/@name\fR
will not be displayed within the tree view.
.SS xhtml
The XHTML provider interprets \fIPATHS\fR as a Windows Help file XHTML TOC
file and looks for referenced documents to create the help source.
.SH SEE ALSO
\fBmdoc\fR(1), 
\fBmdoc\fR(5), 
\fBmonodoc\fR(1)
.SH MAILING LISTS
.TP
Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
.SH WEB SITE
See also: http://www.mono-project.com/docs/tools+libraries/tools/mdoc/