Merge branch 'master' of git://github.com/getpelican/pelican

docs/contribute.rst

@@ -23,7 +23,7 @@ different projects.
 
 To create a virtual environment, use the following syntax::
 
-    $ mkvirtualenv pelican 
+    $ mkvirtualenv pelican
 
 To clone the Pelican source::
 
@@ -65,5 +65,5 @@ Try to respect what is described in the `PEP8 specification
 <http://www.python.org/dev/peps/pep-0008/>`_ when providing patches. This can be
 eased via the `pep8 <http://pypi.python.org/pypi/pep8>`_ or `flake8
 <http://pypi.python.org/pypi/flake8/>`_ tools, the latter of which in
-particular will give you some useful hints about ways in which the 
+particular will give you some useful hints about ways in which the
 code/formatting can be improved.

docs/faq.rst

@@ -26,7 +26,7 @@ suggestions or problems you might have via IRC or the issue tracker.
 If you want to contribute, please fork `the git repository
 <https://github.com/getpelican/pelican/>`_, create a new feature branch, make
 your changes, and issue a pull request. Someone will review your changes as soon
-as possible. Please refer to the :doc:`How to Contribute <contribute>` section 
+as possible. Please refer to the :doc:`How to Contribute <contribute>` section
 for more details.
 
 You can also contribute by creating themes and improving the documentation.
@@ -43,7 +43,7 @@ I'm creating my own theme. How do I use Pygments for syntax highlighting?
 
 Pygments adds some classes to the generated content. These classes are used by
 themes to style code syntax highlighting via CSS. Specifically, you can
-customize the appearance of your syntax highlighting via the ``.codehilite pre`` 
+customize the appearance of your syntax highlighting via the ``.codehilite pre``
 class in your theme's CSS file. To see how various styles can be used to render
 Django code, for example, you can use the demo `on the project website
 <http://pygments.org/demo/15101/>`_.
@@ -105,7 +105,7 @@ I'm getting a warning about feeds generated without SITEURL being set properly
 In order to properly generate all URLs properly in Pelican you will need to set
 ``SITEURL`` to the full path of your blog. When using ``make html`` and the
 default Makefile provided by the `pelican-quickstart` bootstrap script to test
-build your site, it's normal to see this warning since ``SITEURL`` is 
+build your site, it's normal to see this warning since ``SITEURL`` is
 deliberately left undefined. If configured properly no other ``make`` commands
 should result in this warning.
 
@@ -124,5 +124,5 @@ setting names). Here is an exact list of the renamed setting names::
 
 Older 2.x themes that referenced the old setting names may not link properly.
 In order to rectify this, please update your theme for compatibility with 3.0+
-by changing the relevant values in your template files. For an example of 
+by changing the relevant values in your template files. For an example of
 complete feed headers and usage please check out the ``simple`` theme.

docs/getting_started.rst

@@ -17,7 +17,7 @@ While the above is the simplest method, the recommended approach is to create
 a virtual environment for Pelican via virtualenv_ and virtualenvwrapper_ before
 installing Pelican. Assuming you've followed the virtualenvwrapper
 `installation <http://virtualenvwrapper.readthedocs.org/en/latest/install.html>`_
-and `shell configuration 
+and `shell configuration
 <http://virtualenvwrapper.readthedocs.org/en/latest/install.html#shell-startup-file>`_
 steps, you can then open a new terminal session and create a new virtual
 environment for Pelican::
@@ -26,7 +26,7 @@ environment for Pelican::
 
 Once the virtual environment has been created and activated, Pelican can be
 be installed via ``pip`` or ``easy_install`` as noted above. Alternatively, if
-you have the project source, you can install Pelican using the distutils 
+you have the project source, you can install Pelican using the distutils
 method::
 
     $ cd path-to-Pelican-source
@@ -209,7 +209,7 @@ Pages
 If you create a folder named ``pages``, 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 
+Then, use the ``DISPLAY_PAGES_ON_MENU`` setting, which will add all the pages to
 the menu.
 
 If you want to exclude any pages from being linked to or listed in the menu
@@ -219,7 +219,7 @@ things like making error pages that fit the generated theme of your site.
 Importing an existing blog
 --------------------------
 
-It is possible to import your blog from Dotclear, WordPress, and RSS feeds using 
+It is possible to import your blog from Dotclear, WordPress, and RSS feeds using
 a simple script. See :ref:`import`.
 
 Translations
@@ -277,14 +277,13 @@ For RestructuredText, use the code-block directive::
 
        <indented code block goes here>
 
-For Markdown, include the language identifier just above code blocks::
+For Markdown, include the language identifier just above the code block,
+indenting both the identifier and code::
 
         :::identifier
         <code goes here>
-    
-    (indent both the identifier and code)
 
-The specified identifier (e.g. ``python``, ``ruby``) should be one that 
+The specified identifier (e.g. ``python``, ``ruby``) should be one that
 appears on the `list of available lexers <http://pygments.org/docs/lexers/>`_.
 
 Publishing drafts

docs/importer.rst

@@ -31,7 +31,7 @@ BeatifulSoup can be installed like any other Python package::
 
     $ pip install BeautifulSoup
 
-For pandoc, install a package for your operating system from the 
+For pandoc, install a package for your operating system from the
 `pandoc site <http://johnmacfarlane.net/pandoc/installing.html>`_.
 
 

docs/index.rst

@@ -3,7 +3,7 @@ Pelican
 
 Pelican is a static site generator, written in Python_.
 
-* Write your weblog entries directly with your editor of choice (vim!) 
+* Write your weblog entries directly with your editor of choice (vim!)
   in reStructuredText_ or Markdown_
 * Includes a simple CLI tool to (re)generate the weblog
 * Easy to interface with DVCSes and web hooks
@@ -79,4 +79,4 @@ A French version of the documentation is available at :doc:`fr/index`.
 .. _`Pelican documentation`: http://docs.getpelican.com/latest/
 .. _`Pelican's internals`: http://docs.getpelican.com/en/latest/internals.html
 .. _`#pelican on Freenode`: irc://irc.freenode.net/pelican
-.. _webchat: http://webchat.freenode.net/?channels=pelican&uio=d4
+.. _webchat: http://webchat.freenode.net/?channels=pelican&uio=d4

docs/internals.rst

@@ -52,7 +52,7 @@ Take a look at the Markdown reader::
             text = open(filename)
             md = Markdown(extensions = ['meta', 'codehilite'])
             content = md.convert(text)
-            
+
             metadata = {}
             for name, value in md.Meta.items():
                 if name in _METADATA_FIELDS:
@@ -81,7 +81,7 @@ both; only the existing ones will be called.
   context is shared between all generators, and will be passed to the
   templates. For instance, the ``PageGenerator`` ``generate_context`` method
   finds all the pages, transforms them into objects, and populates the context
-  with them. Be careful *not* to output anything using this context at this 
+  with them. Be careful *not* to output anything using this context at this
   stage, as it is likely to change by the effect of other generators.
 
 * ``generate_output`` is then called. And guess what is it made for? Oh,

docs/pelican-themes.rst

@@ -64,7 +64,7 @@ In this example, we can see there are three themes available: ``notmyidea``, ``s
 Note that you can combine the ``--list`` option with the ``-v`` or ``--verbose`` option to get more verbose output, like this:
 
 .. code-block:: console
-    
+
     $ pelican-themes -v -l
     /usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/notmyidea
     /usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/two-column (symbolic link to `/home/skami/Dev/Python/pelican-themes/two-column')
@@ -118,7 +118,7 @@ Creating symbolic links
 To symbolically link a theme, you can use the ``-s`` or ``--symlink``, which works exactly as the ``--install`` option:
 
 .. code-block:: console
-    
+
     # pelican-themes --symlink ~/Dev/Python/pelican-themes/two-column
 
 In this example, the ``two-column`` theme is now symbolically linked to the Pelican themes path, so we can use it, but we can also modify it without having to reinstall it after each modification.
@@ -130,11 +130,11 @@ This is useful for theme development:
     $ sudo pelican-themes -s ~/Dev/Python/pelican-themes/two-column
     $ pelican ~/Blog/content -o /tmp/out -t two-column
     $ firefox /tmp/out/index.html
-    $ vim ~/Dev/Pelican/pelican-themes/two-coumn/static/css/main.css 
+    $ vim ~/Dev/Pelican/pelican-themes/two-coumn/static/css/main.css
     $ pelican ~/Blog/content -o /tmp/out -t two-column
     $ cp /tmp/bg.png ~/Dev/Pelican/pelican-themes/two-coumn/static/img/bg.png
     $ pelican ~/Blog/content -o /tmp/out -t two-column
-    $ vim ~/Dev/Pelican/pelican-themes/two-coumn/templates/index.html 
+    $ vim ~/Dev/Pelican/pelican-themes/two-coumn/templates/index.html
     $ pelican ~/Blog/content -o /tmp/out -t two-column
 
 
@@ -152,7 +152,7 @@ The ``--install``, ``--remove`` and ``--symlink`` option are not mutually exclus
                      --symlink ~/Dev/Python/pelican-themes/two-column \
                      --verbose
 
-In this example, the theme ``notmyidea-cms`` is replaced by the theme ``notmyidea-cms-fr`` 
+In this example, the theme ``notmyidea-cms`` is replaced by the theme ``notmyidea-cms-fr``
 
 
 

docs/plugins.rst

@@ -16,7 +16,7 @@ To load plugins, you have to specify them in your settings file. You have two
 ways to do so.
 Either by specifying strings with the path to the callables::
 
-    PLUGINS = ['pelican.plugins.gravatar',] 
+    PLUGINS = ['pelican.plugins.gravatar',]
 
 Or by importing them and adding them to the list::
 
@@ -76,14 +76,22 @@ request if you need them!
 List of plugins
 ===============
 
-Not all the list are described here, but a few of them have been extracted from
+The following plugins are currently included with Pelican under ``pelican.plugins``:
-the Pelican core and provided in ``pelican.plugins``. They are described here:
 
-Tag cloud
+* `GitHub activity`_
----------
+* `Global license`_
+* `Gravatar`_
+* `HTML tags for reStructuredText`_
+* `Related posts`_
+* `Sitemap`_
 
-Translation
+Ideas for plugins that haven't been written yet:
------------
+
+* Tag cloud
+* Translation
+
+Plugin descriptions
+===================
 
 GitHub activity
 ---------------
@@ -116,23 +124,78 @@ variable, as in the example::
 ``github_activity`` is a list of lists. The first element is the title
 and the second element is the raw HTML from GitHub.
 
+Global license
+--------------
+
+This plugin allows you to define a LICENSE setting and adds the contents of that
+license variable to the article's context, making that variable available to use
+from within your theme's templates.
+
+Gravatar
+--------
+
+This plugin assigns the ``author_gravatar`` variable to the Gravatar URL and
+makes the variable available within the article's context. You can add
+AUTHOR_EMAIL to your settings file to define the default author's email
+address. Obviously, that email address must be associated with a Gravatar
+account.
+
+Alternatively, you can provide an email address from within article metadata::
+
+    :email:  john.doe@example.com
+
+If the email address is defined via at least one of the two methods above,
+the ``author_gravatar`` variable is added to the article's context.
+
+HTML tags for reStructuredText
+------------------------------
+
+This plugin allows you to use HTML tags from within reST documents. Following
+is a usage example, which is in this case a contact form::
+
+    .. html::
+
+        <form method="GET" action="mailto:some email">
+          <p>
+            <input type="text" placeholder="Subject" name="subject">
+            <br />
+            <textarea name="body" placeholder="Message">
+            </textarea>
+            <br />
+            <input type="reset"><input type="submit">
+          </p>
+        </form>
+
+Related posts
+-------------
+
+This plugin adds the ``related_posts`` variable to the article's context.
+To enable, add the following to your settings file::
+
+    from pelican.plugins import related_posts
+    PLUGINS = [related_posts]
+
+You can then use the ``article.related_posts`` variable in your templates.
+For example::
+
+    {% if article.related_posts %}
+        <ul>
+        {% for related_post in article.related_posts %}
+            <li>{{ related_post }}</li>
+        {% endfor %}
+        </ul>
+    {% endif %}
 
 Sitemap
 -------
 
-The plugin generates a sitemap of the blog.
+The sitemap plugin generates plain-text or XML sitemaps. You can use the
-It can generates plain text sitemaps or XML sitemaps.
+``SITEMAP`` variable in your settings file to configure the behavior of the
-
-Configuration
-"""""""""""""
-
-You can use the setting ``SITEMAP`` variable to configure the behavior of the
 plugin.
 
-The ``SITEMAP`` variable must be a Python dictionary, it can contain tree keys:
+The ``SITEMAP`` variable must be a Python dictionary, it can contain three keys:
 
-
+- ``format``, which sets the output format of the plugin (``xml`` or ``txt``)
-- ``format``, which set the output format of the plugin (``xml`` or ``txt``)
 
 - ``priorities``, which is a dictionary with three keys:
 
@@ -154,9 +217,8 @@ The ``SITEMAP`` variable must be a Python dictionary, it can contain tree keys:
 
   - ``indexes``, the update frequency of the index pages
 
-  An valid value is  ``always``, ``hourly``, ``daily``, ``weekly``, ``monthly``,
+  Valid frequency values are ``always``, ``hourly``, ``daily``, ``weekly``, ``monthly``,
-  ``yearly`` or ``never``.
+  ``yearly`` and ``never``.
-
 
 If a key is missing or a value is incorrect, it will be replaced with the
 default value.
@@ -168,11 +230,9 @@ The sitemap is saved in ``<output_path>/sitemap.<format>``.
    They are only used in the XML sitemaps.
    For more information: <http://www.sitemaps.org/protocol.html#xmlTagDefinitions>
 
+**Example**
 
-Example
+Here is an example configuration (it's also the default settings):
-"""""""
-
-Here is an example of configuration (it's also the default settings):
 
 .. code-block:: python
 

docs/report.rst

@@ -4,7 +4,7 @@ Some history about Pelican
 .. warning::
 
     This page comes from a report the original author (Alexis Métaireau) wrote
-    right after writing Pelican, in December 2010. The information may not be 
+    right after writing Pelican, in December 2010. The information may not be
     up-to-date.
 
 Pelican is a simple static blog generator. It parses markup files
@@ -113,7 +113,7 @@ concepts. Here is what happens when calling the ``generate_context``
 method:
 
 * Read the folder “path”, looking for restructured text files, load
-  each of them, and construct a content object (``Article``) with it. To do so, 
+  each of them, and construct a content object (``Article``) with it. To do so,
   use ``Reader`` objects.
 * Update the ``context`` with all those articles.
 

docs/settings.rst

@@ -16,6 +16,9 @@ False, None, etc.), dictionaries, or tuples should *not* be enclosed in
 quotation marks. All other values (i.e., strings) *must* be enclosed in
 quotation marks.
 
+Unless otherwise specified, settings that refer to paths can be either absolute or relative to the
+configuration file.
+
 The settings you define in the configuration file will be passed to the
 templates, which allows you to use your settings to add site-wide content.
 
@@ -58,10 +61,10 @@ Setting name (default value)                                            What doe
                                                                         Python-Markdown documentation for a complete list of
                                                                         supported extensions.
 `OUTPUT_PATH` (``'output/'``)                                           Where to output the generated files.
-`PATH` (``None``)                                                       Path to look at for input files.
+`PATH` (``None``)                                                       Path to content directory to be processed by Pelican.
-`PAGE_DIR` (``'pages'``)                                                Directory to look at for pages.
+`PAGE_DIR` (``'pages'``)                                                Directory to look at for pages, relative to `PATH`.
 `PAGE_EXCLUDES` (``()``)                                                A list of directories to exclude when looking for pages.
-`ARTICLE_DIR` (``''``)                                                  Directory to look at for articles.
+`ARTICLE_DIR` (``''``)                                                  Directory to look at for articles, relative to `PATH`.
 `ARTICLE_EXCLUDES`: (``('pages',)``)                                    A list of directories to exclude when looking for articles.
 `PDF_GENERATOR` (``False``)                                             Set to True if you want to have PDF versions
                                                                         of your documents. You will need to install
@@ -373,19 +376,19 @@ Setting name (default value)                        What does it do?
                                                     alphabetical order; default lists alphabetically.)
 ================================================    =====================================================
 
-Theming
+Themes
-=======
+======
 
-Theming is addressed in a dedicated section (see :ref:`theming-pelican`).
+Creating Pelican themes is addressed in a dedicated section (see :ref:`theming-pelican`).
-However, here are the settings that are related to theming.
+However, here are the settings that are related to themes.
 
 ================================================    =====================================================
 Setting name (default value)                        What does it do?
 ================================================    =====================================================
-`THEME`                                             Theme to use to produce the output. Can be the
+`THEME`                                             Theme to use to produce the output. Can be a relative
-                                                    complete static path to a theme folder, or
+                                                    or absolute path to a theme folder, or the name of a
-                                                    chosen between the list of default themes (see
+                                                    default theme or a theme installed via
-                                                    below)
+                                                    ``pelican-themes`` (see below).
 `THEME_STATIC_PATHS` (``['static']``)               Static theme paths you want to copy. Default
                                                     value is `static`, but if your theme has
                                                     other static paths, you can put them here.
@@ -393,22 +396,32 @@ Setting name (default value)                        What does it do?
 `WEBASSETS` (``False``)                             Asset management with `webassets` (see below)
 ================================================    =====================================================
 
-By default, two themes are available. You can specify them using the `-t` option:
+
+By default, two themes are available. You can specify them using the `THEME` setting or by passing the
+``-t`` option to the ``pelican`` command:
 
 * notmyidea
-* simple (a synonym for "full text" :)
+* simple (a synonym for "plain text" :)
-
-You can define your own theme too, and specify its placement in the same
-manner. (Be sure to specify the full absolute path to it.)
-
-Here is :doc:`a guide on how to create your theme <themes>`
-
-You can find a list of themes at http://github.com/getpelican/pelican-themes.
 
+There are a number of other themes available at http://github.com/getpelican/pelican-themes.
 Pelican comes with :doc:`pelican-themes`, a small script for managing themes.
 
-The `notmyidea` theme can make good use of the following settings. I recommend
+You can define your own theme, either by starting from scratch or by duplicating
-using them in your themes as well.
+and modifying a pre-existing theme. Here is :doc:`a guide on how to create your theme <themes>`.
+
+Following are example ways to specify your preferred theme::
+
+    # Specify name of a built-in theme
+    THEME = "notmyidea"
+    # Specify name of a theme installed via the pelican-themes tool
+    THEME = "chunk"
+    # Specify a customized theme, via path relative to the settings file
+    THEME = "themes/mycustomtheme"
+    # Specify a customized theme, via absolute path
+    THEME = "~/projects/mysite/themes/mycustomtheme"
+
+The built-in `notmyidea` theme can make good use of the following settings. Feel
+free to use them in your themes as well.
 
 =======================   =======================================================
 Setting name              What does it do ?
@@ -444,26 +457,27 @@ adding the following to your configuration::
 Asset management
 ----------------
 
-The `WEBASSETS` setting allows to use the `webassets`_ module to manage assets
+The `WEBASSETS` setting allows you to use the `webassets`_ module to manage
-(css, js). The module must first be installed::
+assets such as CSS and JS files. The module must first be installed::
 
     pip install webassets
 
-`webassets` allows to concatenate your assets and to use almost all of the
+The `webassets` module allows you to perform a number of useful asset management
-hype tools of the moment (see the `documentation`_):
+functions, including:
 
-* css minifier (`cssmin`, `yuicompressor`, ...)
+* CSS minifier (`cssmin`, `yuicompressor`, ...)
-* css compiler (`less`, `sass`, ...)
+* CSS compiler (`less`, `sass`, ...)
-* js minifier (`uglifyjs`, `yuicompressor`, `closure`, ...)
+* JS minifier (`uglifyjs`, `yuicompressor`, `closure`, ...)
 
-Others filters include gzip compression, integration of images in css with
+Others filters include gzip compression, integration of images in CSS via data
-`datauri` and more. Webassets also append a version identifier to your asset
+URIs, and more. `webassets` can also append a version identifier to your asset
-url to convince browsers to download new versions of your assets when you use
+URL to convince browsers to download new versions of your assets when you use
-far future expires headers.
+far-future expires headers. Please refer to the `webassets documentation`_ for
+more information.
 
-When using it with Pelican, `webassets` is configured to process assets in the
+When using with Pelican, `webassets` is configured to process assets in the
-``OUTPUT_PATH/theme`` directory. You can use it in your templates with a
+``OUTPUT_PATH/theme`` directory. You can use `webassets` in your templates by
-template tag, for example:
+including one or more template tags. For example...
 
 .. code-block:: jinja
 
@@ -471,22 +485,22 @@ template tag, for example:
         <link rel="stylesheet" href="{{ ASSET_URL }}">
     {% endassets %}
 
-will produce a minified css file with the version identifier:
+... will produce a minified css file with a version identifier:
 
 .. code-block:: html
 
     <link href="http://{SITEURL}/theme/css/style.min.css?b3a7c807" rel="stylesheet">
 
-The filters can be combined, for example to use the `sass` compiler and minify
+These filters can be combined. Here is an example that uses the SASS compiler
-the output::
+and minifies the output:
 
 .. code-block:: jinja
 
-{% assets filters="sass,cssmin", output="css/style.min.css", "css/style.scss" %}
+    {% assets filters="sass,cssmin", output="css/style.min.css", "css/style.scss" %}
-    <link rel="stylesheet" href="{{ ASSET_URL }}">
+        <link rel="stylesheet" href="{{ ASSET_URL }}">
-{% endassets %}
+    {% endassets %}
 
-Another example for javascript:
+Another example for Javascript:
 
 .. code-block:: jinja
 
@@ -494,20 +508,20 @@ Another example for javascript:
         <script src="{{ ASSETS_URL }}"></script>
     {% endassets %}
 
-will produce a minified and gzipped js file:
+The above will produce a minified and gzipped JS file:
 
 .. code-block:: html
 
     <script src="http://{SITEURL}/theme/js/packed.js?00703b9d"></script>
 
-Pelican's debug mode is propagated to webassets to disable asset packaging,
+Pelican's debug mode is propagated to `webassets` to disable asset packaging
 and instead work with the uncompressed assets. However, this also means that
-the `less` and `sass` files are not compiled, this should be fixed in a future
+the LESS and SASS files are not compiled. This should be fixed in a future
-version of webassets (cf. the related `bug report
+version of `webassets` (cf. the related `bug report
 <https://github.com/getpelican/pelican/issues/481>`_).
 
 .. _webassets: https://github.com/miracle2k/webassets
-.. _documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html
+.. _webassets documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html
 
 Example settings
 ================

docs/themes.rst

@@ -35,7 +35,7 @@ To make your own theme, you must follow the following structure::
 * `templates` contains all the templates that will be used to generate the content.
   I've just put the mandatory templates here; you can define your own if it helps
   you keep things organized while creating your theme.
- 
+
 Templates and variables
 =======================
 
@@ -44,7 +44,7 @@ This document describes which templates should exist in a theme, and which
 variables will be passed to each template at generation time.
 
 All templates will receive the variables defined in your settings file, if they
-are in all-caps. You can access them directly. 
+are in all-caps. You can access them directly.
 
 Common variables
 ----------------
@@ -55,14 +55,14 @@ All of these settings will be available to all templates.
 Variable        Description
 =============   ===================================================
 articles        The list of articles, ordered descending by date
-                All the elements are `Article` objects, so you can 
+                All the elements are `Article` objects, so you can
                 access their attributes (e.g. title, summary, author
                 etc.)
 dates           The same list of articles, but ordered by date,
                 ascending
 tags            A key-value dict containing the tags (the keys) and
                 the list of respective articles (the values)
-categories      A key-value dict containing the categories (keys) 
+categories      A key-value dict containing the categories (keys)
                 and the list of respective articles (values)
 pages           The list of pages
 =============   ===================================================
@@ -182,7 +182,7 @@ dates                   Articles related to this tag, but ordered by date,
                         ascending
 articles_paginator      A paginator object for the list of articles
 articles_page           The current page of articles
-dates_paginator         A paginator object for the list of articles, 
+dates_paginator         A paginator object for the list of articles,
                         ordered by date, ascending
 dates_page              The current page of articles, ordered by date,
                         ascending

docs/tips.rst

@@ -12,11 +12,11 @@ file generator, we can take advantage of this.
 
 User Pages
 ----------
-GitHub allows you to create user pages in the form of ``username.github.com``. 
+GitHub allows you to create user pages in the form of ``username.github.com``.
 Whatever is created in the master branch will be published. For this purpose,
 just the output generated by Pelican needs to pushed to GitHub.
 
-So given a repository containing your articles, just run Pelican over the posts 
+So given a repository containing your articles, just run Pelican over the posts
 and deploy the master branch to GitHub::
 
     $ pelican -s pelican.conf.py ./path/to/posts -o /path/to/output
@@ -35,7 +35,7 @@ really easy, which can be installed via::
 
     $ pip install ghp-import
 
-Then, given a repository containing your articles, you would simply run 
+Then, given a repository containing your articles, you would simply run
 Pelican and upload the output to GitHub::
 
     $ pelican -s pelican.conf.py .

pelican/generators.py

@@ -378,7 +378,7 @@ class PagesGenerator(Generator):
                 os.path.join(self.path, self.settings['PAGE_DIR']),
                 exclude=self.settings['PAGE_EXCLUDES']):
             try:
-                content, metadata = read_file(f)
+                content, metadata = read_file(f, settings=self.settings)
             except Exception, e:
                 logger.warning(u'Could not process %s\n%s' % (f, str(e)))
                 continue

pelican/plugins/global_license.py

@@ -4,13 +4,14 @@ from pelican import signals
 License plugin for Pelican
 ==========================
 
-Simply add license variable in article's context, which contain 
+This plugin allows you to define a LICENSE setting and adds the contents of that
-the license text.
+license variable to the article's context, making that variable available to use
+from within your theme's templates.
 
 Settings:
 ---------
 
-Add LICENSE to your settings file to define default license.
+Define LICENSE in your settings file with the contents of your default license.
 
 """
 

pelican/plugins/gravatar.py

@@ -5,20 +5,22 @@ from pelican import signals
 Gravatar plugin for Pelican
 ===========================
 
-Simply add author_gravatar variable in article's context, which contains
+This plugin assigns the ``author_gravatar`` variable to the Gravatar URL and
-the gravatar url.
+makes the variable available within the article's context.
 
 Settings:
 ---------
 
-Add AUTHOR_EMAIL to your settings file to define default author email.
+Add AUTHOR_EMAIL to your settings file to define the default author's email
+address. Obviously, that email address must be associated with a Gravatar
+account.
 
 Article metadata:
 ------------------
 
 :email:  article's author email
 
-If one of them are defined, the author_gravatar variable is added to
+If one of them are defined, the author_gravatar variable is added to the
 article's context.
 """