Use more direct language in the intro text

6 files changed, 47 insertions, 32 deletions

diff --git a/doc/mallard/C/mal_inline_app.xml b/doc/mallard/C/mal_inline_app.xml
index 5b0ad48..1e71006 100644
--- a/doc/mallard/C/mal_inline_app.xml
+++ b/doc/mallard/C/mal_inline_app.xml
@@ -6,7 +6,7 @@
 <info>
   <link type="guide" xref="mal_inline#elements"/>
 
-  <version number="0.1" date="2007-02-08" status="review"/>
+  <version number="0.1" date="2008-12-12" status="review"/>
 
   <credit type="author">
     <name>Shaun McCance</name>
@@ -34,10 +34,10 @@ mal_inline_app = element app {
 }
 </code></synopsis>
 
-<p>The <code>app</code> element marks the human-readable name of an application
-or the title of a window within an application.  It should not be used to mark
-the name of the command used to run an application; use
-<code xref="mal_inline_cmd">cmd</code> for this purpose instead.</p>
+<p>Use the <code>app</code> element to mark up the human-readable name of an
+application or the title of a window within an application.  Do not use the
+<code>app</code> element to mark up the command used to run an application;
+use <code xref="mal_inline_cmd">cmd</code> for this purpose instead.</p>
 
 
 <!-- BEGIN notes -->
@@ -62,7 +62,9 @@ the name of the command used to run an application; use
 <!-- 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
@@ -71,6 +73,16 @@ the command line.
     <p>To start <app>Totem Movie Player</app>, enter <cmd>totem</cmd> at the
     command line.</p>
   </example>
+
+  <p>Use <code>app</code> to refer to a window:</p>
+
+  <example>
+    <code><![CDATA[
+Use the <app>Theme Preferences</app> window to adjust the look of
+your desktop.
+]]></code>
+    <p>Use the <app>Theme Preferences</app> window to adjust the look of your desktop.</p>
+  </example>
 </section>
 <!-- END examples -->
 
diff --git a/doc/mallard/C/mal_inline_cmd.xml b/doc/mallard/C/mal_inline_cmd.xml
index edee802..add468b 100644
--- a/doc/mallard/C/mal_inline_cmd.xml
+++ b/doc/mallard/C/mal_inline_cmd.xml
@@ -35,18 +35,19 @@ mal_inline_cmd = element cmd {
 }
 </code></synopsis>
 
-<p>The <code>cmd</code> element marks a command or a portion of a command run
-in a shell.  It is frequently used to mark the command to run an application.
-It should not be used to mark the human-readable name of an application; use
+<p>Use the <code>cmd</code> element to mark up a command or a portion of a
+command to run in an interactive shell.  It is frequently used to mark up
+the command to run an application.  Do not use the <code>cmd</code> element
+to mark up the human-readable name of an application; use
 <code xref="mal_inline_app">app</code> for this purpose instead.</p>
 
-<p>The <code>cmd</code> element may be used to mark the entire command,
-including all arguments.  Mallard does not contain elements to mark the
+<p>You may use the <code>cmd</code> element to mark up the entire command,
+including all arguments.  Mallard does not contain elements to mark up the
 arguments specifically, as there is rarely a need to distinguish them.
-The <code>cmd</code> element may also be used to mark parts of a command,
+You may also use the <code>cmd</code> element to mark up parts of a command,
 such as options and arguments, when these need to be referenced alone.</p>
 
-<p>The <code xref="mal_inline_var">var</code> element may be used inside a
+<p>Use the <code xref="mal_inline_var">var</code> element inside a
 <code>cmd</code> element to indicate text that should be replaced
 by the user.</p>
 
diff --git a/doc/mallard/C/mal_inline_code.xml b/doc/mallard/C/mal_inline_code.xml
index a09b4ba..08f387c 100644
--- a/doc/mallard/C/mal_inline_code.xml
+++ b/doc/mallard/C/mal_inline_code.xml
@@ -32,17 +32,18 @@ mal_inline_code = element code {
 }
 </code></synopsis>
 
-<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
+<p>Use the <code>code</code> element to mark up 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.  For commands
+which are run in an interactive shell, however, you should use the
+<code xref="mal_inline_cmd">cmd</code> element, even though they may
+include snippets of shell programming.</p>
+
+<p>You can use the <code>code</code> element to mark up any portion of
+code, including comments or textual content that doesn't strictly follow
+any syntax.</p>
+
+<p>Use the <code xref="mal_inline_var">var</code> element inside a
 <code>code</code> element to indicate text that should be replaced
 by the user.</p>
 
diff --git a/doc/mallard/C/mal_inline_em.xml b/doc/mallard/C/mal_inline_em.xml
index a619b1b..d0df6f0 100644
--- a/doc/mallard/C/mal_inline_em.xml
+++ b/doc/mallard/C/mal_inline_em.xml
@@ -31,10 +31,10 @@ mal_inline_em = element em {
 }
 </code></synopsis>
 
-<p>The <code>em</code> element indicates that its enclosed text should be
-emphasized.  You may use <code>em</code> to stress certain words in a sentence.
-Do not use <code>em</code> to effect a particular typographic style, since it
-may be rendered differently by different processing tools.</p>
+<p>Use the <code>em</code> element to emphasize text.  You may use <code>em</code>
+to stress certain words in a sentence.  Do not use <code>em</code> to effect a
+particular typographic style, since it may be rendered differently by different
+processing tools.</p>
 
 
 <!-- BEGIN notes -->
diff --git a/doc/mallard/C/mal_inline_file.xml b/doc/mallard/C/mal_inline_file.xml
index 69ea5b7..38e6202 100644
--- a/doc/mallard/C/mal_inline_file.xml
+++ b/doc/mallard/C/mal_inline_file.xml
@@ -31,9 +31,9 @@ mal_inline_file = element file {
 }
 </code></synopsis>
 
-<p>The <code>file</code> element marks the name of a file or directory.
-It may also be used to mark collections or portions of filenames, such
-as search paths and file extensions.</p>
+<p>Use the <code>file</code> element to mark up the name of a file or
+directory.  You may also use it to mark up collections or portions of
+filenames, such as search paths and file extensions.</p>
 
 
 <!-- BEGIN notes -->
diff --git a/doc/mallard/C/mal_inline_guiseq.xml b/doc/mallard/C/mal_inline_guiseq.xml
index 5c96050..9fa7ce0 100644
--- a/doc/mallard/C/mal_inline_guiseq.xml
+++ b/doc/mallard/C/mal_inline_guiseq.xml
@@ -31,8 +31,9 @@ mal_inline_guiseq = element guiseq {
 }
 </code></synopsis>
 
-<p>The <code>guiseq</code> element marks a sequence of graphical interface
-elements.  This is typically used to present a sequence of menu items.</p>
+<p>Use the <code>guiseq</code> element to mark up a sequence of graphical
+interface elements.  This is typically used to present a sequence of menu
+items.</p>
 
 
 <!-- BEGIN notes -->