check for iconv only once (#7873)
[mono-project.git] / man / mdoc.1
blob620c45aaf024d223a215aa93141d1df93453ee1a
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
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
61     mdoc update -o docs/en ProjectName.dll
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
72     mdoc export-html -o /srv/www/htdocs/ProjectName docs/en
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
83     cd engine
84     make web
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
95     mdoc assemble -o ProjectName docs/en
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:
104     <?xml version="1.0"?>
105     <monodoc>
106       <source provider="ecma" basefile="ProjectName"
107         path="various" />
108     </monodoc>
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.
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:
122     cp ProjectName.tree ProjectName.zip ProjectName.source \\
123       `pkg-config monodoc --variable sourcesdir`
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
131 \fBmdoc assemble\fR
132 .RS 4
133 Compiles documentation for use within the \fBmonodoc\fR(1) browser.
135 See the \fBmdoc-assemble\fR(1) man page for details.
138 \fBmdoc export-html\fR
139 .RS 4
140 Exports documentation into a directory structure of HTML files.
142 See the \fBmdoc-export-html\fR(1) man page for details.
145 \fBmdoc export-msxdoc\fR
146 .RS 4
147 Exports documentation into the single-file 
148 \fIMicrosoft XML Documentation\fR format.
150 See the \fBmdoc-export-msxdoc\fR(1) man page for details.
153 \fBmdoc help\fR
154 .RS 4
155 View internal help for a given command.
158     mdoc help assemble
161 is equivalent to:
164     mdoc assemble --help
167 Multiple sub-commands may be listed at once:
170     mdoc help assemble export-html update validate
174 \fBmdoc update\fR
175 .RS 4
176 Updates documentation, adding and removing members based upon a reference
177 assembly.
179 See the \fBmdoc-update\fR(1) man page for details.
182 \fBmdoc validate\fR
183 .RS 4
184 Validates the documentation against the Mono documentation schema.
186 See the \fBmdoc-validate\fR(1) man page for details.
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
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