Merge lp:~teknico/juju-gui/reformat-docs into lp:juju-gui/experimental

[Nicola Larosa]

Reformat project docs.

Reformat the project documentation.

Sorry for the diff size. There are only formatting changes
in this branch, I moved the content changes to the next one.

https://codereview.appspot.com/7096056/

[Nicola Larosa (teknico)]

Reviewers: mp+143154_code.launchpad.net,

Message:
Please take a look.

Description:
Reformat project docs.

Reformat the project documentation.

Sorry for the diff size. There are only formatting changes
in this branch, I moved the content changes to the next one.

https://code.launchpad.net/~teknico/juju-gui/reformat-docs/+merge/143154

(do not edit description out of merge proposal)

Please review this at https://codereview.appspot.com/7096056/

Affected files:
   M HACKING
   A [revision details]
   M docs/architecture.rst
   M docs/conf.py
   M docs/d3-component-framework.rst
   M docs/process.rst

[Francesco Banconi (frankban)]

Land as is.

See just a minor comment below.
Thanks for this documentation clean up, Nicola.
The resulting HTML looks nice.

https://codereview.appspot.com/7096056/diff/1/docs/d3-component-framework.rst
File docs/d3-component-framework.rst (right):

https://codereview.appspot.com/7096056/diff/1/docs/d3-component-framework.rst#newcode91
docs/d3-component-framework.rst:91: the event handlers in the various
modules. Render will not usually need to be
Maybe Render here should be written as ``render``?

https://codereview.appspot.com/7096056/

[Nicola Larosa (teknico)]

frankban wrote:
> docs/d3-component-framework.rst:91: the event handlers in the various
modules.
> Render will not usually need to be
> Maybe Render here should be written as ``render``?

I was not sure about it because of the uppercase R needed at the start
of the line, but maybe it should, yes.

https://codereview.appspot.com/7096056/

[lp:~teknico/juju-gui/reformat-docs]

318. By Nicola Larosa on 2013-01-15

Fixes as per reviews.

[Nicola Larosa (teknico)]

Please take a look.

https://codereview.appspot.com/7096056/diff/1/HACKING
File HACKING (right):

https://codereview.appspot.com/7096056/diff/1/HACKING#newcode12
HACKING:12: You will need ``nodejs`` & ``npm`` from the PPA::
benji wrote:
> I don't understand the tendency to put literal quotes around so many
things, it
> seems like a lot of work for nothing. It appears popular in these
parts so I
> won't push the issue, but I am interested in the motivation(s).

I wanted those nouns to stand out a little, and the choice was between
NodeJS and ``nodejs``. I chose the latter because they appear monospace
in commands shortly after, but maybe it's not the best choice.

https://codereview.appspot.com/7096056/diff/1/HACKING#newcode14
HACKING:14: sudo add-apt-repository ppa:chris-lea/node.js
benji wrote:
> Two reasons I like prefixing commands with a pseudo-prompt is that
[snip]

I like them too. I removed them because Jorge Castro asked me to remove
them from the charm README which appears on
https://jujucharms.com/~juju-gui/precise/juju-gui , and it seemed best
to maintain overall consistency in the documentation. But then again,
maybe not.

https://codereview.appspot.com/7096056/diff/1/HACKING#newcode20
HACKING:20: sudo apt-get install imagemagick
benji wrote:
> There is a mixture of two- and four-space indents in this file. I
suspect we
> want one or the other. I lean slightly toward four-space indents.

Actually the indent for code/command samples is two-space all over the
docs. In this file there were a few three-space indents, fixed, thanks.

https://codereview.appspot.com/7096056/diff/1/HACKING#newcode23
HACKING:23: integration, you may want to install JSHint globally in your
system::
benji wrote:
> Should "JSHint" be literal-quoted too?

Well, again, it's a choice between the proper name and the monospace
command, but you're right, we want to be somewhat consistent. :-)

https://codereview.appspot.com/7096056/diff/1/HACKING#newcode104
HACKING:104: Running Unit Tests
benji wrote:
> This is tangential to any change you made, but I would like to suggest
that we
> consider standardizing on having two blank lines before section
headers in reST
> documents. I find that it makes the structure of the document stand
out much
> better. Much for the same reasons we use two newlines to separate the
> module-level elements in Python source.

Uhm. I see your point, I'm not sure I agree, though. The ReST markup for
section headers seem to create a good amount of whitespace already. But
I guess it's a matter of taste.

https://codereview.appspot.com/7096056/diff/1/HACKING#newcode152
HACKING:152: .. _`pertinent variable names`: `Potentially Useful
Release-Oriented Makefile Variables`_
benji wrote:
> I think this is a too-long line.

It is. Shortened.

https://codereview.appspot.com/7096056/

[Nicola Larosa (teknico)]

https://codereview.appspot.com/7096056/

[Nicola Larosa (teknico)]

*** Submitted:

Reformat project docs.

Reformat the project documentation.

Sorry for the diff size. There are only formatting changes
in this branch, I moved the content changes to the next one.

R=frankban, benji
CC=
https://codereview.appspot.com/7096056

https://codereview.appspot.com/7096056/

=== modified file 'HACKING'
--- HACKING	2013-01-03 16:13:25 +0000
+++ HACKING	2013-01-15 14:41:23 +0000
@@ -7,59 +7,58 @@
 Developer Install
 =================
 
-Juju GUI uses nodejs based development tools.
-
-You'll need nodejs & npm from the ppa::
-
-  $ sudo add-apt-repository ppa:chris-lea/node.js
-  $ sudo apt-get update
-  $ sudo apt-get install nodejs npm
+Juju GUI uses nodejs-based development tools.
+
+You will need ``nodejs`` & ``npm`` from the PPA::
+
+  sudo add-apt-repository ppa:chris-lea/node.js
+  sudo apt-get update
+  sudo apt-get install nodejs npm
 
 You also need ImageMagick::
 
-  $ sudo apt-get install imagemagick
+  sudo apt-get install imagemagick
 
 The linter will be installed locally per branch, but if you want editor
-integration, you may want to install jshint globally in your system::
-
-  $ sudo npm install -g jshint
-
-For building the docs, you also need sphinx::
-
-  $ sudo apt-get install python-sphinx
-
-To make releases, you'll need pytz::
-
-  $ sudo apt-get install python-tz
-
-The gui frontend can be installed and run with::
-
-  $ bzr branch lp:juju-gui trunk
-  $ cd trunk
-  $ make prod
+integration, you may want to install ``jshint`` globally in your system::
+
+  sudo npm install -g jshint
+
+For building the docs, you also need Sphinx::
+
+  sudo apt-get install python-sphinx
+
+To make releases, you will need PyTZ::
+
+  sudo apt-get install python-tz
+
+The Juju GUI can be installed and run with::
+
+  bzr branch lp:juju-gui trunk
+  cd trunk
+  make prod
 
 It may take a while for the server to start the first time as npm will
-need to download packages.  When ready, the server will print:
+need to download packages.  When ready, the server will print::
 
-Server listening on 8888
+  Server listening on 8888
 
 You can then access the GUI at <http://localhost:8888/>.
 
-The front-end needs to talk to a Juju backend.  So first you'll need
+The front-end needs to talk to a Juju backend.  So first you will need
 to install Juju::
 
-   $ sudo apt-get install juju zookeeper
-
-Next you'll also need to deploy a juju environment with REST api access.
-Currently that work resides in a pipeline of juju branches. The
-recommended branch to use as a server is
-``lp:~hazmat/juju/rapi-rollup``::
-
-   $ bzr branch lp:~hazmat/juju/rapi-rollup
-
-You can use it with any environment, but for dev purposes, a local
+  sudo apt-get install juju zookeeper
+
+Next you will also need to deploy a Juju environment with REST API access.
+Currently that work resides in a pipeline of Juju branches. The
+recommended branch to use as a server is ``rapi-rollup`` by hazmat::
+
+  bzr branch lp:~hazmat/juju/rapi-rollup
+
+You can use it with any environment, but for development purposes, a local
 environment works well. One environment option specific to this branch
-is the api-port. An appropriate sample configuration::
+is the ``api-port``. An appropriate sample configuration::
 
   default: dev
   environments:
@@ -71,17 +70,17 @@
       juju-origin: ppa
       api-port: 8081
 
-Note that juju-origin is set to the ppa, the api server runs outside of
-the container, and it is launched using whichever branch you're using.
+Note that ``juju-origin`` is set to the PPA, the API server runs outside of
+the container, and it is launched using whichever branch you are using.
 
-Also note that the api-port should be set at 8081, which the gui's
+Also note that the ``api-port`` should be set at 8081, which the GUI's
 initial environment connection currently defaults to.
 
-You'll need to bootstrap the local environment, and deploy one service.
-The api server needs access to the provisioning credentials which are
-lazily initialized in juju upon usage.
+You will need to bootstrap the local environment, and deploy one service.
+The API server needs access to the provisioning credentials which are
+lazily initialized in Juju upon usage.
 
-Juju-gui and rapi-rollup can communicate via an encrypted WebSockets
+``Juju-gui`` and ``rapi-rollup`` can communicate via an encrypted WebSocket
 connection: to enable it, add the following line to the config above::
 
   api-secure: true
@@ -89,38 +88,38 @@
 You will also need to edit your ``app/config.js`` replacing
 ``ws://localhost:8081/ws`` with ``wss://localhost:8081/ws``.
 
-By default, rapi-rollup uses a self-signed certificate; because of that you
-will need to visit the <https://localhost:8081/ws> WebSockets URL with your
-browser and accept the included self-signed certificate, or the WebSockets
+By default, ``rapi-rollup`` uses a self-signed certificate; because of that you
+will need to visit the <https://localhost:8081/ws> WebSocket URL with your
+browser and accept the included self-signed certificate, or the WebSocket
 encrypted connection will not work.
 
-In order to use a different certificate, you add an api-keys option to the
+In order to use a different certificate you add an ``api-keys`` option to the
 config above: its value will be the path of the directory containing the
 certificate and the private key, whose filenames will have to be respectively
 ``juju.crt`` and ``juju.key``.
 
-After this, the gui should be functional (it automatically polls the
-api server for establishing a websocket).
+After this, the GUI should be functional (it automatically polls the
+API server for establishing a websocket).
 
 Running Unit Tests
 ==================
 
-  $ make test-prod
+  make test-prod
 
 Running Lint
 ============
 
-  $ sudo apt-get install python-virtualenv
-  $ make lint
+  sudo apt-get install python-virtualenv
+  make lint
 
 API Documentation
 =================
 
-Generated JavaScript documentation is available in the yuidoc
+Generated JavaScript documentation is available in the ``yuidoc``
 directory.  You can view the docs by running::
 
-  $ make yuidoc
-  $ xdg-open yuidoc/index.html
+  make yuidoc
+  xdg-open yuidoc/index.html
 
 The `documentation <http://yui.github.com/yuidoc/syntax/>`_ for YUIDoc markup
 is available.
@@ -131,36 +130,35 @@
 The project documentation is available in the ``docs/`` directory. It needs
 Sphinx::
 
-  $ sudo apt-get install python-sphinx
+  sudo apt-get install python-sphinx
 
 Build the documentation::
 
-  $ make docs
+  make docs
 
 (This will also generate the above mentioned yuidoc documentation.)
 
 View it::
 
-  $ xdg-open docs/_build/html/index.html
+  xdg-open docs/_build/html/index.html
 
 Making Releases
 ===============
 
-To make a release, you must either be in a checkout of lp:juju-gui
+To make a release, you must either be in a checkout of ``lp:juju-gui``
 without uncommitted changes, or you must override one of the
 `pertinent variable names`_ to force a release.
 
-.. _`pertinent variable names`: `Potentially Useful Release-Oriented Makefile Variables`_
-
-
-To make the release tarball use:
-    $ make distfile
-
-In order to make and upload the release ('make dist'), you also need to have a
-gpg key, and the python-pytz package installed (as well as launchpadlib, but
-that is installed by default in Ubuntu).
-
-See the Process document (docs/process.rst) for step-by-step checklists to
+.. _`pertinent variable names`:
+    `Potentially Useful Release-Oriented Makefile Variables`_
+
+To make the release tarball use ``make distfile``.
+
+In order to make and upload the release (``make dist``), you also need to have
+a GPG key, and the ``python-pytz`` package installed (as well as
+``launchpadlib``, but that is installed by default in Ubuntu).
+
+See the Process document (``docs/process.rst``) for step-by-step checklists to
 make developer and stable releases.
 
 Potentially Useful Release-Oriented Makefile Variables
@@ -168,45 +166,45 @@
 
 The following is a list of pertinent Makefile variables.
 
-FINAL
-  Set FINAL to any non-empty value to make a final release. This will cause
-  the bzr revno to be omitted from the tarball name, and (if you use the
+``FINAL``
+  Set ``FINAL`` to any non-empty value to make a final release. This will cause
+  the ``bzr revno`` to be omitted from the tarball name, and (if you use the
   release target) will cause the release to be uploaded to the stable series
   rather than the trunk series. Example usage::
 
-    $ FINAL=1 make dist
+    FINAL=1 make dist
 
-PROD
-  By default, releases will be uploaded to staging.launchpad.net, which is a
-  separate version of Launchpad that uses a temporary database.  This can be
+``PROD``
+  By default, releases will be uploaded to ``staging.launchpad.net``, which is
+  a separate version of Launchpad that uses a temporary database.  This can be
   convenient for trying out the release process in the Makefile without
-  affecting our actual production releases.  Set PROD to any non-empty value
-  to send uploads to launchpad.net, the production version of Launchpad, when
-  you are ready to make a real release.
+  affecting our actual production releases.  Set ``PROD`` to any non-empty
+  value to send uploads to ``launchpad.net``, the production version of
+  Launchpad, when you are ready to make a real release.
 
   Note that you may need to ask the webops to turn off the two-factor
   authentication on your Launchpad staging account in order for the staging to
-  work. Go to the #launchpad-ops channel on the Canonical IRC server and ask
-  something like "webops, could you disable 2FA on my staging account?"
+  work. Go to the ``#launchpad-ops`` channel on the Canonical IRC server and
+  ask something like "webops, could you disable 2FA on my staging account?".
 
   Example usage::
 
-    $ PROD=1 make dist
+    PROD=1 make dist
 
-IS_TRUNK_BRANCH
+``IS_TRUNK_BRANCH``
   Set this to any non-empty value to force the Makefile to believe it is
   working with a trunk checkout. Example usage::
 
-    $ IS_TRUNK_BRANCH=1 make dist
+    IS_TRUNK_BRANCH=1 make dist
 
-BRANCH_IS_CLEAN
+``BRANCH_IS_CLEAN``
   Set this to any non-empty value to force the Makefile to believe that the
   current code tree has no changes. Example usage::
 
-    $ BRANCH_IS_CLEAN=1 make dist
+    BRANCH_IS_CLEAN=1 make dist
 
-BRANCH_IS_GOOD
+``BRANCH_IS_GOOD``
   Set this to any non-empty value to force the Makefile to bypass checks of
-  IS_TRUNK_BRANCH and BRANCH_IS_CLEAN. Example usage::
+  ``IS_TRUNK_BRANCH`` and ``BRANCH_IS_CLEAN``. Example usage::
 
-    $ BRANCH_IS_GOOD=1 make dist
+    BRANCH_IS_GOOD=1 make dist

=== modified file 'README'
--- README	2012-12-11 15:09:56 +0000
+++ README	2013-01-15 14:41:23 +0000
@@ -20,11 +20,11 @@
 There are no official releases of Juju-GUI yet, so you have to get the source
 code from Launchpad::
 
-  $ bzr branch lp:juju-gui
+  bzr branch lp:juju-gui
 
 The most useful available commands are shown by the command::
 
-  $ make help
+  make help
 
 You'll typically want to run one of ``make prod``,  ``make debug`` or ``make
 devel`` to deploy an environment. You might also run ``make test`` to check

=== modified file 'docs/architecture.rst'
--- docs/architecture.rst	2012-12-11 15:09:56 +0000
+++ docs/architecture.rst	2013-01-15 14:41:23 +0000
@@ -8,13 +8,13 @@
 MVC YUI
 -------
 
-Juju-gui is based on yui's backbone style app framework. The `official docs
+The Juju GUI is based on YUI's Backbone-style app framework. The `official docs
 <http://yuilibrary.com/yui/docs/app/>`_ are highly recommended for developers.
 
 An overview of the individual pieces.
 
-- `Router <http://yuilibrary.com/yui/docs/router/>`_ - Route dispatch by url,
-  saves and restores url state.
+- `Router <http://yuilibrary.com/yui/docs/router/>`_ - Route dispatch by URL,
+  saves and restores URL state.
 
 - `Views <http://yuilibrary.com/yui/docs/view/index.html>`_ - Rendering of a
   view.
@@ -26,7 +26,7 @@
 Environment Integration
 -----------------------
 
-The gui connects and communicates to the environment over a web socket
+The GUI connects and communicates to the environment over a WebSocket
 connection.
 
 RPC Calls
@@ -38,7 +38,7 @@
 RPC Events
 ----------
 
-Messages from the backend for known rpc operation results are messaged out as
+Messages from the backend for known RPC operation results are messaged out as
 Environment events.
 
 Delta Stream
@@ -66,11 +66,11 @@
   -- delta
 
 Questions
----------
+=========
 
 - Model Composition and relations.
 
-- relations by id
+- Relations by id.
 
 - We have multiple object states for a given.
 

=== modified file 'docs/conf.py'
--- docs/conf.py	2012-07-11 03:25:50 +0000
+++ docs/conf.py	2013-01-15 14:41:23 +0000
@@ -3,7 +3,8 @@
 # JujuGUI documentation build configuration file, created by
 # sphinx-quickstart on Tue Jul 10 23:15:46 2012.
 #
-# This file is execfile()d with the current directory set to its containing dir.
+# This file is execfile()d with the current directory set to its containing
+# directory.
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.
@@ -18,13 +19,13 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
 
-# -- General configuration -----------------------------------------------------
+# -- General configuration ----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = []
 
 # Add any paths that contain templates here, relative to this directory.
@@ -66,7 +67,7 @@
 # directories to ignore when looking for source files.
 exclude_patterns = ['_build']
 
-# The reST default role (used for this markup: `text`) to use for all documents.
+# The reST default role (used for this markup: `text`) for all documents.
 #default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
@@ -87,7 +88,7 @@
 #modindex_common_prefix = []
 
 
-# -- Options for HTML output ---------------------------------------------------
+# -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
@@ -167,7 +168,7 @@
 htmlhelp_basename = 'JujuGUIdoc'
 
 
-# -- Options for LaTeX output --------------------------------------------------
+# -- Options for LaTeX output -------------------------------------------------
 
 latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
@@ -180,8 +181,8 @@
 #'preamble': '',
 }
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
+# Grouping the document tree into LaTeX files. List of tuples (source
+# start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
   ('index', 'JujuGUI.tex', u'JujuGUI Documentation',
    u'Juju GUI Developers', 'manual'),
@@ -208,7 +209,7 @@
 #latex_domain_indices = True
 
 
-# -- Options for manual page output --------------------------------------------
+# -- Options for manual page output -------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
@@ -221,7 +222,7 @@
 #man_show_urls = False
 
 
-# -- Options for Texinfo output ------------------------------------------------
+# -- Options for Texinfo output -----------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,

=== modified file 'docs/d3-component-framework.rst'
--- docs/d3-component-framework.rst	2012-12-12 10:05:04 +0000
+++ docs/d3-component-framework.rst	2013-01-15 14:41:23 +0000
@@ -33,7 +33,7 @@
 bindings allow the module to respond to both changes in its underlying data and
 to changes in application state (through things like user interaction). It is
 through these bound events that most rendering and interaction with the scene
-are performed. Render becomes a rarely invoked complete redraw of the scene
+are performed. Rendering becomes a rarely invoked complete redraw of the scene
 while the modules themselves handle incremental updates via their event
 handlers.
 
@@ -46,53 +46,58 @@
 are added options can be passed that will be made available in the Module's
 run time.  Modules added via the ``addModule`` method automatically have a
 reference to the component via an YUI Attribute named ``component``, and any
-options passed to the addModule call result in an Attribute called ``options``,
-which will default to an empty object.
+options passed to the ``addModule`` call result in an Attribute called
+``options``, which will default to an empty object.
 
 ::
 
-    comp = new Component();
-    comp.addModule(MyModule, {foo: bar})
+  comp = new Component();
+  comp.addModule(MyModule, {foo: bar})
 
-This example would create a new component and, then using the MyModule
+This example would create a new component and, then using the ``MyModule``
 constructor, create an instance of this module (or use an instance if directly
 passed) and set the ``component`` and ``options`` Attributes. In this example
 the Module would have its ``foo`` option set to ``bar`` such that::
 
-    modInstance.get('options.foo') === 'bar'
+  modInstance.get('options.foo') === 'bar'
 
-where modInstance is the instance created by the above example's addModule call.
+where ``modInstance`` is the instance created by the above example's
+``addModule`` call.
 
 Components then support rendering, which draws the scene described by any data
-the modules reference. This is done in a number of phases. The first (and often
-only) time ``render`` is called, a special ``renderOnce`` is called. This
-allows the component to do any necessary setup work. Typically this will be to
-create some svg element and retain a reference to it. In the context of
-renderOnce, ``render`` will call ``update`` on each of its modules in the order
-they were added. The ``update`` method is used to recalculate any intermediate
-state associated with rendering the various data objects. This includes things
-like position information. Once ``update`` has been called each module's
-``render`` method is invoked. This performs the actual drawing work.  It is at
-this point that any d3js synthetic events are bound to the canvas (see the
-section on events below). This separation of phases exists to make the life of
-the Module writer simpler. They can rely on whatever elements they'll be drawing
-(adding children to an svg object for example) will already have its container
-properly available due to the renderOnce setup. They can also be sure that
-any ``update`` driven intermediate data will be computed and available for
-use in ``render``. This reduces the need for checks in each module to assert
-the most basic DOM state.
-
-After the initial render its expected that updates to the scene occur via the
-event handlers in the various modules. Render will not usually need to be called
-more than once unless the entire Component rendering is removed from the DOM and
-then later re-attached.
-
-The most important aspect of addModule (and its inverse removeModule) is that
-they properly support adding and removing event listeners. When a component's
-addModule method is triggered it will bind all the declarative events of the
-module, and when removeModule is called it will properly clean up event
-subscriptions. Properly defining and using events is the core of the component
-system and this is described in its own section.
+the modules reference. This is done in a number of phases.
+
+The first (and often only) time ``render`` is called, a special ``renderOnce``
+is called. This allows the component to do any necessary setup work. Typically
+this will be to create some SVG element and retain a reference to it.
+
+In the context of ``renderOnce``, ``render`` will call ``update`` on each of
+its modules in the order they were added. The ``update`` method is used to
+recalculate any intermediate state associated with rendering the various data
+objects. This includes things like position information.
+
+Once ``update`` has been called, each module's ``render`` method is invoked.
+This performs the actual drawing work. It is at this point that any D3
+synthetic events are bound to the canvas (see the section on events below).
+
+This separation of phases exists to make the life of the Module writer simpler.
+They can rely on whatever elements they'll be drawing (adding children to an
+SVG object for example) will already have its container properly available due
+to the ``renderOnce`` setup. They can also be sure that any ``update`` driven
+intermediate data will be computed and available for use in ``render``. This
+reduces the need for checks in each module to assert the most basic DOM state.
+
+After the initial render, it is expected that updates to the scene occur via
+the event handlers in the various modules. ``render`` will not usually need to
+be called more than once unless the entire Component rendering is removed from
+the DOM and then later re-attached.
+
+The most important aspect of ``addModule`` (and its inverse ``removeModule``)
+is that they properly support adding and removing event listeners. When a
+component's addModule method is triggered, it will bind all the declarative
+events of the module, and when ``removeModule`` is called it will properly
+clean up event subscriptions. Properly defining and using events is the core
+of the component system, and this is described in its own section.
 
 As a final step, if the module has a ``componentBound`` callback it will be
 invoked after successfully binding the module. This gives the module a
@@ -102,19 +107,19 @@
 Events
 ======
 
-The heart of the component system events can be defined in a number of ways and
-understanding how to take advantage of the binding features will greatly aid in
-producing a system which allows for clean, clear, well separated concerns and
-which in turn supports incremental rendering and data updates.
+Events are the heart of the component system, and can be defined in a number of
+ways. Understanding how to take advantage of the binding features will greatly
+aid in producing a system which allows for clean, clear, well separated
+concerns, and which in turn supports incremental rendering and data updates.
 
 There are three categories of events supported by the component framework. They
 each have their purpose and share some common syntax around expression in the
 module declaration, but a module writer must understand them all to properly use
 the framework.
 
-When modules are added three sets of declarative events are bound. This is done
-by including in the module an events object with the following (each optional)
-sections::
+When modules are added, three sets of declarative events are bound. This is
+done by including in the module an events object with the following (each
+optional) sections::
 
   events = {scene: {},
             d3: {}
@@ -125,8 +130,8 @@
 delegation. This has advantages in that it scales well and these events can be
 bound once to the top level container object of a component, and will work for
 a DOM element matching its selector. Scene events are defined in one of two
-ways: the first is a shorthand, the later is the more complete definition
-(you'll see this in the other events types as well).
+ways: the first is a shorthand, the second is the more complete definition
+(you will see this in the other events types as well).
 
 ::
 
@@ -136,56 +141,61 @@
 
   scene: {selector: function() {...}}
 
-Though the string name of a callback is preferred, as this makes the whole
+However, the string name of a callback is preferred, as this makes the whole
 set of events more easily readable. The final form is::
 
   scene: {selector: {callback: 'callbackName'}}
 
-This expanded format is common to the other types of event declarations as
+This expanded format is common to the other types of event declarations, as
 well as supporting options available to the other types of bindings.
 
-Regardless of form selector is a CSS selector, typically either a ``.class`` or
-an ``#id`` though pseudo-selectors work as well. With scene events these
-selectors are relative to whatever container was established on initialization
-of the Component. A concrete example might be::
+Regardless of form, ``selector`` is a CSS selector, typically either a
+``.class`` or an ``#id``, though pseudo-selectors work as well. With scene
+events, these selectors are relative to whatever container was established on
+initialization of the Component. A concrete example might be::
 
   scene: {'.person': {click: 'personClick'}}
 
 Which says that whenever an object in the scene with a ``person`` class is
-clicked, invoke the ``personClick`` handler. Handlers all have a common signature.
-To understand the calling convention you must understand a bit about how D3
-data bindings work. If you're not familiar with that, please read the D3
-documents related to data binding. The short version is that each DOM element
-can have data associated with it through D3's sophisticated data binding model.
-In the YUI world it might be common that rendered DOM elements have D3 bound
-data coming from a YUI App.Model. Knowing this we can understand the calling
-convention::
+clicked, invoke the ``personClick`` handler.
+
+Handlers all have a common signature. To understand the calling convention you
+must understand a bit about how D3 data bindings work. If you're not familiar
+with that, please read the D3 documents related to data binding.
+
+The short version is that each DOM element can have data associated with it
+through D3's sophisticated data binding model. In the YUI world it might be
+common that rendered DOM elements have D3 bound data coming from a YUI App
+Model. Knowing this we can understand the calling convention::
 
   callback(D3Data, component)
-  Where 'this' is the DOM element that triggered the selection
-  Any return is ignored.
-
-In the near future scene events will support an additional context attribute in
-their handler definition which can either be ``component`` or ``module`` and will
-default to module.
+
+Where ``this`` is the DOM element that triggered the selection. Any return is
+ignored.
+
+In the near future, scene events will support an additional context attribute
+in their handler definition which can either be ``component`` or ``module``,
+and will default to module.
 
 .. note::
 
-  At the time of this writing this is currently component and doesn't support
-  context selection. This is addressed in a branch and when landed this note
-  can be removed. It's worth noting now as the default will change.
+  At the time of this writing this is currently ``component`` and does not
+  support context selection. This is addressed in a branch, and when landed
+  this note can be removed. It is worth noting now as the default will change.
 
 The second type of event are D3 specific bindings. While declared in a style
-similar to scene events, D3 events are bound after the modules render method is
-triggered, as DOM elements must be present to be bound. There are very few cases
-to prefer this style of event binding over normal scene events; however, there
-are legitimate uses. If the event is a D3 synthetic event such as zoom or drag,
-using D3 event bindings make sense as these cannot be delegated to using scene
-events. The second case we are aware of at the time of this writing is that
-certain mouse events are dealt with more easily using D3 events, as D3 uses a
-well documented system of x, y position coordinates which the mouse events map
-cleanly. This is a possible area for future expansion both in terms of cleaner
-mouse handling and creating a possible mapping of D3 synthetics to YUI custom
+similar to scene events, D3 events are bound after the module's ``render``
+method is triggered, as DOM elements must be present to be bound. There are
+very few cases to prefer this style of event binding over normal scene events;
+however, there are legitimate uses.
+
+If the event is a D3 synthetic event such as zoom or drag, using D3 event
+bindings make sense as these cannot be delegated to using scene events. The
+second case we are aware of at the time of this writing is that certain mouse
+events are dealt with more easily using D3 events, as D3 uses a well documented
+system of x, y position coordinates which the mouse events map cleanly. This
+is a possible area for future expansion both in terms of cleaner mouse
+handling and creating a possible mapping of D3 synthetics to YUI custom
 events. An example of D3 events follows::
 
   d3: {dragstart: 'beginDrag',
@@ -195,22 +205,22 @@
 The calling convention is as above::
 
   callback(D3Data, component)
-  'this' is the DOMElement triggering the event.
-  Return value is ignored.
-
-The final type of event is called ``yui`` events. This classification doesn't
+
+``this`` is the DOMElement triggering the event. Return value is ignored.
+
+The final type of event is called ``yui`` events. This classification does not
 depend on DOM selection or delegation, and is designed to provide simple
 handling; its use case is YUI custom events. A common pattern for
 usage might be to emit events of interest (or possible interest) from one
 module and listen for those events in another. By subscribing to custom events
-across modules, it's reasonably easy to extend functionality with only a loose
+across modules, it is reasonably easy to extend functionality with only a loose
 coupling of the modules themselves (through event names only as an example).
 
 YUI events are defined similarly to the others but differ in some key ways.
-First, they don't depend on a DOM selector, they depend on a YUI styled event
+First, they do not depend on a DOM selector, they depend on a YUI styled event
 name (prefixed or otherwise). Secondly, they support a traditional YUI notion
-of event phases: ``before``, ``on`` and ``after``. For additional details on how those
-work, refer to the YUI event docs.
+of event phases: ``before``, ``on`` and ``after``. For additional details on
+how those work, refer to the YUI event docs.
 
 ::
 
@@ -222,11 +232,11 @@
 
 In this example another module might fire a ``cancelAction`` event; our module
 wants to respond to this by closing its menu before the triggering event is
-handled, and the context (this) of the callback should be this module.
+handled, and the context (``this``) of the callback should be this module.
 
-Context can either be ``component`` or ``module``, with module being the default
-``this`` for handlers. Phase can be ``before``, ``on``, or ``after``, with ``on`` being
-the default.
+Context can either be ``component`` or ``module``, with module being the
+default ``this`` for handlers. Phase can be ``before``, ``on``, or ``after``,
+with ``on`` being the default.
 
 Complete Example
 ================

=== modified file 'docs/process.rst'
--- docs/process.rst	2013-01-03 14:53:18 +0000
+++ docs/process.rst	2013-01-15 14:41:23 +0000
@@ -5,17 +5,17 @@
 Checklist for Starting a Branch
 ===============================
 
-- Understand the problem.  If you don't, ask and be persistent until you do.
+- Understand the problem.  If you do not, ask and be persistent until you do.
 - When determining a solution, consider this preferred `Software
   Architecture Cheat Sheet
-  <http://gorban.org/post/32873465932/software-architecture-cheat-sheet>`_
+  <http://gorban.org/post/32873465932/software-architecture-cheat-sheet>`_.
 - Have a pre-implementation call with someone about your solution.  If you
   are not sure of your solution, prototype before the pre-implementation call.
 - Use TDD.  Your prototype might be perfect, but you can still move it aside
   and rebuild it gradually as you add tests.  It can go quickly.
-- Update the CHANGES.yaml file with your changes.  The newest (topmost)
-  section should have the version "unreleased".  If not and you are
-  making changes, add an "unreleased" section at the top.  All other
+- Update the ``CHANGES.yaml`` file with your changes.  The newest (topmost)
+  section should have the version ``unreleased``.  If not and you are
+  making changes, add an ``unreleased`` section at the top.  All other
   version numbers follow `Semantic Versioning <http://semver.org/>`_.
 
 Checklist for Preparing for a Review
@@ -26,7 +26,7 @@
   - Pre-review your diff!  Tip: you can diff your branch against a local
     trunk named "trunk" with "bzr diff -r ancestor:../trunk/".
 
-    - All new code should have tests.  If it doesn't, be prepared to explain
+    - All new code should have tests.  If it does not, be prepared to explain
       why to skeptical reviewers.
     - Have you cleaned out temporary comments and debugging changes?
     - Is the code understandable?
@@ -35,24 +35,24 @@
   - Run tests!  Someday we'll have that in the lbox hook...
 
 - Make sure there is a bug for your branch.  Ideally there was one when you
-  started, but if not, see the "-new-bug" option to "lbox propose".
+  started, but if not, see the ``-new-bug`` option to ``lbox propose``.
 - Aim for a branch diff size between 300 and 500 lines.
 - Treat branch diff sizes of more than 800 lines as a problem.
 
-  - Try to subdivide it now.  If you can't, explain to your reviewers your
+  - Try to subdivide it now.  If you cannot, explain to your reviewers your
     reasoning.
   - Treat this as an opportunity to learn.  Consider what you could have
     done differently.
 
-- Update the CHANGES.yaml file with a description of the changes you
+- Update the ``CHANGES.yaml`` file with a description of the changes you
   made.  Reference Launchpad bugs if appropriate.
 - If the branch is very minor, such as a documentation change, feel free to
   self-review.  However, *don't neglect to consider your responsibilities
   above*, especially the diff review and running tests (even if you think
-  there's no way the tests could have been affected).
+  there is no way the tests could have been affected).
 
 It is your responsibility to get reviewers of your branch!  Reviewers will
-hopefully take it, but if they don't, rustle some up.
+hopefully take it, but if they do not, rustle some up.
 
 When you get your reviews back, be appreciative, and be sure to respond to
 every request, even if it is to disagree.
@@ -70,11 +70,11 @@
 <http://goo.gl/DBDtJ>`_.
 
 - Run ``make test-prod`` and ``make test-debug`` and confirm that tests pass.
-- Run ``python improv.py -f sample.json`` in the rapi-rollup juju branch, and
-  run ``make server`` with the juju-ui branch.
+- Run ``python improv.py -f sample.json`` in the ``rapi-rollup`` Juju branch,
+  and run ``make server`` with the ``juju-ui`` branch.
 
-  * Don't forget to clear the browser cache: index.html may be sticking around
-    because of the cache.manifest.
+  * Do not forget to clear the browser cache: ``index.html`` may be sticking
+    around because of the cache.manifest.
   * Verify that the browser reports no 404s and no Javascript errors in the
     console.
   * QA the changes if possible, exploring different use cases (and edge cases).
@@ -85,21 +85,21 @@
 - Review the diff, including notes from the above as appropriate.
 
   * Make sure that new code has tests.
-  * Make sure user-facing changes are described in CHANGES.yaml.
+  * Make sure user-facing changes are described in ``CHANGES.yaml``.
   * Make sure you can understand the new code.  Ask for clarification if
     necessary.
   * Consider the advice in this preferred `Software Architecture Cheat Sheet
     <http://gorban.org/post/32873465932/software-architecture-cheat-sheet>`_
   * Make sure changes to a file correspond to the naming conventions and other
     stylistic considerations local to that file, and within our project.
-  * Before you ask for a change, think and make sure you can't compromise
+  * Before you ask for a change, think and make sure you cannot compromise
     reasonably with the coder.  If there is a low importance disagreement, in
     general the coder's position should win.
 
 - In your summary message, thank the coder.
 - In your summary message, if you ask for changes, make it clear whether you
   want to re-review after the changes, or if you automatically approve if the
-  changes are made.  We've agreed to use these arbitrary code phrases, for
+  changes are made.  We have agreed to use these arbitrary code phrases, for
   clarity: "Land as is," "Land with changes," and "Request review".
 
 Checklist for Making a Stable Release
@@ -108,13 +108,13 @@
 - Get a clean branch of the trunk:: ``bzr branch lp:juju-gui``.
 - If you are using a pre-existing branch, make sure it is up-to-date:
   ``bzr pull``.
-- Verify that the top-most version in CHANGES.yaml specifies the expected
+- Verify that the top-most version in ``CHANGES.yaml`` specifies the expected
   version string.  It should be bigger than the most recent version found on
-  https://launchpad.net/juju-gui/stable .  If the most recent version string
-  is "unreleased," do the following.
+  <https://launchpad.net/juju-gui/stable>.  If the most recent version string
+  is ``unreleased``, do the following.
 
-  * Decide what the next version number should be (see http://semver.org/) and
-    change "unreleased" to that value.
+  * Decide what the next version number should be (see <http://semver.org/>)
+    and change ``unreleased`` to that value.
   * Commit to the branch with this checkin message:
     ``bzr commit -m 'Set version for release.'``
   * Push the branch directly to the parent (``bzr push :parent`` should work).
@@ -126,7 +126,8 @@
 - In an empty temporary directory somewhere else on your system, expand the
   tarball: ``tar xvzf PATH_TO_TARBALL``
 - While still in the directory where you extracted the tar file, change to the
-  build-prod directory and start a server: ``python -m SimpleHTTPServer 8888``.
+  ``build-prod`` directory and start a server: ``python -m SimpleHTTPServer
+  8888``.
 - In Chrome and Firefox, QA the application.  At the very least, load the app,
   open the charm panel, go to an inner page, and make sure there are no 404s
   or Javascript errors in the console.  We want a real QA script for the
@@ -139,19 +140,19 @@
 
   * Note that you may need to ask the webops to turn off the two-factor
     authentication on your Launchpad staging account in order for this to
-    work. Go to the #launchpad-ops channel on the Canonical IRC server and ask
-    something like "webops, could you disable 2FA on my staging account?"
+    work. Go to the ``#launchpad-ops`` channel on the Canonical IRC server and
+    ask something like "webops, could you disable 2FA on my staging account?"
   * When Launchpad asks you what level of permissions to grant, assuming you
     are running on your own computer that you manage securely, the easiest
     thing to do is hopefully also reasonably safe: accept that the computer
     may perform all actions, indefinitely.
 
-- Go to https://staging.launchpad.net/juju-gui/stable and verify that you see
+- Go to <https://staging.launchpad.net/juju-gui/stable> and verify that you see
   a new release and a new download file.
 - Download the file, expand it in a temporary directory, run ``python -m
   SimpleHTTPServer 8888``, and do a quick double-check in the browser that it
-  is what you expect.  Looking at juju-ui/version.js should also show you the
-  version you expect.
+  is what you expect.  Looking at ``juju-ui/version.js`` should also show you
+  the version you expect.
 - This is a final release.  Consider asking others to verify the package on
   staging.
 - Now it is time for the actual, real release.  Head back to your branch and
@@ -164,12 +165,13 @@
     is done in production will in many cases eventually be copied over to
     staging, but never vice versa.  Staging data is destroyed periodically.
 
-- Go to https://launchpad.net/juju-gui/stable and verify that you see
+- Go to <https://launchpad.net/juju-gui/stable> and verify that you see
   a new release and a new download file.
 
 - Set the version back to ``unreleased`` by doing the following.
 
-  * Restore ``- unreleased:`` as most recent version string in CHANGES.yaml.
+  * Restore ``- unreleased:`` as most recent version string in
+    ``CHANGES.yaml``.
   * Commit to the branch with this checkin message:
     ``bzr commit -m 'Set version back to unreleased.'``
   * Push the branch directly to the parent (``bzr push :parent`` should work).
@@ -182,7 +184,7 @@
 - Get a clean branch of the trunk:: ``bzr branch lp:juju-gui``.
 - If you are using a pre-existing branch, make sure it is up-to-date:
   ``bzr pull``.
-- Verify that the top-most version in CHANGES.yaml is "unreleased."
+- Verify that the top-most version in ``CHANGES.yaml`` is ``unreleased``.
 - Run ``bzr revno``.  The revno should be bigger than the most recent release
   found on `Launchpad <https://launchpad.net/juju-gui/trunk>`_.
 - Run the tests and verify they pass: ``make test-prod`` and then
@@ -192,9 +194,11 @@
 - In an empty temporary directory somewhere else on your system, expand the
   tarball: ``tar xvzf PATH_TO_TARBALL``.
 - Looking at ``build-prod/juju-ui/version.js`` should show you a version string
-  that combines the value in the branch's CHANGES.yaml with the branch's revno.
+  that combines the value in the branch's ``CHANGES.yaml`` with the branch's
+  revno.
 - While still in the directory where you extracted the tar file, change to the
-  build-prod directory and start a server: ``python -m SimpleHTTPServer 8888``.
+  ``build-prod`` directory and start a server: ``python -m SimpleHTTPServer
+  8888``.
 - In Chrome and Firefox, QA the application.  At the very least, load the app,
   open the charm panel, go to an inner page, and make sure there are no 404s
   or Javascript errors in the console.  We want a real QA script for the
@@ -207,19 +211,19 @@
 
   * Note that you may need to ask the webops to turn off the two-factor
     authentication on your Launchpad staging account in order for this to
-    work. Go to the #launchpad-ops channel on the Canonical IRC server and ask
-    something like "webops, could you disable 2FA on my staging account?"
+    work. Go to the ``#launchpad-ops`` channel on the Canonical IRC server and
+    ask something like "webops, could you disable 2FA on my staging account?"
   * When Launchpad asks you what level of permissions to grant, assuming you
     are running on your own computer that you manage securely, the easiest
     thing to do is hopefully also reasonably safe: accept that the computer
     may perform all actions, indefinitely.
 
-- Go to https://staging.launchpad.net/juju-gui/trunk and verify that you see
+- Go to <https://staging.launchpad.net/juju-gui/trunk> and verify that you see
   a new release and a new download file.
 - Download the file, expand it in a temporary directory, run ``python -m
   SimpleHTTPServer 8888``, and do a quick double-check in the browser that it
-  is what you expect.  Looking at juju-ui/version.js should also show you the
-  version you expect, as seen in the similar earlier step above.
+  is what you expect.  Looking at ``juju-ui/version.js`` should also show you
+  the version you expect, as seen in the similar earlier step above.
 - Now it is time for the actual, real release.  Head back to your branch and
   run ``PROD=1 make dist``.  The computer will again walk you through the
   process.
@@ -230,7 +234,7 @@
     is done in production will in many cases eventually be copied over to
     staging, but never vice versa.  Staging data is destroyed periodically.
 
-- Go to https://launchpad.net/juju-gui/trunk and verify that you see
+- Go to <https://launchpad.net/juju-gui/trunk> and verify that you see
   a new release and a new download file.
 
 You are done!
@@ -244,7 +248,7 @@
 Where bzr may have provided information such as the revno, sensible defaults
 are used instead.  As many of these bzr commands are used to populate
 variables regardless of the target, defining NO_BZR will have an effect on
-all targets, except dist, which will refuse to complete.
+all targets, except ``dist``, which will refuse to complete.
 
 - Note that this allows one to run any make target from the working copy,
   even if it is a lightweight checkout, by skipping steps that involve