diff options
author | Jonathan Pryor <jpryor@novell.com> | 2008-10-17 22:21:13 +0400 |
---|---|---|
committer | Jonathan Pryor <jpryor@novell.com> | 2008-10-17 22:21:13 +0400 |
commit | 01c9d58963c07d7a8b9880950a04e4a0001cb6e1 (patch) | |
tree | 74f4dd687e0bb51d918b9a3bafed22fa77395050 /man/mdoc-assemble.1 | |
parent | 18932bb171989deb9a3cc396fda1caaf24824504 (diff) |
Migrating from monodoc/man to mono/man...
svn path=/trunk/mono/; revision=116273
Diffstat (limited to 'man/mdoc-assemble.1')
-rw-r--r-- | man/mdoc-assemble.1 | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/man/mdoc-assemble.1 b/man/mdoc-assemble.1 new file mode 100644 index 00000000000..0331007106f --- /dev/null +++ b/man/mdoc-assemble.1 @@ -0,0 +1,190 @@ +.\" +.\" mdoc assemble manual page. +.\" (C) 2008 Novell, Inc. +.\" Author: +.\" Jonathan Pryor (jpryor@novell.com) +.\" +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.TH "mdoc-assemble" 1 +.SH NAME +mdoc assemble \- Compile documentation for use in \fBmonodoc\fR(1) +.SH SYNOPSIS +.B mdoc assemble +[OPTIONS]+ +PATHS+ +.SH DESCRIPTION +\fBmdoc assemble\fR creates \fI.tree\fR and \fI.zip\fR files from \fIPATHS\fR +for use in the \fBmonodoc\fR(1) documentation browser. +.PP +The input files must have a supported \fIformat\fR, specified with the +\fI--format\fR option. +.PP +The \fI.tree\fR and \fI.zip\fR files are copied into \fBmonodoc\fR's +\fIsources\fR directory, alongside a \fI.source\fR file which is used by +\fBmonodoc\fR(1) to specify where the documentation should be displayed. +.PP +The \fI.source\fR file has the following format: +.nf + + <?xml version="1.0"?> + <monodoc> + <source provider="PROVIDER" basefile="BASEFILE" path="PATH" /> + </monodoc> + +.fi +The \fI/monodoc/source/@provider\fR attribute specifies which format provider +should be used when reading the \fI.tree\fR and \fI.zip\fR files; this +\fImust\fR correspond to one of the \fI--format\fR values. +.PP +The \fI/monodoc/source/@basefile\fR attribute specifies the filename prefix +for the documentation files. This must be the same prefix as used with the +\fI\-\-out\fR parameter. There should be \fIno\fR filename extension on this +value. +.PP +The \fI/monodoc/source/@path\fR attribute specifies the parent node in +\fBmonodoc\fR(1)'s tree view where the documentation will be inserted. +See the \fI$MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml\fR +file for a list of \fIPATH\fR values (the \fI//node/@name\fR values). +.PP +Once the \fIBASEFILE.source\fR has been written, the documentation can be +installed so that \fBmonodoc\fR(1) will display the documentation with the +command: +.nf + + cp BASEFILE.source BASEFILE.tree BASEFILE.zip \\ + `pkg-config monodoc --variable=sourcesdir` + +.fi +.SH OPTIONS +.TP +\fB\-f\fR, \fB\-\-format\fR=\fIFORMAT\fR +Specifies the documentation format used within \fIPATHS\fR. Valid +\fIFORMAT\fR values include: +\fIecma\fR, +\fIecmaspec\fR, +\fIerror\fR, +\fIhb\fR, +\fIman\fR, +\fIsimple\fR, and +\fIxhtml\fR. +.Sp +See the \fIFORMATS\fR section below for more information about these formats. +.Sp +The default format (if none is specifed) is \fIecma\fR. +.Sp +The \fI\-\-format\fR option may be interleaved with \fIPATHS\fR to +change the format used for the remaining parameters (until the next +\fI\-\-format\fR option is seen), e.g.: +.nf + + mdoc assemble -o PREFIX A B --format=man C D --format=xhtml E + +.fi +will assemble directories \fIA\fR and \fIB\fR with the \fIecma\fR format, +files \fIC\fR and \fID\fR with the \fIman\fR formt, and directory +\fIE\fR with the \fIxhtml\fR format. +.TP +\fB\-o\fR, \fB\-\-out\fR=\fIPREFIX\fR +Specify the output file prefix. \fBmdoc assemble\fR creates the files +\fIPREFIX.zip\fR and \fIPREFIX.tree\fR. +.TP +\fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR +Display a help message and exit. +.SH "FORMATS" +The following documentation formats are supported: +.SS ecma +The \fIMono ECMA Documentation Format\fR, an XML documentation format with one +file per type. +.PP +See the \fBmdoc\fR(5) man page for more information. +.SS ecmaspec +The \fIMono ECMA Specification Documentation Format\fR. +This is not the format you're looking for; it is the format used to represent +the ECMA-334 (C#) standard within \fBmonodoc\fR(1). It is not used to display +class library documentation; for class library documentation, use the +.B ecma +format. +.SS error +The \fIError Documentation Format\fR is used to present detailed error +messages, and is used in \fBmonodoc\fR(1)'s "C# Compiler Error Reference" +tree. +.PP +In this format, \fIPATHS\fR is a configuration file, containing the XML: +.nf + + <ErrorProviderConfig> + <FilesPath>../../mcs/errors</FilesPath> + <Match>cs????*.cs</Match> + <ErrorNumSubstringStart>2</ErrorNumSubstringStart> + <ErrorNumSubstringLength>4</ErrorNumSubstringLength> + <FriendlyFormatString>CS{0:0###}</FriendlyFormatString> + </ErrorProviderConfig> + +.fi +The elements mean: +.TP +.I /ErrorProviderConfig/FilesPath +Specifies where to look for files. +.TP +.I /ErrorProviderConfig/Match +Specifies the filename pattern to look for within the +\fI/ErrorProviderConfig/FilesPath\fR directory. +.TP +.I /ErrorProviderConfig/ErrorNumSubstringStart +Specifies where within the filename the error number starts. +.TP +.I /ErrorProviderConfig/ErrorNumSubstringLength +Specifies how many characters after +\fI/ErrorProviderConfig/ErrorNumSubstringStart\fR to use for the error number. +.TP +.I /ErrorProviderConfig/FriendlyFormatString +Specifies the formatting/display of the node in the \fBmonodoc\fR(1) tree. +.PP +For each file found, it is converted to HTML with C# syntax coloring applied. +.SS simple +The \fISimple Documentation Format\fR file format recursively adds all files +and directories underneath \fIPATHS\fR. When displayed, HTML files are +displayed as-is. Text files are converted into HTML by translating each +newline into an HTML \fI<br>\fR element. No other file type is supported. +.SS man +The \fIMan Page Documentation Format\fR displays groff man pages. (This is +\fInot\fR a full groff parser, and only handles the man page constructs used +within the mono man pages.) +.PP +\fIPATHS\fR is a set of XML files containing: +.nf + + <?xml version="1.0"?> + <manpages> + <manpage name="NAME" page="FILE" /> + </manpages> + +.fi +There may be multiple \fI//manpage\fR elements within the root \fI/manpage\fR +element. +.PP +The \fI/manpages/manpage/@name\fR attribute contains the display name for the +tree view node, which is also the URL of the man page when using +\fBmonodoc\fR(1)'s \fILookup URL\fR command (before prefixing with a +\fIman:\fR prefix). Thus, if \fI/manpages/manpage/@name\fR contains +\fImono(1)\fR, then \fIman:mono(1)\fR can be used in the \fILookup URL\fR +command to view the \fImono(1)\fR man page. +.PP +The \fI/manpages/manpage/@page\fR attribute is the filename that contains the +man page. If this file does not exist, then \fI/manpages/manpage/@name\fR +will not be displayed within the tree view. +.SS xhtml +The XHTML provider interprets \fIPATHS\fR as a Windows Help file XHTML TOC +file and looks for referenced documents to create the help source. +.SH SEE ALSO +\fBmdoc\fR(1), +\fBmdoc\fR(5), +\fBmonodoc\fR(1) +.SH MAILING LISTS +.TP +Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details. +.SH WEB SITE +See also: http://www.mono-project.com/mdoc |