================
PyBlosxom Manual
================

:Author: PyBlosxom Development Team
:Version: $Id: index.txt 1050 2007-06-20 19:11:53Z willhelm $
:Copyright: This document is distributed under the MIT license.

.. contents::



Introduction
============

The manual pages in this directory will cover all aspects of using
and developing for PyBlosxom.  

It is a work in progress.



Mission, What's Missing, and Helping Out
========================================

The mission of this manual is to cover all aspects of using and
developing for `Pyblosxom`_. It is very much a work in
progress. However, we do promise that the manual will get better over
time.

.. _Pyblosxom: http://pyblosxom.sourceforge.net/

This manual will always be free.  It's licensed under the MIT License
along with the rest of PyBlosxom.  The manual is version controlled along 
with the rest of PyBlosxom in the SVN repository at SourceForge.  That's a 
boon because everyone can see the `current state`_.

.. _current state: http://pyblosxom.svn.sourceforge.net/viewvc/pyblosxom/trunk/pyblosxom/docs/

There's no list of what's missing, however, there are a series of
FIXMEs placed around the document with some details as to what needs
to be provided and/or fixed.  I'm sure there are things missing that
have been completely overlooked as well.  This can change if someone
wants to organize a list of missing topics (which would then probably
cause a reorganization of the manual to account for those topics).

If you want to help out with documentation, let us know on the
`pyblosxom-devel`_ mailing list.  If you notice errors, missing
pieces, sections that are unclear, examples that are erroneous, or
anything else, `let us know`_.

.. _pyblosxom-devel: http://lists.sourceforge.net/lists/listinfo/pyblosxom-devel
.. _let us know: mailto:pyblosxom-devel@lists.sourceforge.net

Details of mailing lists and other contact information are on our
web-site at http://pyblosxom.sourceforge.net/.


Contents
========

Note: The documentation exists in a text-form as well as an html-form.
For each bit of documentation, we have the text file as well as a link
to the html file if you're using a web-browser to view this document.


**about_pyblosxom** 

   docs/about_pyblosxom.txt: `about pyblosxom <about_pyblosxom.html>`_

   This document covers what PyBlosxom is and the goals of the PyBlosxom
   project.  It also has a section on who probably shouldn't use PyBlosxom.
   Additionally, it has a section on where to go for help if you're having
   problems with PyBlosxom.

**installation**

   These documents cover PyBlosxom installation, trouble-shooting tips, 
   and where to go for help if PyBlosxom isn't working for you for a variety
   of different setups.

   **install_cgi.txt**

      docs/install_cgi.txt: `install as CGI <install_cgi.html>`_

      Covers installing PyBlosxom under CGI.  This is probably the most common
      installation method.  It's the most comprehensive installation document
      we have, too.

   **install_paste.txt**

      docs/install_paste.txt: `install under Paste <install_paste.html>`_

      Covers installing PyBlosxom with Paste.

   **install_wsgi.txt**

      docs/install_wsgi.txt: `install under WSGI <install_wsgi.html>`_

      Covers installing PyBlosxom under WSGI.

   **install_debian.txt**

      docs/install_debian.txt: `install on Debian <install_debian.html>`_

      Covers installing PyBlosxom on Debian.

**advanced installation**

   docs/advanced_installation.txt: `advanced installation <advanced_installation.html>`_


   This document covers "advanced" aspects of installation such as
   tweaking your ``.htaccess`` file if you are using Apache to make
   the url more user-friendly, ...

**flavours and templates**

   docs/flavours_and_templates.txt: `flavours and templates <flavours_and_templates.html>`_

   This document covers creating and editing flavours and templates.
   Flavours and templates are part of PyBlosxom's templating system.


**plugins**

   docs/plugins.txt: `plugins <plugins.html>`_

   This document covers installing and using plugins with PyBlosxom.

**writing entries**

   docs/writing_entries.txt: `writing entries <writing_entries.html>`_

   This document covers writing entries in your new blog.

**static rendering**

   docs/static_rendering.txt: `static rendering <static_rendering.html>`_

   This document covers static rendering with PyBlosxom.  This allows
   you to generate static pages that constitute your site and can be
   served by any web-server without any need for CGI.

**comments**

   docs/comments.txt: `comments <comments.html>`_

   This document covers installing the comments plugin and related
   plugins.  It also covers ways to reduce comment spam.

**syndication**

   docs/syndication.txt: `syndication <syndication.html>`_

   This document covers how to set up syndication in PyBlosxom.
   PyBlosxom has built-in formats for Atom 1.0, RSS 2.0, and RSS 0.9.1.

**dev architecture**

   docs/dev_architecture.txt: `architecture <dev_architecture.html>`_

   This document covers how PyBlosxom is architected.  If you're writing
   a plugin, then this document will help you know where things are and
   how to use them.

**dev writing plugins**

   docs/dev_writing_plugins.txt: `writing plugins <dev_writing_plugins.html>`_

   This document covers how to write PyBlosxom plugins.  It also covers
   all the callbacks and their semantics.

**config variables**

   docs/config_variables.txt: `config variables <config_variables.html>`_

   This document covers all the variables that are available in your
   ``config.py`` file.