1mdoc-assemble(1) General Commands Manual mdoc-assemble(1)
2
6 mdoc assemble - Compile documentation for use in monodoc(1)
7
9 mdoc assemble [OPTIONS]+ PATHS+
10
12 mdoc assemble creates .tree and .zip files from PATHS for use in the
13 monodoc(1) documentation browser.
14 The input files must have a supported format, specified with the --for‐
16 mat option.
17 The .tree and .zip files are copied into monodoc's sources directory,
19 alongside a .source file which is used by monodoc(1) to specify where
20 the documentation should be displayed.
21 The .source file has the following format:
23 <?xml version="1.0"?>
25 <monodoc>
26 <node label="LABEL" name="PATH" parent="PARENT">
27 <node label="LABEL2" name="PATH2" />
28 <!-- ... -->
29 </node>
30 <source provider="PROVIDER" basefile="BASEFILE" path="PATH" />
31 <!-- other <source/> elements -->
32 </monodoc>
33 The /monodoc/node node is an optional node that specifies where in the
35 monodoc tree the documentation should be displayed, and //node elements
36 may be nested to any depth to create trees. //node/@label is the label
37 that will be displayed within the monodoc tree.
38 //node/@name is the name of the monodoc tree node, and may be used as
40 the value of the /monodoc/source/@path value.
41 //node/@parent is the node name to use as the parent node.
43 $MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml contains a list of such
44 names, and this can be any //node/@name value. If the //node/@parent
45 value isn't found, then it's inserted under the "Various" tree node.
46 The /monodoc/source/@provider attribute specifies which format provider
48 should be used when reading the .tree and .zip files; this must corre‐
49 spond to one of the --format values.
50 The /monodoc/source/@basefile attribute specifies the filename prefix
52 for the documentation files. This must be the same prefix as used with
53 the --out parameter. There should be no filename extension on this
54 value.
55 The /monodoc/source/@path attribute specifies the parent node in mon‐
57 odoc(1)'s tree view where the documentation will be inserted. See the
58 $MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml file for a list of PATH
59 values (the //node/@name values), or it may be a //node/@name value in
60 the same .source file.
61 Once the BASEFILE.source has been written, the documentation can be
63 installed so that monodoc(1) will display the documentation with the
64 command:
65 cp BASEFILE.source BASEFILE.tree BASEFILE.zip \
67 `pkg-config monodoc --variable=sourcesdir`
68
71 -f, --format=FORMAT
72 Specifies the documentation format used within PATHS. Valid
73 FORMAT values include: ecma, ecmaspec, error, hb, man, simple,
74 and xhtml.
75 See the FORMATS section below for more information about these
77 formats.
78 The default format (if none is specifed) is ecma.
80 The --format option may be interleaved with PATHS to change the
82 format used for the remaining parameters (until the next --for‐
83 mat option is seen), e.g.:
84 mdoc assemble -o PREFIX A B --format=man C D --format=xhtml E
86 will assemble directories A and B with the ecma format, files C
88 and D with the man formt, and directory E with the xhtml format.
89 -o, --out=PREFIX
91 Specify the output file prefix. mdoc assemble creates the files
92 PREFIX.zip and PREFIX.tree.
93 -h, -?, --help
95 Display a help message and exit.
96
98 The following documentation formats are supported:
99 ecma
101 The Mono ECMA Documentation Format, an XML documentation format with
102 one file per type.
103 See the mdoc(5) man page for more information.
105 ecmaspec
107 The Mono ECMA Specification Documentation Format. This is not the for‐
108 mat you're looking for; it is the format used to represent the ECMA-334
109 (C#) standard within monodoc(1). It is not used to display class
110 library documentation; for class library documentation, use the ecma
111 format.
112 error
114 The Error Documentation Format is used to present detailed error mes‐
115 sages, and is used in monodoc(1)'s "C# Compiler Error Reference" tree.
116 In this format, PATHS is a configuration file, containing the XML:
118 <ErrorProviderConfig>
120 <FilesPath>../../mcs/errors</FilesPath>
121 <Match>cs????*.cs</Match>
122 <ErrorNumSubstringStart>2</ErrorNumSubstringStart>
123 <ErrorNumSubstringLength>4</ErrorNumSubstringLength>
124 <FriendlyFormatString>CS{0:0###}</FriendlyFormatString>
125 </ErrorProviderConfig>
126 The elements mean:
128 /ErrorProviderConfig/FilesPath
130 Specifies where to look for files.
131 /ErrorProviderConfig/Match
133 Specifies the filename pattern to look for within the /Error‐
134 ProviderConfig/FilesPath directory.
135 /ErrorProviderConfig/ErrorNumSubstringStart
137 Specifies where within the filename the error number starts.
138 /ErrorProviderConfig/ErrorNumSubstringLength
140 Specifies how many characters after /ErrorProviderConfig/Error‐
141 NumSubstringStart to use for the error number.
142 /ErrorProviderConfig/FriendlyFormatString
144 Specifies the formatting/display of the node in the monodoc(1)
145 tree.
146 For each file found, it is converted to HTML with C# syntax coloring
148 applied.
149 simple
151 The Simple Documentation Format file format recursively adds all files
152 and directories underneath PATHS. When displayed, HTML files are dis‐
153 played as-is. Text files are converted into HTML by translating each
154 newline into an HTML <br> element. No other file type is supported.
155 man
157 The Man Page Documentation Format displays groff man pages. (This is
158 not a full groff parser, and only handles the man page constructs used
159 within the mono man pages.)
160 PATHS is a set of XML files containing:
162 <?xml version="1.0"?>
164 <manpages>
165 <manpage name="NAME" page="FILE" />
166 </manpages>
167 There may be multiple //manpage elements within the root /manpage ele‐
169 ment.
170 The /manpages/manpage/@name attribute contains the display name for the
172 tree view node, which is also the URL of the man page when using mon‐
173 odoc(1)'s Lookup URL command (before prefixing with a man: prefix).
174 Thus, if /manpages/manpage/@name contains mono(1), then man:mono(1) can
175 be used in the Lookup URL command to view the mono(1) man page.
176 The /manpages/manpage/@page attribute is the filename that contains the
178 man page. If this file does not exist, then /manpages/manpage/@name
179 will not be displayed within the tree view.
180 xhtml
182 The XHTML provider interprets PATHS as a Windows Help file XHTML TOC
183 file and looks for referenced documents to create the help source.
184
186 mdoc(1), mdoc(5), monodoc(1)
187
189 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for
190 details.
191
193 See also: http://www.mono-project.com/docs/tools+libraries/tools/mdoc/
194 mdoc-assemble(1)