GNOME.org
 

[gnome-doc-utils/mallard: 53/87] Adding DocBook comparisons

commit 3748e35cdef1176b95b0f6031df819123a32e94f
Author: Shaun McCance <shaunm gnome org>
Date:   Mon Dec 1 15:25:28 2008 -0600

    Adding DocBook comparisons
---
 doc/mallard/C/mal_block_code.xml    |   10 +++++++++
 doc/mallard/C/mal_inline_app.xml    |    4 +-
 doc/mallard/C/mal_inline_cmd.xml    |    4 +-
 doc/mallard/C/mal_inline_code.xml   |   39 +++++++++++++++++++++++++++-------
 doc/mallard/C/mal_inline_em.xml     |    2 +-
 doc/mallard/C/mal_inline_file.xml   |   17 +++++++++++---
 doc/mallard/C/mal_inline_gui.xml    |    6 ++--
 doc/mallard/C/mal_inline_guiseq.xml |   16 ++++++++++++++
 doc/mallard/C/mal_inline_input.xml  |   10 +++++++++
 doc/mallard/C/mal_inline_key.xml    |   15 +++++++++++++
 doc/mallard/C/mal_inline_keyseq.xml |   22 ++++++++++++++++++-
 doc/mallard/C/mal_inline_output.xml |   17 +++++++++++++++
 doc/mallard/C/mal_inline_sys.xml    |   14 ++++++++++++
 doc/mallard/C/mal_inline_var.xml    |   10 +++++++++
 14 files changed, 165 insertions(+), 21 deletions(-)

diff --git a/doc/mallard/C/mal_block_code.xml b/doc/mallard/C/mal_block_code.xml
index 7f85076..724b7e2 100644
--- a/doc/mallard/C/mal_block_code.xml
+++ b/doc/mallard/C/mal_block_code.xml
@@ -61,6 +61,16 @@ mal_block_code = element code {
 <!-- BEGIN docbook -->
 <section id="docbook">
   <title>Comparison to DocBook</title>
+  <p>DocBook contains numerous elements for modeling code in procedural and
+  object-oriented programming languages.  Many of these elements can be seen
+  by browsing the content models for the
+  <code href="http://www.docbook.org/tdg/en/html/classsynopsis.html";>classsynopsis</code>
+  and
+  <code href="http://www.docbook.org/tdg/en/html/funcsynopsis.html";>funcsynopsis</code>
+  elements.  Mallard does not attempt to model any programming languages.</p>
+
+
+
   <comment>
     <cite date="2007-01-25"><name>Shaun McCance</name></cite>
     <p>Add: code, class*, func*, programlisting</p>
diff --git a/doc/mallard/C/mal_inline_app.xml b/doc/mallard/C/mal_inline_app.xml
index 24699bd..eb870bc 100644
--- a/doc/mallard/C/mal_inline_app.xml
+++ b/doc/mallard/C/mal_inline_app.xml
@@ -86,9 +86,9 @@ the name of the command used to run an application; use
 <!-- BEGIN docbook -->
 <section id="docbook">
   <title>Comparison to DocBook</title>
-  <p>The <code>app</code> element is functionally similar to DocBook's
+  <p>The <code>app</code> element is similar to the
   <code href="http://www.docbook.org/tdg/en/html/application.html";>application</code>
-  element.</p>
+  element in DocBook.</p>
 </section>
 <!-- END docbook -->
 
diff --git a/doc/mallard/C/mal_inline_cmd.xml b/doc/mallard/C/mal_inline_cmd.xml
index 2caa11e..75873be 100644
--- a/doc/mallard/C/mal_inline_cmd.xml
+++ b/doc/mallard/C/mal_inline_cmd.xml
@@ -137,9 +137,9 @@ you to filter files based on their modification times.</p>
 <!-- BEGIN docbook -->
 <section id="docbook">
   <title>Comparison to DocBook</title>
-  <p>The <code>cmd</code> element is functionally similar to DocBook's
+  <p>The <code>cmd</code> element is similar to the
   <code href="http://www.docbook.org/tdg/en/html/command.html";>command</code>
-  element.  In DocBook, writers frequently use the
+  element in DocBook.  In DocBook, writers frequently use the
   <code href="http://www.docbook.org/tdg/en/html/option.html";>option</code>
   element inside <code>command</code>.  Mallard does not provide an element
   for this purpose.</p>
diff --git a/doc/mallard/C/mal_inline_code.xml b/doc/mallard/C/mal_inline_code.xml
index 26e5e5c..7d3b381 100644
--- a/doc/mallard/C/mal_inline_code.xml
+++ b/doc/mallard/C/mal_inline_code.xml
@@ -32,10 +32,19 @@ mal_inline_code = element code {
 }
 </code></synopsis>
 
-<comment>
-  <cite date="2006-12-08"><name>Shaun McCance</name></cite>
-  <p>Add intro material.</p>
-</comment>
+<p>The <code>code</code> elements marks a portion of text from a computer
+language.  This includes programming languages, markup languages, and the
+contents of any type of file with a structured syntax.  Commands to run in
+an interactive shell, however, should use the <code>cmd</code> element,
+even though they may include snippets of shell programming.</p>
+
+<p>The <code>code</code> element may be used to mark any portion of code,
+including comments or textual content that doesn't strictly follow any
+syntax.</p>
+
+<p>The <code xref="mal_inline_var">var</code> element may be used inside a
+<code>code</code> element to indicate text that should be replaced
+by the user.</p>
 
 
 <!-- BEGIN notes -->
@@ -86,10 +95,24 @@ mal_inline_code = element code {
 <!-- BEGIN docbook -->
 <section id="docbook">
   <title>Comparison to DocBook</title>
-  <comment>
-    <cite date="2007-01-25"><name>Shaun McCance</name></cite>
-    <p>Add: code, class*, func*, programlisting</p>
-  </comment>
+  <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
+  <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>,
+  <code href="http://www.docbook.org/tdg/en/html/function.html";>function</code>,
+  <code href="http://www.docbook.org/tdg/en/html/interfacename.html";>interfacename</code>,
+  <code href="http://www.docbook.org/tdg/en/html/methodname.html";>methodname</code>,
+  <code href="http://www.docbook.org/tdg/en/html/parameter.html";>parameter</code>,
+  <code href="http://www.docbook.org/tdg/en/html/structfield.html";>structfield</code>,
+  <code href="http://www.docbook.org/tdg/en/html/structname.html";>structname</code>, and
+  <code href="http://www.docbook.org/tdg/en/html/varname.html";>varname</code>.
+  Additionally, since Mallard does not provide separate elements for marking
+  portions of markup languages, the <code>code</code> element should be used
+  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>
 </section>
 <!-- END docbook -->
 
diff --git a/doc/mallard/C/mal_inline_em.xml b/doc/mallard/C/mal_inline_em.xml
index d06934d..b0a02e5 100644
--- a/doc/mallard/C/mal_inline_em.xml
+++ b/doc/mallard/C/mal_inline_em.xml
@@ -87,7 +87,7 @@ may be rendered differently by different processing tools.</p>
 <!-- BEGIN docbook -->
 <section id="docbook">
   <title>Comparison to DocBook</title>
-  <p>The <code>em</code> element is functionally similar to the
+  <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 processing tools allow writers to
diff --git a/doc/mallard/C/mal_inline_file.xml b/doc/mallard/C/mal_inline_file.xml
index ac072bf..5369d06 100644
--- a/doc/mallard/C/mal_inline_file.xml
+++ b/doc/mallard/C/mal_inline_file.xml
@@ -31,6 +31,11 @@ mal_inline_file = element file {
 }
 </code></synopsis>
 
+<comment>
+  <cite date="2007-01-30"><name>Shaun McCance</name></cite>
+  <p>Add examples, processing expectations</p>
+</comment>
+
 
 <!-- BEGIN notes -->
 <section id="notes">
@@ -51,9 +56,13 @@ mal_inline_file = element file {
 <!-- END notes -->
 
 
-<comment>
-  <cite date="2007-01-30"><name>Shaun McCance</name></cite>
-  <p>Add examples, processing expectations</p>
-</comment>
+<!-- BEGIN docbook -->
+<section id="docbook">
+  <title>Comparison to DocBook</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 -->
 
 </page>
diff --git a/doc/mallard/C/mal_inline_gui.xml b/doc/mallard/C/mal_inline_gui.xml
index 61e3bf1..f97bb20 100644
--- a/doc/mallard/C/mal_inline_gui.xml
+++ b/doc/mallard/C/mal_inline_gui.xml
@@ -72,10 +72,10 @@ mal_inline_gui = element gui {
 <!-- BEGIN docbook -->
 <section id="docbook">
   <title>Comparison to DocBook</title>
-  <p>The <code>gui</code> element is functionally similar to DocBook's deprecated
+  <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.  DocBook 3 introduced more specific elements for marking up parts of
-  a user interface:
+  element in DocBook.  DocBook 3 introduced more specific elements for marking up
+  parts of a user interface:
   <code href="http://www.docbook.org/tdg/en/html/guibutton.html";>guibutton</code>,
   <code href="http://www.docbook.org/tdg/en/html/guiicon.html";>guiicon</code>,
   <code href="http://www.docbook.org/tdg/en/html/guilabel.html";>guilabel</code>,
diff --git a/doc/mallard/C/mal_inline_guiseq.xml b/doc/mallard/C/mal_inline_guiseq.xml
index 8cefb78..1b334f8 100644
--- a/doc/mallard/C/mal_inline_guiseq.xml
+++ b/doc/mallard/C/mal_inline_guiseq.xml
@@ -49,4 +49,20 @@ elements.  This is typically used to to present a sequence of menu items.</p>
 </section>
 <!-- END notes -->
 
+
+<!-- BEGIN docbook -->
+<section id="docbook">
+  <title>Comparison to DocBook</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
+  different types of interface elements, the contents of <code>guiseq</code>
+  are all <code>gui</code> elements or text.  Currently, Mallard does not
+  provide a way to encode shortcut keys like the
+  <code href="http://www.docbook.org/tdg/en/html/shortcut.html";>shortcut</code>
+  element in DocBook.  It is recommended that shortcuts, when necessary, be
+  written into prose separately.</p>
+</section>
+<!-- END docbook -->
+
 </page>
diff --git a/doc/mallard/C/mal_inline_input.xml b/doc/mallard/C/mal_inline_input.xml
index 84572e6..1659f33 100644
--- a/doc/mallard/C/mal_inline_input.xml
+++ b/doc/mallard/C/mal_inline_input.xml
@@ -55,4 +55,14 @@ mal_inline_input = element input {
 </section>
 <!-- END notes -->
 
+
+<!-- BEGIN docbook -->
+<section id="docbook">
+  <title>Comparison to DocBook</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 -->
+
 </page>
diff --git a/doc/mallard/C/mal_inline_key.xml b/doc/mallard/C/mal_inline_key.xml
index 947aaed..31315fa 100644
--- a/doc/mallard/C/mal_inline_key.xml
+++ b/doc/mallard/C/mal_inline_key.xml
@@ -41,4 +41,19 @@ mal_inline_key = element key {
 </section>
 <!-- END notes -->
 
+
+<!-- BEGIN docbook -->
+<section id="docbook">
+  <title>Comparison to DocBook</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
+  DocBook elements
+  <code href="http://www.docbook.org/tdg/en/html/keysym.html";>keysym</code> and
+  <code href="http://www.docbook.org/tdg/en/html/keycode.html";>keycode</code>.
+  In most cases, these should be marked simply with the
+  <code xref="mal_inline_sys">sys</code> element.</p>
+</section>
+<!-- END docbook -->
+
 </page>
diff --git a/doc/mallard/C/mal_inline_keyseq.xml b/doc/mallard/C/mal_inline_keyseq.xml
index f96df7e..9738c8d 100644
--- a/doc/mallard/C/mal_inline_keyseq.xml
+++ b/doc/mallard/C/mal_inline_keyseq.xml
@@ -23,10 +23,13 @@
 
 <synopsis><code mime="application/relax-ng-compact-syntax">
 mal_inline_keyseq = element keyseq {
+  attribute type { "combo" | "sequence" } ?,
   attribute style { xsd:NMTOKENS } ?,
   attribute * - (mal:* | local:*) { text } *,
 
-  mixed { <link xref="mal_inline_gui">mal_inline_key</link> + }
+  mixed {
+    (<link xref="mal_inline_gui">mal_inline_key</link> | mal_inline_keyseq) *
+  }
 }
 </code></synopsis>
 
@@ -35,6 +38,10 @@ mal_inline_keyseq = element keyseq {
 <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>style</code> attribute takes a space-seperated list of
     style hints.  Processing tools should adjust their rendering according to
     those style hints they understand.</p></item>
@@ -46,4 +53,17 @@ mal_inline_keyseq = element keyseq {
 </section>
 <!-- END notes -->
 
+<!-- BEGIN docbook -->
+<section id="docbook">
+  <title>Comparison to DocBook</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
+  can be nested to indicate sequences of key combinations.  Since Mallard does
+  not provide an element analogous to the DocBook element
+  <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 -->
+
 </page>
diff --git a/doc/mallard/C/mal_inline_output.xml b/doc/mallard/C/mal_inline_output.xml
index 0daee4c..eea3dbd 100644
--- a/doc/mallard/C/mal_inline_output.xml
+++ b/doc/mallard/C/mal_inline_output.xml
@@ -69,4 +69,21 @@ mal_inline_output = element output {
 <!-- END notes -->
 
 
+<!-- BEGIN docbook -->
+<section id="docbook">
+  <title>Comparison to DocBook</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
+  with the <code>style</code> attribute <code>"prompt"</code> in place of DocBook's
+  <code href="http://www.docbook.org/tdg/en/html/prompt.html";>prompt</code>
+  element.  In some cases, it may be appropriate to use the <code>output</code>
+  element with the <code>style</code> attribute <code>"error"</code> in place
+  of DocBook's
+  <code href="http://www.docbook.org/tdg/en/html/errorname.html";>errorname</code> and
+  <code href="http://www.docbook.org/tdg/en/html/errortext.html";>errortext</code>
+  elements.</p>
+</section>
+<!-- END docbook -->
+
 </page>
diff --git a/doc/mallard/C/mal_inline_sys.xml b/doc/mallard/C/mal_inline_sys.xml
index ef92cec..1460116 100644
--- a/doc/mallard/C/mal_inline_sys.xml
+++ b/doc/mallard/C/mal_inline_sys.xml
@@ -41,4 +41,18 @@ mal_inline_sys = element sys {
 </section>
 <!-- END notes -->
 
+
+<!-- BEGIN docbook -->
+<section id="docbook">
+  <title>Comparison to DocBook</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
+  marked using the <code>class</code> attribute on the <code>systemitem</code>
+  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>
+</section>
+<!-- END docbook -->
+
 </page>
diff --git a/doc/mallard/C/mal_inline_var.xml b/doc/mallard/C/mal_inline_var.xml
index 24ffaf6..b72dcb3 100644
--- a/doc/mallard/C/mal_inline_var.xml
+++ b/doc/mallard/C/mal_inline_var.xml
@@ -41,4 +41,14 @@ mal_inline_var = element var {
 </section>
 <!-- END notes -->
 
+
+<!-- BEGIN docbook -->
+<section id="docbook">
+  <title>Comparison to DocBook</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 -->
+
 </page>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]