199 строки
5.6 KiB
Groff
199 строки
5.6 KiB
Groff
.\"
|
|
.\" 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/docs/tools+libraries/tools/mdoc/ for details
|