=================
 About PyBlosxom
=================

What is PyBlosxom
=================

PyBlosxom is a lightweight weblog system.  It was originally a Python
clone of `Blosxom`_ but has since evolved into a weblog system of its
own reminiscent of `Blosxom`_.

.. _Blosxom: http://www.blosxom.com/

PyBlosxom focuses on three things:

**simplicity**

  PyBlosxom stores all data on the file system in plain text files.
  This allows you to use any text editor to create, update and
  manipulate entries.  You can also use existing text-manipulation
  tools, version control, scripts, grep, ...  for managing your blog.

  PyBlosxom can run as a CGI script, WSGI component or you can use it
  to statically compile your website into HTML/XML files.

  Your workflow is your workflow.

**extensibility**

  PyBlosxom has a plugin framework enabling you to augment and enhance
  PyBlosxom's default behavior.  Plugins are written in Python.  We
  maintain a list of plugins in the plugin registry on the website.

  Plugins aren't hard to write.  We're happy to help you write
  plugins.

**community**

  There are several hundred PyBlosxom users out there all of whom have
  different needs.  PyBlosxom is used on a variety of operating
  systems in a variety of environments.  We have the standard open
  source project fare: mailing lists, IRC channel, wiki, ...

PyBlosxom is built to let you use existing text-manipulation tools
without having to build the whole ecology from scratch.

PyBlosxom can be run as:

* a "static renderer" and compile your blog
* a CGI script
* a WSGI application


Why you might not want to use PyBlosxom
=======================================

PyBlosxom is a small open source project and while there is a
community, it's pretty small.  PyBlosxom's features are great
but make it a niche weblog engine.

PyBlosxom is a *file-based* weblog system.  Each blog entry is a separate
file stored in a directory hierarchy on your file system.
By default, the hierarchy is a category tree meaning each blog entry belongs
in a single category.  By default, mtimes are used as the blog entry
timestamp.  There are plugins that change this behavior, but require
extra configuration to use.

There are a lot of other weblog systems out there.  If it's apparent
that PyBlosxom won't work for you, don't force it---use something else.
Possibilities include:

**WordPress**

    http://wordpress.org/

    PHP/database based weblog system that a lot of people use.

**Zine**

    http://zine.pocoo.org/

    Python-based weblog system that's a lot like WordPress, but it's
    written in Python and supports Python plugins.

**ikiwiki**

    http://ikiwiki.info/

    ikiwiki is written in Perl and melds blogging with wiki with
    version control storage.

**jekyll**

    http://github.com/mojombo/jekyll

    A blog-aware, static site generator in Ruby.


Overview of PyBlosxom
=====================

Entries, categories, storage:

* PyBlosxom stores everything as files on the file system---there is
  no database.
* Each blog entry is a file.
* Blog entry files are stored in a directory hierarchy in your *datadir*.
* Each subdirectory in your *datadir* corresponds to a category of
  your blog.

Themes:

* Themes in PyBlosxom are called *flavours*.
* A flavour consists of a set of templates.
* Flavours are stored in a directory called the *flavourdir*.
* PyBlosxom comes with several flavours: html, rss20, and atom.
* The `PyBlosxom website`_ maintains a flavour registry for flavours
  contributed by people like you.
* There's more information in the chapter on
  :ref:`Flavours and Templates <flavours-and-templates>`.

Plugins:

* PyBlosxom has a plugin system.
* Plugins are written in Python.
* Plugins are loaded using the ``plugin_dirs`` and ``load_plugins``
  configuration variables.
* For more information on using plugins see
  :ref:`Plugins <using-plugins>`.
* For more information on writing plugins see
  :ref:`Writing Plugins <writing-plugins>`.
* The `PyBlosxom website`_ maintains a plugin registry for plugins 
  submitted by people like you.

.. _PyBlosxom website: http://pyblosxom.bluesock.org/


.. _project-details-and-contact:

Project details, contact information, and where to go for help
==============================================================

See http://pyblosxom.bluesock.org/contact for details on the mailing lists, 
IRC, source code, issue tracker, and everything else.


Requirements
============

* Python 2.4 or higher, but not Python 3
* (optional) Sphinx for building documentation
* (optional) other things depending on what plugins you install


How to install PyBlosxom
========================

Read the ``INSTALL`` document as well as other documents in the ``docs/``
directory.

If you're upgrading from a previous PyBlosxom version, read the
``UPGRADE`` document as well as ``CHANGELOG`` which covers what's new
in this version and what you'll need to change in your blog.


How to find comprehensive documentation
=======================================

There's a series of text files in the ``docs/`` directory which
comprise the current state of the PyBlosxom manual at the time of this
release.

The most current version of the manual can be found on the `PyBlosxom
website <http://pyblosxom.bluesock.org/>`_ .


How to report bugs, send in patches, fix problems
=================================================

We really appreciate people helping out.

If you discover a problem with PyBlosxom, please let us know on IRC
(``#pyblosxom`` on ``irc.freenode.net``) or on the mailing lists.

If you can additionally fix it, attach a patch file to the bug or send
the patch as an attachment to the pyblosxom-devel mailing list.
When sending a patch, please make sure to describe the details of
the problem you are fixing.


How to run unit tests
=====================

Tests are written with the Python unittest module.

To run core tests, do this::

    python setup.py test

This will build PyBlosxom, then run the tests.

To run plugin unit tests do this::

    PYTHONPATH=. python plugins/testrunner.py

That will run all the plugins tests.

If you would like to add tests to the test suite, please do and send
us patches!
