[mallard] Adding notes about content model to block elements

12 files changed, 188 insertions, 22 deletions

diff --git a/doc/mallard/C/mal_block_code.xml b/doc/mallard/C/mal_block_code.xml
index c4a78a6..32b0b33 100644
--- a/doc/mallard/C/mal_block_code.xml
+++ b/doc/mallard/C/mal_block_code.xml
@@ -47,6 +47,15 @@ by the user.</p>
 <section id="notes">
   <title>Notes</title>
   <list type="bullet">
+    <item><p>The <code>code</code> element can contain a mixture of text and
+    any <link xref="mal_inline">general inline elements</link>.  Whitespace
+    is interpreted literally.</p></item>
+
+    <item><p>The <code>code</code> element can occur in any
+    general block context, including inside
+    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
+    and certain <link xref="mal_block">block elements</link>.</p></item>
+
     <item><p>The <code>style</code> attribute takes a space-separated list of
     style hints.  Processing tools should adjust their behavior according to
     those style hints they understand.</p></item>
@@ -56,7 +65,7 @@ by the user.</p>
 
     <item><p>The <code>code</code> element can have attributes from external
     namespaces.  See <link xref="mal_external"/> for more information
-    on external-namespace attributes on block elements.</p></item>
+    on external-namespace attributes.</p></item>
 
     <item><p>The <code>code</code> element may also be used in an inline context.
     See <link xref="mal_inline_code"/> for more information.</p></item>
diff --git a/doc/mallard/C/mal_block_comment.xml b/doc/mallard/C/mal_block_comment.xml
index 8abe7bb..5a650f6 100644
--- a/doc/mallard/C/mal_block_comment.xml
+++ b/doc/mallard/C/mal_block_comment.xml
@@ -52,6 +52,16 @@ to provide a <code>date</code> attribute.</p>
 <section id="notes">
   <title>Notes</title>
   <list type="bullet">
+    <item><p>The <code>comment</code> element contains an optional
+    <link xref="mal_title">title</link> element, a
+    <link xref="mal_block_cite">cite</link> element, and  any
+    <link xref="mal_block">general block content</link>.</p></item>
+
+    <item><p>The <code>comment</code> element can occur in any
+    general block context, including inside
+    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
+    and certain <link xref="mal_block">block elements</link>.</p></item>
+
     <item><p>The <code>style</code> attribute takes a space-separated list of
     style hints.  Processing tools should adjust their behavior according to
     those style hints they understand.</p></item>
diff --git a/doc/mallard/C/mal_block_example.xml b/doc/mallard/C/mal_block_example.xml
index 0e4ab80..9f6b8be 100644
--- a/doc/mallard/C/mal_block_example.xml
+++ b/doc/mallard/C/mal_block_example.xml
@@ -36,22 +36,26 @@ may be used to group example input with its result, to show different
 steps with different types of block elements, or simply to group some
 paragraphs together.</p>
 
-<comment>
-  <cite date="2008-12-11"><name>Shaun McCance</name></cite>
-  <p>Add explanation, examples</p>
-</comment>
 
 <!-- BEGIN notes -->
 <section id="notes">
   <title>Notes</title>
   <list type="bullet">
+    <item><p>The <code>example</code> element can contain any
+    <link xref="mal_block">general block content</link>.</p></item>
+
+    <item><p>The <code>example</code> element can occur in any
+    general block context, including inside
+    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
+    and certain <link xref="mal_block">block elements</link>.</p></item>
+
     <item><p>The <code>style</code> attribute takes a space-separated list of
     style hints.  Processing tools should adjust their behavior according to
     those style hints they understand.</p></item>
 
     <item><p>The <code>example</code> element can have attributes from external
     namespaces.  See <link xref="mal_external"/> for more information
-    on external-namespace attributes on block elements.</p></item>
+    on external-namespace attributes.</p></item>
   </list>
 </section>
 <!-- END notes -->
diff --git a/doc/mallard/C/mal_block_figure.xml b/doc/mallard/C/mal_block_figure.xml
index e981f9e..2920eb0 100644
--- a/doc/mallard/C/mal_block_figure.xml
+++ b/doc/mallard/C/mal_block_figure.xml
@@ -25,4 +25,29 @@ mal_block_figure = element figure {
   <p>A way to float right, a'la wikipedia?</p>
 </comment>
 
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list type="bullet">
+    <item><p>The <code>figure</code> element contains an optional
+    <link xref="mal_title">title</link> element, an optional
+    <link xref="mal_block_desc">desc</link> element, and  any
+    <link xref="mal_block">general block content</link>.</p></item>
+
+    <item><p>The <code>figure</code> element can occur in any
+    general block context, including inside
+    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
+    and certain <link xref="mal_block">block elements</link>.</p></item>
+
+    <item><p>The <code>style</code> attribute takes a space-separated list of
+    style hints.  Processing tools should adjust their behavior according to
+    those style hints they understand.</p></item>
+
+    <item><p>The <code>figure</code> element can have attributes from external
+    namespaces.  See <link xref="mal_external"/> for more information
+    on external-namespace attributes.</p></item>
+  </list>
+</section>
+<!-- END notes -->
+
 </page>
diff --git a/doc/mallard/C/mal_block_listing.xml b/doc/mallard/C/mal_block_listing.xml
index 3f665b1..8ed6fa3 100644
--- a/doc/mallard/C/mal_block_listing.xml
+++ b/doc/mallard/C/mal_block_listing.xml
@@ -24,6 +24,32 @@ mal_block_listing = element listing {
   <p>Add explanation, examples, processing expectations</p>
 </comment>
 
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list type="bullet">
+    <item><p>The <code>listing</code> element contains an optional
+    <link xref="mal_title">title</link> element, an optional
+    <link xref="mal_block_desc">desc</link> element, and  any
+    <link xref="mal_block">general block content</link>.</p></item>
+
+    <item><p>The <code>listing</code> element can occur in any
+    general block context, including inside
+    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
+    and certain <link xref="mal_block">block elements</link>.</p></item>
+
+    <item><p>The <code>style</code> attribute takes a space-separated list of
+    style hints.  Processing tools should adjust their behavior according to
+    those style hints they understand.</p></item>
+
+    <item><p>The <code>listing</code> element can have attributes from external
+    namespaces.  See <link xref="mal_external"/> for more information
+    on external-namespace attributes.</p></item>
+  </list>
+</section>
+<!-- END notes -->
+
+
 <!-- BEGIN examples -->
 <section id="examples">
   <title>Examples</title>
diff --git a/doc/mallard/C/mal_block_media.xml b/doc/mallard/C/mal_block_media.xml
index 9f634fa..fd7ce1a 100644
--- a/doc/mallard/C/mal_block_media.xml
+++ b/doc/mallard/C/mal_block_media.xml
@@ -48,6 +48,15 @@ for details on how fallback elements are handled.</p>
 <section id="notes">
   <title>Notes</title>
   <list type="bullet">
+    <item><p>The <code>media</code> element can contain any
+    <link xref="mal_block">general block content</link>.  The content is only
+    used as a fallback or alternative.</p></item>
+
+    <item><p>The <code>media</code> element can occur in any
+    general block context, including inside
+    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
+    and certain <link xref="mal_block">block elements</link>.</p></item>
+
     <item><p>The <code>style</code> attribute takes a space-separated list of
     style hints.  Processing tools should adjust their behavior according to
     those style hints they understand.</p></item>
@@ -57,7 +66,7 @@ for details on how fallback elements are handled.</p>
 
     <item><p>The <code>media</code> element can have attributes from external
     namespaces.  See <link xref="mal_external"/> for more information
-    on external-namespace attributes on block elements.</p></item>
+    on external-namespace attributes.</p></item>
 
     <item><p>The <code>media</code> element may also be used in an inline context.
     See <link xref="mal_inline_media"/> for more information.</p></item>
diff --git a/doc/mallard/C/mal_block_note.xml b/doc/mallard/C/mal_block_note.xml
index da77628..190200b 100644
--- a/doc/mallard/C/mal_block_note.xml
+++ b/doc/mallard/C/mal_block_note.xml
@@ -18,10 +18,19 @@ mal_block_note = element note {
 }
 </code></synopsis>
 
-<!-- BEGIN discussion -->
-<section id="discussion">
-  <title>Discussion</title>
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
   <list type="bullet">
+    <item><p>The <code>note</code> element contains an optional
+    <link xref="mal_title">title</link> element and  any
+    <link xref="mal_block">general block content</link>.</p></item>
+
+    <item><p>The <code>note</code> element can occur in any
+    general block context, including inside
+    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
+    and certain <link xref="mal_block">block elements</link>.</p></item>
+
     <item><p>The <code>style</code> attribute takes a space-separated list of
     style hints.  Processing tools should adjust their behavior according to
     those style hints they understand.</p></item>
@@ -30,31 +39,31 @@ mal_block_note = element note {
       <p>The following style hints are recommended:</p>
       <table rules="rows">
         <tr>
-          <td><code>"advanced"</code></td>
+          <td><p><code>"advanced"</code></p></td>
           <td><p>information that advanced users may find useful</p></td>
         </tr>
         <tr>
-          <td><code>"bug"</code></td>
+          <td><p><code>"bug"</code></p></td>
           <td><p>a note about a known bug in the software</p></td>
         </tr>
         <tr>
-          <td><code>"tip"</code></td>
+          <td><p><code>"tip"</code></p></td>
           <td><p>a general tip that may help the reader perform an operation better</p></td>
         </tr>
         <tr>
-          <td><code>"warning"</code></td>
+          <td><p><code>"warning"</code></p></td>
           <td><p>a warning to the reader about a potentially dangerous operation</p></td>
         </tr>
       </table>
     </item>
-  </list>
 
-  <comment>
-    <cite date="2008-10-11"><name>shaunm</name></cite>
-    <p>Add discussion of content model</p>
-  </comment>
+    <item><p>The <code>note</code> element can have attributes from external
+    namespaces.  See <link xref="mal_external"/> for more information
+    on external-namespace attributes.</p></item>
+  </list>
 </section>
-<!-- END discussion -->
+<!-- END notes -->
+
 
 <!-- BEGIN examples -->
 <section id="examples">
diff --git a/doc/mallard/C/mal_block_p.xml b/doc/mallard/C/mal_block_p.xml
index 31d5d69..4898c53 100644
--- a/doc/mallard/C/mal_block_p.xml
+++ b/doc/mallard/C/mal_block_p.xml
@@ -27,6 +27,30 @@ outout.</p>
 </comment>
 
 
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list type="bullet">
+    <item><p>The <code>p</code> element can contain a mixture of text and
+    any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+    <item><p>The <code>p</code> element can occur in any
+    general block context, including inside
+    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
+    and certain <link xref="mal_block">block elements</link>.</p></item>
+
+    <item><p>The <code>style</code> attribute takes a space-separated list of
+    style hints.  Processing tools should adjust their behavior according to
+    those style hints they understand.</p></item>
+
+    <item><p>The <code>p</code> element can have attributes from external
+    namespaces.  See <link xref="mal_external"/> for more information
+    on external-namespace attributes.</p></item>
+  </list>
+</section>
+<!-- END notes -->
+
+
 <!-- BEGIN examples -->
 <section id="examples">
   <title>Examples</title>
diff --git a/doc/mallard/C/mal_block_quote.xml b/doc/mallard/C/mal_block_quote.xml
index 8020c00..841b5c2 100644
--- a/doc/mallard/C/mal_block_quote.xml
+++ b/doc/mallard/C/mal_block_quote.xml
@@ -11,7 +11,7 @@
 <synopsis><code mime="application/relax-ng-compact-syntax">
 mal_block_quote = element quote {
   <link xref="mal_title">mal_title</link> ?,
-  <link xref="mal_block_desc">mal_block_desc</link> ?,
+  <link xref="mal_block_cite">mal_block_cite</link>,
   <link xref="mal_block">mal_block</link> +
 }
 </code></synopsis>
@@ -22,4 +22,32 @@ mal_block_quote = element quote {
   <p>style="epipgraph"</p>
 </comment>
 
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list type="bullet">
+    <item><p>The <code>quote</code> element contains an optional
+    <link xref="mal_title">title</link> element, a
+    <link xref="mal_block_cite">cite</link> element, and  any
+    <link xref="mal_block">general block content</link>.</p></item>
+
+    <item><p>The <code>quote</code> element can occur in any
+    general block context, including inside
+    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
+    and certain <link xref="mal_block">block elements</link>.</p></item>
+
+    <item><p>The <code>style</code> attribute takes a space-separated list of
+    style hints.  Processing tools should adjust their behavior according to
+    those style hints they understand.</p></item>
+
+    <item><p>The <code>quote</code> element can have attributes from external
+    namespaces.  See <link xref="mal_external"/> for more information
+    on external-namespace attributes.</p></item>
+
+    <item><p>The <code>quote</code> element may also be used in an inline context.
+    See <link xref="mal_inline_quote"/> for more information.</p></item>
+  </list>
+</section>
+<!-- END notes -->
+
 </page>
diff --git a/doc/mallard/C/mal_block_screen.xml b/doc/mallard/C/mal_block_screen.xml
index 4e93a3a..5e44426 100644
--- a/doc/mallard/C/mal_block_screen.xml
+++ b/doc/mallard/C/mal_block_screen.xml
@@ -52,6 +52,15 @@ by the user.</p>
 <section id="notes">
   <title>Notes</title>
   <list type="bullet">
+    <item><p>The <code>screen</code> element can contain a mixture of text and
+    any <link xref="mal_inline">general inline elements</link>.  Whitespace
+    is interpreted literally.</p></item>
+
+    <item><p>The <code>screen</code> element can occur in any
+    general block context, including inside
+    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
+    and certain <link xref="mal_block">block elements</link>.</p></item>
+
     <item><p>The <code>style</code> attribute takes a space-separated list of
     style hints.  Processing tools should adjust their behavior according to
     those style hints they understand.</p></item>
diff --git a/doc/mallard/C/mal_block_synopsis.xml b/doc/mallard/C/mal_block_synopsis.xml
index dd11cbf..0673b2c 100644
--- a/doc/mallard/C/mal_block_synopsis.xml
+++ b/doc/mallard/C/mal_block_synopsis.xml
@@ -48,13 +48,23 @@ control element.</p>
 <section id="notes">
   <title>Notes</title>
   <list type="bullet">
+    <item><p>The <code>synopsis</code> element contains an optional
+    <link xref="mal_title">title</link> element, an optional
+    <link xref="mal_block_desc">desc</link> element, and  any
+    <link xref="mal_block">general block content</link>.</p></item>
+
+    <item><p>The <code>synopsis</code> element can occur in any
+    general block context, including inside
+    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
+    and certain <link xref="mal_block">block elements</link>.</p></item>
+
     <item><p>The <code>style</code> attribute takes a space-separated list of
     style hints.  Processing tools should adjust their behavior according to
     those style hints they understand.</p></item>
 
     <item><p>The <code>synopsis</code> element can have attributes from external
     namespaces.  See <link xref="mal_external"/> for more information
-    on external-namespace attributes on block elements.</p></item>
+    on external-namespace attributes.</p></item>
   </list>
 </section>
 <!-- END notes -->
diff --git a/doc/mallard/C/mal_inline_quote.xml b/doc/mallard/C/mal_inline_quote.xml
index 1e8ef93..710ab08 100644
--- a/doc/mallard/C/mal_inline_quote.xml
+++ b/doc/mallard/C/mal_inline_quote.xml
@@ -62,6 +62,9 @@ mal_inline_quote = element quote {
     <item><p>The <code>quote</code> element can have attributes from external
     namespaces.  See <link xref="mal_external"/> for more information
     on external-namespace attributes.</p></item>
+
+    <item><p>The <code>quote</code> element may also be used in a block context.
+    See <link xref="mal_block_quote"/> for more information.</p></item>
   </list>
 </section>
 <!-- END notes -->