Re: Gaps in manual

On Fri, Jun 08, 2007 at 03:31:18PM -0400, Will Guaraldi wrote:
> 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.
> 
Yes, I realise that I *can* generate static/permanent HTML if I want
to (which is quite a plus actually) but the wonderful simplicity of
simply having a hierarchy of text (or rst) files and nothing else at
all is what I really like about Pyblosxom.


> 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.
> 
Yes, OK, but you don't *have* to have anything else at all in the
datadir and that means that using it directly as an information
resource is very practical.

[snip]
> 
> > 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.
> 
Of the six flavours in the Flavour Registry only one unpacks to a
directory called flav.xxxx and files called xxxx.flav in that
directory.  It's not terribly important but it is a bit confusing. 

It might also be a good idea to point out that xxxx.html files can be
put in the datadir (I think!) to give a flavour.

[snip]
> 
> > 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.
> 
Ah, oops, I hadn't realised that!  :-)


> 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.
> 
OK, I had seen there was an alternative way to do it, I was just using
the ?flav=xxx to look at different flavours quickly.


> 
> >     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?
> 
It doesn't explicitly say anywhere that to get a variable expanded in
your template you write $<variable name>, that's all.  It may be
blindingly obvious to anyone who uses HTML templates all the time but
it's not immediately apparent to anyone else (even if, like me,
they're programmers).


> 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.
> 
Absolutely, it's incredibly difficult and the PyBlosxom manual is
actually pretty good.

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