Doc updates

* fixed some language
* fixed some consistency issues
* fixed some 80-line-width issues
* fixed some typos and markup problems

4 files changed, 142 insertions, 132 deletions

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
index 093f492c..1e22ad2d 100644
--- a/docs/source/configuration.rst
+++ b/docs/source/configuration.rst
@@ -19,13 +19,13 @@ mediagoblin.ini
   tweak settings for MediaGoblin, you'll usually tweak them here.
 
 paste.ini
-  This is primarily a server configuration file, on the python side
-  (specifically, on the wsgi side, via `paste deploy
+  This is primarily a server configuration file, on the Python side
+  (specifically, on the WSGI side, via `paste deploy
   <http://pythonpaste.org/deploy/>`_ / `paste script
   <http://pythonpaste.org/script/>`_).  It also sets up some
   middleware that you can mostly ignore, except to configure
   sessions... more on that later.  If you are adding a different
-  python server other than fastcgi / plain http, you might configure
+  Python server other than fastcgi / plain HTTP, you might configure
   it here.  You probably won't need to change this file very much.
 
 
@@ -47,19 +47,23 @@ Let's assume you're doing the virtualenv setup described elsewhere in this
 manual, and you need to make local tweaks to the config files. How do you do 
 that? Let's see.
 
-To make changes to mediagoblin.ini:
+To make changes to mediagoblin.ini ::
 
-  cp mediagoblin.ini mediagoblin_local.ini
+    cp mediagoblin.ini mediagoblin_local.ini
 
-To make changes to paste.ini:
-  cp paste.ini paste_local.ini
+To make changes to paste.ini ::
+
+    cp paste.ini paste_local.ini
 
 From here you should be able to make direct adjustments to the files,
 and most of the commands described elsewhere in this manual will "notice"
 your local config files and use those instead of the non-local version.
 
-(Note that all commands provide a way to pass in a specific config
-file also, usually by a -cf flag.)
+.. note::
+
+   Note that all commands provide a way to pass in a specific config
+   file also, usually by a ``-cf`` flag.
+
 
 Common changes
 ==============
@@ -69,9 +73,9 @@ Enabling email notifications
 
 You'll almost certainly want to enable sending emails.  By default,
 MediaGoblin doesn't really do this... for the sake of developer
-convenience, it runs in "email debug mode".  Change this:
+convenience, it runs in "email debug mode".  Change this::
 
-  email_debug_mode = false
+    email_debug_mode = false
 
 You can (and should) change the "from" email address by setting
 ``email_sender_address``.
@@ -82,21 +86,21 @@ If you have more custom SMTP settings, you also have the following
 options at your disposal, which are all optional, and do exactly what
 they sound like.
 
- - email_smtp_host
- - email_smtp_port
- - email_smtp_user
- - email_smtp_pass
+- email_smtp_host
+- email_smtp_port
+- email_smtp_user
+- email_smtp_pass
 
 All other configuration changes
 -------------------------------
 
-To be perfectly honest, there are quite a few options and I'm not
-going to be able to get to documanting them all in time for 0.1.0.
+To be perfectly honest, there are quite a few options and we haven't had
+time to document them all
 
 So here's a cop-out section saying that if you get into trouble, hop
-onto IRC and we'll help you out:
+onto IRC and we'll help you out::
 
-  #mediagoblin on irc.freenode.net
+    #mediagoblin on irc.freenode.net
 
 Celery
 ======
diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst
index 14b2c9cf..4aded2e6 100644
--- a/docs/source/deploying.rst
+++ b/docs/source/deploying.rst
@@ -11,9 +11,11 @@ it simple with some assumptions and use a setup that combines
 mediagoblin + virtualenv + fastcgi + nginx on a .deb or .rpm based
 GNU/Linux distro.
 
-Note: these tools are for administrators wanting to deploy a fresh
-install.  If instead you want to join in as a contributor, see our
-`Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_ instead.
+.. note::
+
+   These tools are for site administrators wanting to deploy a fresh
+   install.  If instead you want to join in as a contributor, see our
+   `Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_ instead.
 
 Prepare System
 --------------
@@ -33,12 +35,15 @@ MediaGoblin has the following core dependencies:
 On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
 derivatives) issue the following command: ::
 
-  sudo apt-get install mongodb git-core python python-dev python-lxml python-imaging python-virtualenv
+    sudo apt-get install mongodb git-core python python-dev python-lxml \
+        python-imaging python-virtualenv
 
 On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
 following command: ::
 
-  yum install mongodb-server python-paste-deploy python-paste-script git-core python python-devel python-lxml python-imaging python-virtualenv
+    yum install mongodb-server python-paste-deploy python-paste-script \
+        git-core python python-devel python-lxml python-imaging \
+        python-virtualenv
 
 Configure MongoDB
 ~~~~~~~~~~~~~~~~~
@@ -46,10 +51,11 @@ Configure MongoDB
 After installing MongoDB some preliminary database configuration may
 be necessary.
 
-Ensure that MongoDB `journaling <http://www.mongodb.org/display/DOCS/Journaling>`_
-is enabled. Journaling is enabled by default in version 2.0 and later
-64-bit MongoDB instances. Check your deployment, and consider enabling
-journaling if you're running 32-bit systems or earlier version.
+Ensure that MongoDB `journaling
+<http://www.mongodb.org/display/DOCS/Journaling>`_ is enabled. Journaling
+is enabled by default in version 2.0 and later 64-bit MongoDB instances.
+Check your deployment, and consider enabling journaling if you're running
+32-bit systems or earlier version.
 
 .. warning::
 
@@ -77,41 +83,42 @@ create "system account" or dedicated service user. Ensure that it is
 not possible to log in to your system with as this user.
 
 You should create a working directory for MediaGoblin. This document
-assumes your local git repository will be located at  ``/srv/mediagoblin.example.org/mediagoblin/``
-for this documentation. Substitute your prefer ed local deployment path
-as needed.
+assumes your local git repository will be located at 
+``/srv/mediagoblin.example.org/mediagoblin/`` for this documentation.
+Substitute your prefer ed local deployment path as needed.
 
 This document assumes that all operations are performed as this
 user. To drop privileges to this user, run the following command: ::
 
+      su - [mediagoblin]
 
-      su - [mediagoblin]``
-
-Where, "``[mediagoblin]`` is the username of the system user that will
+Where, "``[mediagoblin]``" is the username of the system user that will
 run MediaGoblin.
 
 Install MediaGoblin and Virtualenv
 ----------------------------------
 
-As of |version|, MediaGoblin has a rapid development pace. As a result
-the following instructions recommend installing from the ``master``
-branch of the git repository. Eventually production deployments will
-want to transition to running from more consistent releases.
+.. note::
+
+   As of |version|, MediaGoblin has a rapid development pace. As a result
+   the following instructions recommend installing from the ``master``
+   branch of the git repository. Eventually production deployments will
+   want to transition to running from more consistent releases.
 
 Issue the following commands, to create and change the working
-directory. Modify these commands to reflect your own environment: ::
+directory. Modify these commands to reflect your own environment::
 
-     mkdir -p /srv/mediagoblin.example.org/
-     cd /srv/mediagoblin.example.org/
+    mkdir -p /srv/mediagoblin.example.org/
+    cd /srv/mediagoblin.example.org/
 
-Clone the MediaGoblin repository: ::
+Clone the MediaGoblin repository::
 
-     git clone git://gitorious.org/mediagoblin/mediagoblin.git
+    git clone git://gitorious.org/mediagoblin/mediagoblin.git
 
-And setup the in-package virtualenv: ::
+And setup the in-package virtualenv::
 
-     cd mediagoblin
-     virtualenv . && ./bin/python setup.py develop
+    cd mediagoblin
+    virtualenv . && ./bin/python setup.py develop
 
 .. note::
 
@@ -127,16 +134,16 @@ more reliable and considerably easier to configure and illustrate. If
 you're familiar with Python packaging you may consider deploying with
 your preferred the method.
 
-Assuming you are going to deploy with fastcgi, you should also install
-flup: ::
+Assuming you are going to deploy with FastCGI, you should also install
+flup::
 
-     ./bin/easy_install flup
+    ./bin/easy_install flup
 
 This concludes the initial configuration of the development
 environment. In the future, if at any point you want update your
-codebase, you should also run: ::
+codebase, you should also run::
 
-     ./bin/python setup.py develop --upgrade && ./bin/gmg migrate.
+    ./bin/python setup.py develop --upgrade && ./bin/gmg migrate.
 
 Deploy MediaGoblin Services
 ---------------------------
@@ -145,9 +152,9 @@ Test the Server
 ~~~~~~~~~~~~~~~
 
 At this point MediaGoblin should be properly installed.  You can
-test the deployment with the following command: ::
+test the deployment with the following command::
 
-     ./lazyserver.sh --server-name=broadcast
+    ./lazyserver.sh --server-name=broadcast
 
 You should be able to connect to the machine on port 6543 in your
 browser to confirm that the service is operable.
@@ -156,7 +163,7 @@ Connect the Webserver to MediaGoblin with FastCGI
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This section describes how to configure MediaGoblin to work via
-fastcgi. Our configuration example will use nginx, however, you may
+FastCGI. Our configuration example will use nginx, however, you may
 use any webserver of your choice as long as it supports the FastCGI
 protocol. If you do not already have a web server, consider nginx, as
 the configuration files may be more clear than the
@@ -166,78 +173,78 @@ Create a configuration file at
 ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
 into a directory that will be included in your ``nginx`` configuration
 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
-one of the following commands (as the root user:) ::
+one of the following commands (as the root user)::
 
-     ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
-     ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
+    ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
+    ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
 
 Modify these commands and locations depending on your preferences and
 the existing configuration of your nginx instance. The contents of
-this ``nginx.conf`` file should be modeled on the following: ::
-
-     server {
-      #################################################
-      # Stock useful config options, but ignore them :)
-      #################################################
-      include /etc/nginx/mime.types;
-
-      autoindex off;
-      default_type  application/octet-stream;
-      sendfile on;
-
-      # Gzip
-      gzip on;
-      gzip_min_length 1024;
-      gzip_buffers 4 32k;
-      gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css;
-
-      #####################################
-      # Mounting MediaGoblin stuff
-      # This is the section you should read
-      #####################################
-
-      # Change this to update the upload size limit for your users
-      client_max_body_size 8m;
-
-      server_name mediagoblin.example.org www.mediagoblin.example.org;
-      access_log /var/log/nginx/mediagoblin.example.access.log;
-      error_log /var/log/nginx/mediagoblin.example.error.log;
-
-      # MediaGoblin's stock static files: CSS, JS, etc.
-      location /mgoblin_static/ {
-         alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/;
-      }
-
-      # Instance specific media:
-      location /mgoblin_media/ {
-         alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/;
-      }
-
-      # Mounting MediaGoblin itself via fastcgi.
-      location / {
-         fastcgi_pass 127.0.0.1:26543;
-         include /etc/nginx/fastcgi_params;
-
-         # our understanding vs nginx's handling of script_name vs
-         # path_info don't match :)
-         fastcgi_param PATH_INFO $fastcgi_script_name;
-         fastcgi_param SCRIPT_NAME "";
-      }
+this ``nginx.conf`` file should be modeled on the following::
+
+    server {
+     #################################################
+     # Stock useful config options, but ignore them :)
+     #################################################
+     include /etc/nginx/mime.types;
+
+     autoindex off;
+     default_type  application/octet-stream;
+     sendfile on;
+
+     # Gzip
+     gzip on;
+     gzip_min_length 1024;
+     gzip_buffers 4 32k;
+     gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css;
+
+     #####################################
+     # Mounting MediaGoblin stuff
+     # This is the section you should read
+     #####################################
+
+     # Change this to update the upload size limit for your users
+     client_max_body_size 8m;
+
+     server_name mediagoblin.example.org www.mediagoblin.example.org;
+     access_log /var/log/nginx/mediagoblin.example.access.log;
+     error_log /var/log/nginx/mediagoblin.example.error.log;
+
+     # MediaGoblin's stock static files: CSS, JS, etc.
+     location /mgoblin_static/ {
+        alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/;
+     }
+
+     # Instance specific media:
+     location /mgoblin_media/ {
+        alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/;
+     }
+
+     # Mounting MediaGoblin itself via FastCGI.
+     location / {
+        fastcgi_pass 127.0.0.1:26543;
+        include /etc/nginx/fastcgi_params;
+
+        # our understanding vs nginx's handling of script_name vs
+        # path_info don't match :)
+        fastcgi_param PATH_INFO $fastcgi_script_name;
+        fastcgi_param SCRIPT_NAME "";
      }
+    }
 
 Now, nginx instance is configured to serve the MediaGoblin
 application. Perform a quick test to ensure that this configuration
 works. Restart nginx so it picks up your changes, with a command that
-resembles one of the following (as the root user:) ::
+resembles one of the following (as the root user)::
 
-     sudo /etc/init.d/nginx restart
-     sudo /etc/rc.d/nginx restart
+    sudo /etc/init.d/nginx restart
+    sudo /etc/rc.d/nginx restart
 
 Now start MediaGoblin. Use the following command sequence as an
-example: ::
+example::
 
-     cd /srv/mediagoblin.example.org/mediagoblin/
-     ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
+    cd /srv/mediagoblin.example.org/mediagoblin/
+    ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
 
 Visit the site you've set up in your browser by visiting
 <http://mediagobilin.example.org>. You should see MediaGoblin!
diff --git a/docs/source/foreword.rst b/docs/source/foreword.rst
index 835a7e7a..aa27647f 100644
--- a/docs/source/foreword.rst
+++ b/docs/source/foreword.rst
@@ -5,14 +5,14 @@ Foreword
 About the MediaGoblin Manual
 ============================
 
-This is the user manual for MediaGoblin.  It covers how to set up and
-configure MediaGoblin and the kind of information that someone running
-MediaGoblin would need to know.
+This is the site administrator manual for MediaGoblin.  It covers how
+to set up and configure MediaGoblin and the kind of information that
+someone running MediaGoblin would need to know.
 
 We have other documentation at:
 
 * http://mediagoblin.org/join/ for general "join us" information
-* http://wiki.mediagoblin.org/ for our contributor-focused wiki
+* http://wiki.mediagoblin.org/ for our contributor/developer-focused wiki
 
 
 Improving the MediaGobiin Manual
diff --git a/docs/source/production-deployments.rst b/docs/source/production-deployments.rst
index 7bf26169..ef0bcad6 100644
--- a/docs/source/production-deployments.rst
+++ b/docs/source/production-deployments.rst
@@ -4,8 +4,7 @@ Considerations for Production Deployments
 
 This document contains a number of suggestions for deploying
 MediaGoblin in actual production environments. Consider
-":doc:`deploying`" for a basic overview of how to deploy Media
-Goblin.
+":doc:`deploying`" for a basic overview of how to deploy MediaGoblin.
 
 Deploy with Paste
 -----------------
@@ -17,11 +16,11 @@ process.
 
 Use the following command as the basis for such a script: ::
 
-       CELERY_ALWAYS_EAGER=true \
-        /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
-        /srv/mediagoblin.example.org/mediagoblin/paste.ini \
-        --pid-file=/var/run/mediagoblin.pid \
-        --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \
+    CELERY_ALWAYS_EAGER=true \
+     /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
+     /srv/mediagoblin.example.org/mediagoblin/paste.ini \
+     --pid-file=/var/run/mediagoblin.pid \
+     --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
 
 The above configuration places MediaGoblin in "always eager" mode
 with Celery, this means that submissions of content will be processed
@@ -31,11 +30,11 @@ the user will be able to immediately return to the MediaGoblin site
 while processing is ongoing. In these cases, use the following command
 as the basis for your script: ::
 
-       CELERY_ALWAYS_EAGER=false \
-        /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
-        /srv/mediagoblin.example.org/mediagoblin/paste.ini \
-        --pid-file=/var/run/mediagoblin.pid \
-        --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \
+    CELERY_ALWAYS_EAGER=false \
+     /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
+     /srv/mediagoblin.example.org/mediagoblin/paste.ini \
+     --pid-file=/var/run/mediagoblin.pid \
+     --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
 
 Separate Celery
 ---------------
@@ -57,9 +56,9 @@ such as "ASCII art" or icon sharing, you will need to run ``celeryd``
 as a separate process.
 
 Build an :ref:`init script <init-script>` around the following
-command.
+command::
 
-      CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
+    CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
 
 Modify your existing MediaGoblin and application init scripts, if
 necessary, to prevent them from starting their own ``celeryd``
@@ -77,6 +76,6 @@ distribution/operating system. In the future, MediaGoblin will provide
 example scripts as examples.
 
 .. TODO insert init script here
-.. TODO are additional concernts ?
+.. TODO are additional concerns ?
    .. Other Concerns
    .. --------------