tools/monodoc/Test/man-test3.1

   1 .\"
   2 .\" mdoc manual page.
   3 .\" (C) 2008 Jonathan Pryor
   4 .\" Author:
   5 .\"   Jonathan Pryor (jpryor@novell.com)
   6 .\"
   7 .de Sp \" Vertical space (when we can't use .PP)
   8 .if t .sp .5v
   9 .if n .sp
  10 ..
  11 .TH "mdoc" 1
  12 .SH NAME
  13 mdoc \- Mono documentation management tool
  14 .SH SYNOPSIS
  15 .B mdoc
  16 .I command
  17 [\fIoptions\fR] [\fIargs\fR]
  18 .SH OVERVIEW
  19 \fImdoc\fR is an assembly-based documentation management system.
  20 .PP
  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
  23 the source code.
  24 .PP
  25 The advantages are:
  26 .TP
  27 .I *
  28 .B Code readability.
  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.)
  33 .Sp
  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
  36 being documented.
  37 .TP
  38 .I *
  39 .B Localization.
  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.
  45 .TP
  46 .I *
  47 .B Administration.
  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
  56 create the assembly.
  57 .PP
  58 Documentation can be generated using the \fBmdoc create\fR,
  59 \fBmdoc import-ecma\fR, \fBmdoc import-slashdoc\fR, and \fBmdoc update\fR
  60 commands:
  61
  62 .nf
  63     mdoc create -o docs/en ProjectName.dll
  64 .fi
  65 .PP
  66 Once the documentation stubs have been generated (and hopefully later filled
  67 in with actual documentation), there are three ways to view the documentation:
  68 .TP
  69 .B *
  70 To generate a simple directory of HTML pages (one HTML file per type), use
  71 \fBmdoc export-html\fR:
  72
  73 .nf
  74     mdoc export-html -o /srv/www/htdocs/ProjectName docs/en
  75 .fi
  76 .TP
  77 .B *
  78 To use an ASP.NET webapp to display the sources, see:
  79 \fIhttp://anonsvn.mono-project.com/source/trunk/monodoc/engine/web/\fR.
  80 .TP
  81 .B *
  82 To use the \fBmonodoc\fR(1) documentation browser, you must first
  83 \fIassemble\fR the documentation:
  84
  85 .nf
  86     mdoc assemble -o ProjectName docs/en
  87 .fi
  88
  89 The above command creates the files \fIProjectName.tree\fR and
  90 \fIProjectName.zip\fR.  An additional \fIProjectName.sources\fR file
  91 must be provided which describes where in the help system the documentation
  92 should be hooked up; it is a very simple XML file, like this:
  93
  94 .nf
  95     <?xml version="1.0"?>
  96     <monodoc>
  97       <source provider="ecma" basefile="ProjectName"
  98         path="various" />
  99     </monodoc>
 100 .fi
 101
 102 The above configuration file describes that the documentation is in
 103 ECMA format, that the base file name is \fIProjectName\fR and that it
 104 should be hooked up in the \fI"various"\fR part of the documentation tree.
 105 If you want to look at the various nodes defined in the
 106 documentation, you can look at the \fImonodoc.xml\fR file which is typically
 107 installed in \fI/usr/lib/monodoc/monodoc.xml\fR.
 108 .Sp
 109 Once you have all of the required files (.zip, .tree and .sources) you can
 110 install them into the system with the following command:
 111
 112 .nf
 113     cp ProjectName.tree ProjectName.zip ProjectName.source \\
 114       `pkg-config monodoc --variable sourcesdir`
 115 .fi
 116
 117 The above will copy the files into the directory that Monodoc has
 118 registered; you might need root permissions to do this.  The actual
 119 directory is returned by the \fIpkg-config\fR invocation.
 120 .SH MDOC COMMANDS
 121 .PP
 122 \fBmdoc assemble\fR
 123 .RS 4
 124 Compiles documentation for use within the \fBmonodoc\fR(1) browser.
 125 .PP
 126 See the \fBmdoc-assemble\fR(1) man page for details.
 127 .RE
 128 .PP
 129 \fBmdoc create\fR
 130 .RS 4
 131 Alias for \fBmdoc update\fR.
 132 .RE
 133 .PP
 134 \fBmdoc export-html\fR
 135 .RS 4
 136 Exports documentation into a directory structure of HTML files.
 137 .PP
 138 See the \fBmdoc-export-html\fR(1) man page for details.
 139 .RE
 140 .PP
 141 \fBmdoc export-slashdoc\fR
 142 .RS 4
 143 Exports documentation into a single \fIcsc /doc\fR-formatted XML file.
 144 .PP
 145 See the \fBmdoc-export-slashdoc\fR(1) man page for details.
 146 .RE
 147 .PP
 148 \fBmdoc help\fR
 149 .RS 4
 150 View internal help for a given command.
 151
 152 .nf
 153     mdoc help assemble
 154 .fi
 155
 156 is equivalent to:
 157
 158 .nf
 159     mdoc assemble --help
 160 .fi
 161
 162 Multiple sub-commands may be listed at once:
 163
 164 .nf
 165     mdoc help assemble create export-html
 166 .fi
 167 .RE
 168 .PP
 169 \fBmdoc import-ecma\fR
 170 .RS 4
 171 Imports documentation from an ECMA-formatted documentation file.
 172 .PP
 173 See the \fBmdoc-import-ecma\fR(1) man page for details.
 174 .RE
 175 .PP
 176 \fBmdoc import-slashdoc\fR
 177 .RS 4
 178 Imports documentation from a \fIcsc /doc\fR-formatted documentation file.
 179 .PP
 180 See the \fBmdoc-import-slashdoc\fR(1) man page for details.
 181 .RE
 182 .PP
 183 \fBmdoc normalize\fR
 184 .RS 4
 185 Normalizes documentation.
 186 .PP
 187 See the \fBmdoc-normalize\fR(1) man page for details.
 188 .RE
 189 .PP
 190 \fBmdoc update\fR
 191 .RS 4
 192 Updates documentation, adding and removing members based upon a reference
 193 assembly.
 194 .PP
 195 See the \fBmdoc-update\fR(1) man page for details.
 196 .RE
 197 .PP
 198 \fBmdoc validate\fR
 199 .RS 4
 200 Validates the documentation against the Mono documentation schema.
 201 .PP
 202 See the \fBmdoc-validate\fR(1) man page for details.
 203 .RE
 204 .SH SEE ALSO
 205 mdoc-assemble(1), mdoc-export-html(1), mdoc-update(1),
 206 mdoc-validate(1), mdoc(5)
 207 .SH MAILING LISTS
 208 .TP
 209 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
 210 .SH WEB SITE
 211 Visit http://www.mono-project.com/mdoc for details