Gaps in manual

These are just my initial thoughts as a newcomer to Pyblosxom.  I'm a
a long time Unix C/C++ programmer (since around 1980 or so) and have
been using Slackware Linux on my home system for several years.  I
have been playing with various Wikis, Blogs and CMS systems for a few
months now looking for something that suits.

Thus while I am fairly blog-naive and moderately python naive I am
fairly happy hacking around on the command line.  One of the *big*
advantages of pybloxsom for me is the ability to create my blog (and
other information) using vi (actually vile) in a simple directory
structure such that I can use the reStructured Text files directly as
well as via the web.

So, to things missing from the manual....

In Chapter 1 I think the simplicity of pybloxsom should be expanded. I
hadn't realised until I tried it that the HTML (and other) generation
is 'dynamic', i.e. the HTML isn't kept.  Plus, an important addition,
there is *nothing* but the .txt files in the directory structure from
which the blog/site is generated.  The lack of other 'noise' is, for
me at least, a huge advantage.


A more general comment, the manual layout is a bit odd in that when
you go to a top level section, e.g. Chapter 2 you get to seen the
chapter description plus the whole of section 2.1 but you have to
click on links to get to sections 2.2, 2.3, etc.


I found installation fairly easy though it's not for a total beginner.
I did have a bit of trouble with the name varying in its
capitalisation.  PyBlosxom, Pyblosxom, pyblosxom.  In fact my first
attemp at installation failed due to this (maybe also because I kept
on spelling it pybloxsom) and I finally threw it all away and started
again from scratch which worked OK.

It might be worth emphasising the spelling as it is very easy to get
wrong.


As I've said already in previous mail I found flavours a little
confusing, it isn't helped by only one of the flavours in the flavour
registry actually supplying files with the right names.  It also isn't
immediately clear that "out of the box" pyblosxom doesn't have any
sidebars, menus or similar.


Actual missing (or I can't find it) information:-

    What "?xxxx=yyyy" options are available?  There doesn't seem to be
    a list of these anywhere and I only found the one or two I know
    about by observation.  In particular I can't find anything about
    what the sortby option does.

    There doesn't appear to be anywhere that tells how to use
    variables in templates, again one can find out by looking at
    examples but it would be good to have it spelt out.


-- 
Chris Green

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/