[gnome-doc-utils/mallard: 60/87] Adding some processing expectations for code blocks

[Shaun McCance <shaunm src gnome org>]

commit 5fbd1ffe415442a03f784c44bb7cb9dabf98ad31
Author: Shaun McCance <shaunm gnome org>
Date:   Tue Dec 2 09:17:52 2008 -0600

    Adding some processing expectations for code blocks
---
 doc/mallard/C/mal_block_code.xml |   24 +++++++++++++++++++++++-
 1 files changed, 23 insertions(+), 1 deletions(-)

diff --git a/doc/mallard/C/mal_block_code.xml b/doc/mallard/C/mal_block_code.xml
index 724b7e2..097e362 100644
--- a/doc/mallard/C/mal_block_code.xml
+++ b/doc/mallard/C/mal_block_code.xml
@@ -27,7 +27,8 @@ mal_block_code = element code {
   attribute * - (mal:* | local:*) { text } *,
 
   <link xref="mal_inline">mal_inline</link>
-}</code></synopsis>
+}
+</code></synopsis>
 
 <comment>
   <cite date="2006-12-08"><name>Shaun McCance</name></cite>
@@ -54,6 +55,27 @@ mal_block_code = element code {
     <p>Add processing expectations.  For block, strip leading/trailing
     newline.  Do not strip leading indentation.</p>
   </comment>
+  <p>Processing tools should strip a leading newline and a trailing newline
+  from the text content.  This allows people to write XML like the following:</p>
+  <code>
+&lt;code&gt;
+def frobnicate (foo, bar):
+    if foo:
+        bar
+    else:
+        foo + bar
+&lt;/code&gt;
+</code>
+  <p>This is much more natural to read and write, since every line is on its
+  own without markup.  Processing tools should strip no more than one newline
+  from either end, in case authors need to insert intentional newlines.  If
+  the first or last child is an element, processing tools should not descend
+  into those elements to strip newlines.</p>
+  <p>Processing tools should not attempt to strip uniform indentation from
+  the text contents.  Authors sometimes indent preformatted text to match
+  the indentation of the surrounding markup.  Handling this reliably is
+  difficult and can lead to unexpected results.  Authors should fix their
+  documents if this problem arises.</p>
 </section>
 <!-- END processing -->