More corelib cleanup (dotnet/coreclr#26993)
[mono-project.git] / man / mdoc-assemble.1
blob4497101395cbc91102d77d3e16c779507b664f36
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
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
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>
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
77   cp BASEFILE.source BASEFILE.tree BASEFILE.zip \\
78     `pkg-config monodoc --variable=sourcesdir`
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.:
103   mdoc assemble -o PREFIX A B --format=man C D --format=xhtml E
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.
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.
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.
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.  
135 In this format, \fIPATHS\fR is a configuration file, containing the XML:
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>
147 The elements mean:
149 .I /ErrorProviderConfig/FilesPath
150 Specifies where to look for files.
152 .I /ErrorProviderConfig/Match
153 Specifies the filename pattern to look for within the
154 \fI/ErrorProviderConfig/FilesPath\fR directory.
156 .I /ErrorProviderConfig/ErrorNumSubstringStart
157 Specifies where within the filename the error number starts.
159 .I /ErrorProviderConfig/ErrorNumSubstringLength
160 Specifies how many characters after
161 \fI/ErrorProviderConfig/ErrorNumSubstringStart\fR to use for the error number.
163 .I /ErrorProviderConfig/FriendlyFormatString
164 Specifies the formatting/display of the node in the \fBmonodoc\fR(1) tree.
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.)
177 \fIPATHS\fR is a set of XML files containing:
180   <?xml version="1.0"?>
181   <manpages>
182     <manpage name="NAME" page="FILE" />
183   </manpages>
186 There may be multiple \fI//manpage\fR elements within the root \fI/manpage\fR
187 element.
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.
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
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/