[KSS-checkins] r51975 - kukit/kss.base/trunk/src/kss/base

[gotcha at codespeak.net]

Author: gotcha
Date: Sat Mar  1 09:06:17 2008
New Revision: 51975

Modified:
   kukit/kss.base/trunk/src/kss/base/selectors.txt
Log:
Some hopefully better wording


Modified: kukit/kss.base/trunk/src/kss/base/selectors.txt
==============================================================================
--- kukit/kss.base/trunk/src/kss/base/selectors.txt	(original)
+++ kukit/kss.base/trunk/src/kss/base/selectors.txt	Sat Mar  1 09:06:17 2008
@@ -1,10 +1,11 @@
 Selectors
 =========
 
-The selector is responsible for finding the nodes on which to operate.
-Selectors are executed on the client. Most of them has a single parameter.
+In the client, the selectors are used to find the DOM nodes on which to operate.
+The selectors need to be serialized from the server to the client.
 
 A base class is provided for all selectors.
+Most of them have a single parameter.
 
   >>> from kss.base.selectors import Selector
 
@@ -32,7 +33,7 @@
   >>> htmlid.type
   'htmlid'
 
-They both need a value to operate on.
+Both constructors demand a value.
 
   >>> selector = css('div.main a')
   >>> selector.type
@@ -46,9 +47,11 @@
   >>> selector.value
   'someid'
   
-There are also two somewhat different selectors. The first is special
-in that it selects the same node that was used to call the server
-action. Also note that it does not accept any arguments.
+There are also two somewhat different selectors.
+
+The first is special in that it selects the same node
+that was used to call the server action. 
+Note that its constructor does not accept any arguments.
 
   >>> from kss.base.selectors import samenode
   >>> samenode.type
@@ -59,7 +62,7 @@
   >>> selector.value
   ''
 
-Another core selector is parentnode. This one can be used to use a CSS
+The second selector is `parentnode`. It uses a CSS
 query which only operates on nodes that are the parent (or
 grandparents).
 
@@ -76,8 +79,9 @@
 -------------------------------
 
 Suppose a plugin registers a new selector. It must overwrite type, and
-__init__.  The type of the selector should always be in namespace-name
-notation. Only the core selectors can do without a namespace.
+__init__.  The type of the selector should always be specified as
+`namespace-name`.
+Only the core selectors can do without a namespace.
 
   >>> from kss.base.selectors import Selector
   >>> class MyFunkySelector(Selector):
@@ -85,8 +89,8 @@
   ...     def __init__(self, value):
   ...         self.value = value
 
-We will use this class to create selector instances. In real
-life, the plugin would register this class now with the plugin
+We will use this class to create selector instances. In actual
+code, the plugin would register this class with the plugin
 registry, and the commandset code would look up the class from
 the registry. However, we test the registration somewhere
 else, and just use the class as it is for now:
@@ -103,7 +107,7 @@
   >>> selector.value
   'Selector value'
 
-Currently only the "value" property will be marshalled to the
+Currently, only the `value` property will be marshalled to the
 client. Selectors must therefore have their parameter stored as
 `value`.
 
@@ -118,3 +122,4 @@
 
   >>> print css('div.content')
   css('div.content')
+