1mdoc-assemble(1)            General Commands Manual           mdoc-assemble(1)
2
3
4

NAME

6       mdoc assemble - Compile documentation for use in monodoc(1)
7

SYNOPSIS

9       mdoc assemble [OPTIONS]+ PATHS+
10

DESCRIPTION

12       mdoc  assemble  creates  .tree and .zip files from PATHS for use in the
13       monodoc(1) documentation browser.
14
15       The input files must have a supported format, specified with the --for‐
16       mat option.
17
18       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
22       The .source file has the following format:
23
24         <?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
34       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
39       //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
42       //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
47       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
51       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
56       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
62       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
66         cp BASEFILE.source BASEFILE.tree BASEFILE.zip \
67           `pkg-config monodoc --variable=sourcesdir`
68
69

OPTIONS

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
76              See  the  FORMATS section below for more information about these
77              formats.
78
79              The default format (if none is specifed) is ecma.
80
81              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
85                mdoc assemble -o PREFIX A B --format=man C D --format=xhtml E
86
87              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
90       -o, --out=PREFIX
91              Specify the output file prefix.  mdoc assemble creates the files
92              PREFIX.zip and PREFIX.tree.
93
94       -h, -?, --help
95              Display a help message and exit.
96

FORMATS

98       The following documentation formats are supported:
99
100   ecma
101       The Mono ECMA Documentation Format, an XML  documentation  format  with
102       one file per type.
103
104       See the mdoc(5) man page for more information.
105
106   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
113   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
117       In this format, PATHS is a configuration file, containing the XML:
118
119           <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
127       The elements mean:
128
129       /ErrorProviderConfig/FilesPath
130              Specifies where to look for files.
131
132       /ErrorProviderConfig/Match
133              Specifies the filename pattern to look for  within  the  /Error‐
134              ProviderConfig/FilesPath directory.
135
136       /ErrorProviderConfig/ErrorNumSubstringStart
137              Specifies where within the filename the error number starts.
138
139       /ErrorProviderConfig/ErrorNumSubstringLength
140              Specifies  how many characters after /ErrorProviderConfig/Error‐
141              NumSubstringStart to use for the error number.
142
143       /ErrorProviderConfig/FriendlyFormatString
144              Specifies the formatting/display of the node in  the  monodoc(1)
145              tree.
146
147       For  each  file  found, it is converted to HTML with C# syntax coloring
148       applied.
149
150   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
156   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
161       PATHS is a set of XML files containing:
162
163         <?xml version="1.0"?>
164         <manpages>
165           <manpage name="NAME" page="FILE" />
166         </manpages>
167
168       There  may be multiple //manpage elements within the root /manpage ele‐
169       ment.
170
171       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
177       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
181   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

SEE ALSO

186       mdoc(1), mdoc(5), monodoc(1)
187

MAILING LISTS

189       Visit    http://lists.ximian.com/mailman/listinfo/mono-docs-list    for
190       details.
191

WEB SITE

193       See also: http://www.mono-project.com/docs/tools+libraries/tools/mdoc/
194
195
196
197                                                              mdoc-assemble(1)
Impressum