tools/monodoc/Test/man-test3.html

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11 <table width="100%" bgcolor="#b0c4da"><tr colspan="2"><td>Manual Pages</td></tr>
  12 <tr><td><h3>mdoc(1)</h3></td><td align="right"></td></tr></table>
  13 <h2>NAME</h2><blockquote>
  14 mdoc - Mono documentation management tool
  15 </blockquote><h2>SYNOPSIS</h2><blockquote>
  16 <b>mdoc</b>
  17 <i>command</i>
  18 [<i>options</i>] [<i>args</i>]
  19 </blockquote><h2>OVERVIEW</h2><blockquote>
  20 <i>mdoc</i> is an assembly-based documentation management system.
  21 <p>
  22 <i>mdoc</i> permits creating and updating documentation <i>stubs</i> based on
  23 the contents of an assembly.  It does not rely on documentation found within
  24 the source code.
  25 </p><p>
  26 The advantages are:
  27 </p><dl><dt>
  28 <i>*</i></dt><dd>
  29 <b>Code readability.</b>
  30 Good documentation is frequently (a) verbose, and (b)
  31 filled with examples.  (For comparison, compare Microsoft .NET Framework
  32 documentation, which is often a page or more of docs for each member, to
  33 JavaDoc documentation, which can often be a sentence for each member.)
  34 <p>
  35 Inserting good documentation into the source code can frequently bloat the
  36 source file, as the documentation can be longer than the actual method that is
  37 being documented.
  38 </p></dd><dt>
  39 <i>*</i></dt><dd>
  40 <b>Localization.</b>
  41 In-source documentation formats (such as <i>csc /doc</i>)
  42 have no support for multiple human languages.  If you need to support more
  43 than one human language for documentation purposes, <i>mdoc</i>
  44 is useful as it permits each language's output to reside in its own directory,
  45 and <i>mdoc</i> can add types/members for each separate documentation directory.
  46 </dd><dt>
  47 <i>*</i></dt><dd>
  48 <b>Administration.</b>
  49 It's not unusual to have separate documentation and development teams.  It's
  50 also possible that the documentation team will have minimal experience with
  51 the programming language being used.  In such circumstances, inline
  52 documentation is not desirable as the documentation team could inadvertantly
  53 insert an error into the source code while updating the documentation.
  54 Alternatively, you may not want the documentation team to have access to the
  55 source code for security reasons.  <i>mdoc</i> allows the documentation to be
  56 kept <i>completely</i> separate and distinct from the source code used to
  57 create the assembly.
  58 </dd></dl><p>
  59 Documentation can be generated using the <b>mdoc create</b>,
  60 <b>mdoc import-ecma</b>, <b>mdoc import-slashdoc</b>, and <b>mdoc update</b>
  61 commands:
  62
  63 </p><pre>
  64
  65     mdoc create -o docs/en ProjectName.dll
  66 </pre>
  67 <p>
  68 Once the documentation stubs have been generated (and hopefully later filled
  69 in with actual documentation), there are three ways to view the documentation:
  70 </p><dl><dt>
  71 <b>*</b></dt><dd>
  72 To generate a simple directory of HTML pages (one HTML file per type), use
  73 <b>mdoc export-html</b>:
  74
  75 <pre>
  76
  77     mdoc export-html -o /srv/www/htdocs/ProjectName docs/en
  78 </pre>
  79 </dd><dt>
  80 <b>*</b></dt><dd>
  81 To use an ASP.NET webapp to display the sources, see:
  82 <i>http://anonsvn.mono-project.com/source/trunk/monodoc/engine/web/</i>.
  83 </dd><dt>
  84 <b>*</b></dt><dd>
  85 To use the <b>monodoc</b>(1) documentation browser, you must first
  86 <i>assemble</i> the documentation:
  87
  88 <pre>
  89
  90     mdoc assemble -o ProjectName docs/en
  91 </pre>
  92
  93 The above command creates the files <i>ProjectName.tree</i> and
  94 <i>ProjectName.zip</i>.  An additional <i>ProjectName.sources</i> file
  95 must be provided which describes where in the help system the documentation
  96 should be hooked up; it is a very simple XML file, like this:
  97
  98 <pre>
  99
 100     &lt;?xml version="1.0"?&gt;
 101     &lt;monodoc&gt;
 102       &lt;source provider="ecma" basefile="ProjectName"
 103         path="various" /&gt;
 104     &lt;/monodoc&gt;
 105 </pre>
 106
 107 The above configuration file describes that the documentation is in
 108 ECMA format, that the base file name is <i>ProjectName</i> and that it
 109 should be hooked up in the <i>"various"</i> part of the documentation tree.
 110 If you want to look at the various nodes defined in the
 111 documentation, you can look at the <i>monodoc.xml</i> file which is typically
 112 installed in <i>/usr/lib/monodoc/monodoc.xml</i>.
 113 <p>
 114 Once you have all of the required files (.zip, .tree and .sources) you can
 115 install them into the system with the following command:
 116
 117 </p><pre>
 118
 119     cp ProjectName.tree ProjectName.zip ProjectName.source \
 120       `pkg-config monodoc --variable sourcesdir`
 121 </pre>
 122
 123 The above will copy the files into the directory that Monodoc has
 124 registered; you might need root permissions to do this.  The actual
 125 directory is returned by the <i>pkg-config</i> invocation.
 126 </dd></dl></blockquote><h2>MDOC COMMANDS</h2><blockquote>
 127 <p>
 128 <b>mdoc assemble</b>
 129 </p><blockquote>
 130 Compiles documentation for use within the <b>monodoc</b>(1) browser.
 131 <p>
 132 See the <b>mdoc-assemble</b>(1) man page for details.
 133 </p></blockquote>
 134 <p>
 135 <b>mdoc create</b>
 136 </p><blockquote>
 137 Alias for <b>mdoc update</b>.
 138 </blockquote>
 139 <p>
 140 <b>mdoc export-html</b>
 141 </p><blockquote>
 142 Exports documentation into a directory structure of HTML files.
 143 <p>
 144 See the <b>mdoc-export-html</b>(1) man page for details.
 145 </p></blockquote>
 146 <p>
 147 <b>mdoc export-slashdoc</b>
 148 </p><blockquote>
 149 Exports documentation into a single <i>csc /doc</i>-formatted XML file.
 150 <p>
 151 See the <b>mdoc-export-slashdoc</b>(1) man page for details.
 152 </p></blockquote>
 153 <p>
 154 <b>mdoc help</b>
 155 </p><blockquote>
 156 View internal help for a given command.
 157
 158 <pre>
 159
 160     mdoc help assemble
 161 </pre>
 162
 163 is equivalent to:
 164
 165 <pre>
 166
 167     mdoc assemble --help
 168 </pre>
 169
 170 Multiple sub-commands may be listed at once:
 171
 172 <pre>
 173
 174     mdoc help assemble create export-html
 175 </pre>
 176 </blockquote>
 177 <p>
 178 <b>mdoc import-ecma</b>
 179 </p><blockquote>
 180 Imports documentation from an ECMA-formatted documentation file.
 181 <p>
 182 See the <b>mdoc-import-ecma</b>(1) man page for details.
 183 </p></blockquote>
 184 <p>
 185 <b>mdoc import-slashdoc</b>
 186 </p><blockquote>
 187 Imports documentation from a <i>csc /doc</i>-formatted documentation file.
 188 <p>
 189 See the <b>mdoc-import-slashdoc</b>(1) man page for details.
 190 </p></blockquote>
 191 <p>
 192 <b>mdoc normalize</b>
 193 </p><blockquote>
 194 Normalizes documentation.
 195 <p>
 196 See the <b>mdoc-normalize</b>(1) man page for details.
 197 </p></blockquote>
 198 <p>
 199 <b>mdoc update</b>
 200 </p><blockquote>
 201 Updates documentation, adding and removing members based upon a reference
 202 assembly.
 203 <p>
 204 See the <b>mdoc-update</b>(1) man page for details.
 205 </p></blockquote>
 206 <p>
 207 <b>mdoc validate</b>
 208 </p><blockquote>
 209 Validates the documentation against the Mono documentation schema.
 210 <p>
 211 See the <b>mdoc-validate</b>(1) man page for details.
 212 </p></blockquote>
 213 </blockquote><h2>SEE ALSO</h2><blockquote>
 214 mdoc-assemble(1), mdoc-export-html(1), mdoc-update(1),
 215 mdoc-validate(1), mdoc(5)
 216 </blockquote><h2>MAILING LISTS</h2><blockquote>
 217 <dl><dt>
 218 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.</dt><dd>
 219 </dd></dl></blockquote><h2>WEB SITE</h2><blockquote>
 220 Visit http://www.mono-project.com/mdoc for details
 221