diff options
author | Shaun McCance <shaunm@gnome.org> | 2008-12-12 12:49:36 -0600 |
---|---|---|
committer | Shaun McCance <shaunm@gnome.org> | 2009-04-19 11:13:32 -0500 |
commit | eae4fd2e8e09cc1ca8057dc4dad8e57dbd93d0ef (patch) | |
tree | e159598195548621c25b13bcafb2eeaa46fa03a7 | |
parent | 432254d073f38a15367a5ed9f1c683ed88e6f025 (diff) | |
download | gnome-doc-utils-eae4fd2e8e09cc1ca8057dc4dad8e57dbd93d0ef.tar.gz |
Adding content for some inline elements
-rw-r--r-- | doc/mallard/C/mal_inline_app.xml | 16 | ||||
-rw-r--r-- | doc/mallard/C/mal_inline_cmd.xml | 12 | ||||
-rw-r--r-- | doc/mallard/C/mal_inline_code.xml | 59 | ||||
-rw-r--r-- | doc/mallard/C/mal_inline_file.xml | 6 | ||||
-rw-r--r-- | doc/mallard/C/mal_inline_input.xml | 8 | ||||
-rw-r--r-- | 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. |