===================
config.py variables
===================

:Author: PyBlosxom Development Team
:Version: $Id: config_variables.txt 1059 2007-06-24 16:41:52Z willhelm $
:Copyright: This document is distributed under the MIT license.

.. contents::



Summary
=======

This is a non-comprehensive list of configuration variables in ``config.py``.

If you install any plugins, those plugins may ask you to set additional
variables in your ``config.py`` file--those variables will not be documented
in this file.

Additionally, any variables you set in ``config.py`` will be available in
your templates.  This is useful for allowing you to centralize any
configuration for your blog into your ``config.py`` file and use it in
templates and other places.  For example, you could move all your media
files (JPEG images, GIF images, CSS, ...) into a directory on your server
to be served by Apache and then set the variable ``$media_url`` to the
directory with media files and use that in your templates.


----------------------------

Variables
=========


base_url
--------

**REQUIRED**: no

**DATATYPE**: string

**DEFAULT VALUE**: calculated based on HTTP server variables

This is the base url for your blog.  If someone were to type this
url into their browser, then they would see the main index page
for your blog.

For example, if Joe Smith put his ``pyblosxom.cgi`` script into
a cgi-bin directory and he was using Apache, his base_url might
look like this:

   py["base_url"] = "http://joesmith.net/~joe/cgi-bin/pyblosxom.cgi"

However, it's common that this can be determined by PyBlosxom by looking
at the HTTP environment variables--so if you're not doing any url
re-writing, it's possible that PyBlosxom can correctly determine the
url and you won't have to set the base_url variable at all.

If Joe got tired of that long url, Joe might set up some url re-writing
on my web-server so that the base_url looked like this:

   py["base_url"] = "http://joesmith.net/~joe/blog"


.. Note::

   A note about trailing slashes:

   Your base_url property should NOT have a trailing slash.

.. Note::

   A note about url rewriting:

   If you use mod_rewrite rules or some other url rewriting system on
   your web-server, then you'll want to set this property.


----------------------------

blog_author
-----------

**REQUIRED**: no

**DATATYPE**: string

**DEFAULT VALUE**: ""

This is the name of the author that you want to appear on your blog. 
Very often this is your name or your pseudonym.

If Joe Smith had a blog, he might set his blog_author to "Joe Smith"::

   py["blog_author"] = "Joe Smith"


If Joe Smith had a blog, but went by the pseudonym "Magic Rocks", he
might set his blog_author to "Magic Rocks"::

   py["blog_author"] = "Magic Rocks"


----------------------------

blog_description
----------------

**REQUIRED**: no

**DATATYPE**: string

**DEFAULT VALUE**: ""

This is the description or byline of your blog.  Typically this is
a phrase or a sentence that summarizes what your blog covers.

If you were writing a blog about restaurants in the Boston area, you
might have a blog_description of::

   py["blog_description"] = "Critiques of restaurants in the Boston area"


Or if your blog covered development on PyBlosxom, your blog_description
might go like this::

   py["blog_description"] = "Ruminations on the development of " + \
                            "PyBlosxom and related things"


.. Note::

   A note about long lines:

   Remember that the ``config.py`` file is a Python code file just like
   any other Python code file.  Splitting long lines into shorter lines
   can be done with string concatenation and the ``\`` character which 
   indicates that the next line is a continuation of the current one.

   Additionally, you can use """ ... """ and ''' ... ''' if you like.


----------------------------

blog_email
----------

**REQUIRED**: no

**DATATYPE**: string

**DEFAULT VALUE**: ""

This is the email address you want associated with your blog.

For example, say Joe Smith had an email address ``joe@joesmith.net`` and
wanted that associated with his blog.  Then he would set the email
address as such::

   py["blog_email"] = "joe@joesmith.net"


----------------------------

blog_encoding
-------------

**REQUIRED**: YES

**DATATYPE**: string

**DEFAULT VALUE**: no default value--you must set this

This is the character encoding of your blog.

For example, if your blog was encoded in iso-8859-1, then you would
set the blog_encoding to::

   py["blog_encoding"] = "iso-8859-1"


.. Note::

   A note about encoding values:

   This value must be a valid encoding value.  In general, if you don't
   know what to set your encoding to and you're planning to use US or
   UK English, then setting it to ``iso-8859-1`` is probably fine.

This value should be in the meta section of any HTML- or XHTML-based flavours
and it's also in the header for any feed-based flavours.  An improper
encoding will gummy up some/most feed readers and web-browsers.

FIXME - where can we find more information about what constitutes a
valid encoding value?


----------------------------

blog_icbm
---------

**REQUIRED**: no

**DATATYPE**: string: "float,float"

**DEFAULT_VALUE**: no default value

This is the geographical location of your blgo as a latitude/longitude
pair, if appropriate.  This is used by flavours that support the ICBM
meta tag for HTML- or XHTML-based flavours.  The meta tags are used by
sites like http://geourl.org/ which track where blogs are located.

For example, if you lived at 37.448087, -122.159259, then your blog_icbm
would be set to::

   py["blog_icbm"] = "37.448089,-122.159259"


FIXME - how can you figure out where you are?

----------------------------

blog_language
-------------

**REQUIRED**: YES

**DATATYPE**: string

**DEFAULT VALUE**: no default value--you must set this

This is the primary language code for your blog.  

For example, English users should use ``en``::

   py["blog_language"] = "en"


FIXME - where's a list of valid language codes?

----------------------------

blog_title
----------

**REQUIRED**: YES

**DATATYPE**: string

**DEFAULT VALUE**: no default value--you must set this

This is the title of your blog.  Typically this should be short and is
accompanied by a longer summary of your blog which is set in 
blog_description.

For example, if Joe were writing a blog about cooking, he might title
his blog::

   py["blog_title"] = "Joe's blog about cooking"


----------------------------

codebase
--------

**REQUIRED**: no

**DATATYPE**: string

**DEFAULT VALUE**: no default set

This is the full path to where the PyBlosxom directory is on your
system.  

If you have installed PyBlosxom as a Python library by running 
``python setup.py install`` then you don't need to set the codebase
variable.

If you have NOT installed PyBlosxom as a Python library, then you DO
need to set the codebase variable.  Otherwise the Python interpreter
won't be able to find the PyBlosxom codebase and your blog will not work.

For example, if you untarred PyBlosxom into ``/home/joe/pyblosxom-1.3.2/``,
then the Pyblosxom (uppercase P and lowercase b) directory should be in
``/home/joe/pyblosxom-1.3.2/`` and you would set your codebase variable
like this::

   py["codebase"] = "/home/joe/pyblosxom-1.3.2/"


----------------------------

datadir
-------

**REQUIRED**: YES

**DATATYPE**: string

**DEFAULT VALUE**: no default value--you need to set this

This is the full path to where your blog entries are kept on the
file system.

For example, if you are storing your blog entries in 
``/home/joe/blog/entries/``, then you would set the datadir like this::

   py["datadir"] = "/home/joe/blog/entries/"


.. Note::

   A note about datadir on Windows:

   Use ``/`` to separate directories in the datadir path even if
   you are using Windows.  Examples of valid datadirs on Windows::

      py["datadir"] = "/blog/entries/"

   and::

      py["datadir"] = "e:/blog/entries/"


----------------------------

depth
-----

**REQUIRED**: NO

**DATATYPE**: integer

**DEFAULT VALUE**: defaults to 0--infinite depth

The depth setting determines how many levels deep in the directory
(category) tree that PyBlosxom will display when doing indexes.

* 0 - infinite depth (aka grab everything) DEFAULT
* 1 - datadir only
* n - n levels deep

----------------------------

flavourdir
----------

**REQUIRED**: no

**DATATYPE**: string

**DEFAULT VALUE**: no default value set

This is the full path to where your PyBlosxom flavours are kept.  

If you do not set the flavourdir, then PyBlosxom will look for your
flavours and templates in the datadir alongside your entries.

.. Note::

   A note about the spelling:

   "flavour" is spelled using the British spelling and not the American
   one.

For example, if you want to put your entries in ``/home/joe/blog/entries/``
and your flavour templates in ``/home/joe/blog/flavours/`` you would
set flavourdir and datadir like this::

   py["datadir"] = "/home/joe/blog/entries/"
   py["flavourdir"] = "/home/joe/blog/flavours/"


.. Note::

   A note about flavourdir on Windows:

   Use ``/`` to separate directories in the flavourdir path even if
   you are using Windows.  Examples of valid flavourdir on Windows::

      py["flavourdir"] = "/blog/flavours/"

   and::

      py["flavourdir"] = "e:/blog/flavours/"



----------------------------

default_flavour
---------------

**REQUIRED**: no

**DATATYPE**: string

**DEFAULT VALUE**: "html"

This specified the flavour that will be used if the user doesn't
specify a flavour in the URI.

For example, if you wanted your default flavour to be "joy", then you
would set default_flavour like this::

   py["default_flavour"] = "joy"


Doing this will cause PyBlosxom to use the "joy" flavour whenever URIs
are requested that don't specify the flavour.

For example, the following will all use the "joy" flavour::

   http://joesmith.net/blog/
   http://joesmith.net/blog/index
   http://joesmith.net/blog/movies/
   http://joesmith.net/blog/movies/supermanreturns


----------------------------

ignore_directories
------------------

**REQUIRED**: no

**DATATYPE**: list of strings

**DEFAULT VALUE**: [ ]

The ignore_directories variable allows you to specify which directories
in your datadir should be ignored by PyBlosxom.  

This defaults to an empty list (i.e. PyBlosxom will not ignore any
directories).

For example, if you use CVS to manage the entries in your datadir, then 
you would want to ignore all CVS-related directories like this::

   py["ignore_directories"] = [ "CVS" ]


If you were using CVS and you also wanted to store drafts of entries you 
need to think about some more in a drafts directory in your datadir, then 
you could set your ignore_directories like this::

   py["ignore_directories"] = [ "drafts", "CVS" ]


This would ignore all directories named "CVS" and "drafts" in your datadir
tree.


----------------------------

load_plugins
------------

**REQUIRED**: no

**DATATYPE**: list of strings

**DEFAULT VALUE**: no default value set

If the load_plugins variable is set to a list of strings, then PyBlosxom
will load the plugins specified in the order they were specified in.  If 
the load_plugins variable is set to ``[ ]`` (i.e. an empty list), then
PyBlosxom will not load any plugins.

If the load_plugins variable is not set at all, then PyBlosxom will load
all plugins that it finds in the plugin directories in alphabetical
order.

For example, if you had plugin_dirs set to ``[ "/home/joe/blog/plugins/" ]``
and there were three plugins in that directory ``pluginA.py``, ``pluginB.py``,
and ``pluginC.py`` and you did NOT set load_plugins, then PyBlosxom will
load ``pluginA`` followed by ``pluginB`` followed by ``pluginC``.

If you wanted PyBlosxom to load ``pluginA`` and ``pluginC``, then you
would set load_plugins to::

   py["load_plugins"] = [ "pluginA", "pluginC" ]


.. Note::

   A note about files versus modules:

   load_plugins should contain a list of strings where each string is
   a Python module--not a filename.  So don't add the ``.py`` to the
   end of the module name!


.. Note::

   A note about load_plugins:

   In general, it's better to explicitly set load_plugins to the
   plugins you want to use.  This reduces the confusion about which
   plugins did what when you have problems.  It also reduces the
   potential for accidentally loading plugins you didn't intend to
   load.


.. Note::

   A note about the order of the plugins:

   PyBlosxom loads plugins in the order specified by load_plugins.
   This order also affects the order that callbacks are registered
   and later executed.  For example, if pluginA and pluginB both
   implement the handle callback and you load pluginB first, then
   pluginB will execute before pluginA when the handle callback kicks
   off.

   Usually this isn't a big deal, however it's possible that some plugins
   will want to have a chance to do things before other plugins.  This
   should be specified in the documentation that comes with those
   plugins.


----------------------------

locale
------

**REQUIRED**: no

**DATATYPE**: string

**DEFAULT VALUE**: "C"

FIXME - this needs to be verified

PyBlosxom uses the locale config variable to adjust the values for
month names and dates.

In general, you don't need to set this unless you know you're not
using en_US or en_UK.

A listing of language codes is at
http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt

A listing of country codes is at:
http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

For example, if you wanted to set the locale to the Dutch language
in the Netherlands you'd set locale to::

   py["locale"] = "nl_NL.UTF-8"


----------------------------

log_file
--------

**REQUIRED**: no

**DATATYPE**: string

**DEFAULT VALUE**: no default value set

This specifies the file that PyBlosxom will log messages to.  

If this is set to "NONE", then log messages will be silently ignored.

If PyBlosxom cannot open the file for writing, then log messages will
be sent to sys.stderr.

For example, if you wanted PyBlosxom to log messages to 
``/home/joe/blog/logs/pyblosxom.log``, then you would set log_file
to::

   py["log_file"] = "/home/joe/blog/logs/pyblosxom.log"


If you were on Windows, then you might set it to::

   py["log_file"] = "c:/blog/logs/pyblosxom.log"


----------------------------

log_level
---------

**REQUIRED**: no

**DATATYPE**: string

**DEFAULT VALUE**: no default value set

**POSSIBLE VALUES**: 

* ``critical``
* ``error``
* ``warning``
* ``info``
* ``debug``

This sets the log level for logging messages.

If you set the log_level to ``critical``, then ONLY critical messages
are logged.

If you set the log_level to ``error``, then error and critical messages
are logged.

If you set the log_level to ``warning``, then warning, error, and
critical messages are logged.

So on and so forth.

For "production" blogs (i.e. you're not tinkering with configuration,
new plugins, new flavours, or anything along those lines), then this
should be set to ``warning`` or ``error``.

For example, if you're done tinkering with your blog, you might
set the log_level like this::

   py['log_level'] = "warning"


----------------------------

log_filter
----------

**REQUIRED**: no

**DATATYPE**: string

**DEFAULT VALUE**: no default value specified

This let's you specify which channels should be logged.

If log_filter is set, then ONLY messages from the specified channels
are logged.  Everything else is silently ignored.

Each plugin can log messages on its own channel.  Therefore channel 
name == plugin name.

PyBlosxom logs its messages to a channel named "root".


.. Warning::

   A warning about omitting root:

   If you use log_filter and don't include "root", then PyBlosxom 
   messages will be silently ignored!


For example, if you wanted to filter log messages to "root" and messages
from the "comments" plugin, then you would set log_filter like this::

   py["log_filter"] = [ "root", "comments" ]


FIXME - is the channel name == plugin name done automatically by 
PyBlosxom or is the channel name specified when logging?

----------------------------

num_entries
-----------

**REQUIRED**: no

**DATATYPE**: int

**DEFAULT VALUE**: 5

The num_entries variable specifies the number of entries that show up
on your home page and other category index pages.  It doesn't affect the 
number of entries that show up on date-based archive pages.

It defaults to 5 which means "show at most 5 entries".

If you set it to 0, then it will show all entries that it can.

For example, if you wanted to set num_entries to 10 so that 10 entries
show on your category index pages, you sould set it like this::

   py["num_entries"] = 10


----------------------------

plugin_dirs
-----------

**REQUIRED**: no

**DATATYPE**: list of strings

**DEFAULT VALUE**: [ ]

The plugin_dirs variable lists the directories in which you have PyBlosxom
plugins.

When you set this variable, be sure to set the load_plugins variable
as well.

This defaults to ``[ ]`` which is an empty list.

For example, if you stored your PyBlosxom plugins in 
``/home/joe/blog/plugins/``, then you would set plugin_dirs like this::

   py["plugin_dirs"] = [ "/home/joe/blog/plugins/" ]