From b5fc24ea887d41897182e18c578f9001202dfd17 Mon Sep 17 00:00:00 2001 From: Jonathan Pryor Date: Sat, 18 Oct 2008 19:20:48 +0000 Subject: [PATCH] Migrating from monodoc/man to mono/man... svn path=/trunk/mono/; revision=116386 --- man/mdoc.5 | 794 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 794 insertions(+) create mode 100644 man/mdoc.5 diff --git a/man/mdoc.5 b/man/mdoc.5 new file mode 100644 index 00000000000..bcf1268212e --- /dev/null +++ b/man/mdoc.5 @@ -0,0 +1,794 @@ +.\" +.\" mdoc(5) manual page. +.\" (C) 2008 Jonathan Pryor +.\" 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" 5 +.SH NAME +mdoc \- Mono Documentation XML Format +.SH DESCRIPTION +The assorted Mono documentation programs generate or manipulate XML files +following the mono documentation schema: +.TP +.I mdoc update +Creates or updates mono documentation XML for a set of assemblies. +.TP +.I mdoc validate +Validates the mono documentation XML against the mono documentation XML +schema. +.TP +.I mdoc assemble +Converts the mono documentation XML within a directory structure into a set +of files for use with \fBmonodoc\fR(1). +.TP +.I mdoc export-html +Converts the mono documentation XML within a directory structure into a set +of HTML files that can be viewed with a web browser. +.PP +All of these tools (and more) use the common XML schema described in this man +page. +.SH FILE/DIRECTORY STRUCTURE +There are three sets of Mono documentation XML files: +.TP +.B * +.B index.xml: +contains a list of all assemblies within the containing directory, and all +types and namespaces within those assemblies. +.TP +.B * +.B ns\-*.xml: +There is one ns-*.xml file for each namespace within the assembly; these +files are siblings to +.I index.xml +\&. +.Sp +Examples of +.I ns\-*.xml +files include: \fIns-System.xml\fR, \fIns-System.Collections.xml\fR, and +\fIns-.xml\fR (for the root namespace, though it is recommended to NOT place +types into the root namespace, as \fBmonodoc\fR(1) doesn't display them). +.Sp +The +.I ns\-*.xml +files contain per-namespace documentation. +.TP +.B * +.B NamespaceName/TypeName.xml: +These files are within a dotted +.I NamespaceName +directory, and +.I TypeName +is the name of the type. +.Sp +Examples include: +.I RootType.xml +(if the type has no namespace), +\fISystem/String.xml\fR, +\fISystem.Collections/IEnumerable.xml\fR, and +\fISystem.Collections.Generic/List`1+Enumerator.xml\fR +(the +.I `1 +is the number of generic type parameters the type accepts, and everything +after the +.I + +is a nested type). +.PP +Thus, typical directory contents would resemble: + +.nf + index.xml + ns-System.xml + ns-System.Collections.Generic.xml + System/String.xml + System.Collections.Generic/List`1.xml +.fi +.SH DOCUMENTATION FORMAT +.SS "\fBindex.xml File Format\fR" +.PP +The +.I index.xml +file contains a list of the assemblies nested under the directory containing +.I index.xml +and all namespaces and types within those assemblies. It looks something like +this: + +.nf + + + + + + To be added. + To be added. + + + + + + + + + + + + DocTest + +.fi + +Most of this is maintained automatically, in particular the +.I /Overview/Assemblies +and +.I /Overview/Types +elements. +.PP +The +.I //Namespace/@Name +attribute corresponds to a directory which contains files named +\fI//Type/@Name\fR.xml, while the \fI//Type/@DisplayName\fR attribute contains +a C# type name (if \fI//Type/@DisplayName\fR isn't found, then +\fI//Type/@Name\fR is used as the display name). There should also be a +\fIns-[//Namespace/@Name].xml\fR file. +.PP +There are three elements of interest to authors: +\fI/Overview/Remarks\fR, \fI/Overview/Copyright\fR, and +\fI/Overview/Title\fR, which contain assembly-level documentation. +These elements can contain any of the following XML elements (documented in +the \fBDocumentation XML Elements\fR section): +\fIblock\fR, +\fIcode\fR, +\fIexample\fR, +\fIlist\fR, +\fIpara\fR, +\fIparamref\fR, +\fItypeparamref\fR, +\fIsee\fR, and +\fIul\fR. +.SS "\fBns-*.xml File Format\fR" +The \fIns-*.xml\fR files contain namespace documentation: + +.nf + + + To be added. + To be added. + + +.fi + +The \fI/Namespace/Docs/summary\fR and \fI/Namespace/Docs/remarks\fR elements +should contain namespace documentation. +.PP +The \fIremarks\fR and \fIsummary\fR elements are documented in the +\fBDocumentation XML Elements\fR section. +.SS "\fBNamespaceName/TypeName.xml File Format\fR" +The +.I mono documentation format +is similar to the Ecma documentation format, as described +in ECMA-335 3rd Edition, Partition IV, Chapter 7. +The principal difference from the ECMA format is that each type gets its own +file, within a directory identical to the namespace of the type. There is a +lot of information that is maintained automatically by \fBmdoc\fR(1); +Most of the information within the documentation should +.I not +be edited. This includes the type name (\fI/Type/@FullName\fR), implemented +interfaces (\fI/Type/Interfaces\fR), member information +(\fI/Type/Members/Member/@MemberName\fR, +\fI/Type/Members/Member/MemberSignature\fR, +\fI/Type/Members/Member/MemberType\fR, +\fI/Type/Members/Member/Parameters\fR, etc.). + +.nf + + + + DocTest + 0.0.0.0 + + + System.Attribute + + + + + System.AttributeUsage(System.AttributeTargets.All) + + + + To be added. + To be added. + + + + + Constructor + + 0.0.0.0 + + + + + + To be added. + To be added. + To be added. + + + + +.fi + +The only elements that normally need to be edited are children of the +\fI//Docs\fR elements, which usually contain the text +.I To be added. +The \fI/Type/Docs\fR element contains type-level documentation, while the +\fI/Type/Members/Member/Docs\fR element contains per-member documentation. +.PP +The \fI//Docs\fR elements can contain the following elements: +\fIaltcompliant\fR, +\fIaltmember\fR, +\fIexample\fR, +\fIexception\fR, +\fIparam\fR, +\fIpermission\fR, +\fIremarks\fR, +\fIreturns\fR, +\fIsince\fR, +\fIsummary\fR, +\fIthreadsafe\fR, +\fItypeparam\fR, and +\fIvalue\fR. +.PP +Nested types are not members; they are types, and are documented in their own +file. Consequently, the \fINamespaceName/TypeName.xml\fR files are not +recursive; you do not store a \fI\fR element within a \fI\fR +element. +.SS "\fBDocumentation XML Elements\fR" +The contents of the \fIDocs\fR element is \fIidentical\fR +in semantics and structure to the inline C# documentation format, consisting +of these elements (listed in ECMA-334 3rd Edition, Annex E, Section 2). The +following are used within the element descriptions: +.TP +.I CREF +Refers to a class (or member) reference, and is a string in the format +described below in the \fBCREF FORMAT\fR section. +.TP +.I TEXT +Non-XML text, and XML should not be nested. +.I +.TP +.I XML +Only XML elements should be nested (which indirectly may contain text), but +non-whitespace text should not be an immediate child node. +.TP +.I XML_TEXT +Free-form text and XML, so that other XML elements may be nested. +.PP +The following elements are used in documentation: +.TP +.I +.I +is a top-level element, and should be nested directly under the +.I +element. +.Sp +Allows an entry to be generated for the \fISee Also\fR section. Use +\fI\fR to specify a link from within text. + +.nf + +.fi +.TP +.I XML_TEXT +Create a block of text, similar in concept to a paragraph, but is used to +create divisions within the text. To some extent, a is equivalent to +the HTML

tag. +.Sp +.I SUBSET +should always be the value \fI"none"\fR. +.Sp +.I TYPE +specifies the heading and formatting to use. Recognized types are: +.Sp +.I behaviors +Creates a section with the heading \fIOperation\fR. +.Sp +.I note +Creates a section with the heading \fINote:\fR. +.Sp +.I overrides +Creates a section with the heading \fINote to Inheritors\fR. +.Sp +.I usage +Creates a section with the heading \fIUsage\fR. +.Sp +The \fIblock\fR element can contain the following elements: +\fIblock\fR, +\fIc\fR, +\fIcode\fR, +\fIlist\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, +\fIsubscript\fR, +\fIsup\fR, and +\fItypeparamref\fR. +.TP +.I XML_TEXT +Set text in a code-like font (similar to the HTML element). +.Sp +The \fIc\fR element can contain the following elements: +\fIcode\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, and +\fItypeparamref\fR. +.TP +.I TEXT +Display multiple lines of text in a code-like font (similar to the HTML 
+element).
+.I LANGUAGE
+is the language this code block is for.  For example, if \fILANGUAGE\fR is
+\fBC#\fR, then \fITEXT\fR will get syntax highlighting for the C# language 
+within the Mono Documentation Browser.
+.TP
+.I XML_TEXT
+Indicates an example that should be displayed specially.  For example:
+
+.nf
+    
+      An introductory paragraph.
+      
+        class Example {
+          public static void Main ()
+          {
+            System.Console.WriteLine ("Hello, World!");
+          }
+        }
+      
+    
+.fi
+
+The \fIexample\fR element can contain the following elements:
+\fIc\fR,
+\fIcode\fR,
+\fIlist\fR,
+\fIpara\fR, and
+\fIsee\fR.
+.TP
+.I XML_TEXT
+Identifies an exception that can be thrown by the documented member.
+.Sp
+.I 
+is a top-level element, and should be nested directly under the 
+.I 
+element.
+.Sp
+.I CREF
+is the exception type that is thrown, while
+.I XML_TEXT
+contains the circumstances that would cause 
+.I CREF
+to be thrown.
+
+.nf
+    
+       was .
+    
+.fi
+
+The \fIexception\fR element can contain the following elements:
+\fIblock\fR,
+\fIpara\fR,
+\fIparamref\fR,
+\fIsee\fR, and
+\fItypeparamref\fR.
+.TP
+.I XML
+Create a list or table of items.  
+.I 
+makes use of nested \fIXML\fR, \fIXML\fR,
+\fIXML_TEXT\fR, and \fIXML_TEXT\fR
+elements.
+.Sp
+\fILists\fR have the syntax:
+
+.nf
+     
+      Bullet 1
+      Bullet 2
+      Bullet 3
+    
+.fi
+.Sp
+.I Tables
+have the syntax:
+
+.nf
+    
+       
+        Column 1
+        Column 2
+        Column 3
+      
+      
+        Item 1-A
+        Item 1-B
+        Item 1-C
+      
+      
+        Item 2-A
+        Item 2-B
+        Item 2-C
+      
+    
+.fi
+
+The \fIitem\fR and \fIdescription\fR elements can each contain text and 
+the following elements: 
+\fIblock\fR,
+\fIc\fR,
+\fIpara\fR,
+\fIparamref\fR,
+\fIsee\fR,
+\fIsup\fR, and
+\fItypeparamref\fR.
+.TP
+.I XML_TEXT
+Insert a paragraph of \fIXML_TEXT\fR.
+For example,
+
+.nf
+    
+      This is a paragraph of text.
+    
+.fi
+
+The \fIpara\fR element can contain the following elements:
+\fIblock\fR,
+\fIc\fR,
+\fIexample\fR,
+\fIlink\fR,
+\fIlist\fR,
+\fIonequarter\fR,
+\fIparamref\fR,
+\fIsee\fR,
+\fIsub\fR,
+\fIsup\fR,
+\fItypeparamref\fR, and
+\fIul\fR.
+.TP
+.I XML_TEXT
+.I 
+is a top-level element, and should be nested directly under the 
+.I 
+element.
+.Sp
+Describes the parameter \fINAME\fR of the current constructor, method, or 
+property:
+
+.nf
+    
+      A  containing the number
+      of widgets to process.
+    
+.fi
+
+
+The \fIparam\fR element can contain the following elements:
+\fIblock\fR,
+\fIc\fR,
+\fIexample\fR,
+\fIpara\fR,
+\fIparamref\fR,
+\fIsee\fR, and
+\fItypeparamref\fR.
+.TP
+.I 
+Indicates that \fINAME\fR is a parameter.
+.Sp
+This usually renders \fINAME\fR as italic text, so it is frequently 
+(ab)used as an equivalent to the HTML  element.  See the 
+\fI\fR documentation (above) for an example.
+.Sp
+.TP
+.I XML_TEXT
+Documents the security accessibility requirements of the current member.
+.Sp
+.I 
+is a top-level element, and should be nested directly under the 
+.I 
+element.
+.Sp
+\fICREF\fR is a type reference to the security permission required, while
+\fIXML_TEXT\fR is a description of why the permission is required.
+
+.nf
+    
+      Requires permission for reading and writing files. See 
+      , 
+      .
+    
+.fi
+
+The \fIpermission\fR element can contain the following elements:
+\fIblock\fR,
+\fIpara\fR,
+\fIparamref\fR,
+\fIsee\fR, and
+\fItypeparamref\fR.
+.TP
+.I XML_TEXT
+Contains detailed information about a member.
+.Sp
+.I 
+is a top-level element, and should be nested directly under the 
+.I 
+element.
+
+.nf
+    
+      Insert detailed information here.
+    
+.fi
+
+The \fIremarks\fR element can contain the following elements:
+\fIblock\fR,
+\fIc\fR,
+\fIcode\fR,
+\fIexample\fR,
+\fIlist\fR,
+\fIpara\fR,
+\fIparamref\fR,
+\fIsee\fR, and
+\fItypeparamref\fR.
+.TP
+.I XML_TEXT
+.Sp
+.I 
+is a top-level element, and should be nested directly under the 
+.I 
+element.
+.Sp
+Describes the return value of a method:
+
+.nf
+    
+      A  specifying whether 
+      or not the process can access 
+      .
+    
+.fi
+
+The \fIreturns\fR element can contain the following elements:
+\fIlist\fR,
+\fIpara\fR,
+\fIparamref\fR,
+\fIsee\fR, and
+\fItypeparamref\fR.
+.TP
+\fI\fR, \fI\fR
+Creates a link to the specified member within the current text:
+
+.nf
+    
+.fi
+
+or specifies that \fILANGWORD\fR is a language keyword:
+
+.nf
+    
+.fi
+
+.TP
+.I 
+Do not use \fIseealso\fR, use \fIaltmember\fR.
+.TP
+.I 
+.Sp
+.I 
+is a top-level element, and should be nested directly under the 
+\fI\fR element.
+.Sp
+Permits specification of which version introduced the specified type or
+member.
+
+.nf
+    
+.fi
+
+This generally isn't required, as the \fI//AssemblyInfo/AssemblyVersion\fR
+elements track which assembly versions contain type or member.
+.TP
+.I XML_TEXT
+.Sp
+.I 
+is a top-level element, and should be nested directly under the 
+.I 
+element.
+.Sp
+Provides a (brief!) overview about a type or type member.
+.Sp
+This is usually displayed as part of a class declaration, and should be a
+reasonably short description of the type/member.  Use
+.I 
+for more detailed information.
+.Sp
+The \fIsummary\fR element can contain the following elements:
+\fIblock\fR,
+\fIlist\fR,
+\fIpara\fR,
+\fIparamref\fR,
+\fIsee\fR, and
+\fItypeparamref\fR.
+.TP
+.I XML_TEXT
+.I 
+is a top-level element, and should be nested directly under the 
+.I 
+element.
+.Sp
+This is used to document a type parameter for a generic type or generic method.
+.Sp
+.I NAME
+is the name of the type parameter, while
+.I XML_TEXT
+contains a description of the parameter (what it's used for, what restrictions
+it must meet, etc.).
+
+.nf
+    
+      The type of the underlying collection
+    
+.fi
+
+The \fItypeparam\fR element can contain the following elements:
+\fIblock\fR,
+\fIc\fR,
+\fIpara\fR,
+\fIparamref\fR,
+\fIsee\fR, and
+\fItypeparamref\fR.
+.TP
+.I 
+Used to indicate that \fINAME\fR is a type parameter.
+.TP
+.I XML_TEXT
+.I 
+is a top-level element, and should be nested directly under the 
+.I 
+element.
+.Sp
+Allows a property to be described.
+
+.nf
+    
+      A  containing a widget name.
+    
+.fi
+
+The \fIvalue\fR element can contain the following elements:
+\fIblock\fR,
+\fIc\fR,
+\fIexample\fR,
+\fIlist\fR,
+\fIpara\fR,
+\fIparamref\fR,
+\fIsee\fR, and
+\fItypeparamref\fR.
+.PP
+.SH CREF FORMAT
+String IDs (\fICREF\fRs) are used to refer to a type or member of a type.  
+String IDs are documented in ECMA-334 3rd Edition, Annex E.3.1.  They consist 
+of a \fImember type prefix\fR, the full type name (namespace + name, separated 
+by \fI.\fR), possibly followed by the member name and other information.
+.PP
+Member type prefixes:
+.TP
+.I "C:"
+The CREF refers to a constructor.  The (optional) parameter list is
+enclosed in parenthesis and follows the type name:
+\fIC:System.String(System.Char,System.Int32)\fR.
+.TP
+.I "E:"
+The CREF refers to an event.  The event name follows the type name:
+\fIE:System.AppDomain.AssemblyLoad\fR.
+.TP
+.I "F:"
+The CREF refers to a field.  The field name follows the type name:
+\fIF:System.Runtime.InteropServices.DllImportAttribute.SetLastError\fR.
+.TP
+.I "M:"
+Refers to a constructor or method.  Constructors may append 
+.I .ctor
+to the type name (instead of using the above
+.I C:
+constructor format), while methods append the method name and an (optional)
+count of the number of generic parameters.  Both constructors and methods 
+may append the method parameter list enclosed in parenthesis.
+.Sp
+Examples: 
+\fIM:System.Object..ctor\fR,
+\fIM:System.String..ctor(System.Char[])\fR,
+\fIM:System.String.Concat(System.Object)\fR,
+\fIM:System.Array.Sort``1(``0[])\fR,
+\fIM:System.Collections.Generic.List`1..ctor\fR,
+\fIM:System.Collections.Generic.List`1.Add(`0)\fR.
+.TP
+.I "N:"
+Refers to a namespace, e.g. \fIN:System\fR.
+.TP
+.I "P:"
+Refers to a property.  If the property is an indexer or takes parameters, 
+the parameter types are appended to the property name and enclosed with
+paranthesis:
+\fIP:System.String.Length\fR,
+\fIP:System.String.Chars(System.Int32)\fR.
+.TP
+.I "T:"
+The CREF refers to a type, with the number of generic types appended:
+\fIT:System.String\fR,
+\fIT:System.Collections.Generic.List`1\fR,
+\fIT:System.Collections.Generic.List`1.Enumerator\fR.
+.PP
+To make matters more interesting, generic types & members have two
+representations: the "unbound" representation (shown in examples above), in
+which class names have the count of generic parameters appended to their name.
+There is also a "bound" representation, in which the binding of generic
+parameters is listed within '{' and '}' or '<' and '>'.
+(Use of '<' and '>' is less common, as within an XML document their escaped
+character entities must instead be used, leading to '<' and '>'.)
+.PP
+.B Unbound:
+.TP
+.B *
+.I T:System.Collections.Generic.List`1
+.TP
+.B *
+.I T:System.Collections.Generic.Dictionary`2
+.PP
+.B Bound:
+.TP
+.B *
+.I T:System.Collections.Generic.List{System.Int32}
+.TP
+.B *
+.I T:System.Collections.Generic.List
+.TP
+.B *
+.I T:System.Collections.Generic.List<System.Int32>
+.TP
+.B *
+.I T:System.Predicate{System.Action{System.String}}
+.PP
+As you can see, bound variants can be arbitrarily complex (just like
+generics).
+.PP
+Furthermore, if a generic parameter is bound to the generic parameter of a
+type or method, the "index" of the type/method's generic parameter is used 
+as the binding, so given
+
+.nf
+    class FooType {
+      public static void Foo (System.Predicate predicate)
+      {
+      }
+    }
+.fi
+
+The CREF for this method is
+\fIM:FooType.Foo``1(System.Predicate{``0})\fR,
+.I ``0
+is the 0th generic parameter index which is bound to 
+\fISystem.Predicate\fR.
+.SH SEE ALSO
+mdoc(1), monodocer(1)
+.SH MAILING LISTS
+.TP
+Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
+.SH WEB SITE
+Visit http://www.mono-project.com for details
-- 
2.25.1