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

[gotcha at codespeak.net]

Author: gotcha
Date: Sat Mar  1 11:55:40 2008
New Revision: 51980

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


Modified: kukit/kss.base/trunk/src/kss/base/commands.txt
==============================================================================
--- kukit/kss.base/trunk/src/kss/base/commands.txt	(original)
+++ kukit/kss.base/trunk/src/kss/base/commands.txt	Sat Mar  1 11:55:40 2008
@@ -2,14 +2,14 @@
 KSS Commands
 ============
 
-The KSS commands system allows you to create a properly formatted KSS
-response. 
+The KSS client awaits a response with properly formatted commands.
+`KSSCommands` is the server-side component that is serialized in the response. 
 
 Command renderer
 ================
 
 The command renderer is the core of the system. This object is responsible
-for create the KSS response. We will now take a look at an example to see it
+for creating the KSS response. We take a look at an example to see it
 in action.
 
   >>> from kss.base import KSSCommands
@@ -18,23 +18,23 @@
 
   >>> commands = KSSCommands()
 
-We can add commands to the renderer using the `add` method. To do this we
-also need to create a selector. In this case we will use the CSS selector.
-For more information about selectors look at the selector documentation.
+We can add commands to the renderer using the `add` method. To do this, we
+need to instantiate a selector (the CSS selector, in this example).
+For more information about selectors, look at the selector documentation.
+
+Let us add a command. The first argument is the name of the action
+which will be invoked on the client. The second argument is the selector.
+The keyword arguments become arguments to the client side action.
 
   >>> from kss.base.selectors import css
   >>> commands.add('replaceHTML', css('#someid'), html='some value')
 
-Now we have added a command. The first argument is the name of the action
-which will be invoked on the client. Our second argument is the selector.
-Any given keyword arguments become arguments to the client side action.
-
-You can add any number of commands this way. Each command will be executed
-in the order that it is added.
+You can add any number of commands this way. Commands are executed in the
+client in the order they have been added on the server.
 
   >>> commands.add('someOtherAction', css('#otherid'), arg='some arg')
 
-Now that we have a few commands we can render them.
+Now that we have a few commands, we can render them.
 
   >>> commands.render()
   '...some value...some arg...'
@@ -48,26 +48,24 @@
   >>> from xml.dom import minidom
   >>> doc = minidom.parseString(commands.render())
 
-In this case there are two commands in the response (because of the
+In this case, the response hold two commands (added in the
 previous examples). They are represented as command nodes.
 
   >>> doc.getElementsByTagName('command')
   [<DOM Element: command at ...>, <DOM Element: command at ...>]
 
-Each parameter is represented by a child node in a command. Their name
-is stored in the attribute and their value is put within text nodes or
-CDATA blocks. Which type of node is used depends on the type of
+Each parameter is represented as a child node in a command. 
+Parameter name is stored as an attribute. 
+Parameter value is put within text nodes or CDATA blocks.
+Which type of node is used depends on the type of
 the keyword argument given to the command.
 
-Depending on the type the serialisation to XML changes. Strings and
-unicode objects will be send as text nodes. You can also mark data as
-HTML, XML or CDATA blocks. This is used so that these can have special
-escaping rules.
+The serialization to XML depends on the value type.
+Strings and unicode objects ar sent as text nodes.
+You can also mark data as HTML, XML or CDATA blocks.
+These will have specific escaping rules.
 
   >>> from kss.base import xmldata, htmldata, cdatadata
-
-Now if we make a command with these types the output will be different.
-
   >>> commands = KSSCommands()
   >>> commands.add('htmlAction', css('#someid'), html=htmldata('some value'))
   >>> commands.add('cdataAction', css('#otherid'), arg=cdatadata('some arg'))
@@ -95,14 +93,13 @@
   >>> commands.render()
   '...<![CDATA[some value]]>...'
 
-CDATA nodes are used for serializing XML or HTML. This makes the
+CDATA nodes are used to serialize XML or HTML. This makes the
 response more readable when looking at it from traffic sniffers or
 other debugging tools.
 
-We have another case where CDATA is used. That is when we serialize a
-normal value larger than 4KB. This is because Firefox chops text nodes
-at 4KB blocks (which makes the client side handling more
-difficult). Using CDATA avoids the chopping.
+We have another case where CDATA is used : when we serialize text
+ value larger than 4KB. This is a workaround a Firefox bug.
+Firefox chops text nodes at 4KB blocks : this makes the client side handling more difficult). Using CDATA avoids the chopping.
 
 The example below demonstrates this behaviour.
 
@@ -127,7 +124,7 @@
 
   >>> commands = KSSCommands()
 
-By default it does nothing. 
+When empty, it is rendered a blank line. 
 
   >>> print commands
   <BLANKLINE>
@@ -138,8 +135,8 @@
   >>> print commands
   replaceHTML(css('#someid'))
 
-If you add parameters they are also shown in the string
-representation. Parameters are sorted before display to make them
+Parameters are also rendered in the string representation.
+Parameters are sorted before display to make them
 stable for testing.
 
   >>> commands = KSSCommands()
@@ -158,8 +155,7 @@
 Features for working with commands
 ==================================
 
-If we add a parameter with a `None` value it will not be put into the
-response.
+Parameter with a `None` value is not rendered into the response.
 
   >>> commands.clear()
   >>> commands.add('parameterCommand', css('#something'),
@@ -167,9 +163,8 @@
   >>> print commands
   parameterCommand(css('#something'), value='Testing')
 
-You can also use strings instead of a selector instance as a value for
-selector. In this case the string will automatically be converted to a
-selector on the client. By default this is the CSS selector.
+If the selector is a string instead of a selector class instance,
+the string is converted to a CSS selector on the client.
 
   >>> commands.clear()
   >>> commands.add('replaceHTML', '#someid', html='some value')
@@ -180,30 +175,29 @@
 Command sets
 ============
 
-A command set wraps the commands system so that you get a highlevel way to
+Command sets wrap the commands system and provide a highlevel API to
 communicate with the browser. Command sets are responsible for escaping and
-validating data and can provider a nicer api for calling.
+validating data. 
 
-We will now take a look at the base class for all commandsets.
+Let us take a look at the base class for all commandsets.
 
   >>> from kss.base.commands import KSSCommandSet
   >>> commands = KSSCommands()
   >>> commandset = KSSCommandSet(commands)
 
-All this does is wrap our commands in the command set. We can still access the
+It wraps commands in the command set. We can still access the
 commands directly by using the `commands` attribute.
 
   >>> commandset.commands
   <...KSSCommands object at ...>
 
-The thing that makes this interesting is the actual command sets. Take a look
-at the core commands for a better understanding of the usage pattern.
+Take a look at the core command set for a better understanding of the usage pattern.
 
 
 Using command sets
 ==================
 
-In the previous examples we saw how to load command sets directly. Normally we
+In the previous examples, we saw how to load command sets directly. Usually, we
 do not need to do this. This is because the command renderer can also look
 them up by name. This is done by using the KSS plugin registry.
 
@@ -213,19 +207,21 @@
   >>> from kss.base.corecommands import KSSCoreCommands
   >>> from kss.base.registry import command_set_registry
 
-Now we can register our command set. For more information about the registry look at the documentation of kss.pluginregistry.
+Now we can register our command set. (For more information about the registry
+look at the documentation of kss.pluginregistry.)
 
   >>> command_set_registry.register('core', KSSCoreCommands)
 
-To access a command set just need to create our command renderer like we do
-normally.
+Command sets are accessed as attributes on the command renderer.
 
   >>> commands = KSSCommands()
-
-We can now access the command set. This is done using attribute access.
-
   >>> commands.core.replaceInnerHTML(css('div'), 'example')
   >>> print commands
   replaceInnerHTML(css('div'), html=htmldata('example'))
-  
+
+In this case, we used `replaceInnerHTML` method that is defined in the core
+command set. This is equivalent but shorter than explicitely adding a command.
+ 
+Let us clean up.
+
   >>> command_set_registry.unregister('core')