From: Jonathan Pryor Date: Fri, 17 Oct 2008 18:21:07 +0000 (-0000) Subject: Migrating from monodoc/man to mono/man... X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=commitdiff_plain;h=18932bb171989deb9a3cc396fda1caaf24824504;p=mono.git Migrating from monodoc/man to mono/man... svn path=/trunk/mono/; revision=116272 --- diff --git a/man/mdoc.1 b/man/mdoc.1 new file mode 100644 index 00000000000..dd2ecace4bd --- /dev/null +++ b/man/mdoc.1 @@ -0,0 +1,198 @@ +.\" +.\" 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 + + + + + + +.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