[mallard] Finishing info_credit and info_copyright

2 files changed, 186 insertions, 13 deletions

diff --git a/doc/mallard/C/mal_info_copyright.xml b/doc/mallard/C/mal_info_copyright.xml
index 3020625..2dd4945 100644
--- a/doc/mallard/C/mal_info_copyright.xml
+++ b/doc/mallard/C/mal_info_copyright.xml
@@ -5,6 +5,8 @@
 <info>
   <link type="guide" xref="mal_info#elements"/>
 
+  <revision version="0.1" date="2009-05-28" status="review"/>
+
   <credit type="author">
     <name>Shaun McCance</name>
     <email>shaunm@gnome.org</email>
@@ -16,17 +18,79 @@
 
   <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
 
-  <revision version="0.1" date="2007-02-23" status="stub"/>
+  <desc>Record information about copyright holders.</desc>
 </info>
 
 <title>Copyright Information</title>
 
 <synopsis><code mime="application/relax-ng-compact-syntax">
 mal_info_copyright = element copyright {
-  element year { text } +,
-  element name { <link xref="mal_inline">mal_inline</link> },
-  element email { <link xref="mal_inline">mal_inline</link> } ?
+  attribute * - (mal:* | local:*) { text } *,
+
+  ( element year { text } +
+  &amp; element name { <link xref="mal_inline">mal_inline</link> }
+  &amp; element email { <link xref="mal_inline">mal_inline</link> } ?
+  &amp; element * - (mal:* | local:*) { mal_inline } *
+  )
 }
 </code></synopsis>
 
+<p>Use the <code>copyright</code> element to include information about the
+copyright holders of the page or section.  You can record the name and email
+address of the copyright holder, as well as any years in which the holder
+contributed copyrighted material.</p>
+
+
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list>
+    <item><p>The <code>copyright</code> element contains one or more <code>year</code>
+    elements, a <code>name</code> element, and an optional <code>email</code> element.
+    The <code>copyright</code> element can also contain elements from external
+    namespaces.  The order of the child elements does not matter.</p></item>
+
+    <item><p>The <code>copyright</code> element can occur in any
+    <code xref="mal_info">info</code> element.</p></item>
+
+    <item><p>The <code>copyright</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 processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>There are no specific processing expectations for the <code>copyright</code>
+  element.  As an informational element, it is not necessarily displayed.  Some
+  tools, however, may choose to display copyrights at the bottom of a page, on a
+  separate information page, or in a dialog.</p>
+
+  <p>When processing the children of a <code>copyright</code> element, tools
+  should select the child elements they understand and ignore all other child
+  content.</p>
+</section>
+<!-- END processing -->
+
+
+<!-- BEGIN comparison -->
+<section id="comparison">
+  <title>Comparison to Other Formats</title>
+
+  <p>The <code>copyright</code> element is similar to the
+  <code href="http://www.docbook.org/tdg/en/html/copyright.html">copyright</code>
+  element in DocBook.  Mallard allows more information to be recorded about a
+  particular copyright holder through informational child elements.  In DocBook,
+  a single <code>copyright</code> element can have multiple
+  <code href="http://www.docbook.org/tdg/en/html/holder.html">holder</code>
+  children.  In Mallard, each <code>copyright</code> element is restricted to
+  a single copyright holder.</p>
+</section>
+<!-- END comparison -->
+
+
 </page>
diff --git a/doc/mallard/C/mal_info_credit.xml b/doc/mallard/C/mal_info_credit.xml
index 705e595..7ecebb3 100644
--- a/doc/mallard/C/mal_info_credit.xml
+++ b/doc/mallard/C/mal_info_credit.xml
@@ -5,7 +5,20 @@
 <info>
   <link type="guide" xref="mal_info#elements"/>
 
-  <revision version="0.1" date="2007-02-22" status="stub"/>
+  <revision version="0.1" date="2009-05-28" status="review"/>
+
+  <credit type="author">
+    <name>Shaun McCance</name>
+    <email>shaunm@gnome.org</email>
+  </credit>
+  <copyright>
+    <year>2008</year>
+    <name>Shaun McCance</name>
+  </copyright>
+
+  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
+
+  <desc>Give credit where credit is due.</desc>
 </info>
 
 <title>Credits</title>
@@ -15,16 +28,112 @@ mal_info_credit = element credit {
   attribute type {
     "author"     | "editor"       |
     "maintainer" | "collaborator" |
-    "translator" | "publisher"    },
-  attribute date { xsd:date } ?,
-  element name { <link xref="mal_inline">mal_inline</link> },
-  element email { <link xref="mal_inline">mal_inline</link> } ?
+    "translator" | "publisher"    } ?,
+  attribute * - (mal:* | local:*) { text } *,
+
+  ( element name { <link xref="mal_inline">mal_inline</link> }
+  &amp; element email { <link xref="mal_inline">mal_inline</link> } ?
+  &amp; element * - (mal:* | local:*) { mal_inline } *
+  )
 }
 </code></synopsis>
 
-<comment>
-  <cite date="2007-01-22"><name>Shaun McCance</name></cite>
-  <p>Add examples, processing expectations</p>
-</comment>
+<p>Use the <code>credit</code> element to record credits for who has contributed
+to the page or section.  You can optionally use the <code>type</code> attribute
+to specify what type of contribution the person has made.  If a person has made
+contributions in multiple roles, include multiple <code>credit</code> elements
+for that person.</p>
+
+
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list>
+    <item><p>The <code>credit</code> element contains a <code>name</code> element
+    and an optional <code>email</code> element.  The <code>credit</code> element
+    can also contain elements from external namespaces.  The order of the child
+    elements does not matter.</p></item>
+
+    <item><p>The <code>credit</code> element can occur in any
+    <code xref="mal_info">info</code> element.</p></item>
+
+    <item>
+      <p>The optional <code>type</code> attribute can be used to specify
+      what type of contribution the person has made.  The following values are
+      allowed:</p>
+
+      <table rules="rows">
+        <tr>
+          <td><p><code>"author"</code></p></td>
+          <td><p>somebody responsible for writing content</p></td>
+        </tr>
+        <tr>
+          <td><p><code>"editor"</code></p></td>
+          <td><p>somebody who has provided reviews or editorial corrections</p></td>
+        </tr>
+        <tr>
+          <td><p><code>"maintainer"</code></p></td>
+          <td><p>the person or entity currently responsible for the work</p></td>
+        </tr>
+        <tr>
+          <td><p><code>"collaborator"</code></p></td>
+          <td><p>somebody who has provided extensive rough information</p></td>
+        </tr>
+        <tr>
+          <td><p><code>"translator"</code></p></td>
+          <td><p>somebody who has translated the work into another language</p></td>
+        </tr>
+        <tr>
+          <td><p><code>"publisher"</code></p></td>
+          <td><p>a person or entity who distributes formatted copies</p></td>
+        </tr>
+      </table>
+    </item>
+
+    <item><p>The <code>credit</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 processing -->
+<section id="processing">
+  <title>Processing Expectations</title>
+
+  <p>There are no specific processing expectations for the <code>credit</code>
+  element.  As an informational element, it is not necessarily displayed.  Some
+  tools, however, may choose to display credits at the bottom of a page, on a
+  separate information page, or in a dialog.</p>
+
+  <p>When processing the children of a <code>credit</code> element, tools
+  should select the child elements they understand and ignore all other child
+  content.</p>
+</section>
+<!-- END processing -->
+
+
+<!-- BEGIN comparison -->
+<section id="comparison">
+  <title>Comparison to Other Formats</title>
+
+  <p>The <code>credit</code> element serves the purpose of the
+  <code href="http://www.docbook.org/tdg/en/html/author.html">author</code>,
+  <code href="http://www.docbook.org/tdg/en/html/collab.html">collab</code>,
+  <code href="http://www.docbook.org/tdg/en/html/corpauthor.html">corpauthor</code>,
+  <code href="http://www.docbook.org/tdg/en/html/editor.html">editor</code>,
+  <code href="http://www.docbook.org/tdg/en/html/othercredit.html">othercredit</code>, and
+  <code href="http://www.docbook.org/tdg/en/html/publisher.html">publisher</code>
+  elements in DocBook.  DocBook does not have specific elements for maintainers
+  and translators.</p>
+
+  <p>In DocBook, certain credit elements have highly structured content, whereas
+  others allow simple inline text.  In Mallard, all credits use simple structured
+  content.  While Mallard does not provide child elements for everything that can
+  be recorded in DocBook, elements from external namespaces may be used for any
+  additional information that is needed.</p>
+</section>
+<!-- END comparison -->
 
 </page>