Re: [pyblosxom-users] Flavours and templates

[Chris G <cl...@is...>]

On Fri, Jan 29, 2010 at 12:46:28PM -0500, will kahn-greene wrote:
> 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.
> 
Yes, I hear what you're saying.  However from the *users* point of
view changing what a browser sees (i.e. different HTML templates) is
not the same sort of animal as changing the output format (i.e. HTML
or RSS or text or whatever).

I think (maybe I'm wrong) that most people will be interested in
changing what they see in their browser, i.e. they want to output
'different HTML' and the documentation doesn't really address this
requirement directly.


> 
> > 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?
> 
I'm now looking at the sphinx built documentation that comes with 1.5
(having worked out how to build it last night).

There's nothing explicit about what's changed re flavours in 1.5, I
just looked at the "Changes between 1.4.3 and 1.5" section.

By the way *starting* the section on Flavours and Templates by talking
about the renderer is a bit confusing because one almost certainly
doesn't want to get involved with the renderer.


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

I'm quite sure I am!  :-)


>                                   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.
> 
But doesn't your example of a 'joy' flavour continue this confusion? 
The flavours in the Flavour Repository are, as you say above, given
names which describe their appearance and all (except RDF possibly,
not sure) output HTML or at least Web browser interpretable output.

Your 'joy' example is a different beast.


> 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.
> 
Don't the template files have to have the same suffix as well?  E.g.
the 1024px flavour has files with a 1024px suffix.  However the
pyblosxom-gray flavour unpacks into a directory called pyblosxom-gray
but produces files with a .html suffix.


> The ``default_flavour`` specifies which flavour is used by default when 
> the url doesn't specify which flavour to use.
> 
Yes, OK, I think I'm with that now.  The only flavour I've tried that
this works with 'out of the box' though is 1024px as that's the only
one that comes with files with a suffix matching the flavour name.

> 
> > 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.
> 
I'm looking at the 1.5 documentation now, unpacked from the SVN download.

First thing, as noted above, I think you need to remove the stuff
about the renderer from the Summary section, as I understand it that's
developer rather than user information and doesn't really affect
changing flavours at all.  This could either go at the end of the
section or maybe in a different section.

The section "In the flavourdir" says:-

    You can parallel the category directories in your datadir allowing you
    to have different flavours apply to different directories. In the
    example above, the work category has a different html flavour than the
    root and home categories.

    This structure also makes it easier to use flavour packs found in the
    flavour registry on the PyBlosxom website.

    Flavour directories must end in .flav.

I think maybe you want to split the example so the first "In the
flavourdir" example has flavours *only* in the flavourdir.  Then a
second example with the extra flavour in the work directory. 

It's not absolutely clear what "parallel the category directories in
your datadir" means.  I think one could simply say "putting a flavour
in a directory in your datadir will apply that flavour to that
category of your blog".  In fact this is what the next section "In
flavour directories in the datadir" describes so I'd forget about the
bit about "parallel the category directories" in the section above
completely.  Just say at the end of the next section that it overrides the
flavourdir. 

Is the "In the datadir" section the original way that flavours worked?
It *seems* that the suffix is necessary even when flavours are in a
directory as I've just found that 1024px *does* work if you use it by
changing the default flavour to 1024px but it *doesn't* work if you
put its files in a html.flav directory.  However the default html.flav
works both with and without suffixes on the template files.

> 
> > 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.
> 
I'd be happy to do a little on that front, probably by adding more to
the README files than anything else.

As noted above I've found that the 1024px flavour does actually work,
just not using the way I found that worked with the other flavours.

Thanks for all the feedback, apart from anything else I think I know
better how flavours work now!

-- 
Chris Green