GNOME.org
 

[gnome-doc-utils/mallard: 72/87] Adding content for some inline elements

commit eae4fd2e8e09cc1ca8057dc4dad8e57dbd93d0ef
Author: Shaun McCance <shaunm gnome org>
Date:   Fri Dec 12 12:49:36 2008 -0600

    Adding content for some inline elements
---
 doc/mallard/C/mal_inline_app.xml    |   16 +++++++++
 doc/mallard/C/mal_inline_cmd.xml    |   12 +++---
 doc/mallard/C/mal_inline_code.xml   |   59 ++++++++++++++++++++++++++++------
 doc/mallard/C/mal_inline_file.xml   |    6 ++-
 doc/mallard/C/mal_inline_input.xml  |    8 +++-
 doc/mallard/C/mal_inline_output.xml |   20 +++++++-----
 6 files changed, 92 insertions(+), 29 deletions(-)

diff --git a/doc/mallard/C/mal_inline_app.xml b/doc/mallard/C/mal_inline_app.xml
index 9f20a48..5b0ad48 100644
--- a/doc/mallard/C/mal_inline_app.xml
+++ b/doc/mallard/C/mal_inline_app.xml
@@ -59,6 +59,22 @@ the name of the command used to run an application; use
 <!-- END notes -->
 
 
+<!-- BEGIN examples -->
+<section id="examples">
+  <title>Examples</title>
+  <p>Use <code>app</code> to mark up the name of an application:</p>
+  <example>
+    <code><![CDATA[
+To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at
+the command line.
+]]></code>
+    <p>To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at the
+    command line.</p>
+  </example>
+</section>
+<!-- END examples -->
+
+
 <!-- BEGIN processing -->
 <section id="processing">
   <title>Processing Expectations</title>
diff --git a/doc/mallard/C/mal_inline_cmd.xml b/doc/mallard/C/mal_inline_cmd.xml
index ec7b9c9..edee802 100644
--- a/doc/mallard/C/mal_inline_cmd.xml
+++ b/doc/mallard/C/mal_inline_cmd.xml
@@ -92,8 +92,8 @@ by the user.</p>
 
   <example>
     <code><![CDATA[
-<p>To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at
-the command line.</p>
+To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at
+the command line.
 ]]></code>
     <p>To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at the
     command line.</p>
@@ -104,9 +104,9 @@ the command line.</p>
 
   <example>
     <code><![CDATA[
-<p>To view a file in <app>Totem Movie Player</app>, enter <cmd>totem
+To view a file in <app>Totem Movie Player</app>, enter <cmd>totem
 <var>file</var></cmd> at the command line, replacing <var>file</var>
-with the name of the file.</p>
+with the name of the file.
 ]]></code>
     <p>To view a file in <app>Totem Movie Player</app>, enter <cmd>totem <var>file</var></cmd>
     at the command line, replacing <var>file</var> with the name of the file.</p>
@@ -116,8 +116,8 @@ with the name of the file.</p>
 
   <example>
     <code><![CDATA[
-<p>The <cmd>-mtime</cmd> option for the <cmd>find</cmd> command allows
-you to filter files based on their modification times.</p>
+The <cmd>-mtime</cmd> option for the <cmd>find</cmd> command allows
+you to filter files based on their modification times.
 ]]></code>
     <p>The <cmd>-mtime</cmd> option for the <cmd>find</cmd> command allows you to
     filter files based on their modification times.</p>
diff --git a/doc/mallard/C/mal_inline_code.xml b/doc/mallard/C/mal_inline_code.xml
index d451a46..a09b4ba 100644
--- a/doc/mallard/C/mal_inline_code.xml
+++ b/doc/mallard/C/mal_inline_code.xml
@@ -14,7 +14,7 @@
     <name>Shaun McCance</name>
   </copyright>
 
-  <version number="0.1" date="2008-02-19" status="incomplete"/>
+  <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>
@@ -72,10 +72,42 @@ by the user.</p>
 <!-- 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 the name of a function, struct, or other
+  constuct in a programming language:</p>
+
+  <example>
+    <code><![CDATA[
+Use <code>gtk_container_add</code> to add a child widget to a
+<code>GtkButton</code>.
+]]></code>
+    <p>Use <code>gtk_container_add</code> to add a child widget to a <code>GtkButton</code>.</p>
+  </example>
+
+  <p>Use <code>code</code> with <code xref="mal_inline_var">var</code> to mark
+  up code with a placeholder for an argument the user should supply:</p>
+
+  <example>
+    <code><![CDATA[
+To create a new button with a label, use
+<code>gtk_button_new_with_label(<var>label</var>)</code>,
+replacing <var>label</var> with the text of the label.
+]]></code>
+    <p>To create a new button with a label, use
+    <code>gtk_button_new_with_label(<var>label</var>)</code>,
+    replacing <var>label</var> with the text of the label.</p>
+  </example>
+
+  <p>Link to a web page directly with a <code>code</code> element:</p>
+
+  <example>
+    <code><![CDATA[
+Use <code>code</code> with <code xref="mal_inline_var">var</code> to mark
+up code with a placeholder for an argument the user should supply.
+]]></code>
+    <p>Use <code>code</code> with <code xref="mal_inline_var">var</code> to mark
+    up code with a placeholder for an argument the user should supply.</p>
+  </example>
 </section>
 <!-- END examples -->
 
@@ -83,11 +115,16 @@ by the user.</p>
 <!-- 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>Code snippets should be displayed in a fixed-width font.  This mimics
+  the look of a typical environment where code is typed.  More importantly,
+  fixed-width fonts tend to have more distinction between visually similar
+  characters.  This is particularly important in code, since letters often
+  appear without the context of a known word that helps make them discernable
+  in normal prose.</p>
+
+  <p>For particularly long code snippets, processing tools may use a background
+  color or border to make the beginning and end clear, although authors should
+  prefer <link xref="mal_block_code">code blocks</link> for long code snippets.</p>
 </section>
 <!-- END processing -->
 
@@ -97,7 +134,7 @@ by the user.</p>
   <title>Comparison to DocBook</title>
   <p>The <code>code</code> element is similar to the
   <code href="http://www.docbook.org/tdg/en/html/code.html";>code</code> element
-  in DocBook.  Since Mallard does not attempt to model programming languages, the
+  in DocBook.  Since Mallard does not attempt to model programming languages,
   <code>code</code> may be used in place of numerous DocBook elements, including
   <code href="http://www.docbook.org/tdg/en/html/classname.html";>classname</code>,
   <code href="http://www.docbook.org/tdg/en/html/constant.html";>constant</code>,
diff --git a/doc/mallard/C/mal_inline_file.xml b/doc/mallard/C/mal_inline_file.xml
index 99025c3..69ea5b7 100644
--- a/doc/mallard/C/mal_inline_file.xml
+++ b/doc/mallard/C/mal_inline_file.xml
@@ -58,8 +58,10 @@ as search paths and file extensions.</p>
 <!-- BEGIN processing -->
 <section id="processing">
   <title>Processing Expectations</title>
-  <p>Filenames should be rendered in a fixed-width or wide font to reduce
-  ambiguity between visually similar characters.</p>
+  <p>Filenames should be displayed in a fixed-width or wide font.  Fixed-width
+  fonts tend to have more distinction between visually similar characters.  This
+  is particularly important in filenames, since letters often appear without the
+  context of a known word that helps make them discernable in normal prose.</p>
 </section>
 <!-- END processing -->
 
diff --git a/doc/mallard/C/mal_inline_input.xml b/doc/mallard/C/mal_inline_input.xml
index f9db268..57b80f0 100644
--- a/doc/mallard/C/mal_inline_input.xml
+++ b/doc/mallard/C/mal_inline_input.xml
@@ -32,6 +32,9 @@ mal_inline_input = element input {
 }
 </code></synopsis>
 
+<comment><cite date="2008-12-12"><name>Shaun McCance</name></cite>
+<p>Add intro text</p></comment>
+
 
 <!-- BEGIN notes -->
 <section id="notes">
@@ -41,8 +44,9 @@ mal_inline_input = element input {
     style hints.  Processing tools should adjust their rendering according to
     those style hints they understand.</p></item>
 
-    <item><p>The <code>input</code> element, together with the <code>output</code>
-    element, may be used to mark up the contents of a <code>screen</code> element,
+    <item><p>The <code>input</code> element, together with the
+    <code xref="mal_inline_outpu">output</code> element, may be used to mark up
+    the contents of a <code xref="mal_block_screen">screen</code> element,
     allowing processing tools to render them differently.</p></item>
 
     <item><p>The <code>input</code> element can link to other pages or documents.
diff --git a/doc/mallard/C/mal_inline_output.xml b/doc/mallard/C/mal_inline_output.xml
index 3faf281..3b1374c 100644
--- a/doc/mallard/C/mal_inline_output.xml
+++ b/doc/mallard/C/mal_inline_output.xml
@@ -31,6 +31,9 @@ mal_inline_output = element output {
 }
 </code></synopsis>
 
+<comment><cite date="2008-12-12"><name>Shaun McCance</name></cite>
+<p>Add intro text</p></comment>
+
 
 <!-- BEGIN notes -->
 <section id="notes">
@@ -43,19 +46,20 @@ mal_inline_output = element output {
     <item>
       <p>Typical values for the <code>style</code> attribute include:</p>
       <table><tr>
-        <td><code>output</code></td>
-        <td>Standard output from a running program</td>
+        <td><p><code>output</code></p></td>
+        <td><p>Standard output from a running program</p></td>
       </tr><tr>
-        <td><code>error</code></td>
-        <td>Standard error from a running program</td>
+        <td><p><code>error</code></p></td>
+        <td><p>Standard error from a running program</p></td>
       </tr><tr>
-        <td><code>prompt</code></td>
-        <td>The command prompt for an interactive shell</td>
+        <td><p><code>prompt</code></p></td>
+        <td><p>The command prompt for an interactive shell</p></td>
       </tr></table>
     </item>
 
-    <item><p>The <code>output</code> element, together with the <code>input</code>
-    element, may be used to mark up the contents of a <code>screen</code> element,
+    <item><p>The <code>output</code> element, together with the
+    <code xref="mal_inline_input">input</code> element, may be used to mark up
+    the contents of a <code xref="mal_block_screen">screen</code> element,
     allowing processing tools to render them differently.</p></item>
 
     <item><p>The <code>output</code> element can link to other pages or documents.
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]