Enhance and correct documentation

docs/getting_started.rst

@@ -83,15 +83,20 @@ Viewing the generated files
 ---------------------------
 
 The files generated by Pelican are static files, so you don't actually need
-anything special to view them. You can either use your browser to open the
-files on your disk::
+anything special to view them. You can use your browser to open the generated
+HTML files directly::
 
     firefox output/index.html
 
-Or run a simple web server using Python::
+Because the above method may have trouble locating your CSS and other linked
+assets, running a simple web server using Python will often provide a more
+reliable previewing experience::
 
     cd output && python -m SimpleHTTPServer
 
+Once the ``SimpleHTTPServer`` has been started, you can preview your site at
+http://localhost:8000/
+
 Upgrading
 ---------
 
@@ -452,25 +457,24 @@ And ``image-test.md`` would include::
     ![Alt Text]({filename}/images/han.jpg)
 
 Any content can be linked in this way. What happens is that the ``images``
-directory gets copied to ``output/static/`` upon publishing. This is
-because ``images`` is in the ``settings["STATIC_PATHS"]`` list by default. If
-you want to have another directory, say ``pdfs`` you would need to add the
-following to ``pelicanconf.py``::
+directory gets copied to ``output/`` during site generation because Pelican
+includes ``images`` in the ``STATIC_PATHS`` setting's list by default. If
+you want to have another directory, say ``pdfs``, copied from your content to
+your output during site generation, you would need to add the following to
+your settings file::
 
     STATIC_PATHS = ['images', 'pdfs']
 
-And then the ``pdfs`` directory would also be copied to ``output/static/``.
+After the above line has been added, subsequent site generation should copy the
+``content/pdfs/`` directory to ``output/pdfs/``.
 
 You can also link to categories or tags, using the ``{tag}tagname`` and
 ``{category}foobar`` syntax.
 
-For backward compatibility, Pelican also supports bars ``||``, besides ``{}``,
-i.e. the ``filename``, ``tag`` and ``category`` identifiers can be enclosed
-in bars ``|`` instead of braces ``{}``, for example, ``|filename|an_article.rst``,
-``|tag|tagname``,  ``|category|foobar``.
-
-Using ``{}`` ensures that the syntax will not collide with markdown extensions or
-reST directives.
+For backward compatibility, Pelican also supports bars (``||``) in addition to
+curly braces (``{}``). For example: ``|filename|an_article.rst``,
+``|tag|tagname``, ``|category|foobar``. The syntax was changed from ``||`` to
+``{}`` to avoid collision with Markdown extensions or reST directives.
 
 Importing an existing blog
 --------------------------
@@ -590,12 +594,12 @@ tagsfile        string        ctags file to use for name definitions.
 tagurlformat    string        format for the ctag links.
 =============   ============  =========================================
 
-Note that, depending on its version, your pygments module might not have
-all of these available. See the `Pygments documentation
-<http://pygments.org/docs/formatters/>`_ for the HTML formatter for more
+Note that, depending on the version, your Pygments module might not have
+all of these options available. Refer to the *HtmlFormatter* section of the
+`Pygments documentation <http://pygments.org/docs/formatters/>`_ for more
 details on each of the options.
 
-for example the below code block enables line numbers, starting at 153,
+For example, the following code block enables line numbers, starting at 153,
 and prefixes the Pygments CSS classes with *pgcss* to make the names
 more unique and avoid possible CSS conflicts::
 
@@ -606,25 +610,25 @@ more unique and avoid possible CSS conflicts::
 
        <indented code block goes here>
 
-It is also possible to specify the ``PYGMENTS_RST_OPTIONS`` variable
-in your Pelican configuration file for settings that will be
-automatically applied to every code block.
+It is also possible to specify the ``PYGMENTS_RST_OPTIONS`` variable in your
+Pelican settings file to include options that will be automatically applied to
+every code block.
 
-For example, if you wanted to have line numbers on for every code block
+For example, if you want to have line numbers displayed for every code block
 and a CSS prefix you would set this variable to::
 
-    PYGMENTS_RST_OPTIONS = { 'classprefix': 'pgcss', 'linenos': 'table'}
+    PYGMENTS_RST_OPTIONS = {'classprefix': 'pgcss', 'linenos': 'table'}
 
-If specified, settings for individual code blocks will override the
-defaults in the configuration file.
+If specified, settings for individual code blocks will override the defaults in
+your settings file.
 
 Publishing drafts
 -----------------
 
 If you want to publish an article as a draft (for friends to review before
-publishing, for example), you can add a ``status: draft`` attribute to its
+publishing, for example), you can add a ``Status: draft`` attribute to its
 metadata. That article will then be output to the ``drafts`` folder and not
-listed on the index page nor on any category page.
+listed on the index page nor on any category or tag page.
 
 .. _virtualenv: http://www.virtualenv.org/
 .. _W3C ISO 8601: http://www.w3.org/TR/NOTE-datetime