Merge pull request #5714 from alexischr/update_bockbuild

[mono.git] / man / mdoc.5

diff --git a/man/mdoc.5 b/man/mdoc.5
index bcf1268212e5031e32ac8a34326a70436c1b9171..3cd4bbea5558369f244d1873b7f220ec20c73074 100644 (file)
--- a/man/mdoc.5
+++ b/man/mdoc.5
@@ -328,13 +328,26 @@ The \fIc\fR element can contain the following elements:
 \fIsee\fR, and
 \fItypeparamref\fR.
 .TP
-.I <code lang="LANGUAGE">TEXT</code>
+.I <code lang="LANGUAGE" src="SOURCE">TEXT</code>
 Display multiple lines of text in a code-like font (similar to the HTML <pre/>
 element).
+.Sp
 .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.
+.Sp
+.I SOURCE
+is only interpreted by \fBmdoc-update\fR(1).  If the \fIsrc\fR attribute is
+present when \fBmdoc-update\fR(1) is run, then \fISOURCE\fR is a file 
+(relative to \fBmdoc-update\fR(1)'s \fB--out\fR directory) that
+should be inserted as the value for \fITEXT\fR.
+The contents of \fITEXT\fR will be ignored by \fBmdoc-update\fR(1)
+and replaced on every invocation.  \fISOURCE\fR can also contain an "anchor",
+e.g. \fIsrc="path/to/file.cs#RegionMarker"\fR.  If an anchor is present,
+\fIand\fR \fILANGUAGE\fR is \fIC#\fR, then \fI#region RegionMarker\fR will be
+searched for, and the contents between the \fI#region\fR and the following
+\fI#endregion\fR will be inserted as the value for \fITEXT\fR element.
 .TP
 .I <example>XML_TEXT</example>
 Indicates an example that should be displayed specially.  For example:
@@ -388,6 +401,31 @@ The \fIexception\fR element can contain the following elements:
 \fIsee\fR, and
 \fItypeparamref\fR.
 .TP
+.I <format type="TYPE">XML_TEXT</format>
+The \fI<format/>\fR element is an "escape hatch," for including (possibly XML)
+content that is not valid \fBmdoc\fR(5) content.  It's the moral equivalent of
+\fBperlpod\fR(1) \fI=begin format\fR blocks.
+
+\fITYPE\fR is the mime type of \fIXML_TEXT\fR.  \fBmdoc\fR(5) processors may
+skip \fIformat/>\fR blocks of they use a type that isn't supported.
+
+For example:
+
+.nf
+    <format type="text/html">
+      <table width="100%">
+        <tr><td style="color:red">Hello, world!</td></tr>
+      </table>
+    </format>
+.fi
+
+would cause the embedded HTML \fI<table/>\fR element to be inserted inline
+into the resulting HTML document when \fBmdoc-export-html\fR(1) processes the
+file.  (Likewise, it may be skipped if processed by another program.)
+
+\fIformat/>\fR is intended to simplify importing documentation from existing
+documentation sources.  It should not be relied upon, if at all possible.
+.TP
 .I <list>XML</list>
 Create a list or table of items.  
 .I <list/>
@@ -565,6 +603,8 @@ Describes the return value of a method:
 .fi
 
 The \fIreturns\fR element can contain the following elements:
+\fIc\fR,
+\fIformat\fR,
 \fIlist\fR,
 \fIpara\fR,
 \fIparamref\fR,
@@ -725,7 +765,7 @@ Refers to a namespace, e.g. \fIN:System\fR.
 .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:
+parenthesis:
 \fIP:System.String.Length\fR,
 \fIP:System.String.Chars(System.Int32)\fR.
 .TP