man/mdoc.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 .B *
  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 .B *
  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 .B *
  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 update\fR command:
  59 .nf
  60
  61     mdoc update -o docs/en ProjectName.dll
  62
  63 .fi
  64 Once the documentation stubs have been generated (and hopefully later filled
  65 in with actual documentation), there are three ways to view the documentation:
  66 .TP
  67 .B *
  68 To generate a simple directory of HTML pages (one HTML file per type), use
  69 \fBmdoc export-html\fR:
  70 .nf
  71
  72     mdoc export-html -o /srv/www/htdocs/ProjectName docs/en
  73
  74 .fi
  75 .TP
  76 .B *
  77 To use an ASP.NET webapp to display the sources, see:
  78 \fIhttp://anonsvn.mono-project.com/source/trunk/monodoc/engine/web/\fR.
  79 .Sp
  80 From a \fImonodoc\fR source checkout, you can do this:
  81 .nf
  82
  83     cd engine
  84     make web
  85
  86 .fi
  87 This will use \fBxsp\fR(1) to serve the ASP.NET webapp;
  88 Visit \fIhttp://localhost:8080/\fR to view the documentation.
  89 .TP
  90 .B *
  91 To use the \fBmonodoc\fR(1) documentation browser, you must first
  92 \fIassemble\fR the documentation:
  93 .nf
  94
  95     mdoc assemble -o ProjectName docs/en
  96
  97 .fi
  98 The above command creates the files \fIProjectName.tree\fR and
  99 \fIProjectName.zip\fR.  An additional \fIProjectName.sources\fR file
 100 must be provided which describes where in the help system the documentation
 101 should be hooked up; it is a very simple XML file, like this:
 102 .nf
 103
 104     <?xml version="1.0"?>
 105     <monodoc>
 106       <source provider="ecma" basefile="ProjectName"
 107         path="various" />
 108     </monodoc>
 109
 110 .fi
 111 The above configuration file describes that the documentation is in
 112 ECMA format, that the base file name is \fIProjectName\fR and that it
 113 should be hooked up in the \fI"various"\fR part of the documentation tree.
 114 If you want to look at the various nodes defined in the
 115 documentation, you can look at the \fImonodoc.xml\fR file which is typically
 116 installed in \fI/usr/lib/monodoc/monodoc.xml\fR.
 117 .Sp
 118 Once you have all of the required files (.zip, .tree and .sources) you can
 119 install them into the system with the following command:
 120 .nf
 121
 122     cp ProjectName.tree ProjectName.zip ProjectName.source \\
 123       `pkg-config monodoc --variable sourcesdir`
 124
 125 .fi
 126 The above will copy the files into the directory that Monodoc has
 127 registered; you might need root permissions to do this.  The actual
 128 directory is returned by the \fIpkg-config\fR invocation.
 129 .SH MDOC COMMANDS
 130 .PP
 131 \fBmdoc assemble\fR
 132 .RS 4
 133 Compiles documentation for use within the \fBmonodoc\fR(1) browser.
 134 .PP
 135 See the \fBmdoc-assemble\fR(1) man page for details.
 136 .RE
 137 .PP
 138 \fBmdoc export-html\fR
 139 .RS 4
 140 Exports documentation into a directory structure of HTML files.
 141 .PP
 142 See the \fBmdoc-export-html\fR(1) man page for details.
 143 .RE
 144 .PP
 145 \fBmdoc export-msxdoc\fR
 146 .RS 4
 147 Exports documentation into the single-file
 148 \fIMicrosoft XML Documentation\fR format.
 149 .PP
 150 See the \fBmdoc-export-msxdoc\fR(1) man page for details.
 151 .RE
 152 .PP
 153 \fBmdoc help\fR
 154 .RS 4
 155 View internal help for a given command.
 156
 157 .nf
 158     mdoc help assemble
 159 .fi
 160
 161 is equivalent to:
 162
 163 .nf
 164     mdoc assemble --help
 165 .fi
 166
 167 Multiple sub-commands may be listed at once:
 168
 169 .nf
 170     mdoc help assemble export-html update validate
 171 .fi
 172 .RE
 173 .PP
 174 \fBmdoc update\fR
 175 .RS 4
 176 Updates documentation, adding and removing members based upon a reference
 177 assembly.
 178 .PP
 179 See the \fBmdoc-update\fR(1) man page for details.
 180 .RE
 181 .PP
 182 \fBmdoc validate\fR
 183 .RS 4
 184 Validates the documentation against the Mono documentation schema.
 185 .PP
 186 See the \fBmdoc-validate\fR(1) man page for details.
 187 .RE
 188 .SH SEE ALSO
 189 mdoc(5),
 190 mdoc-assemble(1),
 191 mdoc-export-html(1),
 192 mdoc-update(1),
 193 mdoc-validate(1)
 194 .SH MAILING LISTS
 195 .TP
 196 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
 197 .SH WEB SITE
 198 Visit http://www.mono-project.com/docs/tools+libraries/tools/mdoc/ for details