Update FAQ and changelog

docs/changelog.rst

@@ -5,10 +5,17 @@ Release history
 ================
 
 * Support for Python 3!
-* Ensure exceptions are raised if they take place during processing
+* Override page save-to location from meta-data (enables using a static page as
-  with autoreload enabled with debug enabled.
+  the site's home page, for example)
+* Time period archives (per-year, per-month, and per-day archives of posts)
+* Posterous blog import
+* Improve WordPress blog import
+* Migrate plugins to separate repository
+* Improve HTML parser
 * Provide ability to show or hide categories from menu using
-  ``DISPLAY_CATEGORIES_ON_MENU`` option.
+  ``DISPLAY_CATEGORIES_ON_MENU`` option
+* Auto-regeneration can be told to ignore files via ``IGNORE_FILES`` setting
+* Document-relative URL generation (``RELATIVE_URLS``) is now off by default
 
 3.1 (2012-12-04)
 ================

docs/faq.rst

@@ -12,7 +12,7 @@ Those who don't have an IRC client handy can jump in immediately via
 `IRC webchat <http://webchat.freenode.net/?channels=pelican&uio=d4>`_. Because
 of differing time zones, you may not get an immediate response to your question,
 but please be patient and stay logged into IRC — someone will almost always
-respond.
+respond if you wait long enough (it may take a few hours).
 
 If you are unable to resolve your issue or if you have a feature request, please
 refer to the `issue tracker <https://github.com/getpelican/pelican/issues>`_.
@@ -20,9 +20,11 @@ refer to the `issue tracker <https://github.com/getpelican/pelican/issues>`_.
 How can I help?
 ================
 
-There are several ways to help out. First, you can use Pelican and report any
+There are several ways to help out. First, you can report any Pelican
 suggestions or problems you might have via IRC or the `issue tracker
-<https://github.com/getpelican/pelican/issues>`_.
+<https://github.com/getpelican/pelican/issues>`_. If submitting an issue
+report, please check the existing issue list first in order to avoid submitting
+a duplicate issue.
 
 If you want to contribute, please fork `the git repository
 <https://github.com/getpelican/pelican/>`_, create a new feature branch, make
@@ -35,7 +37,7 @@ You can also contribute by creating themes and improving the documentation.
 Is it mandatory to have a configuration file?
 =============================================
 
-No, it's not. Configuration files are just an easy way to configure Pelican.
+Configuration files are optional and are just an easy way to configure Pelican.
 For basic operations, it's possible to specify options while invoking Pelican
 via the command line. See ``pelican --help`` for more information.
 
@@ -58,14 +60,14 @@ I want to use Markdown, but I got an error.
 ===========================================
 
 Markdown is not a hard dependency for Pelican, so you will need to explicitly
-install it. You can do so by typing the following, including ``sudo`` if
+install it. You can do so by typing the following command, prepending ``sudo``
-required::
+if permissions require it::
 
-    (sudo) pip install markdown
+    pip install markdown
 
-If you don't have pip installed, consider installing the pip installer via::
+If you don't have ``pip`` installed, consider installing it via::
 
-    (sudo) easy_install pip
+    easy_install pip
 
 Can I use arbitrary meta-data in my templates?
 ==============================================
@@ -84,20 +86,24 @@ That meta-data can then be accessed in the template::
 How do I assign custom templates on a per-page basis?
 =====================================================
 
-It's as simple as adding an extra line of metadata to any pages or articles you
+It's as simple as adding an extra line of meta-data to any pages or articles
-want to have its own template.
+you want to have its own template. For example, this is how it would be handled
+for content in reST format::
 
     :template: template_name
 
+For content in Markdown format::
+
+    Template: template_name
+
 Then just make sure your theme contains the relevant template file (e.g.
 ``template_name.html``).
 
-How can I override the generated url of a specific page or article?
+How can I override the generated URL of a specific page or article?
 ===================================================================
 
-It's as simple as specifying the ``url`` and ``save_as`` special metadata to
+Include ``url`` and ``save_as`` meta-data in any pages or articles that you want
-any pages or articles you want to override the generated url.
+to override the generated URL. Here is an example page in reST format::
-Here is an example rst page::
 
     Override url/save_as page
     #########################
@@ -105,18 +111,32 @@ Here is an example rst page::
     :url: override/url/
     :save_as: override/url/index.html
 
-You're done, the page will be written to ``override/url/index.html``
+With this meta-data, the page will be written to ``override/url/index.html``
 and Pelican will use url ``override/url/`` to link to this page.
 
+How can I use a static page as my home page?
+============================================
+
+The override feature mentioned above can be used to specify a static page as
+your home page. The following Markdown example could be stored in
+``content/pages/home.md``::
+
+    Title: Welcome to My Site
+    URL: /
+    save_as: index.html
+
+    Thank you for visiting. Welcome!
+
 What if I want to disable feed generation?
 ==========================================
 
-To disable all feed generation, all feed settings should be set to ``None``.
+To disable feed generation, all feed settings should be set to ``None``.
-All but two feed settings already default to ``None``, so if you want to disable
+All but three feed settings already default to ``None``, so if you want to
-all feed generation, you only need to specify the following settings::
+disable all feed generation, you only need to specify the following settings::
 
     FEED_ALL_ATOM = None
     CATEGORY_FEED_ATOM = None
+    TRANSLATION_FEED_ATOM = None
 
 Please note that ``None`` and ``''`` are not the same thing. The word ``None``
 should not be surrounded by quotes.
@@ -124,23 +144,20 @@ should not be surrounded by quotes.
 I'm getting a warning about feeds generated without SITEURL being set properly
 ==============================================================================
 
-`RSS and Atom feeds require all URLs and links in them to be absolute
+`RSS and Atom feeds require all URL links to be absolute
 <http://validator.w3.org/feed/docs/rss2.html#comments>`_.
-In order to properly generate all URLs properly in Pelican you will need to set
+In order to properly generate links in Pelican you will need to set ``SITEURL``
-``SITEURL`` to the full path of your blog. When using ``make html`` and the
+to the full path of your site.
-default Makefile provided by the `pelican-quickstart` bootstrap script to test
-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.
 
-Feeds are still generated when this warning is displayed but may not validate.
+Feeds are still generated when this warning is displayed, but links within may
+be malformed and thus the feed may not validate.
 
 My feeds are broken since I upgraded to Pelican 3.x
 ===================================================
 
 Starting in 3.0, some of the FEED setting names were changed to more explicitly
 refer to the Atom feeds they inherently represent (much like the FEED_RSS
-setting names). Here is an exact list of the renamed setting names::
+setting names). Here is an exact list of the renamed settings::
 
     FEED -> FEED_ATOM
     TAG_FEED -> TAG_FEED_ATOM