Add command argument/option/quoting help information.

common/locale/en-US/all.xml

@@ -12,29 +12,29 @@
 
 <toc/>
 
-<include href="intro" tag="intro.html"/>
-<include href="starting" tag="starting.html"/>
-<include href="browsing" tag="browsing.html"/>
-<include href="buffer" tag="buffer.html"/>
-<include href="cmdline" tag="cmdline.html"/>
-<include href="insert" tag="insert.html"/>
-<include href="options" tag="options.html"/>
-<include href="pattern" tag="pattern.html"/>
-<include href="tabs" tag="tabs.html"/>
-<include href="hints" tag="hints.html"/>
-<include href="map" tag="map.html"/>
-<include href="eval" tag="eval.html"/>
-<include href="marks" tag="marks.html"/>
-<include href="repeat" tag="repeat.html"/>
-<include href="autocommands" tag="autocommands.html"/>
-<include href="print" tag="print.html"/>
-<include href="gui" tag="gui.html"/>
-<include href="styling" tag="styling.html"/>
-<include href="message" tag="message.html"/>
-<include href="developer" tag="developer.html"/>
-<include href="various" tag="various.html"/>
-<include href="plugins" tag="plugins.html"/>
-<include href="index" tag="index.html"/>
+<include href="intro" tag="intro.xml"/>
+<include href="starting" tag="starting.xml"/>
+<include href="browsing" tag="browsing.xml"/>
+<include href="buffer" tag="buffer.xml"/>
+<include href="cmdline" tag="cmdline.xml"/>
+<include href="insert" tag="insert.xml"/>
+<include href="options" tag="options.xml"/>
+<include href="pattern" tag="pattern.xml"/>
+<include href="tabs" tag="tabs.xml"/>
+<include href="hints" tag="hints.xml"/>
+<include href="map" tag="map.xml"/>
+<include href="eval" tag="eval.xml"/>
+<include href="marks" tag="marks.xml"/>
+<include href="repeat" tag="repeat.xml"/>
+<include href="autocommands" tag="autocommands.xml"/>
+<include href="print" tag="print.xml"/>
+<include href="gui" tag="gui.xml"/>
+<include href="styling" tag="styling.xml"/>
+<include href="message" tag="message.xml"/>
+<include href="developer" tag="developer.xml"/>
+<include href="various" tag="various.xml"/>
+<include href="plugins" tag="plugins.xml"/>
+<include href="index" tag="index.xml"/>
 
 </document>
 

common/locale/en-US/cmdline.xml

@@ -152,6 +152,7 @@
     </description>
 </item>
 
+
 <h2 tag="cmdline-lines">Ex command lines</h2>
 
 <item>
@@ -212,7 +213,73 @@
             </ul>
         </p>
     </description>
-    </item>
+</item>
+
+<h3 tag="cmdline-arguments">Ex command-line arguments</h3>
+
+<p>
+    Most Ex commands accept a number of options and arguments. Arguments and
+    options are generally separated by spaces, and treat a number of
+    characters, including <em>\</em>, <em>'</em>, <em>"</em>, and <em>|</em>,
+    specially.  Moreover, certain arguments have their own special characters.
+    For instance, when using <ex>:set</ex> to change a <t>stringlist</t>
+    option, the comma character is used to separate elements of said list. Or
+    when calling <ex>:autocmd</ex>, the pattern given may be negated by
+    prefixing it with a <em>!</em>. In order to use these characters in
+    command arguments, stripped of their special meaning, they must be quoted.
+</p>
+
+<p tag="cmdline-quoting quoting">
+    &dactyl.appName; offers four distinct quoting styles, each with its own
+    distinct advantages and disadvantages. The first, and most basic, is the
+    automatic quoting applied to the commands listed in <ex>:bar</ex>. When
+    any of these commands is invoked, their final argument is always
+    interpreted literally. No characters have special meaning whatsoever, and
+    no care need be taken to quote anything. Additionally, the following three
+    optional quoting characters are available:
+</p>
+
+<dl>
+    <dt>\</dt>
+    <dd>
+        This is the most basic quoting character. When it is encountered
+        outside of single or double quotes, it forces the next character to be
+        interpreted literally. So, for instance, <tt>\\</tt> ⇒ <tt>\</tt>, 
+        <tt>\'</tt> ⇒ <tt>'</tt>, <tt>\a</tt> ⇒ <tt>a</tt>, and
+        <tt>\␣</tt> ⇒ <tt>␣</tt>.
+    </dd>
+    <dt>'</dt>
+    <dd>
+        Any character inside single quotes aside from the ' character itself
+        is interpreted literally. To include a literal single quote, it must
+        be doubled. So, <code>'foo\ ''bar\\ baz\' ⇒ foo\ 'bar\\ baz\</code>
+    </dd>
+    <dt>"</dt>
+    <dd>
+        Any character inside of double quotes except for <em>"</em> and
+        <em>\</em> is interpreted literally. A literal double quote may be
+        included by preceding it with a backslash. Any other occurrence of a
+        backslash starts an escape sequence as in JavaScript strings. Among
+        the available escape sequences are:
+        <dl>
+            <dt>\n</dt> <dd>A newline character.</dd>
+            <dt>\t</dt> <dd>A tab character.</dd>
+            <dt>\0nn</dt> <dd>Where each <em>n</em> is a digit between 0 and 7, represents an octal character code.</dd>
+            <dt>\xdd</dt> <dd>Where each <em>d</em> is a digit between 0 and F, represents a hexidecimal character code.</dd>
+            <dt>\uxxxx</dt> <dd>Where each <em>x</em> is a digit between 0 and F, a Unicode character at code-point <em>xxxx</em>.</dd>
+        </dl>
+    </dd>
+</dl>
+
+<p tag="cmdline-options">
+    Many Ex commands accept option arguments in addition to regular arguments.
+    Option arguments begin with a hyphen (<em>-</em>), and often have a short
+    form and a long form, such as <em>-name</em> and <em>-n</em>. Most options
+    accept arguments, which come after the option separated by either a space
+    or an equal sign. For instance, the following three forms,
+    <ex>-name=<str>foo</str></ex>, <ex>-name <str>foo</str></ex>, and
+    <ex>-n <str>foo</str></ex>, are all acceptable and entirely equivalent.
+</p>
 
 </document>
 

pentadactyl/TODO

@@ -25,7 +25,6 @@ BUGS:
 (recent Mercurial regressions):
 
 FEATURES:
-9 Add quoting help tag
 8 Document Caret and Visual modes.
 8 replace global variables with plugin scoped user options
 8 fix local options

pentadactyl/locale/en-US/all.xml

@@ -7,7 +7,7 @@
     xmlns="&xmlns.dactyl;"
     xmlns:html="&xmlns.html;">
 
-<include href="tutorial" tag="tutorial.html" insertafter="intro.html" />
+<include href="tutorial" tag="tutorial.xml" insertafter="intro.xml" />
 
 </overlay>