[gnome-doc-utils/mallard: 85/87] Flushed out screen documentation, some categorization work on blocks
- From: Shaun McCance <shaunm src gnome org>
- To: svn-commits-list gnome org
- Subject: [gnome-doc-utils/mallard: 85/87] Flushed out screen documentation, some categorization work on blocks
- Date: Sun, 19 Apr 2009 12:21:28 -0400 (EDT)
commit 154d3b1d8e9e63b161f62d3031c62c12ae2d2507
Author: Shaun McCance <shaunm recto localdomain>
Date: Thu Apr 16 23:01:11 2009 -0500
Flushed out screen documentation, some categorization work on blocks
---
doc/mallard/C/mal_block.xml | 9 +++
doc/mallard/C/mal_block_caption.xml | 2 +-
doc/mallard/C/mal_block_cite.xml | 2 +-
doc/mallard/C/mal_block_code.xml | 34 ++-------
doc/mallard/C/mal_block_media.xml | 2 +-
doc/mallard/C/mal_block_quote.xml | 2 +-
doc/mallard/C/mal_block_screen.xml | 126 +++++++++++++++++++++++++++++++++--
7 files changed, 141 insertions(+), 36 deletions(-)
diff --git a/doc/mallard/C/mal_block.xml b/doc/mallard/C/mal_block.xml
index 30ecd1a..1215fd5 100644
--- a/doc/mallard/C/mal_block.xml
+++ b/doc/mallard/C/mal_block.xml
@@ -41,6 +41,15 @@ mal_block = (
</comment>
+<!-- BEGIN elements -->
+<section id="elements" style="2column">
+ <info>
+ <title type="link">Block Elements</title>
+ </info>
+ <title>Elements</title>
+</section>
+<!-- END elements -->
+
<!-- BEGIN simple -->
<section id="simple">
<title>Simple Block Elements</title>
diff --git a/doc/mallard/C/mal_block_caption.xml b/doc/mallard/C/mal_block_caption.xml
index 49b7e19..b1272c8 100644
--- a/doc/mallard/C/mal_block_caption.xml
+++ b/doc/mallard/C/mal_block_caption.xml
@@ -3,7 +3,7 @@
id="mal_block_caption">
<info>
- <link type="guide" xref="mal_block"/>
+ <link type="guide" xref="mal_block#elements"/>
<credit type="author">
<name>Shaun McCance</name>
diff --git a/doc/mallard/C/mal_block_cite.xml b/doc/mallard/C/mal_block_cite.xml
index 2ce4838..4ba1c01 100644
--- a/doc/mallard/C/mal_block_cite.xml
+++ b/doc/mallard/C/mal_block_cite.xml
@@ -3,7 +3,7 @@
id="mal_block_cite">
<info>
- <link type="guide" xref="mal_block"/>
+ <link type="guide" xref="mal_block#elements"/>
<credit type="author">
<name>Shaun McCance</name>
diff --git a/doc/mallard/C/mal_block_code.xml b/doc/mallard/C/mal_block_code.xml
index a11fe6a..5495a5e 100644
--- a/doc/mallard/C/mal_block_code.xml
+++ b/doc/mallard/C/mal_block_code.xml
@@ -50,32 +50,14 @@ mal_block_code = element code {
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
- <comment>
- <cite date="2007-01-25"><name>Shaun McCance</name></cite>
- <p>Add processing expectations. For block, strip leading/trailing
- newline. Do not strip leading indentation.</p>
- </comment>
- <p>display 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>
-<code>
-def frobnicate (foo, bar):
- if foo:
- bar
- else:
- foo + bar
-</code>
-</code>
- <p>This is much more natural to read and write, since every line is on its
- own without markup. Display 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, display tools should not descend
- into those elements to strip newlines.</p>
- <p>Display 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>
+
+ <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>
+
+ <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
+ font.</p>
</section>
<!-- END processing -->
diff --git a/doc/mallard/C/mal_block_media.xml b/doc/mallard/C/mal_block_media.xml
index 872f7f1..9be862f 100644
--- a/doc/mallard/C/mal_block_media.xml
+++ b/doc/mallard/C/mal_block_media.xml
@@ -3,7 +3,7 @@
id="mal_block_media">
<info>
- <link type="guide" xref="mal_block"/>
+ <link type="guide" xref="mal_block#elements"/>
<version number="0.1" date="2007-02-21" status="stub"/>
</info>
diff --git a/doc/mallard/C/mal_block_quote.xml b/doc/mallard/C/mal_block_quote.xml
index 28c79fc..c592acd 100644
--- a/doc/mallard/C/mal_block_quote.xml
+++ b/doc/mallard/C/mal_block_quote.xml
@@ -2,7 +2,7 @@
type="topic" id="mal_block_quote">
<info>
- <link type="guide" xref="mal_block"/>
+ <link type="guide" xref="mal_block#elements"/>
<link type="seealso" xref="mal_inline_quote"/>
<version number="0.1" date="2007-02-21" status="stub"/>
</info>
diff --git a/doc/mallard/C/mal_block_screen.xml b/doc/mallard/C/mal_block_screen.xml
index 7ba871f..2ea4f6f 100644
--- a/doc/mallard/C/mal_block_screen.xml
+++ b/doc/mallard/C/mal_block_screen.xml
@@ -3,9 +3,23 @@
id="mal_block_screen">
<info>
- <link type="guide" xref="mal_block#simple"/>
+ <link type="guide" xref="mal_block#elements"/>
+ <link type="seealso" xref="mal_block_code"/>
- <version number="0.1" date="2007-02-21" status="stub"/>
+ <version number="0.1" date="2009-04-16" status="review"/>
+
+ <credit type="author">
+ <name>Shaun McCance</name>
+ <email>shaunm gnome org</email>
+ </credit>
+ <copyright>
+ <year>2009</year>
+ <name>Shaun McCance</name>
+ </copyright>
+
+ <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
+
+ <desc>Mark up a an interactive shell session.</desc>
</info>
<title>Screens</title>
@@ -20,9 +34,109 @@ mal_block_screen = element screen {
}
</code></synopsis>
-<comment>
- <cite date="2006-11-08"><name>Shaun McCance</name></cite>
- <p>Add intro, examples, and processing expectations.</p>
-</comment>
+<p>Use the <code>screen</code> element to mark up a sequence of commands
+and program output from an interactive shell session. The contents of
+a <code>screen</code> element are displayed verbatim. While all inline
+content is allowed, <code xref="mal_inline_input">input</code> and
+<code xref="mal_inline_output">output</code> will frequently be used
+to provide richer markup inside a <code>screen</code> element.</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. A MIME type is
+ assumed to apply to the user input only; thus, processing tools may ignore
+ the MIME type if the <code>screen</code> element is not composed of
+ <code>input</code> and <code>output</code> elements.</p></item>
+
+ <item>
+ <p>Typical values for the <code>mime</code> attribute include:</p>
+ <table><tr>
+ <td><p><code>application/x-sh</code></p></td>
+ <td>Command to execute with the Bourne shell</td>
+ </tr><tr>
+ <td><p><code>application/x-csh</code></p></td>
+ <td>Command to execute with the C shell</td>
+ </tr></table>
+ </item>
+
+ <item><p>The <code>screen</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>
+ </list>
+</section>
+<!-- END notes -->
+
+
+<!-- BEGIN examples -->
+<section id="examples">
+ <title>Examples</title>
+
+ <p>Use <code>screen</code> to mark up a long command:</p>
+
+ <example>
+ <code><![CDATA[
+<screen>
+xsltproc -o mal_block_screen.html \
+ --stringparam mal.cache.file `pwd`/mallard.cache \
+ `pkg-config --variable mal2html gnome-doc-utils` mal_block_screen.html
+</screen>
+]]></code>
+ <screen>
+xsltproc -o mal_block_screen.html \
+ --stringparam mal.cache.file `pwd`/mallard.cache \
+ `pkg-config --variable mal2html gnome-doc-utils` mal_block_screen.html
+</screen>
+ </example>
+
+ <p>Use <code xref="mal_inline_input">input</code> and <code xref="mal_inline_output">output</code>
+ inside <code>screen</code> for richer text:</p>
+
+ <example>
+ <code><![CDATA[
+<screen>
+<output type="prompt">[rupert gnome] </output><input>ls foo bar</input>
+<output type="error">foo: cannot access file: No such file or directory</output>
+<output>bar</output></screen>
+]]></code>
+ <screen>
+<output style="prompt">[rupert gnome] </output><input>ls foo bar</input>
+<output style="error">foo: cannot access file: No such file or directory</output>
+<output>bar</output></screen>
+ </example>
+</section>
+<!-- END examples -->
+
+
+<!-- BEGIN processing -->
+<section id="processing">
+ <title>Processing Expectations</title>
+
+ <p>Screens 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>
+
+ <p>Screens 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 font.</p>
+</section>
+<!-- END processing -->
+
+
+<!-- BEGIN docbook -->
+<section id="docbook">
+ <title>Comparison to DocBook</title>
+
+ <p>The <code>screen</code> element is similar to the
+ <code href="http://www.docbook.org/tdg/en/html/screen.html";>screen</code>
+ element in DocBook.</p>
+</section>
+<!-- END docbook -->
</page>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
