--- /dev/null
+.\"
+.\" mdoc manual page.
+.\" (C) 2008 Jonathan Pryor
+.\" Author:
+.\" Jonathan Pryor (jpryor@novell.com)
+.\"
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.TH "mdoc" 1
+.SH NAME
+mdoc \- Mono documentation management tool
+.SH SYNOPSIS
+.B mdoc
+.I command
+[\fIoptions\fR] [\fIargs\fR]
+.SH OVERVIEW
+\fImdoc\fR is an assembly-based documentation management system.
+.PP
+\fImdoc\fR permits creating and updating documentation \fIstubs\fR based on
+the contents of an assembly. It does not rely on documentation found within
+the source code.
+.PP
+The advantages are:
+.TP
+.B *
+.B Code readability.
+Good documentation is frequently (a) verbose, and (b)
+filled with examples. (For comparison, compare Microsoft .NET Framework
+documentation, which is often a page or more of docs for each member, to
+JavaDoc documentation, which can often be a sentence for each member.)
+.Sp
+Inserting good documentation into the source code can frequently bloat the
+source file, as the documentation can be longer than the actual method that is
+being documented.
+.TP
+.B *
+.B Localization.
+In-source documentation formats (such as \fIcsc /doc\fR)
+have no support for multiple human languages. If you need to support more
+than one human language for documentation purposes, \fImdoc\fR
+is useful as it permits each language's output to reside in its own directory,
+and \fImdoc\fR can add types/members for each separate documentation directory.
+.TP
+.B *
+.B Administration.
+It's not unusual to have separate documentation and development teams. It's
+also possible that the documentation team will have minimal experience with
+the programming language being used. In such circumstances, inline
+documentation is not desirable as the documentation team could inadvertantly
+insert an error into the source code while updating the documentation.
+Alternatively, you may not want the documentation team to have access to the
+source code for security reasons. \fImdoc\fR allows the documentation to be
+kept \fIcompletely\fR separate and distinct from the source code used to
+create the assembly.
+.PP
+Documentation can be generated using the \fBmdoc update\fR command:
+.nf
+
+ mdoc update -o docs/en ProjectName.dll
+
+.fi
+Once the documentation stubs have been generated (and hopefully later filled
+in with actual documentation), there are three ways to view the documentation:
+.TP
+.B *
+To generate a simple directory of HTML pages (one HTML file per type), use
+\fBmdoc export-html\fR:
+.nf
+
+ mdoc export-html -o /srv/www/htdocs/ProjectName docs/en
+
+.fi
+.TP
+.B *
+To use an ASP.NET webapp to display the sources, see:
+\fIhttp://anonsvn.mono-project.com/source/trunk/monodoc/engine/web/\fR.
+.Sp
+From a \fImonodoc\fR source checkout, you can do this:
+.nf
+
+ cd engine
+ make web
+
+.fi
+This will use \fBxsp\fR(1) to serve the ASP.NET webapp;
+Visit \fIhttp://localhost:8080/\fR to view the documentation.
+.TP
+.B *
+To use the \fBmonodoc\fR(1) documentation browser, you must first
+\fIassemble\fR the documentation:
+.nf
+
+ mdoc assemble -o ProjectName docs/en
+
+.fi
+The above command creates the files \fIProjectName.tree\fR and
+\fIProjectName.zip\fR. An additional \fIProjectName.sources\fR file
+must be provided which describes where in the help system the documentation
+should be hooked up; it is a very simple XML file, like this:
+.nf
+
+ <?xml version="1.0"?>
+ <monodoc>
+ <source provider="ecma" basefile="ProjectName"
+ path="various" />
+ </monodoc>
+
+.fi
+The above configuration file describes that the documentation is in
+ECMA format, that the base file name is \fIProjectName\fR and that it
+should be hooked up in the \fI"various"\fR part of the documentation tree.
+If you want to look at the various nodes defined in the
+documentation, you can look at the \fImonodoc.xml\fR file which is typically
+installed in \fI/usr/lib/monodoc/monodoc.xml\fR.
+.Sp
+Once you have all of the required files (.zip, .tree and .sources) you can
+install them into the system with the following command:
+.nf
+
+ cp ProjectName.tree ProjectName.zip ProjectName.source \\
+ `pkg-config monodoc --variable sourcesdir`
+
+.fi
+The above will copy the files into the directory that Monodoc has
+registered; you might need root permissions to do this. The actual
+directory is returned by the \fIpkg-config\fR invocation.
+.SH MDOC COMMANDS
+.PP
+\fBmdoc assemble\fR
+.RS 4
+Compiles documentation for use within the \fBmonodoc\fR(1) browser.
+.PP
+See the \fBmdoc-assemble\fR(1) man page for details.
+.RE
+.PP
+\fBmdoc export-html\fR
+.RS 4
+Exports documentation into a directory structure of HTML files.
+.PP
+See the \fBmdoc-export-html\fR(1) man page for details.
+.RE
+.PP
+\fBmdoc export-msxdoc\fR
+.RS 4
+Exports documentation into the single-file
+\fIMicrosoft XML Documentation\fR format.
+.PP
+See the \fBmdoc-export-msxdoc\fR(1) man page for details.
+.RE
+.PP
+\fBmdoc help\fR
+.RS 4
+View internal help for a given command.
+
+.nf
+ mdoc help assemble
+.fi
+
+is equivalent to:
+
+.nf
+ mdoc assemble --help
+.fi
+
+Multiple sub-commands may be listed at once:
+
+.nf
+ mdoc help assemble export-html update validate
+.fi
+.RE
+.PP
+\fBmdoc update\fR
+.RS 4
+Updates documentation, adding and removing members based upon a reference
+assembly.
+.PP
+See the \fBmdoc-update\fR(1) man page for details.
+.RE
+.PP
+\fBmdoc validate\fR
+.RS 4
+Validates the documentation against the Mono documentation schema.
+.PP
+See the \fBmdoc-validate\fR(1) man page for details.
+.RE
+.SH SEE ALSO
+mdoc(5),
+mdoc-assemble(1),
+mdoc-export-html(1),
+mdoc-update(1),
+mdoc-validate(1)
+.SH MAILING LISTS
+.TP
+Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
+.SH WEB SITE
+Visit http://www.mono-project.com/mdoc for details
projects / mono.git / commitdiff