[gnome-doc-utils/mallard] Finishing off code blocks and adding info to screen and inline code

[Shaun McCance <shaunm src gnome org>]

commit af5d420242a4bda73db11f00c21c5253a9c341e2
Author: Shaun McCance <shaunm gnome org>
Date:   Sun Apr 19 11:44:30 2009 -0500

    Finishing off code blocks and adding info to screen and inline code
---
 doc/mallard/C/mal_block_code.xml   |   94 ++++++++++++++++++++++++++----------
 doc/mallard/C/mal_block_screen.xml |    8 ++-
 doc/mallard/C/mal_inline_code.xml  |    9 ++-
 3 files changed, 81 insertions(+), 30 deletions(-)

diff --git a/doc/mallard/C/mal_block_code.xml b/doc/mallard/C/mal_block_code.xml
index 5495a5e..017179a 100644
--- a/doc/mallard/C/mal_block_code.xml
+++ b/doc/mallard/C/mal_block_code.xml
@@ -3,19 +3,23 @@
       id="mal_block_code">
 
 <info>
-  <link type="guide" xref="mal_block#simple"/>
+  <link type="guide" xref="mal_block#elements"/>
   <link type="seealso" xref="mal_inline_code"/>
 
+  <version number="0.1" date="2009-04-19" status="review"/>
+
   <credit type="author">
     <name>Shaun McCance</name>
     <email>shaunm gnome org</email>
   </credit>
   <copyright>
-    <year>2008</year>
+    <year>2008-2009</year>
     <name>Shaun McCance</name>
   </copyright>
 
-  <version number="0.1" date="2007-02-21" status="stub"/>
+  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
+
+  <desc>Mark up a block of code or the contents of a file.</desc>
 </info>
 
 <title>Code Blocks</title>
@@ -30,19 +34,58 @@ mal_block_code = element code {
 }
 </code></synopsis>
 
-<comment>
-  <cite date="2006-12-08"><name>Shaun McCance</name></cite>
-  <p>Add intro material.</p>
-</comment>
+<p>Use the <code>code</code> element to mark up a block of text from
+a computer language.  This will typically be used for programming
+languages, markup languages, and configuration files; however, you
+may use <code>code</code> for the contents of any text file.</p>
+
+<p>Use the <code xref="mal_inline_var">var</code> element inside a
+<code>code</code> element to indicate text that should be replaced
+by the user.</p>
+
+
+<!-- BEGIN notes -->
+<section id="notes">
+  <title>Notes</title>
+  <list type="bullet">
+    <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>mime</code> attribute takes a valid MIME type.  Processing
+    tools may adjust their behavior for particular MIME types.</p></item>
+
+    <item><p>The <code>code</code> element can have attributes from external
+    namespaces.  See <link xref="mal_attr_external"/> for more information
+    on external-namespace attributes on inline elements.</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>
+  </list>
+</section>
+<!-- END notes -->
 
 
 <!-- BEGIN examples -->
 <section id="examples">
   <title>Examples</title>
-  <comment>
-    <cite date="2007-01-25"><name>Shaun McCance</name></cite>
-    <p>Add examples.</p>
-  </comment>
+
+  <p>Use <code>code</code> to mark up a class definition:</p>
+
+  <example>
+    <code><![CDATA[<code mime="text/x-c++src">
+class BeanStalk {
+public:
+  void add_bean(Bean bean);
+  int count_beans();
+}</code>]]></code>
+    <code mime="text/x-c++src">
+class BeanStalk {
+public:
+  void add_bean(Bean bean);
+  int count_beans();
+}</code>
+  </example>
 </section>
 <!-- END examples -->
 
@@ -53,7 +96,9 @@ mal_block_code = element code {
 
   <p>Code blocks should be displayed verbatim, with all whitespace and line
   breaks reproduced in the rendered output.  The only exception is a single
-  leading line break, which should be stripped by display tools if present.</p>
+  leading line break, which should be stripped by display tools if present.
+  Display tools should only strip a leading line break in an initial text
+  node.  They are not expected to strip line breaks from child elements.</p>
 
   <p>Code blocks should be displayed in a fixed-width font.  Inline markup may
   cause style variations, but they should not cause a change to a variable-width
@@ -62,24 +107,23 @@ mal_block_code = element code {
 <!-- END processing -->
 
 
-<!-- BEGIN docbook -->
-<section id="docbook">
-  <title>Comparison to DocBook</title>
-  <p>DocBook contains numerous elements for modeling code in procedural and
-  object-oriented programming languages.  Many of these elements can be seen
-  by browsing the content models for the
+<!-- BEGIN comparison -->
+<section id="comparison">
+  <title>Comparison to Other Formats</title>
+  <p>The <code>code</code> element is similar to the
+  <code href="http://www.docbook.org/tdg/en/html/programlisting.html";>programlisting</code>
+  element in DocBook.  DocBook also contains numerous elements for modeling
+  code in procedural and object-oriented programming languages.  Many of
+  these elements can be seen by browsing the content models for the
   <code href="http://www.docbook.org/tdg/en/html/classsynopsis.html";>classsynopsis</code>
   and
   <code href="http://www.docbook.org/tdg/en/html/funcsynopsis.html";>funcsynopsis</code>
   elements.  Mallard does not attempt to model any programming languages.</p>
 
-
-
-  <comment>
-    <cite date="2007-01-25"><name>Shaun McCance</name></cite>
-    <p>Add: code, class*, func*, programlisting</p>
-  </comment>
+  <p>The <code>code</code> element is similar to the
+  <code href="http://docs.oasis-open.org/dita/v1.1/CS01/langspec/langref/codeblock.html";>codeblock</code>
+  element in DITA.</p>
 </section>
-<!-- END docbook -->
+<!-- END comparison -->
 
 </page>
diff --git a/doc/mallard/C/mal_block_screen.xml b/doc/mallard/C/mal_block_screen.xml
index c47aeb2..5fe65f1 100644
--- a/doc/mallard/C/mal_block_screen.xml
+++ b/doc/mallard/C/mal_block_screen.xml
@@ -19,7 +19,7 @@
 
   <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
 
-  <desc>Mark up a an interactive shell session.</desc>
+  <desc>Mark up a textual user interface or an interactive shell session.</desc>
 </info>
 
 <title>Screens</title>
@@ -44,6 +44,10 @@ to provide richer markup when showing a shell session.</p>
 <p>The <code>screen</code> element may also be used to mark up a single
 command in a block context.</p>
 
+<p>Use the <code xref="mal_inline_var">var</code> element inside a
+<code>screen</code> element to indicate text that should be replaced
+by the user.</p>
+
 
 <!-- BEGIN notes -->
 <section id="notes">
@@ -158,7 +162,7 @@ xsltproc -o mal_block_screen.html \
 
 <!-- BEGIN comparison -->
 <section id="comparison">
-  <title>Comparison to DocBook</title>
+  <title>Comparison to Other Formats</title>
 
   <p>The <code>screen</code> element is similar to the
   <code href="http://www.docbook.org/tdg/en/html/screen.html";>screen</code>
diff --git a/doc/mallard/C/mal_inline_code.xml b/doc/mallard/C/mal_inline_code.xml
index b2b9ace..3cdbd4e 100644
--- a/doc/mallard/C/mal_inline_code.xml
+++ b/doc/mallard/C/mal_inline_code.xml
@@ -5,17 +5,17 @@
 <info>
   <link type="guide" xref="mal_inline#elements"/>
 
+  <version number="0.1" date="2008-12-12" status="review"/>
+
   <credit type="author">
     <name>Shaun McCance</name>
     <email>shaunm gnome org</email>
   </credit>
   <copyright>
-    <year>2008</year>
+    <year>2008-2009</year>
     <name>Shaun McCance</name>
   </copyright>
 
-  <version number="0.1" date="2008-12-12" status="review"/>
-
   <desc>Mark up code from a programming, markup, or other machine-readable format.</desc>
 </info>
 
@@ -65,6 +65,9 @@ by the user.</p>
     <item><p>The <code>code</code> element can have attributes from external
     namespaces.  See <link xref="mal_attr_external"/> for more information
     on external-namespace attributes on inline elements.</p></item>
+
+    <item><p>The <code>code</code> element may also be used in a block context.
+    See <link xref="mal_block_code"/> for more information.</p></item>
   </list>
 </section>
 <!-- END notes -->