Imported Upstream version 6.4.0upstream/6.4.0

11 files changed, 124 insertions, 88 deletions

diff --git a/docs/creating-a-site.txt b/docs/creating-a-site.txt
index 097bfb5..423b2c1 100644
--- a/docs/creating-a-site.txt
+++ b/docs/creating-a-site.txt
@@ -8,6 +8,8 @@
 Creating a Site (Not a Blog) with Nikola
 ========================================
 
+.. class:: lead
+
 One of the most frequent questions I get about Nikola is "but how do
 I create a site that's not a blog?". And of course, that's because the
 documentation is heavily blog-oriented. This document will change that ;-)
diff --git a/docs/creating-a-theme.txt b/docs/creating-a-theme.txt
index 35c2dbf..40a4566 100644
--- a/docs/creating-a-theme.txt
+++ b/docs/creating-a-theme.txt
@@ -8,6 +8,8 @@
 Creating A Theme From Scratch (Almost)
 ======================================
 
+.. class:: lead
+
 There is some documentation about creating themes for Nikola, but maybe a tutorial is also a useful way
 to explain it. So, here it is. I'll explain how to create a theme (almost) from scratch. All themes
 in Nikola must inherit from the ``base`` theme. In this case, we will inherit from ``bootstrap``
diff --git a/docs/extending.txt b/docs/extending.txt
index 25d1782..fb216c5 100644
--- a/docs/extending.txt
+++ b/docs/extending.txt
@@ -8,7 +8,7 @@
 Extending Nikola
 ================
 
-:Version: 6.3.0
+:Version: 6.4.0
 :Author: Roberto Alsina <ralsina@netmanagers.com.ar>
 
 .. class:: alert alert-info pull-right
@@ -16,11 +16,13 @@ Extending Nikola
 .. contents::
 
 
+.. class:: lead
+
 Nikola is extensible. Almost all its functionality is based on plugins,
 and you can add your own or replace the provided ones.
 
 Plugins consist of a metadata file (with ``.plugin`` extension) and
-a python module (a ``.py`` file) or package (a folder containing
+a Python module (a ``.py`` file) or package (a folder containing
 a ``__init__.py`` file.
 
 To use a plugin in your site, you just have to put it in a ``plugins``
@@ -74,7 +76,7 @@ When you run ``nikola --help`` you will see something like this::
 That will give you a list of all available commands in your version of Nikola.
 Each and every one of those is a plugin. Let's look at a typical example:
 
-First, the ``command_serve.plugin`` file:
+First, the ``serve.plugin`` file:
 
 .. code-block:: ini
 
@@ -94,7 +96,7 @@ First, the ``command_serve.plugin`` file:
           (and the .plugin file examples and explanations).
 
 For your own plugin, just change the values in a sensible way. The
-``Module`` will be used to find the matching python module, in this case
+``Module`` will be used to find the matching Python module, in this case
 ``serve.py``, from which this is the interesting bit:
 
 .. code-block:: python
@@ -104,7 +106,7 @@ For your own plugin, just change the values in a sensible way. The
     # You have to inherit Command for this to be a
     # command plugin:
 
-    class CommandBuild(Command):
+    class CommandServe(Command):
         """Start test server."""
 
         name = "serve"
@@ -272,9 +274,9 @@ These have access to the ``site`` object which contains your timeline and
 your configuration.
 
 The critical bit of Task plugins is their ``gen_tasks`` method, which ``yields``
-`doit tasks <http://pydoit.org/tasks.html>`_
+`doit tasks <http://pydoit.org/tasks.html>`_.
 
-The details of how to handle dependencies, etc. are a bit too much for this
+The details of how to handle dependencies, etc., are a bit too much for this
 document, so I'll just leave you with an example, the ``copy_assets`` task.
 First the ``task_copy_assets.plugin`` file, which you should copy and edit
 in the logical ways:
@@ -371,7 +373,7 @@ SignalHandler Plugins
 ---------------------
 
 These plugins extend the ``SignalHandler`` class and connect to one or more
-signals via `blinker <http://pythonhosted.org/blinker/>`_
+signals via `blinker <http://pythonhosted.org/blinker/>`_.
 
 The easiest way to do this is to reimplement ``set_site()`` and just connect to
 whatever signals you want there.
@@ -381,7 +383,7 @@ Currently Nikola emits the following signals:
 ``sighandlers_loaded``
     Right after SignalHandler plugin activation.
 ``initialized``
-    Right after plugin activation
+    Right after plugin activation.
 ``configured``
     When all the configuration file is processed. Note that plugins are activated before this is emitted.
 ``new_post``
diff --git a/docs/getting-help.txt b/docs/getting-help.txt
index 9cad1b3..31edc8d 100644
--- a/docs/getting-help.txt
+++ b/docs/getting-help.txt
@@ -3,7 +3,7 @@
 .. date: 1970-01-01 15:00:00
 .. description: Get help using Nikola, or contact us.
 
-:Version: 6.3.0
+:Version: 6.4.0
 
 .. class:: alert alert-info pull-right
 
diff --git a/docs/internals.txt b/docs/internals.txt
index 75e2a97..06a2747 100644
--- a/docs/internals.txt
+++ b/docs/internals.txt
@@ -8,6 +8,8 @@
 Nikola Internals
 ================
 
+.. class:: lead
+
 When trying to guide someone into adding a feature in Nikola, it hit me that
 while the way it's structured makes sense **to me** it is far from obvious.
 
@@ -52,7 +54,7 @@ actions
     What the task **does**. For example, convert a markdown document into HTML.
 
 dependencies
-    If this file changes, then we need to redo the actions. If this confguration
+    If this file changes, then we need to redo the actions. If this configuration
     option changes, redo it, etc.
 
 targets
@@ -90,7 +92,7 @@ Posts and Stories
 
 Nikola has a concept of posts and stories. Both are more or less the same thing, except
 posts are added into RSS feeds and stories are not. All of them are in a list called
-"the timeline" formed by objects of class ``Post``
+"the timeline" formed by objects of class ``Post``.
 
 When you are creating a task that needs the list of posts and/or stories (for example,
 the RSS creation plugin), your plugin should call ``self.site.scan_posts()`` to ensure
@@ -115,12 +117,12 @@ The workflow included with nikola is as follows (incomplete!):
    fragment is stored in a cache (the ``posts`` plugin).
 #. The configured theme has templates (and a template engine), which are applied to the post's
    HTML fragment and metadata (the ``pages`` plugin).
-#. The original sources for the post are copied to some accessible place (the ``sources`` plugin)
-#. If the post is tagged, some pages and RSS feeds for each tag are updated (the ``tags`` plugin)
-#. If the post is new, it's included in the blog's RSS feed (the ``rss`` plugin)
-#. The post is added in the right place in the index pages for the blog (the ``indexes`` plugin)
-#. CSS/JS/Images for the theme are put in the right places (the ``copy_assets`` and ``bundles`` plugins)
-#. A File describing the whole site is created (the ``sitemap`` plugin)
+#. The original sources for the post are copied to some accessible place (the ``sources`` plugin).
+#. If the post is tagged, some pages and RSS feeds for each tag are updated (the ``tags`` plugin).
+#. If the post is new, it's included in the blog's RSS feed (the ``rss`` plugin).
+#. The post is added in the right place in the index pages for the blog (the ``indexes`` plugin).
+#. CSS/JS/Images for the theme are put in the right places (the ``copy_assets`` and ``bundles`` plugins).
+#. A File describing the whole site is created (the ``sitemap`` plugin).
 
 You can add whatever you want to that list: just create a plugin for it.
 
diff --git a/docs/man/nikola.1 b/docs/man/nikola.1
index f794ccb..214a924 100644
--- a/docs/man/nikola.1
+++ b/docs/man/nikola.1
@@ -1,9 +1,9 @@
-.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.43.3.
-.TH NIKOLA "1" "January 2014" "nikola 6.3.0" "User Commands"
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.44.1.
+.TH NIKOLA "1" "March 2014" "nikola 6.4.0" "User Commands"
 .SH NAME
-nikola \- manual page for nikola 6.3.0
+nikola \- manual page for nikola 6.4.0
 .SH DESCRIPTION
-Nikola is a tool to create static websites and blogs. For full documentation and more information, please visit http://getnikola.com
+Nikola is a tool to create static websites and blogs. For full documentation and more information, please visit http://getnikola.com/
 .SS "Available commands:"
 .TP
 nikola auto
@@ -66,6 +66,9 @@ list tasks from dodo file
 nikola mincss
 apply mincss to the generated site
 .TP
+nikola new_page
+create a new page in the site
+.TP
 nikola new_post
 create a new blog post or site page
 .TP
diff --git a/docs/manual.txt b/docs/manual.txt
index d78b4f6..ea080bb 100644
--- a/docs/manual.txt
+++ b/docs/manual.txt
@@ -8,7 +8,7 @@
 The Nikola Handbook
 ===================
 
-:Version: 6.3.0
+:Version: 6.4.0
 
 .. class:: alert alert-info pull-right
 
@@ -203,16 +203,6 @@ 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
@@ -257,7 +247,16 @@ Longer version:
 After that, run ``nikola init --demo sitename`` and that will create a folder called
 ``sitename`` containing a functional demo site.
 
-Nikola is packaged for some Linux distributions, you may get that instead.
+Nikola is packaged for some Linux distributions, you may get that instead. e.g.
+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/
 
 libxml/libxslt errors
 ~~~~~~~~~~~~~~~~~~~~~
@@ -310,10 +309,15 @@ Installation on Windows and Windows support
 Nikola supports Windows!  Keep in mind, though, that there are some
 caveats:
 
-1. ``lxml`` and ``Pillow`` require compiled extensions.  Compiling them on
-Windows is hard for most people.  Fortunately, compiled packages exist.  Check
-their `PyPI <https://pypi.python.org/>`_ pages to find official packages, `the unofficial Gohlke binaries <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_ site, or get them somewhere else.  If you are using virtualenvs, using those pre-built packages is possible through ``virtualenv --system-site-packages``.
-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:
+#. ``lxml`` and ``Pillow`` require compiled extensions.  Compiling them on
+   Windows is hard for most people.  Fortunately, compiled packages exist.
+   Check their `PyPI <https://pypi.python.org/>`_ pages to find official packages,
+   `the unofficial Gohlke binaries <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_
+   site, or get them somewhere else.  If you are using virtualenvs, using those
+   pre-built packages is possible through ``virtualenv --system-site-packages``.
+#. 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 HDD partitions and letters (instead of
@@ -322,8 +326,8 @@ their `PyPI <https://pypi.python.org/>`_ pages to find official packages, `the u
      problems)
    * CR+LF (aka ``\r\n``) as the line separator (instead of LF ``\n``)
 
-3. Windows also dislikes some characters in paths.
-4. Most of our developers run Linux on a daily basis and may not have the full knowledge required to resolve issues relating to Windows.
+#. Most of our developers run Linux on a daily basis and may not have the full
+   knowledge required to resolve issues relating to Windows.
 
 Getting Started
 ---------------
@@ -397,39 +401,41 @@ and even individual files like ``nikola build output/index.html``
 Nikola also has other commands besides ``build``::
 
     $ nikola help
-        Nikola is a tool to create static websites and blogs. For full documentation and more information,
-        please visit http://getnikola.com
-
-
-        Available commands:
-        nikola auto                 automatically detect site changes, rebuild and optionally refresh a browser
-        nikola bootswatch_theme     given a swatch name from bootswatch.com and a parent theme, creates a custom theme
-        nikola build                run tasks
-        nikola check                check links and files in the generated site
-        nikola clean                clean action / remove targets
-        nikola console              start an interactive python console with access to your site and configuration
-        nikola deploy               deploy the site
-        nikola dumpdb               dump dependency DB
-        nikola forget               clear successful run status from internal DB
-        nikola help                 show help
-        nikola ignore               ignore task (skip) on subsequent runs
-        nikola import_blogger       import a blogger dump
-        nikola import_feed          import a RSS/Atom dump
-        nikola import_wordpress     import a WordPress dump
-        nikola init                 create a Nikola site in the specified folder
-        nikola install_theme        install theme into current site
-        nikola list                 list tasks from dodo file
-        nikola mincss               apply mincss to the generated site
-        nikola new_post             create a new blog post or site page
-        nikola run                  run tasks
-        nikola serve                start the test webserver
-        nikola strace               use strace to list file_deps and targets
-        nikola version              print the Nikola version number
-
-        nikola help                 show help / reference
-        nikola help <command>       show command usage
-        nikola help <task-name>     show task usage
-
+    Nikola is a tool to create static websites and blogs. For full documentation and more information, please visit http://getnikola.com/
+
+
+    Available commands:
+      nikola auto                 automatically detect site changes, rebuild and optionally refresh a browser
+      nikola bootswatch_theme     given a swatch name from bootswatch.com and a parent theme, creates a custom theme
+      nikola build                run tasks
+      nikola check                check links and files in the generated site
+      nikola clean                clean action / remove targets
+      nikola console              start an interactive Python console with access to your site
+      nikola deploy               deploy the site
+      nikola doit_auto            automatically execute tasks when a dependency changes
+      nikola dumpdb               dump dependency DB
+      nikola forget               clear successful run status from internal DB
+      nikola help                 show help
+      nikola ignore               ignore task (skip) on subsequent runs
+      nikola import_blogger       import a blogger dump
+      nikola import_feed          import a RSS/Atom dump
+      nikola import_wordpress     import a WordPress dump
+      nikola init                 create a Nikola site in the specified folder
+      nikola install_plugin       install plugin into current site
+      nikola install_theme        install theme into current site
+      nikola list                 list tasks from dodo file
+      nikola mincss               apply mincss to the generated site
+      nikola new_post             create a new blog post or site page
+      nikola orphans              list all orphans
+      nikola run                  run tasks
+      nikola serve                start the test webserver
+      nikola strace               use strace to list file_deps and targets
+      nikola tabcompletion        generate script for tab-complention
+      nikola version              print the Nikola version number
+
+      nikola help                 show help / reference
+      nikola help <command>       show command usage
+      nikola help <task-name>     show task usage
 
 The ``serve`` command starts a web server so you can see the site you are creating::
 
@@ -496,7 +502,7 @@ 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
+will become a CSS 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
@@ -661,8 +667,10 @@ and ``PAGES`` configuration options::
         ("stories/*.rst", "stories", "story.tmpl"),
     )
 
-It will use the first location that has the last item in ``POSTS``, or the last
-one in ``PAGES`` if ``POSTS`` is empty.
+``new_post`` will use the *first* path in ``POSTS`` (or ``PAGES`` if ``-p`` is
+supplied) that ends with the extension of your desired markup format (as
+defined in ``COMPILERS`` in conf.py) as the directory that the new post will be
+written into.  If no such entry can be found, the post won’t be created.
 
 The ``new_post`` command supports some options::
 
@@ -798,7 +806,7 @@ 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
+CSS class to the post.  Each post can have one and exactly one type.  Nikola
 styles the following types in the default themes:
 
 +-----------------+----------------------------+------------------+
@@ -870,26 +878,38 @@ There are lots of things you can do to personalize your website, but let's see
 the easy ones!
 
 CSS tweaking
-    The default configuration includes a file, ``themes/default/assets/css/custom.css``
-    which is empty. Put your CSS there, for minimal disruption of the provided CSS files.
+    Using the default configuration, you can create a ``assets/css/custom.css``
+    file and then it will be loaded from the ``<head>`` blocks of your site
+    pages.  Create it and put your CSS code there, for minimal disruption of the
+    provided CSS files.
 
     If you feel tempted to touch other files in assets, you probably will be better off
     with a `custom theme <theming.html>`__.
 
+    If you want to use LESS_ or Sass_ for your custom CSS, or the theme you use
+    contains LESS or Sass code that you want to override, create a ``less`` or
+    ``sass`` directory in your site root, put your ``.less`` or ``.scss`` files
+    there and a targets file containing the files you want compiled. Any
+    ``.less`` or ``.scss`` files from the theme chain that you want to use will
+    need to be included in your files.
+
+.. _LESS: http://lesscss.org/
+.. _Sass: http://sass-lang.com/
+
 Template tweaking
     If you really want to change the pages radically, you will want to do a
     `custom theme <theming.html>`__.
 
 
 Navigation Links
-    The 'NAVIGATION_LINKS' option lets you define what links go in a sidebar or menu
+    The ``NAVIGATION_LINKS`` option lets you define what links go in a sidebar or menu
     (depending on your theme) so you can link to important pages, or to other sites.
 
     The format is a language-indexed dictionary, where each element is a tuple of
     tuples which are one of:
 
     1. A (url, text) tuple, describing a link
-    2. A ((url, text), (url, text), (url, text), title) tuple, describing a submenu / sublist.
+    2. A (((url, text), (url, text), (url, text)), title) tuple, describing a submenu / sublist.
 
     Example::
 
@@ -1148,7 +1168,7 @@ You can apply post processing to the files in your site, in order to optimize th
 or change them in arbitrary ways. For example, you may want to compress all CSS
 and JS files using yui-compressor.
 
-To do that, you can use the provided helper adding this in your ``config.py``::
+To do that, you can use the provided helper adding this in your ``conf.py``::
 
   from nikola import filters
 
diff --git a/docs/social_buttons.txt b/docs/social_buttons.txt
index 61260bc..de7fecf 100644
--- a/docs/social_buttons.txt
+++ b/docs/social_buttons.txt
@@ -8,7 +8,7 @@
 Using Alternative Social Buttons with Nikola
 ============================================
 
-:Version: 6.3.0
+:Version: 6.4.0
 
 .. class:: alert alert-info pull-right
 
diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py
index 26080aa..faf2db1 100644
--- a/docs/sphinx/conf.py
+++ b/docs/sphinx/conf.py
@@ -54,9 +54,9 @@ copyright = '2012-2014, The Nikola Contributors'
 # built documents.
 #
 # The short X.Y version.
-version = '6.3.0'
+version = '6.4.0'
 # The full version, including alpha/beta/rc tags.
-release = '6.3.0'
+release = '6.4.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/theming.txt b/docs/theming.txt
index 1886741..b370948 100644
--- a/docs/theming.txt
+++ b/docs/theming.txt
@@ -8,13 +8,15 @@
 Theming Nikola
 ==============
 
-:Version: 6.3.0
+:Version: 6.4.0
 :Author: Roberto Alsina <ralsina@netmanagers.com.ar>
 
 .. class:: alert alert-info pull-right
 
 .. contents::
 
+.. class:: lead
+
 This document is a reference about themes. If you want a tutorial, please read
 `Creating a Theme <creating-a-theme.html>`_
 
@@ -127,7 +129,8 @@ These are the templates that come with the included themes:
     This template handles comments. You should probably never touch it :-)
     It uses a bunch of helper templates, one for each supported comment system:
     ``disqus_helper.tmpl`` ``facebook_helper.tmpl`` ``googleplus_helper.tmpl``
-    ``intensedebate_helper.tmpl`` ``livefyre_helper.tmpl`` ``moot_helper.tmpl``
+    ``intensedebate_helper.tmpl`` ``isso_helper.tmpl`` ``livefyre_helper.tmpl``
+    ``moot_helper.tmpl``
 
 ``crumbs.tmpl`` ``slides.tmpl``
     These templates help render specific UI items, and can be tweaked as needed.
diff --git a/docs/upgrading-to-v6.txt b/docs/upgrading-to-v6.txt
index adcad08..ab89614 100644
--- a/docs/upgrading-to-v6.txt
+++ b/docs/upgrading-to-v6.txt
@@ -8,7 +8,9 @@
 Upgrading to v6
 ===============
 
-:Version: 6.3.0
+:Version: 6.4.0
+
+.. class:: lead
 
 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