3 .\" (C) 2008 Jonathan Pryor
5 .\" Jonathan Pryor (jpryor@novell.com)
7 .de Sp \" Vertical space (when we can't use .PP)
13 mdoc \- Mono documentation management tool
17 [\fIoptions\fR] [\fIargs\fR]
19 \fImdoc\fR is an assembly-based documentation management system.
21 \fImdoc\fR permits creating and updating documentation \fIstubs\fR based on
22 the contents of an assembly. It does not rely on documentation found within
29 Good documentation is frequently (a) verbose, and (b)
30 filled with examples. (For comparison, compare Microsoft .NET Framework
31 documentation, which is often a page or more of docs for each member, to
32 JavaDoc documentation, which can often be a sentence for each member.)
34 Inserting good documentation into the source code can frequently bloat the
35 source file, as the documentation can be longer than the actual method that is
40 In-source documentation formats (such as \fIcsc /doc\fR)
41 have no support for multiple human languages. If you need to support more
42 than one human language for documentation purposes, \fImdoc\fR
43 is useful as it permits each language's output to reside in its own directory,
44 and \fImdoc\fR can add types/members for each separate documentation directory.
48 It's not unusual to have separate documentation and development teams. It's
49 also possible that the documentation team will have minimal experience with
50 the programming language being used. In such circumstances, inline
51 documentation is not desirable as the documentation team could inadvertantly
52 insert an error into the source code while updating the documentation.
53 Alternatively, you may not want the documentation team to have access to the
54 source code for security reasons. \fImdoc\fR allows the documentation to be
55 kept \fIcompletely\fR separate and distinct from the source code used to
58 Documentation can be generated using the \fBmdoc update\fR command:
61 mdoc update -o docs/en ProjectName.dll
64 Once the documentation stubs have been generated (and hopefully later filled
65 in with actual documentation), there are three ways to view the documentation:
68 To generate a simple directory of HTML pages (one HTML file per type), use
69 \fBmdoc export-html\fR:
72 mdoc export-html -o /srv/www/htdocs/ProjectName docs/en
77 To use an ASP.NET webapp to display the sources, see:
78 \fIhttp://anonsvn.mono-project.com/source/trunk/monodoc/engine/web/\fR.
80 From a \fImonodoc\fR source checkout, you can do this:
87 This will use \fBxsp\fR(1) to serve the ASP.NET webapp;
88 Visit \fIhttp://localhost:8080/\fR to view the documentation.
91 To use the \fBmonodoc\fR(1) documentation browser, you must first
92 \fIassemble\fR the documentation:
95 mdoc assemble -o ProjectName docs/en
98 The above command creates the files \fIProjectName.tree\fR and
99 \fIProjectName.zip\fR. An additional \fIProjectName.sources\fR file
100 must be provided which describes where in the help system the documentation
101 should be hooked up; it is a very simple XML file, like this:
104 <?xml version="1.0"?>
106 <source provider="ecma" basefile="ProjectName"
111 The above configuration file describes that the documentation is in
112 ECMA format, that the base file name is \fIProjectName\fR and that it
113 should be hooked up in the \fI"various"\fR part of the documentation tree.
114 If you want to look at the various nodes defined in the
115 documentation, you can look at the \fImonodoc.xml\fR file which is typically
116 installed in \fI/usr/lib/monodoc/monodoc.xml\fR.
118 Once you have all of the required files (.zip, .tree and .sources) you can
119 install them into the system with the following command:
122 cp ProjectName.tree ProjectName.zip ProjectName.source \\
123 `pkg-config monodoc --variable sourcesdir`
126 The above will copy the files into the directory that Monodoc has
127 registered; you might need root permissions to do this. The actual
128 directory is returned by the \fIpkg-config\fR invocation.
133 Compiles documentation for use within the \fBmonodoc\fR(1) browser.
135 See the \fBmdoc-assemble\fR(1) man page for details.
138 \fBmdoc export-html\fR
140 Exports documentation into a directory structure of HTML files.
142 See the \fBmdoc-export-html\fR(1) man page for details.
145 \fBmdoc export-msxdoc\fR
147 Exports documentation into the single-file
148 \fIMicrosoft XML Documentation\fR format.
150 See the \fBmdoc-export-msxdoc\fR(1) man page for details.
155 View internal help for a given command.
167 Multiple sub-commands may be listed at once:
170 mdoc help assemble export-html update validate
176 Updates documentation, adding and removing members based upon a reference
179 See the \fBmdoc-update\fR(1) man page for details.
184 Validates the documentation against the Mono documentation schema.
186 See the \fBmdoc-validate\fR(1) man page for details.
196 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
198 Visit http://www.mono-project.com/docs/tools+libraries/tools/mdoc/ for details