1mdoc(1)                     General Commands Manual                    mdoc(1)
2
3
4

NAME

6       mdoc - Mono documentation management tool
7

SYNOPSIS

9       mdoc command [options] [args]
10

OVERVIEW

12       mdoc is an assembly-based documentation management system.
13
14       mdoc  permits  creating  and  updating documentation stubs based on the
15       contents of an assembly.  It  does  not  rely  on  documentation  found
16       within the source code.
17
18       The advantages are:
19
20       *      Code readability.  Good documentation is frequently (a) verbose,
21              and (b) filled with examples.  (For comparison,  compare  Micro‐
22              soft .NET Framework documentation, which is often a page or more
23              of docs for each member, to  JavaDoc  documentation,  which  can
24              often be a sentence for each member.)
25
26              Inserting good documentation into the source code can frequently
27              bloat the source file, as the documentation can be  longer  than
28              the actual method that is being documented.
29
30       *      Localization.   In-source  documentation  formats  (such  as csc
31              /doc) have no support for multiple human languages.  If you need
32              to  support  more than one human language for documentation pur‐
33              poses, mdoc is useful as it permits each  language's  output  to
34              reside  in its own directory, and mdoc can add types/members for
35              each separate documentation directory.
36
37       *      Administration.  It's not unusual to have separate documentation
38              and  development  teams.  It's also possible that the documenta‐
39              tion team will have minimal experience with the programming lan‐
40              guage  being  used.  In such circumstances, inline documentation
41              is not desirable as the documentation team  could  inadvertantly
42              insert an error into the source code while updating the documen‐
43              tation.  Alternatively, you may not want the documentation  team
44              to  have  access  to the source code for security reasons.  mdoc
45              allows the documentation to be kept completely separate and dis‐
46              tinct from the source code used to create the assembly.
47
48       Documentation can be generated using the mdoc update command:
49
50           mdoc update -o docs/en ProjectName.dll
51
52       Once  the  documentation stubs have been generated (and hopefully later
53       filled in with actual documentation), there are three ways to view  the
54       documentation:
55
56       *      To  generate a simple directory of HTML pages (one HTML file per
57              type), use mdoc export-html:
58
59                  mdoc export-html -o /srv/www/htdocs/ProjectName docs/en
60
61
62       *      To  use  an  ASP.NET  webapp  to  display  the   sources,   see:
63              http://anonsvn.mono-project.com/source/trunk/mon
64              odoc/engine/web/.
65
66              From a monodoc source checkout, you can do this:
67
68                  cd engine
69                  make web
70
71              This  will  use  xsp(1)  to  serve  the  ASP.NET  webapp;  Visit
72              http://localhost:8080/ to view the documentation.
73
74       *      To  use  the  monodoc(1)  documentation  browser, you must first
75              assemble the documentation:
76
77                  mdoc assemble -o ProjectName docs/en
78
79              The above command creates the files  ProjectName.tree  and  Pro‐
80              jectName.zip.   An  additional  ProjectName.sources file must be
81              provided which describes where in the help system the documenta‐
82              tion  should  be  hooked  up; it is a very simple XML file, like
83              this:
84
85                  <?xml version="1.0"?>
86                  <monodoc>
87                    <source provider="ecma" basefile="ProjectName"
88                      path="various" />
89                  </monodoc>
90
91              The above configuration file describes that the documentation is
92              in  ECMA format, that the base file name is ProjectName and that
93              it should be hooked up in the "various" part of  the  documenta‐
94              tion  tree.  If you want to look at the various nodes defined in
95              the documentation, you can look at the monodoc.xml file which is
96              typically installed in /usr/lib/monodoc/monodoc.xml.
97
98              Once  you  have  all  of  the  required  files  (.zip, .tree and
99              .sources) you can install them into the system with the  follow‐
100              ing command:
101
102                  cp ProjectName.tree ProjectName.zip ProjectName.source \
103                    `pkg-config monodoc --variable sourcesdir`
104
105              The  above  will  copy the files into the directory that Monodoc
106              has registered; you might need root permissions to do this.  The
107              actual directory is returned by the pkg-config invocation.
108

MDOC COMMANDS

110       mdoc assemble
111           Compiles documentation for use within the monodoc(1) browser.
112
113           See the mdoc-assemble(1) man page for details.
114
115       mdoc export-html
116           Exports documentation into a directory structure of HTML files.
117
118           See the mdoc-export-html(1) man page for details.
119
120       mdoc export-msxdoc
121           Exports documentation into the single-file Microsoft XML Documenta‐
122           tion format.
123
124           See the mdoc-export-msxdoc(1) man page for details.
125
126       mdoc help
127           View internal help for a given command.
128
129               mdoc help assemble
130
131           is equivalent to:
132
133               mdoc assemble --help
134
135           Multiple sub-commands may be listed at once:
136
137               mdoc help assemble export-html update validate
138
139       mdoc update
140           Updates documentation, adding and removing  members  based  upon  a
141           reference assembly.
142
143           See the mdoc-update(1) man page for details.
144
145       mdoc validate
146           Validates the documentation against the Mono documentation schema.
147
148           See the mdoc-validate(1) man page for details.
149

SEE ALSO

151       mdoc(5),  mdoc-assemble(1),  mdoc-export-html(1), mdoc-update(1), mdoc-
152       validate(1)
153

MAILING LISTS

155       Visit    http://lists.ximian.com/mailman/listinfo/mono-docs-list    for
156       details.
157

WEB SITE

159       Visit http://www.mono-project.com/mdoc for details
160
161
162
163                                                                       mdoc(1)
Impressum