Re: [pyblosxom-users] Flavours and templates

[will kahn-g. <wi...@bl...>]

On 01/29/2010 12:26 PM, Chris G wrote:
> As a (second time around) newcomer to pyblosxom I find the Flavours
> and Templates setup a little confusing.  I'll try and explain my
> problems in the following sections.
>
> 1 - There seem to be two different sorts of flavours, maybe they both
>      work the same way but it's still confusing.  There are the
>      flavours to produce different *sorts* of output, e.g. RSS and Atom
>      and html, and then there are (presumably) flavours to produce
>      different appearance in one type of output (like 'skins' in other
>      applications).

I think it's more general than that.  A flavour is a series of templates 
defining one output.  The output could be html, xhtml, xml, rdf, rss, 
rss2, atom, plain text, some kind of funky image visualization, ...


>      Initially at least it's not at all obvious how to produce
>      different HTML flavours, e.g. how to change pyblosxom's
>      appearance.  The documentation doesn't seem to tell one how to do
>      this, it only gives a rather unrealistic 'joy' example.

I'm pretty sure the documentation walks through the structure of a 
flavour and what templates are required.  Beyond that, it's just writing 
the templates.


> 2 - The default HTML flavour doesn't seem to follow the rules, it's in
>      a directory called html.flav but the files in that directory
>      *don't* have the .html suffix. So when you look at the files in a
>      downloaded flavour they don't match the default ones and you're a
>      bit stuck knowing what to do.

PyBlosxom 1.5 changes how flavours work and I'm pretty sure this is 
described in the flavours and templates documentation.

The flavour packs on the web-site need to be updated.

By the way, are you looking at the docs on the web-site or the docs in 
the docs/ directory?


> 3 - I found the only sensible way to change to one of the downloaded
>      flavours was to put the xxxx.flav directory into the flavours
>      directory of my blog installation and then change its name to
>      html.flav. (In reality one can shuffle directory names between
>      different flavours using symbolic links of course)
>
> 4 - It isn't clear what the default_flavour in config.py refers to, is
>      it the name of the flavour directory (e.g. the html in html.flav)
>      or is it the suffix on the template files inside that directory?
>      Or is it both?  (I guess it depends where the template files are
>      installed but I'm not sure).  It seems a bit odd anyway to have to
>      call a flavour which is really an HTML flavour some other name and
>      thus change the suffix on the template files - or am I totally
>      confused here?

It sounds like you're confused.  The name of a flavour is how the 
flavour is referred to.  It sounds like you're conflating how a flavour 
is implemented (file names, directory names, ...) with what a flavour is.

In PyBlosxom 1.5 a flavour is a group of templates.  It's easiest to 
package the templates in a directory named ``<flavourname>.flav``.  If 
you have a flavour named "joy", the directory would be ``joy.flav``.  If 
you have an flavour named "atom", the directory would be ``atom.flav``. 
  This directory goes in the directory specified as ``flavour_dir`` in 
your config.py file.  And that's it.

The ``default_flavour`` specifies which flavour is used by default when 
the url doesn't specify which flavour to use.


> 5 - The different places where one can install the flavour files add
>      to the confusion, I guess this has changed as pyblosxom has
>      changed. It would maybe be a good idea to describe one way of
>      doing it fully (for me the flavours directory in $blogdir) and
>      then say there are other possibilities.  At the moment it's a bit
>      mixed up (this may relate to the confusion between the name of the
>      flavour being a directory name or the suffix on the template
>      files).

I thought this is all pretty well documented.  I'll double check the 
documentation, but I'm puzzled as to how it's confusing.  If there are 
specific sections or paragraphs of the documentation you find confusing, 
let me know and I'll work on them.

Also, make sure you're looking at the documentation in the docs/ 
directory and not the documentation on the web-site.  There is no 
documentation on the web-site for PyBlosxom 1.5 yet because it's still 
in development and hasn't been released.


> 6 - Not all of the flavours in the flavours directory work and those
>      that do have a lot of hard-coded links to files in the authors'
>      blogs.  A little bit more information in the README about the blog
>      layout and what plugins are being used would help.

The flavour packs on the web-site need to be updated.

Any help with that would be much appreciated.  Otherwise, I'll get to it 
when I get to it.

/will