Add some rough docs for :group and the various -group flags.

--HG--
branch : groups

5 files changed, 154 insertions, 9 deletions

diff --git a/common/locale/en-US/autocommands.xml b/common/locale/en-US/autocommands.xml
index a67e9a13..f326c104 100644
--- a/common/locale/en-US/autocommands.xml
+++ b/common/locale/en-US/autocommands.xml
@@ -41,6 +41,12 @@
             interpreted as an Ex command.
         </p>
 
+        <p>
+            If the <em>-group</em>=<a>group</a> flag is given, add this autocmd
+            to the named <t>group</t>. Any filters for <a>group</a> apply in
+            addition to <oa>pat</oa>.
+        </p>
+
         <note>
             This behavior differs from Vim's implementation in that
             <oa>pat</oa> is a regular expression rather than a glob.
diff --git a/common/locale/en-US/map.xml b/common/locale/en-US/map.xml
index e4b6256f..96a325bb 100644
--- a/common/locale/en-US/map.xml
+++ b/common/locale/en-US/map.xml
@@ -119,6 +119,7 @@
     <dt>-count</dt> <dd>Accept a count before the requisite key press. Sets the <tt>count</tt> parameter to the result. (short name <em>-c</em>)</dd>
     <dt>-description</dt> <dd>A description of this mapping (short name <em>-d</em>)</dd>
     <dt>-ex</dt> <dd>Execute <a>rhs</a> as an Ex command rather than keys (short name <em>-e</em>)</dd>
+    <dt>-group=<a>group</a></dt> <dd>Add this command to the given <t>group</t> (short name <em>-g</em>)</dd>
     <dt>-javascript</dt> <dd>Execute <a>rhs</a> as JavaScript rather than keys (short names <em>-js</em>, <em>-j</em>)</dd>
     <dt>-literal=<a>n</a></dt> <dd>Parse the <a>n</a>th argument without specially processing any quote or meta characters. (short name <em>-l</em>)</dd>
     <dt>-modes</dt> <dd>Create this mapping in the given modes (short names <em>-mode</em>, <em>-m</em>)</dd>
@@ -198,7 +199,10 @@
     <spec>:tm<oa>ap</oa></spec>
     <spec>:cm<oa>ap</oa></spec>
     <description>
-        <p>List all mappings for the applicable mode(s).</p>
+        <p>
+            List all mappings for the applicable mode(s). Mappings are
+            partitioned into <t>groups</t>.
+        </p>
     </description>
 </item>
 
@@ -561,9 +565,12 @@
 </item>
 
 <item>
-    <spec>:com<oa>mand</oa> <a>cmd</a></spec>
+    <spec>:com<oa>mand</oa> <oa>cmd</oa></spec>
     <description>
-        <p>List all user-defined commands that start with <a>cmd</a>.</p>
+        <p>
+            List all user-defined commands that start with <oa>cmd</oa>. Commands
+            are partitioned into <t>groups</t>.
+        </p>
     </description>
 </item>
 
@@ -598,11 +605,18 @@
             options when the command is defined.
         </p>
 
+        <h3 tag=":command-group">Grouping</h3>
+
+        <p>
+            The <em>-group</em> flag (short name: <em>-g</em>) can be used to
+            assign this command to a specific <t>group</t>.
+        </p>
+
         <h3 tag="E175 E176 :command-nargs">Argument handling</h3>
 
         <p>
             By default, user commands accept no arguments. This can be changed by specifying
-            the -nargs option.
+            the <tt>-nargs</tt> option.
         </p>
 
         <p>The valid values are:</p>
diff --git a/common/locale/en-US/repeat.xml b/common/locale/en-US/repeat.xml
index 56aab737..a713fa6d 100644
--- a/common/locale/en-US/repeat.xml
+++ b/common/locale/en-US/repeat.xml
@@ -133,6 +133,99 @@
 </item>
 
 
+<h2 tag="group groups">Groups</h2>
+
+<p>
+    In order to facilitate script writing, especially scripts which only
+    apply to certain web sites, many types of commands and mappings can
+    be assigned to a named group. In addition to helping identify the
+    source of such mappings in listings, and aiding in the cleanup of
+    scripts, these groups can be configured to apply only to certain web
+    sites.
+</p>
+
+<item>
+    <tags>:gr :group</tags>
+    <spec>:group<oa>!</oa> <a>group</a> …</spec>
+    <description>
+        <p>List all active <t>groups</t>.</p>
+    </description>
+</item>
+
+<item>
+    <spec>:group<oa>!</oa> <a>group</a> …</spec>
+    <description>
+        <p>
+            Select, create, or modify a <t>group</t>. After invocation,
+            <a>group</a> becomes the default group for all further commands
+            issued in the current script. If <oa>!</oa> is given the group is
+            cleared of all mappings, commands, and any other entries bound to
+            it.
+        </p>
+
+        <p>The following <a>group</a> names have special meanings:</p>
+
+        <dl>
+            <dt>builtin</dt> <dd>The default group for builtin items. Can not be modified in any way by scripts.</dd>
+            <dt>default</dt> <dd>The default group for this script.</dd>
+            <dt>user</dt> <dd>The default group for the command line and <t>&dactyl.name;rc</t>.</dd>
+        </dl>
+
+        <p>The following arguments are available:</p>
+
+        <dl>
+            <dt>-args=<a>javascript</a></dt> <dd>JavaScript Object which augments the arguments passed to commands, mappings, and autocommands (short name: <em>-a</em>)</dd>
+            <dt>-description</dt> <dd>A description of this group (short names: <em>-desc</em>, <em>-d</em>)</dd>
+            <dt>-locations=<a>filters</a></dt> <dd>The URLs for which this group should be active. See <t>site-filters</t> (short names: <em>-locs</em>, <em>-loc</em>, <em>-l</em>)</dd>
+            <dt>-nopersist</dt> <dd>Do not save this group to an auto-generated RC file (short name: <em>-n</em>)</dd>
+        </dl>
+    </description>
+</item>
+
+
+<h2 tag="site-filter site-filters">Site Filters</h2>
+
+<p>
+    Many &dactyl.appName; commands accept filters so that they may be applied
+    only to specific sites. Most of these commands accept filters in any of the
+    following formats:
+</p>
+
+<dl>
+    <dd>domain</dd>
+    <dt>
+        Any filter which is a valid domain name will match any site on that
+        domain or any sub-domain thereof. These filters may contain any letter
+        of the Roman alphabet, Arabic numerals, hyphens, and full stops.
+        Non-Latin domain names must be punycode encoded.
+    </dt>
+
+    <dd>URL prefix</dd>
+    <dt>
+        Any URL beginning with a valid protocol name and ending with a
+        <tt>*</tt> is treated as a URL prefix. It will match any URL which
+        begins with the given filter sans the trailing asterisk.
+    </dt>
+
+    <dd>Full URL</dd>
+    <dt>
+        Any URL beginning with a valid protocol name and not ending with an
+        asterisk is treated as a full URL match. It will match any page which
+        has a URL identical to the filter.
+    </dt>
+
+    <dd>Regular expression</dd>
+    <dt>
+        Any filter which does not fall into one of the above categories is
+        treated as a case-sensitive regular expression.
+    </dt>
+</dl>
+
+<p>
+    In most cases, any of the above may be prefixed with a <tt>!</tt> character
+    to invert the sense of the match.
+</p>
+
 <h2 tag="using-scripts">Using scripts</h2>
 
 <item>
@@ -157,6 +250,32 @@
             for more information.
         </p>
 
+        <h3 tag=":source-contexts">Script Contexts</h3>
+
+        <p>
+            Each script executes in its own JavaScript context. This means that
+            any global variable or function, including those defined by
+            <ex>:javascript</ex> and the <tt>-javascript</tt> flag of
+            <ex>:map</ex>, <ex>:command</ex>, and <ex>:autocmd</ex>,
+            is directly available only within the current script. Outside of the
+            current script, they can only be accessed as properties of the
+            script's global object, which is stored in the <tt>plugins</tt>
+            global under the script's full path.
+        </p>
+
+        <h3 tag=":source-groups">Script Groups</h3>
+
+        <p>
+            In addition to its own JavaScript context, each script is executed
+            with its own default <link topic="groups">group</link> into which
+            its styles, mappings, commands, and autocommands are placed. This
+            means that commands such as <ex>:comclear!</ex> can be issued
+            without fear of trampling other user-defined mappings. The command
+            <ex>:group! default</ex> can be issued to clear all such items at
+            once, and should be placed at the head of most scripts to prevent
+            the accumulation of stale items when the script is re-sourced.
+        </p>
+
         <h3 tag=":source-css">Cascading Stylesheets</h3>
 
         <p>
diff --git a/common/locale/en-US/starting.xml b/common/locale/en-US/starting.xml
index cd9ca6c9..2a6d33d1 100644
--- a/common/locale/en-US/starting.xml
+++ b/common/locale/en-US/starting.xml
@@ -95,7 +95,7 @@
                 Windows only. If this file exists, its contents
                 are executed and <tt>$MY_&dactyl.idName;RC</tt> set to its path.
             </li>
-            <li>
+            <li tag="&dactyl.name;rc ">
                 <em>~/.&dactyl.name;rc</em>
                 <strut/>
                 If this file exists, its contents are executed.
diff --git a/common/locale/en-US/styling.xml b/common/locale/en-US/styling.xml
index efa47be0..6ac53f5a 100644
--- a/common/locale/en-US/styling.xml
+++ b/common/locale/en-US/styling.xml
@@ -149,10 +149,11 @@
     <spec>:sty<oa>le</oa><oa>!</oa> <oa>-name=<a>name</a></oa> <oa>-append</oa> <a>filter</a> <oa>css</oa></spec>
     <description>
         <p>
-            Add CSS styles to the browser or to web pages. <a>filter</a> is a comma-separated
-            list of URLs to match. URLs ending with <em>*</em> are matched as prefixes, URLs not
-            containing any <em>:</em> or <em>/</em> characters are matched as domains. <oa>css</oa> is a full
-            CSS rule set (e.g., <tt>body { color: blue; }</tt>).
+            Add CSS styles to the browser or to web pages. <a>filter</a> is a
+            comma-separated list of <t>site-filters</t> for which the style will
+            apply. Regular expression filters may not be used and the <tt>!</tt>
+            character may not be used to invert the sense of the match.
+            <oa>css</oa> is a full CSS rule set (e.g., <tt>body { color: blue; }</tt>).
         </p>
 
         <p>The following options are available:</p>
@@ -166,6 +167,11 @@
                 applies to contents user interface widgets as well as normal
                 elements. (short name <em>-A</em>)</dd>
 
+            <dt>-group=<a>group</a></dt>
+            <dd>The <t>group</t> to which to add this style. Please note that
+                this grouping is for semantic and cleanup purposes only. No
+                additional site filtering is applied.</dd>
+
             <dt>-name=<a>name</a></dt>
             <dd>If provided, any existing style with the same name is
                 overridden, and the style may later be deleted using