Imported Upstream version 6.3.0upstream/6.3.0

12 files changed, 275 insertions, 54 deletions

diff --git a/docs/creating-a-site.txt b/docs/creating-a-site.txt
index a200d54..097bfb5 100644
--- a/docs/creating-a-site.txt
+++ b/docs/creating-a-site.txt
@@ -38,7 +38,7 @@ configuration file:
     BLOG_TITLE = "Not a Blog"
     # This is the main URL for your site. It will be used
     # in a prominent link
-    SITE_URL = "http://notablog.ralsina.com.ar"
+    SITE_URL = "http://notablog.ralsina.com.ar/"
     BLOG_EMAIL = "ralsina@kde.org"
     BLOG_DESCRIPTION = "This is a demo site (not a blog) for Nikola."
 
@@ -168,6 +168,6 @@ or whatever.
     in http://yoursite.com/blog (you may want to add links to it in NAVIGATION_LINKS of course).
 
 You can see the finished site in http://notablog.ralsina.com.ar and its full configuration in
-http://ralsina.com.ar/listings/notablog/conf.py.html
+http://ralsina.me/listings/notablog/conf.py.html
 
 I hope this was helpful!
diff --git a/docs/creating-a-theme.txt b/docs/creating-a-theme.txt
index 1e67410..35c2dbf 100644
--- a/docs/creating-a-theme.txt
+++ b/docs/creating-a-theme.txt
@@ -263,7 +263,7 @@ It turns out ``bootstrap`` doesn' have one of those! That's because it inherits
     <%inherit file="base.tmpl"/>
     <%block name="content">
         % for post in posts:
-            <div class="postbox">
+            <div class="postbox post-${post.meta('type')}">
             <h1><a href="${post.permalink()}">${post.title()}</a>
             <small>&nbsp;&nbsp;
                 ${messages("Posted")}: <time class="published" datetime="${post.date.isoformat()}">${post.formatted_date(date_format)}</time>
@@ -291,7 +291,7 @@ box, add links for the posts tags, move the date there, etc.
     <%inherit file="base.tmpl"/>
     <%block name="content">
         % for post in posts:
-            <div class="postbox">
+            <div class="postbox post-${post.meta('type')}">
             <h1><a href="${post.permalink()}">${post.title()}</a></h1>
                 <div class="meta" style="background-color: rgb(234, 234, 234); ">
                     <span class="authordate">
diff --git a/docs/extending.txt b/docs/extending.txt
index f5c7aae..25d1782 100644
--- a/docs/extending.txt
+++ b/docs/extending.txt
@@ -8,7 +8,7 @@
 Extending Nikola
 ================
 
-:Version: 6.2.1
+:Version: 6.3.0
 :Author: Roberto Alsina <ralsina@netmanagers.com.ar>
 
 .. class:: alert alert-info pull-right
diff --git a/docs/getting-help.txt b/docs/getting-help.txt
new file mode 100644
index 0000000..9cad1b3
--- /dev/null
+++ b/docs/getting-help.txt
@@ -0,0 +1,75 @@
+.. title: Help, Bugs, Contact
+.. slug: contact
+.. date: 1970-01-01 15:00:00
+.. description: Get help using Nikola, or contact us.
+
+:Version: 6.3.0
+
+.. class:: alert alert-info pull-right
+
+.. contents::
+
+Help and Support
+================
+
+1. A `mailing list`_, nikola-discuss on Google Groups exists.
+2. There is an IRC channel, #nikola on Freenode.  You can find many
+   developers and volunteers (users) there which are there to provide
+   help, if they are around and read your message.
+3. You can also contact `@GetNikola <http://twitter.com/GetNikola>`_ on
+   Twitter.
+4. If you are experiencing a bug, [1]_ you should report it on GitHub (see
+   below).
+
+Plugins and Themes
+------------------
+
+Plugins and Themes from the Indexes are not officially supported.
+
+1. Ask the `mailing list`_, which may or may not work out.
+2. You can also try the IRC channel if the theme/plugin is very popular.
+3. Report an issue at the `plugins issue tracker`_ or at the `themes
+   issue tracker`_.
+4. Contact the author of the plugin/theme.  The name of the author of a
+   plugin is available in the ``.plugin`` and ``.py`` files.  Tracking
+   down theme authors can be much harder due to how our architecture
+   works (but certainly is doable).
+
+Report a Bug, Request a Feature
+===============================
+
+Bug reports should be sent to the `Issue tracker`_ at GitHub.
+
+Feature requests should be sent to the or to the `Issue tracker`_ or to
+the `mailing list`_, especially if they require further discussion.
+
+Administrativia
+===============
+
+If you are in need of getting administrativia [2]_ resolved, you may want
+to e-mail info@getnikola.com and therefore contact the people behind the
+project.  Note that this email **may not** be used for support matters.
+Messages are forwarded to all three administrators, the names and
+personal addresses (if you need to contact them personally) of you can
+find below.
+
+Administrators
+--------------
+
++----------------+-----------------+-----------+-----------------------+
+| Name           | GitHub Nickname | Location  | E-mail                |
++================+=================+===========+=======================+
+| Roberto Alsina | ralsina         | Argentina | roberto@getnikola.com |
++----------------+-----------------+-----------+-----------------------+
+| Damián Avila   | damianavila     | Argentina | damian@getnikola.com  |
++----------------+-----------------+-----------+-----------------------+
+| Chris Warrick  | Kwpolska        | Poland    | chris@getnikola.com   |
++----------------+-----------------+-----------+-----------------------+
+
+.. [1] `As defined on Wikipedia. <http://en.wikipedia.org/wiki/Software_bug>`_
+.. [2] `administrative matters <http://en.wiktionary.org/wiki/administrativia>`_
+
+.. _mailing list: http://groups.google.com/group/nikola-discuss
+.. _Issue tracker: https://github.com/getnikola/nikola/issues
+.. _plugins issue tracker: https://github.com/getnikola/plugins/issues
+.. _themes issue tracker: https://github.com/getnikola/nikola-themes/issues
diff --git a/docs/internals.txt b/docs/internals.txt
index 14de433..75e2a97 100644
--- a/docs/internals.txt
+++ b/docs/internals.txt
@@ -59,7 +59,7 @@ targets
     Files that the action generates. No two actions can have the same targets.
 
 basename:name
-    Each task is identified by either a name or a basename:name pair. Nikola
+    Each task is identified by either a name or a basename:name pair.
 
 .. sidebar:: More about tasks
 
diff --git a/docs/man/nikola.1 b/docs/man/nikola.1
index 9385a2a..f794ccb 100644
--- a/docs/man/nikola.1
+++ b/docs/man/nikola.1
@@ -1,7 +1,7 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.43.3.
-.TH NIKOLA "1" "November 2013" "nikola 6.2.1" "User Commands"
+.TH NIKOLA "1" "January 2014" "nikola 6.3.0" "User Commands"
 .SH NAME
-nikola \- manual page for nikola 6.2.1
+nikola \- manual page for nikola 6.3.0
 .SH DESCRIPTION
 Nikola is a tool to create static websites and blogs. For full documentation and more information, please visit http://getnikola.com
 .SS "Available commands:"
@@ -22,11 +22,14 @@ nikola clean
 clean action / remove targets
 .TP
 nikola console
-Start an interactive Python (IPython\->bpython\->plain) console with access to your site and configuration
+start an interactive Python console with access to your site
 .TP
 nikola deploy
 deploy the site
 .TP
+nikola doit_auto
+automatically execute tasks when a dependency changes
+.TP
 nikola dumpdb
 dump dependency DB
 .TP
@@ -66,6 +69,9 @@ apply mincss to the generated site
 nikola new_post
 create a new blog post or site page
 .TP
+nikola orphans
+list all orphans
+.TP
 nikola run
 run tasks
 .TP
@@ -75,6 +81,9 @@ start the test webserver
 nikola strace
 use strace to list file_deps and targets
 .TP
+nikola tabcompletion
+generate script for tab\-complention
+.TP
 nikola version
 print the Nikola version number
 .TP
diff --git a/docs/manual.txt b/docs/manual.txt
index c186260..d78b4f6 100644
--- a/docs/manual.txt
+++ b/docs/manual.txt
@@ -8,7 +8,7 @@
 The Nikola Handbook
 ===================
 
-:Version: 6.2.1
+:Version: 6.3.0
 
 .. class:: alert alert-info pull-right
 
@@ -89,11 +89,16 @@ out there.
 Getting Help
 ------------
 
-* Feel free to contact me at ralsina@netmanagers.com.ar for questions about Nikola.
+.. class:: lead
+
+`Get help here! <http://getnikola.com/contact.html>`_
+
+TL;DR:
+
 * You can file bugs at `the issue tracker <https://github.com/getnikola/nikola/issues>`__
 * You can discuss Nikola at the `nikola-discuss google group <http://groups.google.com/group/nikola-discuss>`_
 * You can subscribe to `the Nikola Blog <http://getnikola.com/blog>`_
-* You can follow `Nikola on Twitter <https://twitter.com/nikolagenerator>`_
+* You can follow `Nikola on Twitter <https://twitter.com/GetNikola>`_
 
 Why Static?
 -----------
@@ -198,6 +203,16 @@ of how to "get" something for your specific operating system are left to you.
 
 The short version is: ``pip install nikola``
 
+If you are running Arch Linux, there are AUR packages, available in Python 2/3
+and stable/git master flavors: `python-nikola`__ / `python2-nikola`__ for the
+latest stable release or `python-nikola-git`__ / `python2-nikola-git`__ for the
+GitHub master.  (only one package may be installed at the same time.)
+
+__ https://aur.archlinux.org/packages/python-nikola/
+__ https://aur.archlinux.org/packages/python2-nikola/
+__ https://aur.archlinux.org/packages/python-nikola-git/
+__ https://aur.archlinux.org/packages/python2-nikola-git/
+
 Note that you need Python v2.6 or newer OR v3.3 or newer.
 
 For some features it may give you an error message telling you that you need to
@@ -205,7 +220,10 @@ install something else. For example, if it tells you you need ``requests``::
 
    pip install requests
 
-And so on.
+And so on.  Alternatively, you can install the ``requirements-full.txt`` file
+shipped with the full source tree to get everything.  (or `see the file
+online
+<https://github.com/getnikola/nikola/blob/master/requirements-full.txt>`_)
 
 Longer version:
 
@@ -229,6 +247,9 @@ Longer version:
       #. Get `yapsy <http://yapsy.sourceforge.net>`_
       #. Get `PyRSS2Gen <http://www.dalkescientific.com/Python/PyRSS2Gen.html>`_
       #. Get `pytz <http://pytz.sourceforge.net/>`_
+      #. Get `Logbook <http://pythonhosted.org/Logbook/>`_
+      #. Get `blinker <http://pythonhosted.org/blinker/>`_
+      #. Get `Setuptools <http://pythonhosted.org/setuptools/>`_
       #. If using Python 2, get `configparser <http://pypi.python.org/pypi/configparser/3.2.0r3>`_
 
 #. run ``python setup.py install``
@@ -238,7 +259,10 @@ After that, run ``nikola init --demo sitename`` and that will create a folder ca
 
 Nikola is packaged for some Linux distributions, you may get that instead.
 
-*NOTE*: If you get a ``ERROR: /bin/sh: 1: xslt-config: not found`` or ``fatal error:
+libxml/libxslt errors
+~~~~~~~~~~~~~~~~~~~~~
+
+If you get a ``ERROR: /bin/sh: 1: xslt-config: not found`` or ``fatal error:
 libxml/xmlversion.h: No such file or directory`` when running ``pip install -r requirements.txt``, install *libxml* and *libxslt* libraries, like so:
 
 Debian systems::
@@ -246,9 +270,27 @@ Debian systems::
     sudo apt-get install libxml2-dev
     sudo apt-get install libxslt1-dev
 
-Red Hat/RPM based systems::
+Red Hat/RPM-based systems::
+
+    sudo yum install libxslt-devel libxml2-devel
+
+Python.h not found
+~~~~~~~~~~~~~~~~~~
 
-    yum install libxslt-devel libxml2-devel
+If you get an error to the effect of ``Python.h not found``, you need to
+install development packages for Python.
+
+Debian systems::
+
+    sudo apt-get install python-dev
+
+Red Hat/RPM-based systems::
+
+    sudo yum install python-devel
+
+Note that many other distros/operating systems (including Arch Linux,
+\*BSD and OS X) do not require such packages, as C headers are included
+with the base distribution of Python.
 
 Installation on Linux, Mac OS X, \*BSD, and any other POSIX-compatible OS
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -274,7 +316,8 @@ their `PyPI <https://pypi.python.org/>`_ pages to find official packages, `the u
 2. Windows has some differences over POSIX, which may cause some features to work incorrectly under Windows.  If any problems occur, please do not hesitate to report them.  Some of the differeces include:
 
    * ``\`` as path separator (instead of ``/``)
-   * the concept of partitions
+   * the concept of HDD partitions and letters (instead of
+     seamless mounting under one root)
    * some characters in paths are disallowed (although this shouldn’t cause
      problems)
    * CR+LF (aka ``\r\n``) as the line separator (instead of LF ``\n``)
@@ -442,6 +485,7 @@ The content of that file is as follows::
     .. tags:
     .. link:
     .. description:
+    .. type: text
 
     Write your post here.
 
@@ -451,6 +495,9 @@ The third line is the post's date, and is set to "now".
 
 The other lines are optional. Tags are comma-separated. The ``link`` is an original
 source for the content, and ``description`` is mostly useful for SEO.
+``type`` is the post type, whatever you set here (prepended with ``post-``)
+will become a class of the `<article>` element for this post.  Defaults to
+``text`` (resulting in a ``post-text`` class)
 
 You can add your own metadata fields in the same manner, if you use a theme that
 supports them (for example: ``.. author: John Doe``)
@@ -458,7 +505,7 @@ supports them (for example: ``.. author: John Doe``)
 To add these metadata fields to all new posts by default, you can set the
 variable ``ADDITIONAL_METADATA`` in your configuration.  For example, you can
 add the author metadata to all new posts by default, by adding the following
-to your configuration ::
+to your configuration::
 
     ADDITIONAL_METADATA = {
         'author': 'John Doe'
@@ -500,11 +547,11 @@ to your configuration ::
        Set "True" if you do not want to see the **story** title as a
        heading of the page (does not work for posts).
 
-
 .. note:: The Two-File Format
 
    Nikola originally used a separate ``.meta`` file. That will still work!
-   The format of the meta files is the same as shown above, but without the
+   The format of the meta files is the same as shown above (i.e. only
+   the 7 base fields, in the order listed above), but without the
    explanations::
 
         How to make money
@@ -512,27 +559,64 @@ to your configuration ::
         2012/09/15 19:52:05
 
 If you are writing a multilingual site, you can also create a per-language
-post file (for example: ``how-to-make-money.txt.es``). This one can replace
-metadata of the default language, for example:
+post file (for example: ``how-to-make-money.txt.es`` with the default TRANSLATIONS_PATTERN, see below).
+This one can replace metadata of the default language, for example:
 
 * The translated title for the post or page
 * A translated version of the page name
 
+The pattern used for finding translations is controlled by the
+TRANSLATIONS_PATTERN variable in your configuration file.
+
+The default as in the example above is to append the language code to the
+filename path to identify a translation of a file, so the German translation
+of ``some_file.rst`` should be named ``some_file.rst.de``. This is because
+the TRANSLATIONS_PATTERN variable is by default set to::
+
+    TRANSLATIONS_PATTERN = "{path}.{ext}.{lang}"
+
+However, if you don't want your Polish input files to be considered
+Perl code (e.g. ``some_file.rst.pl``), you could use this pattern::
+
+    TRANSLATIONS_PATTERN = "{path}.{lang}.{ext}"
+
+Note that this pattern will become the default in v7.0.0.
+
+.. note:: Considered languages
+
+    nikola will only look for translation of input files for languages
+    specified in the TRANSLATIONS variable.
+
 You can edit these files with your favourite text editor, and once you are happy
 with the contents, generate the pages as explained in `Getting Started`_
 
 Currently supported languages are
 
+* Basque
+* Bulgarian
 * Catalan
+* Chinese (Simplified)
+* Croatian
+* Czech
+* Dutch
 * English
+* Esperanto
+* Estonian
+* Finnish
 * French
 * German
 * Greek
 * Italian
+* Japanese
+* Norwegian Bokmål
+* Persian
 * Polish
+* Portuguese
 * Russian
-* Simplified Chinese.
+* Slovenian
 * Spanish
+* Turkish
+* Urdu
 
 If you wish to add support for more languages, check out the instructions
 at the `theming guide <http://getnikola.com/theming.html>`_.
@@ -549,9 +633,11 @@ and ``PAGES`` configuration options::
     # (whatever/thing.txt).
     #
     # That fragment could have an associated metadata file (whatever/thing.meta),
-    # and optionally translated files (example for spanish, with code "es"):
+    # and optionally translated files (example for Spanish, with code "es"):
     #     whatever/thing.txt.es and whatever/thing.meta.es
     #
+    #     This assumes you use the default TRANSLATIONS_PATTERN.
+    #
     # From those files, a set of HTML fragment files will be generated:
     # cache/whatever/thing.html (and maybe cache/whatever/thing.html.es)
     #
@@ -707,6 +793,21 @@ to the same as above), with no other post on Monday, at/after 7am,
 setting ``SCHEDULE_FORCE_TODAY = True`` will have your post scheduled
 to Monday, instead of being scheduled to Wednesday 7am.
 
+Post Types
+~~~~~~~~~~
+
+Nikola supports specifying post types, just like Tumblr does.  Post
+types affect the look of your posts, by adding a ``post-YOURINPUTHERE``
+class to the post.  Each post can have one and exactly one type.  Nikola
+styles the following types in the default themes:
+
++-----------------+----------------------------+------------------+
+| Name(s)         | Description                | Styling          |
++=================+============================+==================+
+| text            | plain text — default value | standard         |
++-----------------+----------------------------+------------------+
+| micro           | “small” (short) posts      | big serif font   |
++-----------------+----------------------------+------------------+
 
 Creating a Page
 ---------------
@@ -901,7 +1002,7 @@ One caveat is that if any command has a % in it, you should double them.
 Here is an example, from my own site's deployment script::
 
     DEPLOY_COMMANDS = [
-        'rsync -rav --delete output/* ralsina@lateral.netmanagers.com.ar:/srv/www/lateral',
+        'rsync -rav --delete output/ ralsina@lateral.netmanagers.com.ar:/srv/www/lateral',
         'rdiff-backup output ~/blog-backup',
         "links -dump 'http://www.twingly.com/ping2?url=lateral.netmanagers.com.ar'",
     ]
@@ -924,7 +1025,8 @@ Nikola supports several third party comment systems:
 * `LiveFyre <http://www.livefyre.com/>`_
 * `Moot <http://moot.it>`_
 * `Google+ <http://plus.google.com>`_
-* `Facebook <http://facebook.com>`_
+* `Facebook <http://facebook.com/>`_
+* `isso <http://posativ.org/isso/>`_
 
 By default it will use DISQUS, but you can change by setting ``COMMENT_SYSTEM``
 to one of "disqus", "intensedebate", "livefyre", "moot", "googleplus" or
@@ -944,6 +1046,8 @@ to one of "disqus", "intensedebate", "livefyre", "moot", "googleplus" or
    * For Facebook, you need to `create an app
      <https://developers.facebook.com/apps>` (turn off sandbox mode!)
      and get an **App ID**
+   * For isso, it is the URL of isso (must be world-accessible and **have a trailing slash**,
+     default ``http://localhost:8080/``)
 
 To use comments in a visible site, you should register with the service and
 then set the ``COMMENT_SYSTEM_ID`` option.
@@ -1191,6 +1295,10 @@ The ID is 78131362 and you can embed the audio with this::
 
     .. soundcloud:: 78131362
 
+You can also embed playlists, via the `soundcloud_playlist` directive which works the same way.
+
+    .. soundcloud_playlist:: 9411706
+
 Code
 ~~~~
 
@@ -1486,7 +1594,8 @@ Custom Plugins
 --------------
 
 You can create your own plugins (see :doc:`extending`) and use them in your own
-site by putting them in a ``plugins/`` folder.
+site by putting them in a ``plugins/`` folder.  You can also put them in
+directories listed in the ``EXTRA_PLUGINS_DIRS`` configuration variable.
 
 
 Getting Extra Plugins
@@ -1495,7 +1604,7 @@ Getting Extra Plugins
 If you want extra plugins, there is also the `Plugins Index <http://plugins.getnikola.com/>`_.
 
 Similarly to themes, there is a nice, built-in command to install them —
-``install_plugin``:
+``install_plugin``::
 
     $ nikola install_plugin -l
     Plugins:
@@ -1524,6 +1633,10 @@ Similarly to themes, there is a nice, built-in command to install them —
 You can also share plugins you created with the community!  Visit the
 `GitHub repository <https://github.com/getnikola/plugins>`__ to find out more.
 
+You can use the plugins in this repository without installing them into your
+site, by cloning the repository and adding the path of the plugins directory to
+the ``EXTRA_PLUGINS_DIRS`` list in your configuration.
+
 License
 -------
 
diff --git a/docs/social_buttons.txt b/docs/social_buttons.txt
index efbf9df..61260bc 100644
--- a/docs/social_buttons.txt
+++ b/docs/social_buttons.txt
@@ -8,7 +8,7 @@
 Using Alternative Social Buttons with Nikola
 ============================================
 
-:Version: 6.2.1
+:Version: 6.3.0
 
 .. class:: alert alert-info pull-right
 
diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py
index 9e24c8f..26080aa 100644
--- a/docs/sphinx/conf.py
+++ b/docs/sphinx/conf.py
@@ -47,16 +47,16 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'Nikola'
-copyright = '2013, The Nikola Contributors'
+copyright = '2012-2014, The Nikola Contributors'
 
 # The version info for the project yo're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '6.2.0'
+version = '6.3.0'
 # The full version, including alpha/beta/rc tags.
-release = '6.2.0'
+release = '6.3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/sphinx/index.txt b/docs/sphinx/index.txt
index 6d899ab..9395e67 100644
--- a/docs/sphinx/index.txt
+++ b/docs/sphinx/index.txt
@@ -17,11 +17,3 @@ the Nikola website <http://getnikola.com/documentation.html>`_.
    internals
    tests
    social_buttons
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
diff --git a/docs/theming.txt b/docs/theming.txt
index 99492ab..1886741 100644
--- a/docs/theming.txt
+++ b/docs/theming.txt
@@ -8,7 +8,7 @@
 Theming Nikola
 ==============
 
-:Version: 6.2.1
+:Version: 6.3.0
 :Author: Roberto Alsina <ralsina@netmanagers.com.ar>
 
 .. class:: alert alert-info pull-right
@@ -172,6 +172,10 @@ These are the templates that come with the included themes:
     Used to display the list of tags and categories. ``tag.tmpl`` is used to show the contents
     of a single tag or category.
 
+``tagindex.tmpl``
+    Used to display tag indexes, if ``TAG_PAGES_ARE_INDEXES`` is True.
+    By default, it just inherits ``index.tmpl``.
+
 You can add other templates for specific pages, which the user can then use in his ``POSTS``
 or ``PAGES`` option in ``conf.py``. Also, keep in mind that your theme is yours,
 there is no reason why you would need to maintain the inheritance as it is, or not
diff --git a/docs/upgrading-to-v6.txt b/docs/upgrading-to-v6.txt
index 386d6ab..adcad08 100644
--- a/docs/upgrading-to-v6.txt
+++ b/docs/upgrading-to-v6.txt
@@ -8,7 +8,7 @@
 Upgrading to v6
 ===============
 
-:Version: 6.2.1
+:Version: 6.3.0
 
 Nikola tries fairly hard to be compatible between versions. However, there were
 a few areas which were getting clunky, and needed fxing. So, here's what you may
@@ -21,9 +21,6 @@ Themes
 ------
 
 **NOTE**
-    The install_theme command is not working yet, get themes from https://github.com/getnikola/nikola-themes
-
-**NOTE**
     There is no equivalent for the jinja-default theme yet. If you have a custom,
     jinja-based theme, upgrading is probably a bad idea right now.
 
@@ -50,11 +47,16 @@ break for you.
 
 Facebook comments support changed the HTML tag to:
 
-.. code-block: html
+.. code-block:: mako
 
-    <html% if comment_system == 'facebook': xmlns:fb="http://ogp.me/ns/fb#"
-    %endif lang="${lang}">
+    <html
+    %if comment_system == 'facebook':
+    xmlns:fb="http://ogp.me/ns/fb#"
+    %endif
+    lang="${lang}">
 
+If you do not want to use Facebook comments, you can leave the old ``<html
+lang="${lang}">`` tag in and it will work just fine.
 
 Comments
 ~~~~~~~~
@@ -72,10 +74,36 @@ If you don't, your theme should work just fine, but support only disqus comments
 Configuration
 -------------
 
-A number of options have been renamed. In all cases, the behaviour should be **exactly** as
-before. If it's not, let me know. Also, you will get warnings. That doesn't mean things
-broke. They are there to inform you of what's happening, and that you need to tweak
-your config.
+A number of options have been renamed. In most cases, the behaviour
+should be **exactly** as before.
+
+However, ``post_pages`` was split into ``POSTS`` and ``PAGES``.  Long
+story short, anything that had a ``True`` as the ``use_in_feeds``
+(last) value goes to ``POSTS`` and anything with ``False`` goes to
+``PAGES``.  For example:
+
+.. code-block:: python
+
+    post_pages = (
+        ("posts/*.txt", "", "post.tmpl", True),
+        ("stories/*.txt", "p", "story.tmpl", False),
+        ("stories/*.html", "s", "story.tmpl", False),
+    )
+
+    ### becomes ###
+
+    POSTS = (
+        ("posts/*.txt", "", "post.tmpl"),
+    )
+
+    PAGES = (
+        ("stories/*.txt", "p", "story.tmpl"),
+        ("stories/*.html", "s", "story.tmpl"),
+    )
+
+Also, you will get warnings. That doesn't mean things broke. They are
+there to inform you of what's happening, and that you need to tweak your
+config.
 
-All the deprecated options will work during the v6 cycle, and only be removed in v7, when
-those warnings will become errors.
+All the deprecated options will work during the v6 cycle, and only be
+removed in v7, when those warnings will become errors.