[gnome-doc-utils/mallard] Adding notes about content model and parents to inline elements.
- From: Shaun McCance <shaunm src gnome org>
- To: svn-commits-list gnome org
- Subject: [gnome-doc-utils/mallard] Adding notes about content model and parents to inline elements.
- Date: Tue, 12 May 2009 21:18:17 -0400 (EDT)
commit eeda2b911020c4968d7b443e52eaea5b2230c360
Author: Shaun McCance <shaunm gnome org>
Date: Tue May 12 15:00:17 2009 -0500
Adding notes about content model and parents to inline elements.
Based on input from Paul Cutler. Hopefully makes things more clear
for those who can't read RELAX-NG. Also rearranged some notes,
cleaned up some language, and changed all comparison sections to
Comparison to Other Formats.
---
doc/mallard/C/mal_inline_app.xml | 25 +++++++++----
doc/mallard/C/mal_inline_cmd.xml | 31 +++++++++++------
doc/mallard/C/mal_inline_code.xml | 27 +++++++++-----
doc/mallard/C/mal_inline_em.xml | 28 ++++++++++-----
doc/mallard/C/mal_inline_file.xml | 25 +++++++++----
doc/mallard/C/mal_inline_gui.xml | 47 ++++++++++++++++----------
doc/mallard/C/mal_inline_guiseq.xml | 31 ++++++++++++-----
doc/mallard/C/mal_inline_input.xml | 37 +++++++++++++--------
doc/mallard/C/mal_inline_key.xml | 33 +++++++++++++-----
doc/mallard/C/mal_inline_keyseq.xml | 56 ++++++++++++++++++-------------
doc/mallard/C/mal_inline_link.xml | 63 ++++++++++++++++++++++------------
doc/mallard/C/mal_inline_media.xml | 29 ++++++++++-----
doc/mallard/C/mal_inline_output.xml | 39 +++++++++++++--------
doc/mallard/C/mal_inline_quote.xml | 28 +++++++++++++++
doc/mallard/C/mal_inline_span.xml | 28 +++++++++++++++
doc/mallard/C/mal_inline_sys.xml | 25 +++++++++----
doc/mallard/C/mal_inline_var.xml | 38 ++++++++++++++++----
17 files changed, 405 insertions(+), 185 deletions(-)
diff --git a/doc/mallard/C/mal_inline_app.xml b/doc/mallard/C/mal_inline_app.xml
index f87ffce..b0b6fbe 100644
--- a/doc/mallard/C/mal_inline_app.xml
+++ b/doc/mallard/C/mal_inline_app.xml
@@ -44,16 +44,25 @@ use <code xref="mal_inline_cmd">cmd</code> for this purpose instead.</p>
<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>app</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>app</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
<item><p>The <code>app</code> element can link to other pages or documents.
See <link xref="mal_attr_link"/> for more information.</p></item>
+ <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>app</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>
+ on external-namespace attributes.</p></item>
</list>
</section>
<!-- END notes -->
@@ -111,13 +120,13 @@ your desktop.
<!-- END processing -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
<p>The <code>app</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/application.html";>application</code>
element in DocBook.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/doc/mallard/C/mal_inline_cmd.xml b/doc/mallard/C/mal_inline_cmd.xml
index 6c741ff..41537c4 100644
--- a/doc/mallard/C/mal_inline_cmd.xml
+++ b/doc/mallard/C/mal_inline_cmd.xml
@@ -56,6 +56,18 @@ by the user.</p>
<section id="notes">
<title>Notes</title>
<list type="bullet">
+ <item><p>The <code>cmd</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>cmd</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
+
+ <item><p>The <code>cmd</code> element can link to other pages or documents.
+ See <link xref="mal_attr_link"/> for more information.</p></item>
+
<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>
@@ -74,12 +86,9 @@ by the user.</p>
</tr></table>
</item>
- <item><p>The <code>cmd</code> element can link to other pages or documents.
- See <link xref="mal_attr_link"/> for more information.</p></item>
-
<item><p>The <code>cmd</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>
+ on external-namespace attributes.</p></item>
</list>
</section>
<!-- END notes -->
@@ -131,7 +140,7 @@ you to filter files based on their modification times.
<!-- BEGIN processing -->
<section id="processing">
<title>Processing Expectations</title>
- <p>Commands should be displayed in a fixed-width font. This mimics the look
+ <p>Commands are displayed in a fixed-width font. This mimics the look
of a typical environment where commands are executed. More importantly,
fixed-width fonts tend to have more distinction between visually similar
characters. This is particularly important in commands, since letters often
@@ -142,15 +151,15 @@ you to filter files based on their modification times.
how to use them to a particular effect. This can make it difficult to find
the end of the command quickly. Surrounding text content, especially
punctuation, can sometimes be confused for part of the command. For this
- reason, it is recommended that display tools apply a border or background
- color to commands.</p>
+ reason, it is recommended that commands be displayed with a border or
+ background color.</p>
</section>
<!-- END processing -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
<p>The <code>cmd</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/command.html";>command</code>
@@ -165,6 +174,6 @@ you to filter files based on their modification times.
<p>See <link xref="principle-justenough"/> for more background.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/doc/mallard/C/mal_inline_code.xml b/doc/mallard/C/mal_inline_code.xml
index 3cdbd4e..189011a 100644
--- a/doc/mallard/C/mal_inline_code.xml
+++ b/doc/mallard/C/mal_inline_code.xml
@@ -52,6 +52,18 @@ by the user.</p>
<section id="notes">
<title>Notes</title>
<list type="bullet">
+ <item><p>The <code>code</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>code</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
+
+ <item><p>The <code>code</code> element can link to other pages or documents.
+ See <link xref="mal_attr_link"/> for more information.</p></item>
+
<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>
@@ -59,12 +71,9 @@ by the user.</p>
<item><p>The <code>mime</code> attribute takes a valid MIME type. Processing
tools may adjust their behavior for particular MIME types.</p></item>
- <item><p>The <code>code</code> element can link to other pages or documents.
- See <link xref="mal_attr_link"/> for more information.</p></item>
-
<item><p>The <code>code</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>
+ on external-namespace attributes.</p></item>
<item><p>The <code>code</code> element may also be used in a block context.
See <link xref="mal_block_code"/> for more information.</p></item>
@@ -133,9 +142,9 @@ up code with a placeholder for an argument the user should supply.
<!-- END processing -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</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,
@@ -154,9 +163,7 @@ up code with a placeholder for an argument the user should supply.
in place of the DocBook elements
<code href="http://www.docbook.org/tdg/en/html/markup.html";>markup</code> and
<code href="http://www.docbook.org/tdg/en/html/sgmltag.html";>sgmltag</code>.</p>
-
- <p>See <link xref="principle-justenough"/> for more background.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/doc/mallard/C/mal_inline_em.xml b/doc/mallard/C/mal_inline_em.xml
index 82c6337..506796e 100644
--- a/doc/mallard/C/mal_inline_em.xml
+++ b/doc/mallard/C/mal_inline_em.xml
@@ -41,16 +41,25 @@ display tools.</p>
<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>em</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>em</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
<item><p>The <code>em</code> element can link to other pages or documents.
See <link xref="mal_attr_link"/> for more information.</p></item>
+ <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>em</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>
+ on external-namespace attributes.</p></item>
</list>
</section>
<!-- END notes -->
@@ -98,17 +107,16 @@ Note that <em>accelerators</em> are different from <em>mnemonics</em>.
<!-- END processing -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
<p>The <code>em</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/emphasis.html";>emphasis</code>
element in DocBook. Athough DocBook does not normatively specify a means of
controlling the presentation, most DocBook display tools allow writers to
set the <code>role</code> attribute to <code>bold</code> or <code>strong</code>
- to specify bold text. We explicitly recommend against doing this in Mallard
- documents and display tools.</p>
+ to specify bold text. No such recommendation is made for Mallard.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/doc/mallard/C/mal_inline_file.xml b/doc/mallard/C/mal_inline_file.xml
index 2a07008..f8e5308 100644
--- a/doc/mallard/C/mal_inline_file.xml
+++ b/doc/mallard/C/mal_inline_file.xml
@@ -40,16 +40,25 @@ filenames, such as search paths and file extensions.</p>
<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>file</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>file</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
<item><p>The <code>file</code> element can link to other pages or documents.
See <link xref="mal_attr_link"/> for more information.</p></item>
+ <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>file</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>
+ on external-namespace attributes.</p></item>
</list>
</section>
<!-- END notes -->
@@ -66,13 +75,13 @@ filenames, such as search paths and file extensions.</p>
<!-- END processing -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
<p>The <code>file</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/filename.html";>filename</code>
element in DocBook.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/doc/mallard/C/mal_inline_gui.xml b/doc/mallard/C/mal_inline_gui.xml
index 2af9a4b..205f165 100644
--- a/doc/mallard/C/mal_inline_gui.xml
+++ b/doc/mallard/C/mal_inline_gui.xml
@@ -42,6 +42,22 @@ control is being marked up.</p>
<section id="notes">
<title>Notes</title>
<list type="bullet">
+ <item><p>The <code>gui</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>gui</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
+
+ <item><p>The <code>gui</code> element can also occur inside the
+ <code xref="mal_inline_guiseq">guiseq</code> element, where it has
+ special meaning.</p></item>
+
+ <item><p>The <code>gui</code> element can link to other pages or documents.
+ See <link xref="mal_attr_link"/> for more information.</p></item>
+
<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>
@@ -82,12 +98,9 @@ control is being marked up.</p>
</tr>
</table></item>
- <item><p>The <code>gui</code> element can link to other pages or documents.
- See <link xref="mal_attr_link"/> for more information.</p></item>
-
<item><p>The <code>gui</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>
+ on external-namespace attributes.</p></item>
</list>
</section>
<!-- END notes -->
@@ -126,21 +139,21 @@ of your keyboard to meet certain accessibility needs.
<title>Processing Expectations</title>
<p>No particular special rendering is required for <code>gui</code> elements.
- Display tools may use subtle effects such as lightened text to distinguish
- interface labels elements from the surrounding text.</p>
-
- <p>In certain environments, display tools may decorate interface labels
- with an icon or other effect based on the <code>style</code> attribute.
- For example, in a table of options where the first element of each row is
- a <code>gui</code> element, those with the <code>checkbox</code> style
- hint could be decorated with a check box icon.</p>
+ Interface labels may be rendered with lightened text or other sublte styling
+ effects to distinguish them from the surrounding text.</p>
+
+ <p>In certain environments, interface labels may be decorated with an icon or
+ other effect based on the <code>style</code> attribute. For example, in a
+ table of options where the first element of each row is a <code>gui</code>
+ element, those with the <code>checkbox</code> style hint could be decorated
+ with a check box icon.</p>
</section>
<!-- END processing -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
<p>The <code>gui</code> element is similar to the deprecated
<code href="http://www.docbook.org/tdg/en/html/interface.html";>interface</code>
element in DocBook. DocBook 3 introduced more specific elements for marking up
@@ -156,9 +169,7 @@ of your keyboard to meet certain accessibility needs.
on a single element. Furthermore, DocBook's various elements are nowhere near
exhaustive. Thus, authors must frequently either abuse a specific element or
use the deprecated <code>interface</code> element.</p>
-
- <p>See <link xref="principle-justenough"/> for more background.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/doc/mallard/C/mal_inline_guiseq.xml b/doc/mallard/C/mal_inline_guiseq.xml
index fefa4b6..78d9da4 100644
--- a/doc/mallard/C/mal_inline_guiseq.xml
+++ b/doc/mallard/C/mal_inline_guiseq.xml
@@ -40,13 +40,22 @@ items.</p>
<section id="notes">
<title>Notes</title>
<list type="bullet">
+ <item><p>The <code>guiseq</code> element can contain a mixture of text and
+ <code xref="mal_inline_gui">gui</code> elements.</p></item>
+
+ <item><p>The <code>guiseq</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
+
<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>guiseq</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>
+ on external-namespace attributes.</p></item>
</list>
</section>
<!-- END notes -->
@@ -66,7 +75,6 @@ a new document.
<p>Select <guiseq><gui>File</gui><gui>New</gui></guiseq> to open
a new document.</p>
</example>
-
</section>
<!-- END examples -->
@@ -75,18 +83,23 @@ a new document.
<section id="processing">
<title>Processing Expectations</title>
- <p>Display tools should show each of the child <code>gui</code> elements as
- normal, adding a separator between them. The exact separator may vary according
- to the language and style preferences, but it will typically be some sort of
+ <p>Each of the child <code>key</code> elements and text nodes, except
+ whitespace-only text nodes, is displayed as described below, adding a
+ separator between them. The exact separator may vary according to the
+ language and style preferences, but it will typically be some sort of
right-pointing arrow or triangle, or left-pointing for right-to-left
languages.</p>
+
+ <p>Child <code>gui</code> elements are shown as normal. Text nodes
+ have their whitespace normalized to strip leading and trailing spaces.
+ Text nodes may be rendered using a font variation.</p>
</section>
<!-- END processing -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
<p>The <code>guiseq</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/menuchoice.html";>menuchoice</code>
element in DocBook. Since Mallard does not provide different elements for
@@ -97,6 +110,6 @@ a new document.
element in DocBook. It is recommended that shortcuts, when necessary, be
written into prose separately.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/doc/mallard/C/mal_inline_input.xml b/doc/mallard/C/mal_inline_input.xml
index d60d4e6..1a91d77 100644
--- a/doc/mallard/C/mal_inline_input.xml
+++ b/doc/mallard/C/mal_inline_input.xml
@@ -41,21 +41,30 @@ or into a text field in a graphical application.</p>
<section id="notes">
<title>Notes</title>
<list type="bullet">
+ <item><p>The <code>input</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>input</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
+
+ <item><p>The <code>input</code> element can link to other pages or documents.
+ See <link xref="mal_attr_link"/> for more information.</p></item>
+
<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>input</code> element can have attributes from external
+ namespaces. See <link xref="mal_attr_external"/> for more information
+ on external-namespace attributes.</p></item>
+
<item><p>The <code>input</code> element, together with the
<code xref="mal_inline_output">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 treat them differently.</p></item>
-
- <item><p>The <code>input</code> element can link to other pages or documents.
- See <link xref="mal_attr_link"/> for more information.</p></item>
-
- <item><p>The <code>input</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 -->
@@ -75,21 +84,21 @@ or into a text field in a graphical application.</p>
<section id="processing">
<title>Processing Expectations</title>
- <p>User input should be displayed in a fixed-width or wide font. Fixed-width
+ <p>User input is displayed in a fixed-width or wide font. Fixed-width
fonts tend to have more distinction between visually similar characters.
- Display tools may use a background color or border to make the beginning
- and end of the input clear.</p>
+ A border or background color may be used to make the beginning and end of
+ the intput clear.</p>
</section>
<!-- END processing -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
<p>The <code>input</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/userinput.html";>userinput</code>
element in DocBook.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/doc/mallard/C/mal_inline_key.xml b/doc/mallard/C/mal_inline_key.xml
index cf7bdb1..e79ff19 100644
--- a/doc/mallard/C/mal_inline_key.xml
+++ b/doc/mallard/C/mal_inline_key.xml
@@ -44,16 +44,29 @@ these instead.</p>
<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>key</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>key</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
+
+ <item><p>The <code>key</code> element can also occur inside the
+ <code xref="mal_inline_keyseq">keyseq</code> element, where it has
+ special meaning.</p></item>
<item><p>The <code>key</code> element can link to other pages or documents.
See <link xref="mal_attr_link"/> for more information.</p></item>
+ <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>key</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>
+ on external-namespace attributes.</p></item>
</list>
</section>
<!-- END notes -->
@@ -99,15 +112,15 @@ Press the <key>Down</key> key to select the next item.
<title>Processing Expectations</title>
<p>No particular special rendering is required for <code>key</code> elements.
- Display tools may use subtle effects such as lightened text or borders to
- distinguish keys from the surrounding text.</p>
+ Keys may be rendered with lightened text or other sublte styling effects to
+ distinguish them from the surrounding text.</p>
</section>
<!-- END processing -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
<p>The <code>key</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/keycap.html";>keycap</code>
element in DocBook. Mallard does not provide elements analogous to the
@@ -117,6 +130,6 @@ Press the <key>Down</key> key to select the next item.
In most cases, these should be marked simply with the
<code xref="mal_inline_sys">sys</code> element.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/doc/mallard/C/mal_inline_keyseq.xml b/doc/mallard/C/mal_inline_keyseq.xml
index 272b2e2..bc053c0 100644
--- a/doc/mallard/C/mal_inline_keyseq.xml
+++ b/doc/mallard/C/mal_inline_keyseq.xml
@@ -24,8 +24,8 @@
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_inline_keyseq = element keyseq {
- attribute type { "combo" | "sequence" } ?,
attribute style { xsd:NMTOKENS } ?,
+ attribute type { "combo" | "sequence" } ?,
attribute * - (mal:* | local:*) { text } *,
mixed {
@@ -44,17 +44,28 @@ key press. You can use text without markup to indicate a class of keys, such as
<section id="notes">
<title>Notes</title>
<list type="bullet">
- <item><p>The <code>type</code> element indicates whether the keys should be
- pressed together (<code>"combo"</code>) or in sequence (<code>"sequence"</code>).
- The default is <code>"combo"</code>.</p></item>
+ <item><p>The <code>keyseq</code> element can contain a mixture of text,
+ <code xref="mal_inline_key">key</code> elements, and other
+ <code>keyseq</code> elements.</p></item>
+
+ <item><p>The <code>keyseq</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
+
<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>type</code> element indicates whether the keys should be
+ pressed together (<code>"combo"</code>) or in sequence (<code>"sequence"</code>).
+ The default is <code>"combo"</code>.</p></item>
+
<item><p>The <code>keyseq</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>
+ on external-namespace attributes.</p></item>
</list>
</section>
<!-- END notes -->
@@ -127,28 +138,25 @@ There are various ways to modify drag behavior by using
<section id="processing">
<title>Processing Expectations</title>
- <p>Display tools should show each of the children except whitespace-only
- text nodes, adding a separator between them. The exact separator may vary
- according to language and style preferences, and according to the
- <code>type</code> attribute. For sequences, a space is typically used.
- For combinations, the plus sign (+) is most frequently used on modern
- systems, although the hyphen (-) is still common in some areas. Display
- tools may use a style hint to choose different separators.</p>
-
- <p>Child <code>key</code> and <code>keyseq</code> elements should be shown
- as normal. Text nodes should have their whitespace normalized to strip
- leading and trailing spaces. Text nodes may be rendered using a font
- variation such as italics.</p>
-
- <p>Display tools may use subtle effects such as lightened text or borders
- to distinguish key sequences from the surrounding text.</p>
+ <p>Each of the child <code>key</code> elements and text nodes, except
+ whitespace-only text nodes, is displayed as described below, adding a
+ separator between them. The exact separator may vary according to
+ language and style preferences, and according to the <code>type</code>
+ attribute. For sequences, a space is typically used. For combinations,
+ the plus sign (+) is most frequently used on modern systems, although the
+ hyphen (-) is still common in some areas. A style hint may be used to
+ choose between different separators.</p>
+
+ <p>Child <code>key</code> and <code>keyseq</code> elements are shown as
+ normal. Text nodes have their whitespace normalized to strip leading and
+ trailing spaces. Text nodes may be rendered using a font variation.</p>
</section>
<!-- END processing -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
<p>The <code>keyseq</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/keycombo.html";>keycombo</code>
element in DocBook. Like <code>keycombo</code>, <code>keyseq</code> elements
@@ -157,6 +165,6 @@ There are various ways to modify drag behavior by using
<code href="http://www.docbook.org/tdg/en/html/mousebutton.html";>mousebutton</code>,
mouse actions in key sequences should be written as text content without markup.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/doc/mallard/C/mal_inline_link.xml b/doc/mallard/C/mal_inline_link.xml
index 01dd244..478fe0c 100644
--- a/doc/mallard/C/mal_inline_link.xml
+++ b/doc/mallard/C/mal_inline_link.xml
@@ -23,20 +23,14 @@
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_inline_link = element link {
+ ( attribute xref { text } |
+ attribute href { text } |
+ ( attribute xref { text }, attribute href { text } )
+ ),
attribute style { xsd:NMTOKENS } ?,
attribute * - (mal:* | local:*) { text } *,
- ( ( attribute xref { text },
- <link xref="mal_inline">mal_inline</link> ?
- ) |
- ( attribute dref { text },
- attribute href { text } ?,
- <link xref="mal_inline">mal_inline</link>
- ) |
- ( attribute href { text },
- <link xref="mal_inline">mal_inline</link>
- )
- )
+ <link xref="mal_inline">mal_inline</link>
}
</code></synopsis>
@@ -45,28 +39,53 @@ mal_inline_link = element link {
<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>link</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
- <item><p>The <code>link</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>
+ <item><p>The <code>link</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
<item><p>The <code>xref</code> attribute creates a link to another page
or section within the same document. When text content is omitted, the
content is automatically taken from the title of the page or section
being linked to.</p></item>
- <item><p>The <code>dref</code> attribute creates a link to a page or
- section in another document. An <code>href</code> attribute can be
- provide as a fallback for systems that don't understand document
- links.</p></item>
-
<item><p>The <code>href</code> attribute creates a link to a web page
or other network-accessible resource.</p></item>
+
+ <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>link</code> element can have attributes from external
+ namespaces. See <link xref="mal_attr_external"/> for more information
+ on external-namespace attributes.</p></item>
</list>
</section>
<!-- END notes -->
+
+<!-- BEGIN examples -->
+<section id="examples">
+ <title>Examples</title>
+</section>
+<!-- END examples -->
+
+
+<!-- BEGIN processing -->
+<section id="processing">
+ <title>Processing Expectations</title>
+</section>
+<!-- END processing -->
+
+
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
+</section>
+<!-- END comparison -->
+
</page>
diff --git a/doc/mallard/C/mal_inline_media.xml b/doc/mallard/C/mal_inline_media.xml
index 4fc37ee..1b10547 100644
--- a/doc/mallard/C/mal_inline_media.xml
+++ b/doc/mallard/C/mal_inline_media.xml
@@ -15,12 +15,12 @@
<synopsis><code mime="application/relax-ng-compact-syntax">
mal_block_media = element media {
<link xref="mal_attr_link">mal_attr_link</link> ?,
+ attribute style { xsd:NMTOKENS } ?,
attribute type { "image" | "video" | "audio" | "application" } ?,
attribute mime { text } ?,
attribute src { text },
attribute height { text },
attribute width { text },
- attribute style { xsd:NMTOKENS } ?,
attribute * - (mal:* | local:*) { text } *,
<link xref="mal_inline">mal_inline</link>
@@ -38,6 +38,18 @@ for details on how fallback elements are handled.</p>
<section id="notes">
<title>Notes</title>
<list type="bullet">
+ <item><p>The <code>media</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>media</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
+
+ <item><p>The <code>media</code> element can link to other pages or documents.
+ See <link xref="mal_attr_link"/> for more information.</p></item>
+
<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>
@@ -45,12 +57,9 @@ for details on how fallback elements are handled.</p>
<item><p>The <code>mime</code> attribute takes a valid MIME type for the
object that is being inserted.</p></item>
- <item><p>The <code>media</code> element can link to other pages or documents.
- See <link xref="mal_attr_link"/> for more information.</p></item>
-
<item><p>The <code>media</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>
+ on external-namespace attributes.</p></item>
<item><p>The <code>media</code> element may also be used in a block context.
See <link xref="mal_block_media"/> for more information.</p></item>
@@ -83,10 +92,10 @@ Drake, the Mallard mascot
<section id="processing">
<title>Processing Expectations</title>
- <p>When a <code>media</code> element occurs in an inline context, it should be
- displayed as an inline element. The exact rendering of a <code>media</code>
- element will depend on the <code>type</code> and <code>mime</code> attributes.
- Display tools may need to add controls for audio and video objects.</p>
+ <p>When a <code>media</code> element occurs in an inline context, it is displayed
+ inline. The exact rendering of a <code>media</code> element will depend on the
+ <code>type</code> and <code>mime</code> attributes. It may be necessary to add
+ controls for audio and video objects.</p>
<p>The <code>application</code> type is intended for embedding interactive
applications in documents. There are currently no specific recommendations
@@ -100,7 +109,7 @@ Drake, the Mallard mascot
reasons.</p>
<p>When a display tool cannot display a <code>media</code> element, it
- should display the child elements of the element, as if the <code>media</code>
+ displays the child elements of the element, as if the <code>media</code>
element itself were replaced by its children. The child elements may consist
of simply another <code>media</code> element referencing a different type of
content. When processing any child <code>media</code> elements, display tools
diff --git a/doc/mallard/C/mal_inline_output.xml b/doc/mallard/C/mal_inline_output.xml
index 3838961..569e5d8 100644
--- a/doc/mallard/C/mal_inline_output.xml
+++ b/doc/mallard/C/mal_inline_output.xml
@@ -48,6 +48,18 @@ differently.</p>
<section id="notes">
<title>Notes</title>
<list type="bullet">
+ <item><p>The <code>output</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>output</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
+
+ <item><p>The <code>output</code> element can link to other pages or documents.
+ See <link xref="mal_attr_link"/> for more information.</p></item>
+
<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>
@@ -66,17 +78,14 @@ differently.</p>
</tr></table>
</item>
+ <item><p>The <code>output</code> element can have attributes from external
+ namespaces. See <link xref="mal_attr_external"/> for more information
+ on external-namespace attributes.</p></item>
+
<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 treat them differently.</p></item>
-
- <item><p>The <code>output</code> element can link to other pages or documents.
- See <link xref="mal_attr_link"/> for more information.</p></item>
-
- <item><p>The <code>output</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 -->
@@ -135,16 +144,16 @@ if you use the Bourne-again shell.
<section id="processing">
<title>Processing Expectations</title>
- <p>Computer output should be displayed in a fixed-width or wide font.
- Fixed-width fonts tend to have more distinction between visually similar
- characters. Display tools may use a background color or border to
- make the beginning and end of the ouptut clear.</p>
+ <p>Computer output is displayed in a fixed-width or wide font. Fixed-width
+ fonts tend to have more distinction between visually similar characters.
+ A border or background color may be used to make the beginning and end of
+ the ouptut clear.</p>
</section>
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
<p>The <code>output</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/computeroutput.html";>computeroutput</code>
element in DocBook. When necessary, the <code>output</code> element may be used
@@ -157,6 +166,6 @@ if you use the Bourne-again shell.
<code href="http://www.docbook.org/tdg/en/html/errortext.html";>errortext</code>
elements.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/doc/mallard/C/mal_inline_quote.xml b/doc/mallard/C/mal_inline_quote.xml
index 8f3a694..f28e191 100644
--- a/doc/mallard/C/mal_inline_quote.xml
+++ b/doc/mallard/C/mal_inline_quote.xml
@@ -39,4 +39,32 @@ mal_inline_quote = element quote {
<p>style="epipgraph"</p>
</comment>
+<!-- BEGIN notes -->
+<section id="notes">
+ <title>Notes</title>
+ <list type="bullet">
+ <item><p>The <code>quote</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>quote</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
+
+ <item><p>The <code>quote</code> element can link to other pages or documents.
+ See <link xref="mal_attr_link"/> for more information.</p></item>
+
+ <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>quote</code> element can have attributes from external
+ namespaces. See <link xref="mal_attr_external"/> for more information
+ on external-namespace attributes.</p></item>
+ </list>
+</section>
+<!-- END notes -->
+
+
</page>
diff --git a/doc/mallard/C/mal_inline_span.xml b/doc/mallard/C/mal_inline_span.xml
index 2c0527d..0d1745b 100644
--- a/doc/mallard/C/mal_inline_span.xml
+++ b/doc/mallard/C/mal_inline_span.xml
@@ -24,4 +24,32 @@ mal_inline_span = element span {
}
</code></synopsis>
+
+<!-- BEGIN notes -->
+<section id="notes">
+ <title>Notes</title>
+ <list type="bullet">
+ <item><p>The <code>span</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>span</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
+
+ <item><p>The <code>span</code> element can link to other pages or documents.
+ See <link xref="mal_attr_link"/> for more information.</p></item>
+
+ <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>span</code> element can have attributes from external
+ namespaces. See <link xref="mal_attr_external"/> for more information
+ on external-namespace attributes.</p></item>
+ </list>
+</section>
+<!-- END notes -->
+
</page>
diff --git a/doc/mallard/C/mal_inline_sys.xml b/doc/mallard/C/mal_inline_sys.xml
index e5cf2cf..df0bd9f 100644
--- a/doc/mallard/C/mal_inline_sys.xml
+++ b/doc/mallard/C/mal_inline_sys.xml
@@ -27,16 +27,25 @@ mal_inline_sys = element sys {
<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>sys</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>sys</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
<item><p>The <code>sys</code> element can link to other pages or documents.
See <link xref="mal_attr_link"/> for more information.</p></item>
+ <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>sys</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>
+ on external-namespace attributes.</p></item>
</list>
</section>
<!-- END notes -->
@@ -56,9 +65,9 @@ mal_inline_sys = element sys {
<!-- END processing -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
<p>The <code>sys</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/systemitem.html";>systemitem</code>
element in DocBook. DocBook has gained numerous elements which were once
@@ -69,6 +78,6 @@ mal_inline_sys = element sys {
<p>See <link xref="principle-justenough"/> for more background.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
diff --git a/doc/mallard/C/mal_inline_var.xml b/doc/mallard/C/mal_inline_var.xml
index 7b28a21..fd22eb9 100644
--- a/doc/mallard/C/mal_inline_var.xml
+++ b/doc/mallard/C/mal_inline_var.xml
@@ -35,16 +35,25 @@ an indicated argument.</p>
<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>var</code> element can contain a mixture of text and
+ any <link xref="mal_inline">general inline elements</link>.</p></item>
+
+ <item><p>The <code>var</code> element can occur in any
+ general inline context, including inside most
+ <link xref="mal_inline">inline elements</link>, some
+ <link xref="mal_block#basic">basic block elements</link>, and certain
+ <link xref="mal_info">informational elements</link>.</p></item>
<item><p>The <code>var</code> element can link to other pages or documents.
See <link xref="mal_attr_link"/> for more information.</p></item>
+ <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>var</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>
+ on external-namespace attributes.</p></item>
<item><p>See <link xref="mal_inline_cmd"/> and <link xref="mal_inline_code"/>
for examples using <code>var</code>.</p></item>
@@ -53,13 +62,26 @@ an indicated argument.</p>
<!-- END notes -->
-<!-- BEGIN docbook -->
-<section id="docbook">
- <title>Comparison to DocBook</title>
+<!-- BEGIN processing -->
+<section id="processing">
+ <title>Processing Expectations</title>
+
+ <p>Variable text is typically displayed in an italic or oblique font. When
+ used inside a fixed-width element such as <code xref="mal_inline_cmd">cmd</code>
+ or <code xref="mal_inline_code">code</code>, it will inherit the fixed-width
+ font. In running prose, however, the <code>var</code> element does not cause
+ its contents to be displayed in a fixed-width font.</p>
+</section>
+<!-- END processing -->
+
+
+<!-- BEGIN comparison -->
+<section id="comparison">
+ <title>Comparison to Other Formats</title>
<p>The <code>var</code> element is similar to the
<code href="http://www.docbook.org/tdg/en/html/replaceable.html";>replaceable</code>
element in DocBook.</p>
</section>
-<!-- END docbook -->
+<!-- END comparison -->
</page>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
