Doc fixes and improvements

docs/getting_started.rst

@@ -161,7 +161,7 @@ following syntax (give your file the ``.rst`` extension)::
     :author: Alexis Metaireau
     :summary: Short version for index and feeds
 
-Pelican implements an extension of reStructuredText to enable support for the
+Pelican implements an extension to reStructuredText to enable support for the
 ``abbr`` HTML tag. To use it, write something like this in your post::
 
     This will be turned into :abbr:`HTML (HyperText Markup Language)`.
@@ -188,16 +188,17 @@ directory in which the file resides. For example, a file located at
 ``python/foobar/myfoobar.rst`` will have a category of ``foobar``. If you would
 like to organize your files in other ways where the name of the subfolder would
 not be a good category name, you can set the setting ``USE_FOLDER_AS_CATEGORY``
-to ``False``. If summary isn't given, setting ``SUMMARY_MAX_LENGTH`` determines
-how many words from the beginning of an article are used as the summary.
+to ``False``. If there is no summary metadata for a given post, the
+``SUMMARY_MAX_LENGTH`` setting can be used to specify how many words from the
+beginning of an article are used as the summary.
 
-You can also extract any metadata from the filename through a regexp to be set
-in the ``FILENAME_METADATA`` setting.
+You can also extract any metadata from the filename through a regular
+expression to be set in the ``FILENAME_METADATA`` setting.
 All named groups that are matched will be set in the metadata object. The
 default value for the ``FILENAME_METADATA`` setting will only extract the date
 from the filename. For example, if you would like to extract both the date and
 the slug, you could set something like:
-``'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'``.
+``'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'``
 
 Please note that the metadata available inside your files takes precedence over
 the metadata extracted from the filename.
@@ -205,7 +206,7 @@ the metadata extracted from the filename.
 Generate your blog
 ------------------
 
-The ``make`` shortcut commands mentioned in the ``Kickstart a blog`` section
+The ``make`` shortcut commands mentioned in the *Kickstart a blog* section
 are mostly wrappers around the ``pelican`` command that generates the HTML from
 the content. The ``pelican`` command can also be run directly::
 
@@ -231,11 +232,11 @@ run the ``pelican`` command with the ``-r`` or ``--autoreload`` option.
 Pages
 -----
 
-If you create a folder named ``pages``, itself in the content folder, all the
+If you create a folder named ``pages`` inside the content folder, all the
 files in it will be used to generate static pages.
 
-Then, use the ``DISPLAY_PAGES_ON_MENU`` setting, which will add all the pages to
-the menu.
+Then, use the ``DISPLAY_PAGES_ON_MENU`` setting to add all those pages to
+the primary navigation menu.
 
 If you want to exclude any pages from being linked to or listed in the menu
 then add a ``status: hidden`` attribute to its metadata. This is useful for
@@ -244,9 +245,13 @@ things like making error pages that fit the generated theme of your site.
 Linking to internal content
 ---------------------------
 
-Since Pelican 3.1, you now have the ability to do cross-site linking.
+From Pelican 3.1 onwards, it is now possible to specify intra-site links to
+files in the *source content* hierarchy instead of files in the *generated*
+hierarchy. This makes it easier to link from the current post to other posts
+and images that may be sitting alongside the current post (instead of having
+to determine where those resources will be placed after site generation).
 
-To link to an internal content, you will have to use the following syntax:
+To link to internal content, use the following syntax:
 ``|filename|path/to/file``.
 
 For example, you may want to add links between "article1" and "article2" given
@@ -264,20 +269,20 @@ In this example, ``article1.rst`` could look like::
     Title: The first article
     Date: 2012-12-01
 
-    See below cross-site links examples in restructured text.
+    See below intra-site link examples in reStructuredText format.
 
-    `a root-relative link <|filename|/cat/article2.md>`_
-    `a file-relative link <|filename|cat/article2.md>`_
+    `a link relative to content root <|filename|/cat/article2.md>`_
+    `a link relative to current file <|filename|cat/article2.md>`_
 
 and ``article2.md``::
 
     Title: The second article
     Date: 2012-12-01
 
-    See below cross-site links examples in markdown.
+    See below intra-site link examples in Markdown format.
 
-    [a root-relative link](|filename|/article1.rst)
-    [a file-relative link](|filename|../article1.rst)
+    [a link relative to content root](|filename|/article1.rst)
+    [a link relative to current file](|filename|../article1.rst)
 
 .. note::
 
@@ -334,13 +339,12 @@ then instead ensure that the translated article titles are identical, since the
 slug will be auto-generated from the article title.
 
 Syntax highlighting
----------------------
+-------------------
 
 Pelican is able to provide colorized syntax highlighting for your code blocks.
-To do so, you have to use the following conventions (you need to put this in
-your content files).
+To do so, you have to use the following conventions inside your content files.
 
-For RestructuredText, use the code-block directive::
+For reStructuredText, use the code-block directive::
 
     .. code-block:: identifier
 
@@ -373,7 +377,7 @@ anything special to see what's happening with the generated files.
 
 You can either use your browser to open the files on your disk::
 
-    $ firefox output/index.html
+    firefox output/index.html
 
 Or run a simple web server using Python::