Re: Gaps in manual

On 6/8/07, Chris G <[email protected]> wrote:
>
> 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.

This isn't necessarily true, but is rather true because of how you set
up your blog.  You can do static rendering which generates all the
HTML and other output as static files as opposed to dynamically
generated files.  These files would then be served by your web-server
like any other HTML or other types of files.

Also, you can keep other things in your datadir.  I have a couple of
plugins that keep other information in my datadir.  Additionally, you
can opt to have your flavour templates in your datadir by not
specifying a flavourdir in the config file.


> 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.

That's how we had it set up with docbook.  We've very recently
switched to reST format for the manual and will be updating the manual
accordingly.


> 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.

I'll think about these issues and try to factor them into the INSTALL
and install.txt guides.  I agree with you that the text could be
clearer on these points and that installation text can probably be
honed.


> 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.

I'm not entirely sure as to what this means.


> It also isn't immediately clear that "out of the box" pyblosxom doesn't
> have any sidebars, menus or similar.

That's an interesting point--I don't think we spell out what an
out-of-the-box installation actually contains anywhere.  I'll work on
adding that to the manual.


> 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.

I don't think there is a sortby option.  I'm guessing that you're
looking at the pyblosxom site templates I put in the tar ball.  The
PyBlosxom site uses the registry module which has its own
functionality including a sortby feature.  This is not something that
comes with PyBlosxom.

I think the only querystring option that PyBlosxom supports is
"flav=xxx", but I discourage its use.  It's better to specify the
flavour using extension.


>     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.

I'm not sure what you mean by "how to use variables in templates".
Can you clarify this paragraph?

I really appreciate your comments.  Building a manual that's clear,
concise, and comprehensive is non-trivial and impossible to do without
the thoughts and observations of others.

If anyone else has comments, thoughts, or additions that should be
added to the manual, let us know.  If you could go a step further and
provide text to be added or fixed, that would be very helpful.

/will

-------------------------------------------------------------------------
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/