diff options
author | Shaun McCance <shaunm@gnome.org> | 2009-05-13 16:17:09 -0500 |
---|---|---|
committer | Shaun McCance <shaunm@gnome.org> | 2009-05-13 16:17:09 -0500 |
commit | d1ca9f057261dc155e628b4af86a397b7cea0c17 (patch) | |
tree | 7194ab26e66b2b79fb36f8aa1145a97e81463b71 | |
parent | 094b53780f5de03aeaaaac107de3a9dd2b9d0e1c (diff) | |
download | gnome-doc-utils-d1ca9f057261dc155e628b4af86a397b7cea0c17.tar.gz |
[mallard] Finishing up some inline elements: input, sys, span
-rw-r--r-- | doc/mallard/C/mal_inline_input.xml | 28 | ||||
-rw-r--r-- | doc/mallard/C/mal_inline_span.xml | 57 | ||||
-rw-r--r-- | doc/mallard/C/mal_inline_sys.xml | 31 |
3 files changed, 108 insertions, 8 deletions
diff --git a/doc/mallard/C/mal_inline_input.xml b/doc/mallard/C/mal_inline_input.xml index 1165e6c..1b49bdc 100644 --- a/doc/mallard/C/mal_inline_input.xml +++ b/doc/mallard/C/mal_inline_input.xml @@ -11,11 +11,11 @@ <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-16" status="incomplete"/> + <version number="0.1" date="2009-06-13" status="review"/> <desc>Mark up text the user should input into a computer program.</desc> </info> @@ -74,8 +74,28 @@ or into a text field in a graphical application.</p> <section id="examples"> <title>Examples</title> - <comment><cite date="2008-12-16"><name>Shaun McCance</name></cite> - <p>Add examples</p></comment> + <p>Use <code>input</code> to mark up a user response to a prompt:</p> + + <example> + <code><![CDATA[Type <input>Y</input> at the prompt to proceed.]]></code> + <p>Type <input>Y</input> at the prompt to proceed.</p> + </example> + + <p>Use <code>input</code> and <code xref="mal_inline_output">output</code> + inside a <code xref="mal_block_screen">screen</code> element:</p> + + <example> + <code><![CDATA[ +<screen> +<output style="prompt">$ </output><input>ls mal_inline_output.xml</input> +<output>mal_inline_output.xml</output> +</screen> +]]></code> +<screen> +<output style="prompt">$ </output><input>ls mal_inline_output.xml</input> +<output>mal_inline_output.xml</output> +</screen> + </example> </section> <!-- END examples --> diff --git a/doc/mallard/C/mal_inline_span.xml b/doc/mallard/C/mal_inline_span.xml index 5ad4a32..5749c6b 100644 --- a/doc/mallard/C/mal_inline_span.xml +++ b/doc/mallard/C/mal_inline_span.xml @@ -6,7 +6,18 @@ <link type="guide" xref="mal_inline#elements"/> <link type="seealso" xref="mal_attr_link"/> - <version number="0.1" date="2007-02-21" status="stub"/> + <version number="0.1" date="2009-05-13" status="review"/> + + <credit type="author"> + <name>Shaun McCance</name> + <email>shaunm@gnome.org</email> + </credit> + <copyright> + <year>2007-2009</year> + <name>Shaun McCance</name> + </copyright> + + <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" /> <desc>A generic inline element that can be used for semantic, localization, and styling purpose.</desc> @@ -24,6 +35,11 @@ mal_inline_span = element span { } </code></synopsis> +<p>Use the <code>span</code> element to surround a run of text +without using any of the semantic <link xref="mal_inline">inline +elements</link>. This is frequently necessary for extensions +using attributes from external namespaces.</p> + <!-- BEGIN notes --> <section id="notes"> @@ -52,4 +68,43 @@ mal_inline_span = element span { </section> <!-- END notes --> + +<!-- BEGIN examples --> +<section id="examples"> + <title>Examples</title> + + <p>Use <code>span</code> with an external-namespace attribute to mark a word + as untranslatable using the + <link href="http://www.w3.org/TR/its/">Internationalization Tag Set</link>:</p> + + <example> + <code><![CDATA[ +This <phrase its:translate="no">word</phrase> should not be translated.]]></code> + <p>This <phrase xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0" + its:translate="no">word</phrase> should not be translated.</p> + </example> +</section> +<!-- END examples --> + + +<!-- BEGIN processing --> +<section id="processing"> + <title>Processing Expectations</title> + + <p>No particular special rendering is required for <code>span</code> elements. + Processing tools may have special processing rules for certain style hints or + external-namespace attributes.</p> +</section> +<!-- END processing --> + + +<!-- BEGIN comparison --> +<section id="comparison"> + <title>Comparison to Other Formats</title> + <p>The <code>span</code> element is similar to the + <code href="http://www.docbook.org/tdg/en/html/phrase.html">phrase</code> + element in DocBook.</p> +</section> +<!-- END comparison --> + </page> diff --git a/doc/mallard/C/mal_inline_sys.xml b/doc/mallard/C/mal_inline_sys.xml index 3eea0f8..3dbb736 100644 --- a/doc/mallard/C/mal_inline_sys.xml +++ b/doc/mallard/C/mal_inline_sys.xml @@ -5,7 +5,16 @@ <info> <link type="guide" xref="mal_inline#elements"/> - <version number="0.1" date="2007-02-21" status="stub"/> + <credit type="author"> + <name>Shaun McCance</name> + <email>shaunm@gnome.org</email> + </credit> + <copyright> + <year>2008-2009</year> + <name>Shaun McCance</name> + </copyright> + + <version number="0.1" date="2009-05-13" status="review"/> <desc>Mark up general identifiers found on computer systems.</desc> </info> @@ -22,6 +31,11 @@ mal_inline_sys = element sys { } </code></synopsis> +<p>Use the <code>sys</code> element to mark up any type of system item that +isn't covered by other elements such as <code xref="mal_inline_file">file</code>, +<code xref="mal_inline_cmd">cmd</code>, or +<code xref="mal_inline_code">code</code>.</p> + <!-- BEGIN notes --> <section id="notes"> @@ -54,6 +68,13 @@ mal_inline_sys = element sys { <!-- BEGIN examples --> <section id="examples"> <title>Examples</title> + + <p>Use <code>sys</code> to mark up a domain name:</p> + + <example> + <code><![CDATA[The Linux kernel is hosted on <sys>git.kernel.org</sys>.]]></code> + <p>The Linux kernel is hosted on <sys>git.kernel.org</sys>.</p> + </example> </section> <!-- END examples --> @@ -61,6 +82,12 @@ mal_inline_sys = element sys { <!-- BEGIN processing --> <section id="processing"> <title>Processing Expectations</title> + + <p>System items are displayed in a fixed-width font. Fixed-width fonts + tend to have more distinction between visually similar characters. This + is particularly important in system items, since letters often appear + without the context of a known word that helps make them discernable in + normal prose.</p> </section> <!-- END processing --> @@ -75,8 +102,6 @@ mal_inline_sys = element sys { element. Since Mallard does not provide the level of markup specificity that DocBook does, the <code>sys</code> element should be used in place of these and various other elements.</p> - - <p>See <link xref="principle-justenough"/> for more background.</p> </section> <!-- END comparison --> |