Give it a proofreading pass.

docs/source/configuration.rst

@@ -3,24 +3,28 @@ Configuration
 =============
 
 DXR learns how to index your source trees by means of an ini-formatted
-configuration file. It gets passed to :program:`dxr-build.py` at indexing time::
+configuration file:
+
+.. include:: example-configuration.rst
+
+It gets passed to :program:`dxr-build.py` at indexing time::
 
     dxr-build.py my_config_file.config
 
 Sections
 ========
 
-The configuration file is divided into sections. The ``DXR`` section holds global
-options; other sections describe trees to be indexed.
+The configuration file is divided into sections. The ``[DXR]`` section holds
+global options; other sections describe trees to be indexed.
 
 You can use all the fancy interpolation features of Python's
 `ConfigParser <http://docs.python.org/library/configparser.html>`__ class to
 save repetition.
 
-DXR Section
------------
+[DXR] Section
+-------------
 
-Here are the options that can live in the ``DXR`` section:
+Here are the options that can live in the ``[DXR]`` section:
 
 ``target_folder``
     Where to put the built :term:`index`. **Required.**
@@ -88,8 +92,8 @@ here).
 Tree Sections
 -------------
 
-Any section that is not named ``DXR`` represents a tree to be indexed. Here are
-the options describing a tree:
+Any section that is not named ``[DXR]`` represents a tree to be indexed. Here
+are the options describing a tree:
 
 ``build_command``
     Command for building your source code. Default:
@@ -101,11 +105,11 @@ the options describing a tree:
 
 ``disabled_plugins``
    Plugins disabled in this tree, in addition to ones already disabled in the
-   ``DXR`` section. Default: ``*``
+   ``[DXR]`` section. Default: ``*``
 
 ``enabled_plugins``
     Plugins enabled in this tree. Default: ``*``. It is impossible to enable a
-    plugin not already enabled in the ``DXR`` section.
+    plugin not already enabled in the ``[DXR]`` section.
 
 ``ignore_patterns``
     Space-separated list of Unix `shell-style
@@ -129,10 +133,10 @@ Plugin-Specific Options
 =======================
 
 Options prefixed with ``plugin_`` (except ``plugin_folder``) are reserved for
-use by plugins. These options can appear in the global ``DXR`` section or in
+use by plugins. These options can appear in the global ``[DXR]`` section or in
 tree sections. Plugin developers should name their config options like
-``plugin_<plugin name>_<option>``. (See :doc:`plugins` for more details on
-plugin development.)
+``plugin_<plugin name>_<option>``. (See :ref:`writing-plugins` for more details
+on plugin development.)
 
 At the moment, all the existing plugin options are valid only in tree sections:
 

docs/source/deployment.rst

@@ -3,10 +3,10 @@ Deployment
 ==========
 
 Once you decide to put DXR into production for use by multiple people, it's
-time to move beyond the :doc:`getting-started` instructions. You need real
-machines—not Vagrant VMs—and a real web server like Apache. This chapter helps
-you deploy DXR on the Linux machines [#]_ of your choice and configure them to
-handle multi-user traffic volumes.
+time to move beyond the :doc:`getting-started` instructions. You likely need
+real machines—not Vagrant VMs—and you definitely need a robust web server like
+Apache. This chapter helps you deploy DXR on the Linux machines [#]_ of your
+choice and configure them to handle multi-user traffic volumes.
 
 DXR generates an :term:`index` for one or more source trees offline. This is
 well suited to a dedicated build server. The generated index is then
@@ -22,8 +22,8 @@ OS Packages
 
 Since you're no longer using the Vagrant VM, you'll need to install several
 packages on both your build and web servers. These are the Ubuntu package
-names, but most of them are named clearly enough to make obvious the
-equivalents on other distributions:
+names, but they should be clear enough to map to their equivalents on other
+distributions:
 
 *  make
 *  build-essential
@@ -50,7 +50,7 @@ though you'd then need to build DXR on a different machine and transfer it over.
     The list of packages above is maintained by hand and might fall behind,
     despite our best efforts. If you suspect something is missing, look at
     :file:`vagrant_provision.sh` in the DXR source tree, which does the actual
-    setup of the VM, which is itself automatically tested.
+    setup of the VM and is automatically tested.
 
 Python Packages
 ---------------
@@ -107,7 +107,9 @@ the env is activated. ::
 It's also convenient to install the TriLite library globally. Otherwise,
 :program:`dxr-build.py` will complain that it can't find the TriLite SQLite
 extension unless you prepend ``LD_LIBRARY_PATH=dxr/trilite`` at every
-invocation. To install TriLite... ::
+invocation. It's also a challenge to get a web server to see the lib, since you
+don't have a ready opportunity to interpose an environment variable. To install
+TriLite... ::
 
     cp dxr/trilite/libtrilite.so /usr/local/lib/
     sudo ldconfig
@@ -131,7 +133,7 @@ kick off the indexing process::
     for just one source tree. This is useful for building each tree on a
     different machine, though it does leave you with the task of stitching the
     resulting single-tree indexes together, a matter of moving some directories
-    around and tweaking the :file:`config.py` file.
+    around and tweaking the generated :file:`config.py` file.
 
 The index is generated in the directory specified by the ``target_folder``
 directive. It contains a minimal configuration file, a SQLite database to
@@ -142,8 +144,8 @@ Generally, you use something like cron to repeat indexing on a schedule or in
 response to source tree changes. After an indexing run, the index has to be
 made available to the web servers. One approach is to share it on a common NFS
 volume (and use an atomic :command:`mv` to swap the new one into place).
-Alternatively, you can simply copy the index to the web server. (Of course, an
-atomic :command:`mv` remains advisable.)
+Alternatively, you can simply copy the index to the web server (in which case
+an atomic :command:`mv` remains advisable, of course).
 
 
 Serving Your Index
@@ -168,8 +170,8 @@ are unable to install the TriLite library globally on your system::
 
     LD_LIBRARY_PATH=dxr/trilite dxr-serve.py target
 
-mod_wsgi
---------
+Apache and mod_wsgi
+-------------------
 
 DXR is also a WSGI application and can be deployed on Apache with mod_wsgi_, on
 uWSGI_, or on any other web server that supports the WSGI protocol.
@@ -209,9 +211,11 @@ Finally, make sure mod_wsgi is installed and enabled. Then, restart Apache::
     sudo apache2ctl stop
     sudo apache2ctl start
 
-Changes to
-:file:`/etc/apache2/envvars` don't take effect if you only run :command:`sudo
-apache2ctl restart`.
+
+.. note::
+
+    Changes to :file:`/etc/apache2/envvars` don't take effect if you run only
+    :command:`sudo apache2ctl restart`.
 
 Additional configuration might be required, depending on your version
 of Apache, your other Apache configuration, and where DXR is
@@ -246,8 +250,8 @@ Here is a complete example config, for reference::
 uWSGI
 -----
 
-uWSGI is the new hotness and well worth considering. The first person to deploy
-DXR under uWSGI should document it here.
+uWSGI_ is the new hotness and well worth considering. The first person to
+deploy DXR under uWSGI should document it here.
 
 
 Upgrading

docs/source/development.rst

@@ -2,6 +2,7 @@
 Development
 ===========
 
+
 Architecture
 ------------
 
@@ -74,8 +75,9 @@ Changes to server-side HTML templates or the DB schema:
     Run ``make`` inside :file:`tests/test_basic`.
 
 Stop :program:`dxr-serve.py`, run the build step, and then fire up the server
-again. If you're changing Python code that runs only at request time, the
-server should notice and restart itself a few seconds after you save.
+again. If you're changing Python code that runs only at request time, you
+shouldn't need to do anything; :program:`dxr-serve.py` should notice and
+restart itself a few seconds after you save.
 
 
 Testing
@@ -99,7 +101,7 @@ DXR supports two kinds of tests:
    deletes the instance. If you want to examine the instance manually
    for troubleshooting, set this to ``False``.
 
-2. A heavier sort of test which consists of a full DXR instance on disk.
+2. A heavier sort which consists of a full DXR instance on disk.
    ``test_ignores`` is an example. Within these instances are one or
    more Python files containing subclasses of ``DxrInstanceTestCase``
    which express the actual tests. These instances can be built like any
@@ -145,7 +147,7 @@ instance, of the new format, has been built before deploying the change.
 
 If you aren't sure whether to bump the format version, you can always build an
 instance using the old code, then check out the new code and try to serve the
-old instance with it. If it works, you're probably safe not bumping the format.
+old instance with it. If it works, you're probably safe not bumping the version.
 
 
 Coding Conventions
@@ -156,6 +158,8 @@ Follow `PEP 8`_ for Python code, but don't sweat the line length too much.
 .. _PEP 8: http://www.python.org/dev/peps/pep-0008/
 
 
+.. _writing-plugins:
+
 Writing Plugins
 ---------------
 
@@ -164,7 +168,7 @@ Writing Plugins
     DXR is in the middle of a plugin system redesign that will move much of
     DXR's core functionality to plugins, eliminate singletons and custom
     loading tricks, and increase the capabilities of the plugin API. This
-    chapter documents the old system.
+    section documents the old system.
 
 Structure and API
 =================
@@ -246,8 +250,8 @@ A plugin folder must contain these 3 files:
 Crash Early, Crash Often
 ========================
 
-Since DXR's indexer generally runs without manual supervision, it's best to err
-on the side of crashing rather than risk incorrectness. Any error that could
+Since DXR's indexer generally runs without manual supervision, it's better to
+err on the side of crashing than to risk incorrectness. Any error that could
 make a plugin emit inaccurate output should be fatal. This keeps DXR's
 structural queries trustworthy.
 
@@ -265,8 +269,8 @@ that plugins document their keys in the plugin section of
 :doc:`configuration`.
 
 
-FAQ
----
+Troubleshooting
+---------------
 
 Why is my copy of DXR acting erratic, failing at searches, making requests for JS templates that shouldn't exist, and just generally not appearing to be in sync with my changes?
     Did you run ``python setup.py install`` for DXR at some point? Never, ever

docs/source/download-boot-and-build.rst

@@ -14,10 +14,11 @@ Booting And Building
 
 DXR runs only on Linux at the moment (and possibly other UNIX-like operating
 systems). The easiest way to get things set up is to use the included,
-preconfigured Vagrant_ VM. You'll need Vagrant and a provider for it. We
-recommend VirtualBox.
+preconfigured Vagrant_ VM. You'll need Vagrant and a virtualization provider
+for it. We recommend VirtualBox.
 
-First, run these commands in DXR's top-level directory::
+Once you've installed VirtualBox and Vagrant, run these commands in DXR's
+top-level directory::
 
    vagrant up
    vagrant ssh

docs/source/example-configuration.rst

@@ -0,0 +1,9 @@
+::
+
+    [DXR]
+    target_folder       = /path/for/the/output
+
+    [yourproject]
+    source_folder       = /path/to/your/code
+    object_folder       = /path/to/your/code
+    build_command       = make clean; make -j $jobs

docs/source/getting-started.rst

@@ -2,7 +2,7 @@
 Getting Started
 ===============
 
-The fastest path to a working DXR instance is fourfold:
+The fastest path to a working DXR instance is...
 
 1. Get the source code you want to index.
 2. Tell DXR how to build it.
@@ -24,15 +24,9 @@ a build. (Currently, DXR supports structural queries only for C and C++.) If
 you have a simple build process powered by :command:`make`, a configuration
 like this might suffice. Place the following in a file called
 :file:`dxr.config`. The location of the file doesn't matter; the usual
-place is adjacent to your source directory. ::
+place is adjacent to your source directory.
 
-    [DXR]
-    target_folder       = /path/for/the/output
-
-    [yourproject]
-    source_folder       = /path/to/your/code
-    object_folder       = /path/to/your/code
-    build_command       = make clean; make -j $jobs
+.. include:: example-configuration.rst
 
 .. note::
 

docs/source/use.rst

@@ -5,6 +5,12 @@ Use
 Querying
 ========
 
+DXR queries are almost entirely text-based. In addition to being fast to input
+for experienced users, having an all-text representation invites handy tricks
+like `Firefox keyword bookmarks`_.
+
+.. _`Firefox keyword bookmarks`: http://kb.mozillazine.org/Using_keyword_searches
+
 A DXR query is a series of space-delimited :term:`terms<term>`:
 
 * :term:`Filtered terms<filtered term>` are structured as ``<filter name>:<argument>``:
@@ -19,20 +25,21 @@ A DXR query is a series of space-delimited :term:`terms<term>`:
   * ``hello``
   * ``three independent words``
 
-The way terms are combined is somewhat odd, and this will change in a future
-version. For now, the behavior is as follows: terms are ANDed together on a
-per-file basis and then ORed together on a per-line basis. For example, if you
-searched for ``hairy gerbils``, the results would be files containing both the
-words "hairy" and "gerbils", but the lines shown would be ones containing
-*either* "hairy" or "gerbils". The upside is that this makes comments and
-strings spanning multiple lines easy to find.
+The way terms are combined is somewhat odd and will change in a future version.
+For now, the behavior is as follows: terms are ANDed together on a per-file
+basis and then ORed together on a per-line basis. For example, if you searched
+for ``hairy gerbils``, the results would be files containing both the words
+"hairy" and "gerbils", but the lines shown would be ones containing either
+"hairy" *or* "gerbils". The upside is that this makes multi-line comments and
+strings easy to find.
 
 Quoting
 -------
 
-Single and double quotes help express literal spaces and other oddities.
-Singles can contain doubles, doubles can contain singles, and each kind can
-contain itself if backslash-escaped:
+Single and double quotes can be used in filter arguments and in text terms to
+help express literal spaces and other oddities. Singles can contain doubles,
+doubles can contain singles, and each kind can contain itself if
+backslash-escaped:
 
 * A phrase with a space: ``"Hello, world"``
 * Quotes in a plain text search, taken as literals since they're not leading:
@@ -45,12 +52,12 @@ contain itself if backslash-escaped:
 Highlighting
 ============
 
-Source code views support highlighting lines or runs of lines and sharing those
-highlighted regions.
+Source code views support highlighting lines, runs of lines, and even multiple
+runs of lines at once.
 
-There are four ways to highlight. Each way updates the hash portion of the URL
-so the highlighted lines can be restored when a page is bookmarked or shared
-via chat, bug reports, or so on.
+There are four ways to highlight. Each updates the hash portion of the URL so
+the highlighted regions are maintained when a page is bookmarked or shared via
+chat, bug reports, etc.
 
 single click
     Single-click a line to select it. Click it again to deselect it.
@@ -60,11 +67,11 @@ single click then shift-click
     After selecting a single line, hold Shift, and click a line above or below
     it to highlight the entire range between.
 
-control- or commnd-click
+control- or command-click
     Hold Control or Command (depending on your OS) while clicking a line to add
     it to the set of already highlighted lines. Do it again to deselect it.
 
 control- or command-click, then shift-click
-    After selecting one or more lines, use Control- or Commnd-Click to
+    After selecting one or more lines, use Control- or Command-Click to
     highlight the first in a new range of lines. Then, Shift-click, and the
     second range will be added to the existing highlighted set.