From d06250eeefe03cfe518a2587f2753eb99460c36f Mon Sep 17 00:00:00 2001 From: Kris Maglione Date: Fri, 11 Feb 2011 03:44:23 -0500 Subject: [PATCH] Add some rough docs for :group and the various -group flags. --HG-- branch : groups --- common/content/dactyl.js | 4 +- common/locale/en-US/autocommands.xml | 6 ++ common/locale/en-US/map.xml | 22 ++++- common/locale/en-US/repeat.xml | 119 +++++++++++++++++++++++++++ common/locale/en-US/starting.xml | 2 +- common/locale/en-US/styling.xml | 14 +++- common/modules/contexts.jsm | 2 +- 7 files changed, 158 insertions(+), 11 deletions(-) diff --git a/common/content/dactyl.js b/common/content/dactyl.js index 8e9baae6..461e5a8d 100644 --- a/common/content/dactyl.js +++ b/common/content/dactyl.js @@ -678,7 +678,9 @@ var Dactyl = Module("dactyl", XPCOM(Ci.nsISupportsWeakReference, ModuleBase), { fileMap["plugins"] = function () ['text/xml;charset=UTF-8', help]; fileMap["versions"] = function () { - let NEWS = util.httpGet(config.addon.getResourceURI("NEWS").spec).responseText; + let NEWS = util.httpGet(config.addon.getResourceURI("NEWS").spec, + { mimeType: "text/plain;charset=UTF-8" }) + .responseText; let re = util.regexp( \s*) 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.

+

+ If the -group=group flag is given, add this autocmd + to the named group. Any filters for group apply in + addition to pat. +

+ This behavior differs from Vim's implementation in that pat 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 @@
-count
Accept a count before the requisite key press. Sets the count parameter to the result. (short name -c)
-description
A description of this mapping (short name -d)
-ex
Execute rhs as an Ex command rather than keys (short name -e)
+
-group=group
Add this command to the given group (short name -g)
-javascript
Execute rhs as JavaScript rather than keys (short names -js, -j)
-literal=n
Parse the nth argument without specially processing any quote or meta characters. (short name -l)
-modes
Create this mapping in the given modes (short names -mode, -m)
@@ -198,7 +199,10 @@ :tmap :cmap -

List all mappings for the applicable mode(s).

+

+ List all mappings for the applicable mode(s). Mappings are + partitioned into groups. +

@@ -561,9 +565,12 @@ - :command cmd + :command cmd -

List all user-defined commands that start with cmd.

+

+ List all user-defined commands that start with cmd. Commands + are partitioned into groups. +

@@ -598,11 +605,18 @@ options when the command is defined.

+

Grouping

+ +

+ The -group flag (short name: -g) can be used to + assign this command to a specific group. +

+

Argument handling

By default, user commands accept no arguments. This can be changed by specifying - the -nargs option. + the -nargs option.

The valid values are:

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 @@ +

Groups

+ +

+ 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. +

+ + + :gr :group + :group! group … + +

List all active groups.

+ + + + + :group! group … + +

+ Select, create, or modify a group. After invocation, + group becomes the default group for all further commands + issued in the current script. If ! is given the group is + cleared of all mappings, commands, and any other entries bound to + it. +

+ +

The following group names have special meanings:

+ +
+
builtin
The default group for builtin items. Can not be modified in any way by scripts.
+
default
The default group for this script.
+
user
The default group for the command line and &dactyl.name;rc.
+
+ +

The following arguments are available:

+ +
+
-args=javascript
JavaScript Object which augments the arguments passed to commands, mappings, and autocommands (short name: -a)
+
-description
A description of this group (short names: -desc, -d)
+
-locations=filters
The URLs for which this group should be active. See site-filters (short names: -locs, -loc, -l)
+
-nopersist
Do not save this group to an auto-generated RC file (short name: -n)
+
+ + + + +

Site Filters

+ +

+ 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: +

+ +
+
domain
+
+ 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. +
+ +
URL prefix
+
+ Any URL beginning with a valid protocol name and ending with a + * is treated as a URL prefix. It will match any URL which + begins with the given filter sans the trailing asterisk. +
+ +
Full URL
+
+ 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. +
+ +
Regular expression
+
+ Any filter which does not fall into one of the above categories is + treated as a case-sensitive regular expression. +
+
+ +

+ In most cases, any of the above may be prefixed with a ! character + to invert the sense of the match. +

+

Using scripts

@@ -157,6 +250,32 @@ for more information.

+

Script Contexts

+ +

+ Each script executes in its own JavaScript context. This means that + any global variable or function, including those defined by + :javascript and the -javascript flag of + :map, :command, and :autocmd, + 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 plugins + global under the script's full path. +

+ +

Script Groups

+ +

+ In addition to its own JavaScript context, each script is executed + with its own default group into which + its styles, mappings, commands, and autocommands are placed. This + means that commands such as :comclear! can be issued + without fear of trampling other user-defined mappings. The command + :group! default 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. +

+

Cascading Stylesheets

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 $MY_&dactyl.idName;RC set to its path. -

  • +
  • ~/.&dactyl.name;rc 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 @@ :style! -name=name -append filter css

    - Add CSS styles to the browser or to web pages. filter is a comma-separated - list of URLs to match. URLs ending with * are matched as prefixes, URLs not - containing any : or / characters are matched as domains. css is a full - CSS rule set (e.g., body { color: blue; }). + Add CSS styles to the browser or to web pages. filter is a + comma-separated list of site-filters for which the style will + apply. Regular expression filters may not be used and the ! + character may not be used to invert the sense of the match. + css is a full CSS rule set (e.g., body { color: blue; }).

    The following options are available:

    @@ -166,6 +167,11 @@ applies to contents user interface widgets as well as normal elements. (short name -A) +
    -group=group
    +
    The group to which to add this style. Please note that + this grouping is for semantic and cleanup purposes only. No + additional site filtering is applied.
    +
    -name=name
    If provided, any existing style with the same name is overridden, and the style may later be deleted using diff --git a/common/modules/contexts.jsm b/common/modules/contexts.jsm index 75f271e5..183bead1 100644 --- a/common/modules/contexts.jsm +++ b/common/modules/contexts.jsm @@ -9,7 +9,7 @@ try { Components.utils.import("resource://dactyl/bootstrap.jsm"); defineModule("contexts", { exports: ["Contexts", "Group", "contexts"], - use: ["commands", "options", "services", "storage", "styles", "util"] + use: ["commands", "options", "services", "storage", "styles", "template", "util"] }, this); var Group = Class("Group", {