man/mdassembler.1

   1 .\"
   2 .\" mdassembler manual page.
   3 .\" (C) 2006 Jonathan Pryor
   4 .\" Author:
   5 .\"   Jonathan Pryor (jonpryor@vt.edu)
   6 .\"
   7 .de Sp \" Vertical space (when we can't use .PP)
   8 .if t .sp .5v
   9 .if n .sp
  10 ..
  11 .TH "mdassembler" 1
  12 .SH NAME
  13 mdassembler \- Compile documentation for use in monodoc browser
  14 .SH SYNOPSIS
  15 .B mdassembler
  16 OPTIONS*
  17 DIRS+
  18 .SH DESCRIPTION
  19 \fImdassembler\fR has been obsoleted by \fBmdoc\fR(1).  See the
  20 \fBmdoc-assemble\fR(1) man page.
  21 .PP
  22 .I mdassembler
  23 is a program that creates
  24 .I .tree
  25 and
  26 .I .zip
  27 files for use in the
  28 .B monodoc
  29 documentation browser.
  30 .PP
  31 The
  32 .I .tree
  33 and
  34 .I .zip
  35 files are copied into monodoc's
  36 .I sources
  37 directory, and reside with a
  38 .I .source
  39 file which is used by
  40 .B monodoc
  41 to specify where the documentation should be displayed.
  42 The
  43 .I .source
  44 file's
  45 .I /monodoc/source/@basefile
  46 attribute specifies the filename prefix for the documentation files.  This
  47 must be the same prefix as used with the
  48 .B \-\-out
  49 parameter.
  50 .PP
  51 .SH OPTIONS
  52 .TP
  53 .I \-\-ecma
  54 The documentation found within
  55 .I DIRS
  56 is in the Mono ECMA documentation format.
  57 See the
  58 .B Mono ECMA Documentation Format
  59 section below.
  60 .TP
  61 .I \-\-ecmaspec
  62 The documentation found within
  63 .I DIRS
  64 is in the ECMA Specification documentation format.
  65 See the
  66 .B Mono ECMA Specification Documentation Format
  67 section below.
  68 .TP
  69 .I \-\-error
  70 The documentation found within
  71 .I DIRS
  72 is in "error" format.
  73 See the
  74 .B Error Documentation Format
  75 section below.
  76 .TP
  77 .I \-\-help
  78 Show program argument information.
  79 .TP
  80 .I \-\-man
  81 The documentation found within
  82 .I DIRS
  83 is in man page format.
  84 See the
  85 .B Man Page Documentation Format
  86 section below.
  87 .TP
  88 .I \-o, \-\-out PREFIX
  89 Specify the output file prefix.
  90 .B mdassembler
  91 creates the files
  92 .I PREFIX.zip
  93 and
  94 .I PREFIX.tree
  95 \&.
  96 .TP
  97 .I \-\-simple
  98 The documentation found within
  99 .I DIRS
 100 is in "simple" format.
 101 See the
 102 .B Simple Documentation Format
 103 section below.
 104 .TP
 105 .I \-\-xhtml, \-\-hb
 106 The documentation found within
 107 .I DIRS
 108 is in XHTML format.
 109 See the
 110 .B XHTML Documentation Format
 111 section below.
 112 .PP
 113 .SH "FORMATS"
 114 The following documentation formats are supported:
 115 .SS Mono ECMA Documentation Format
 116 An XML documentation format with one file per type.
 117 .PP
 118 See the \fBmdoc\fR(5) man page for more information.
 119 .SS Mono ECMA Specification Documentation Format
 120 This is not the format you're looking for.
 121 .PP
 122 This is the format used to represent the ECMA-334 (C#) standard within
 123 \fBmonodoc\fR.  It is not used to display class library documentation;
 124 for class library
 125 documentation, use the
 126 .B \-\-ecma
 127 format.
 128 .SS Error Documentation Format
 129 Used to present detailed error messages, and is used in
 130 \fBmonodoc\fR's "C# Compiler Error Reference"
 131 tree.
 132 .I DIRS
 133 is not a directory, but is instead a configuration file, containing the XML:
 134
 135 .nf
 136     <ErrorProviderConfig>
 137         <FilesPath>../../mcs/errors</FilesPath>
 138         <Match>cs????*.cs</Match>
 139         <ErrorNumSubstringStart>2</ErrorNumSubstringStart>
 140         <ErrorNumSubstringLength>4</ErrorNumSubstringLength>
 141         <FriendlyFormatString>CS{0:0###}</FriendlyFormatString>
 142     </ErrorProviderConfig>
 143 .fi
 144
 145 .I /ErrorProviderConfig/FilesPath
 146 specifies where to look for files,
 147 .I /ErrorProviderConfig/Match
 148 specifies the filename pattern to look for within
 149 \fI/ErrorProviderConfig/FilesPath\fR,
 150 .I /ErrorProviderConfig/ErrorNumSubstringStart
 151 and
 152 .I /ErrorProviderConfig/ErrorNumSubstringLength
 153 control which portion of the filename is used as the error number, and
 154 .I /ErrorProviderConfig/FriendlyFormatString
 155 controls how the formatting/display of the node in the
 156 .B monodoc
 157 tree.
 158 .PP
 159 For each file found, it is converted to HTML with C# syntax coloring applied.
 160 .SS Simple Documentation Format
 161 Converts text files into HTML by translating each newline into an HTML
 162 .I <br>
 163 element.
 164 .SS Man Page Documentation Format
 165 Converts man pages into HTML for display.
 166 .SS XHTML Documentation Format
 167 Copies the XHTML file as-is.
 168 .SH EXAMPLES
 169 To install your documenation for use with monodoc:
 170 .TP
 171 .I Create a PREFIX.source file
 172 with the contents:
 173 .nf
 174
 175 <?xml version="1.0"?>
 176 <monodoc>
 177   <source provider="FORMAT" basefile="PREFIX" path="PATH"/>
 178 </monodoc>
 179
 180 .fi
 181 where FORMAT is the documentation format contained within the
 182 .I PREFIX.tree
 183 file, e.g.
 184 \fIecma\fR, or \fIsimple\fR.
 185 .I PREFIX is the basename of the
 186 .I .tree
 187 and
 188 .I .zip
 189 files that
 190 .B mdassembler
 191 creates.
 192 .I PATH
 193 is the "path" in the monodoc tree that should contain the documentation.
 194 See the
 195 .I @prefix@/lib/monodoc/monodoc.xml
 196 file for a list of PATH values
 197 (the
 198 .I //node/@name
 199 values).
 200 .sp
 201 See also: http://www.mono-project.com/docs/tools+libraries/tools/monodoc/generating-documentation/
 202 .TP
 203 .I Create your documentation
 204 See also the
 205 .BR monodocer (1)
 206 man page, e.g.
 207 .nf
 208
 209         monodocer -assembly:foo.dll -path:foo/en
 210
 211 .fi
 212 .TP
 213 .I Assemble the documentation
 214 .nf
 215
 216         mdassembler --ecma foo/en PREFIX
 217
 218 .fi
 219 Make sure that you use the same
 220 .I PREFIX
 221 here as you did above.
 222 .TP
 223 .I Install the documentation by using the command
 224 .nf
 225
 226         cp PREFIX.source PREFIX.tree PREFIX.zip \\
 227         `pkg-config monodoc --variable=sourcesdir`
 228
 229 .fi
 230 (Note the backticks used in the
 231 .B pkg-config
 232 command!)
 233 This copies the
 234 .I .source
 235 ,
 236 .I .tree
 237 , and
 238 .I .zip
 239 files into the
 240 .B monodoc
 241 .I sources
 242 directory, which will allow
 243 .B monodoc
 244 to display the documentation.
 245 .SH SEE ALSO
 246 \fBmdcs2ecma\fR(1),
 247 \fBmdnormalizer\fR(1),
 248 \fBmdoc\fR(1),
 249 \fBmdoc-assemble\fR(1),
 250 \fBmdvalidator\fR(1),
 251 \fBmonodocer\fR(1),
 252 \fBmonodocs2html\fR(1)
 253 .SH MAILING LISTS
 254 .TP
 255 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
 256 .SH WEB SITE
 257 See also: http://www.mono-project.com
 258 and
 259 http://www.mono-project.com/docs/tools+libraries/tools/mdassembler/