Re: Flavours and templates

On 01/30/2010 08:46 AM, Chris G wrote:
> On Fri, Jan 29, 2010 at 12:46:28PM -0500, will kahn-greene wrote:
>> On 01/29/2010 12:26 PM, Chris G wrote:
>>>       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.

I fully expect PyBlosxom users to be technically oriented.  As such, I 
fully believe that users ARE developers and vice versa.  For people that 
don't fit in this group, I encourage them in the documentation and 
elsewhere on the site to look at other blog systems since PyBlosxom 
isn't going to work for them at this time.

Having said that, output is output is output.  So I don't think I agree 
with the this.

I'm interested in hearing other peoples' point of view.  Is this too 
complicated for technical people?  Is there a better way to distill it 
down?  (patches against svn trunk accepted!)


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

This puzzles me...  If you look at the changes section, the following 
bits all pertain to changes in flavours and templates:

6. Template variable syntax $id_escaped and $id_urlencoded has been 
removed. Use $escape(id) and $urlencode(id) instead.

9. Removed blog_title_with_path variable. If you were using this 
variable in your templates, replace it. i.e. instead of:

$blog_title_with_path

do:

$blog_title : $pi_bl

2. If you have template variables that end in _urlencoded and _escaped, 
it’s better to instead call tools.escape_text(...) and 
tools.urlencode_text(...) or use filter functions $escape(var) and 
$urlencode(var).


It is missing a note about the changes for flavour file extensions. 
I'll add that later today.


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

PyBlosxom is a loose collection of transformations allowing you to 
implement a workflow that works for you.  If you do have another 
renderer (and I think there are some in the registry), the flavours and 
templates section won't apply.  It doesn't apply to the debug renderer. 
  I think it's important to make sure the context is correct here.


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

It's not a different beast--it's just a different name for a flavour. 
Output is output is output--the name is just a name.


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

I'll think about this, but I'm puzzled as to why you're having so many 
issues.

Does anyone else find this documentation confusing?  I've posted it on 
the site and you can see it here:

http://pyblosxom.sourceforge.net/1.5/flavours_and_templates.html

/will

------------------------------------------------------------------------------
The Planet: dedicated and managed hosting, cloud storage, colocation
Stay online with enterprise data centers and the best network in the business
Choose flexible plans and management services without long-term contracts
Personal 24x7 support from experience hosting pros just a phone call away.
http://p.sf.net/sfu/theplanet-com