man/mdoc-assemble.1

   1 .\"
   2 .\" mdoc assemble manual page.
   3 .\" (C) 2008 Novell, Inc.
   4 .\" Author:
   5 .\"   Jonathan Pryor (jpryor@novell.com)
   6 .\"
   7 .de Sp \" Vertical space (when we can't use .PP)
   8 .if t .sp .5v
   9 .if n .sp
  10 ..
  11 .TH "mdoc-assemble" 1
  12 .SH NAME
  13 mdoc assemble \- Compile documentation for use in \fBmonodoc\fR(1)
  14 .SH SYNOPSIS
  15 .B mdoc assemble
  16 [OPTIONS]+
  17 PATHS+
  18 .SH DESCRIPTION
  19 \fBmdoc assemble\fR creates \fI.tree\fR and \fI.zip\fR files from \fIPATHS\fR
  20 for use in the \fBmonodoc\fR(1) documentation browser.
  21 .PP
  22 The input files must have a supported \fIformat\fR, specified with the
  23 \fI--format\fR option.
  24 .PP
  25 The \fI.tree\fR and \fI.zip\fR files are copied into \fBmonodoc\fR's
  26 \fIsources\fR directory, alongside a \fI.source\fR file which is used by
  27 \fBmonodoc\fR(1) to specify where the documentation should be displayed.
  28 .PP
  29 The \fI.source\fR file has the following format:
  30 .nf
  31
  32   <?xml version="1.0"?>
  33   <monodoc>
  34     <node label="LABEL" name="PATH" parent="PARENT">
  35       <node label="LABEL2" name="PATH2" />
  36       <!-- ... -->
  37     </node>
  38     <source provider="PROVIDER" basefile="BASEFILE" path="PATH" />
  39     <!-- other <source/> elements -->
  40   </monodoc>
  41
  42 .fi
  43 The \fI/monodoc/node\fR node is an optional node that specifies where in the
  44 monodoc tree the documentation should be displayed, and \fI//node\fR elements
  45 may be nested to any depth to create trees.  \fI//node/@label\fR is the label
  46 that will be displayed within the monodoc tree.
  47 .PP
  48 \fI//node/@name\fR is the name of the monodoc tree node, and may be used as
  49 the value of the \fI/monodoc/source/@path\fR value.
  50 .PP
  51 \fI//node/@parent\fR is the node name to use as the parent node.
  52 \fI$MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml\fR contains a list of such
  53 names, and this can be any \fI//node/@name\fR value.  If the
  54 \fI//node/@parent\fR value isn't found, then it's inserted under the
  55 "Various" tree node.
  56 .PP
  57 The \fI/monodoc/source/@provider\fR attribute specifies which format provider
  58 should be used when reading the \fI.tree\fR and \fI.zip\fR files; this
  59 \fImust\fR correspond to one of the \fI--format\fR values.
  60 .PP
  61 The \fI/monodoc/source/@basefile\fR attribute specifies the filename prefix
  62 for the documentation files.  This must be the same prefix as used with the
  63 \fI\-\-out\fR parameter.  There should be \fIno\fR filename extension on this
  64 value.
  65 .PP
  66 The \fI/monodoc/source/@path\fR attribute specifies the parent node in
  67 \fBmonodoc\fR(1)'s tree view where the documentation will be inserted.
  68 See the \fI$MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml\fR
  69 file for a list of \fIPATH\fR values (the \fI//node/@name\fR values), or it
  70 may be a \fI//node/@name\fR value in the same \fI.source\fR file.
  71 .PP
  72 Once the \fIBASEFILE.source\fR has been written, the documentation can be
  73 installed so that \fBmonodoc\fR(1) will display the documentation with the
  74 command:
  75 .nf
  76
  77   cp BASEFILE.source BASEFILE.tree BASEFILE.zip \\
  78     `pkg-config monodoc --variable=sourcesdir`
  79
  80 .fi
  81 .SH OPTIONS
  82 .TP
  83 \fB\-f\fR, \fB\-\-format\fR=\fIFORMAT\fR
  84 Specifies the documentation format used within \fIPATHS\fR.  Valid
  85 \fIFORMAT\fR values include:
  86 \fIecma\fR,
  87 \fIecmaspec\fR,
  88 \fIerror\fR,
  89 \fIhb\fR,
  90 \fIman\fR,
  91 \fIsimple\fR, and
  92 \fIxhtml\fR.
  93 .Sp
  94 See the \fIFORMATS\fR section below for more information about these formats.
  95 .Sp
  96 The default format (if none is specifed) is \fIecma\fR.
  97 .Sp
  98 The \fI\-\-format\fR option may be interleaved with \fIPATHS\fR to
  99 change the format used for the remaining parameters (until the next
 100 \fI\-\-format\fR option is seen), e.g.:
 101 .nf
 102
 103   mdoc assemble -o PREFIX A B --format=man C D --format=xhtml E
 104
 105 .fi
 106 will assemble directories \fIA\fR and \fIB\fR with the \fIecma\fR format,
 107 files \fIC\fR and \fID\fR with the \fIman\fR formt, and directory
 108 \fIE\fR with the \fIxhtml\fR format.
 109 .TP
 110 \fB\-o\fR, \fB\-\-out\fR=\fIPREFIX\fR
 111 Specify the output file prefix.  \fBmdoc assemble\fR creates the files
 112 \fIPREFIX.zip\fR and \fIPREFIX.tree\fR.
 113 .TP
 114 \fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR
 115 Display a help message and exit.
 116 .SH "FORMATS"
 117 The following documentation formats are supported:
 118 .SS ecma
 119 The \fIMono ECMA Documentation Format\fR, an XML documentation format with one
 120 file per type.
 121 .PP
 122 See the \fBmdoc\fR(5) man page for more information.
 123 .SS ecmaspec
 124 The \fIMono ECMA Specification Documentation Format\fR.
 125 This is not the format you're looking for; it is the format used to represent
 126 the ECMA-334 (C#) standard within \fBmonodoc\fR(1).  It is not used to display
 127 class library documentation; for class library documentation, use the
 128 .B ecma
 129 format.
 130 .SS error
 131 The \fIError Documentation Format\fR is used to present detailed error
 132 messages, and is used in \fBmonodoc\fR(1)'s "C# Compiler Error Reference"
 133 tree.
 134 .PP
 135 In this format, \fIPATHS\fR is a configuration file, containing the XML:
 136 .nf
 137
 138     <ErrorProviderConfig>
 139         <FilesPath>../../mcs/errors</FilesPath>
 140         <Match>cs????*.cs</Match>
 141         <ErrorNumSubstringStart>2</ErrorNumSubstringStart>
 142         <ErrorNumSubstringLength>4</ErrorNumSubstringLength>
 143         <FriendlyFormatString>CS{0:0###}</FriendlyFormatString>
 144     </ErrorProviderConfig>
 145
 146 .fi
 147 The elements mean:
 148 .TP
 149 .I /ErrorProviderConfig/FilesPath
 150 Specifies where to look for files.
 151 .TP
 152 .I /ErrorProviderConfig/Match
 153 Specifies the filename pattern to look for within the
 154 \fI/ErrorProviderConfig/FilesPath\fR directory.
 155 .TP
 156 .I /ErrorProviderConfig/ErrorNumSubstringStart
 157 Specifies where within the filename the error number starts.
 158 .TP
 159 .I /ErrorProviderConfig/ErrorNumSubstringLength
 160 Specifies how many characters after
 161 \fI/ErrorProviderConfig/ErrorNumSubstringStart\fR to use for the error number.
 162 .TP
 163 .I /ErrorProviderConfig/FriendlyFormatString
 164 Specifies the formatting/display of the node in the \fBmonodoc\fR(1) tree.
 165 .PP
 166 For each file found, it is converted to HTML with C# syntax coloring applied.
 167 .SS simple
 168 The \fISimple Documentation Format\fR file format recursively adds all files
 169 and directories underneath \fIPATHS\fR.  When displayed, HTML files are
 170 displayed as-is.  Text files are converted into HTML by translating each
 171 newline into an HTML \fI<br>\fR element.  No other file type is supported.
 172 .SS man
 173 The \fIMan Page Documentation Format\fR displays groff man pages.  (This is
 174 \fInot\fR a full groff parser, and only handles the man page constructs used
 175 within the mono man pages.)
 176 .PP
 177 \fIPATHS\fR is a set of XML files containing:
 178 .nf
 179
 180   <?xml version="1.0"?>
 181   <manpages>
 182     <manpage name="NAME" page="FILE" />
 183   </manpages>
 184
 185 .fi
 186 There may be multiple \fI//manpage\fR elements within the root \fI/manpage\fR
 187 element.
 188 .PP
 189 The \fI/manpages/manpage/@name\fR attribute contains the display name for the
 190 tree view node, which is also the URL of the man page when using
 191 \fBmonodoc\fR(1)'s \fILookup URL\fR command (before prefixing with a
 192 \fIman:\fR prefix).  Thus, if \fI/manpages/manpage/@name\fR contains
 193 \fImono(1)\fR, then \fIman:mono(1)\fR can be used in the \fILookup URL\fR
 194 command to view the \fImono(1)\fR man page.
 195 .PP
 196 The \fI/manpages/manpage/@page\fR attribute is the filename that contains the
 197 man page.  If this file does not exist, then \fI/manpages/manpage/@name\fR
 198 will not be displayed within the tree view.
 199 .SS xhtml
 200 The XHTML provider interprets \fIPATHS\fR as a Windows Help file XHTML TOC
 201 file and looks for referenced documents to create the help source.
 202 .SH SEE ALSO
 203 \fBmdoc\fR(1),
 204 \fBmdoc\fR(5),
 205 \fBmonodoc\fR(1)
 206 .SH MAILING LISTS
 207 .TP
 208 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
 209 .SH WEB SITE
 210 See also: http://www.mono-project.com/docs/tools+libraries/tools/mdoc/