pyblosxom-users — Mailing list for pyblosxom users and hackers.

Re: [pyblosxom-users] A simple question about ordering of posts

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

On 02/01/2010 06:24 AM, Chris G wrote:
>
> Should it be added to the documentation? (cb_truncatelist that is)
> Or is it too likely to cause problems?

Whoops!  It should be in the docs.  I'll add it before I release 1.5.

/will

Re: [pyblosxom-users] Flavours and templates

[chombee <ch...@la...>]

On Sun, Jan 31, 2010 at 10:14:49PM -0500, will kahn-greene wrote:
> 
> I'm seriously thinking about organizing a PyBlosxom documentation sprint 
> this week.  I'd probably organize it something along these lines:
> 
> 1. create a bunch of PiratePad pads--one per chapter that needs work in 
> the manual
> 
> 2. send a list of chapter -> PiratePad URLs to the develop list
> 
> 3. anyone who wants to work on a chapter goes to the URL for that 
> chapter and starts typing
> 
> 4. at the end of next week, I'd go through the changes, edit them, and 
> pull them into svn
> 
> Does that sound interesting to anyone?  It alleviates the pain of not 
> having svn checkin access and seriously lowers the barriers to entry for 
> helping with the documentation.

I think it's a neat idea, unfortunately I doubt that I would have time
to contribute next week.

Re: [pyblosxom-users] A simple question about ordering of posts

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

On Mon, Feb 01, 2010 at 11:24:45AM +0000, Chris G wrote:
> On Sun, Jan 31, 2010 at 09:58:54PM -0500, will kahn-greene wrote:
> > On 01/31/2010 11:16 AM, Chris G wrote:
> > > Yes, I've got this done, I have a cb_filelist which essentially
> > > duplicates blosxom_file_list_handler() but without the reverse of the
> > > sort order.
> > 
> > You could cheat and use the truncatelist callback which kicks of after 
> > the entrylist is sorted in blosxom_file_list_handler.
> > 
> I found this callback in the code when I was copying duplicates

Delete that 'duplicates'.

> blosxom_file_list_handler() as I had to have a copy of the code which
> is called as the default truncatelist for blosxom_file_list_handler()
> to work.
> 
> > It'd look something like this:
> > 
> > from Pyblosxom.pyblosxom import blosxom_truncate_list_handler
> > 
> > def cb_truncatelist(args):
> >      entrylist = args["entry_list"]
> >      entrylist.reverse()
> >      args["entry_list"] = entrylist
> > 
> >      return blosxom_truncate_list_handler(args)
> > 
> > 
> > This fails miserably if you have other plugins that implement the 
> > truncatelist callback and want to do other things.  For example, I have 
> > a wbgpager plugin that implements truncatelist to provide paging and the 
> > above cb_truncatelist would hose that.
> > 
> Should it be added to the documentation? (cb_truncatelist that is)
> Or is it too likely to cause problems?
> 
> 
> > I almost added a sort callback for 1.5.  I'm pretty sure blosxom has 
> > one.  If any of you think it'd be useful to have, I can add it in a 
> > jiffy for 1.5.
> > 
> Well I do I suppose.  :-)
> 
> -- 
> Chris Green
> 
> 
> ------------------------------------------------------------------------------
> 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
> _______________________________________________
> pyblosxom-users mailing list
> pyb...@li...
> https://lists.sourceforge.net/lists/listinfo/pyblosxom-users

-- 
Chris Green

Re: [pyblosxom-users] A simple question about ordering of posts

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

On Sun, Jan 31, 2010 at 09:58:54PM -0500, will kahn-greene wrote:
> On 01/31/2010 11:16 AM, Chris G wrote:
> > Yes, I've got this done, I have a cb_filelist which essentially
> > duplicates blosxom_file_list_handler() but without the reverse of the
> > sort order.
> 
> You could cheat and use the truncatelist callback which kicks of after 
> the entrylist is sorted in blosxom_file_list_handler.
> 
I found this callback in the code when I was copying duplicates
blosxom_file_list_handler() as I had to have a copy of the code which
is called as the default truncatelist for blosxom_file_list_handler()
to work.

> It'd look something like this:
> 
> from Pyblosxom.pyblosxom import blosxom_truncate_list_handler
> 
> def cb_truncatelist(args):
>      entrylist = args["entry_list"]
>      entrylist.reverse()
>      args["entry_list"] = entrylist
> 
>      return blosxom_truncate_list_handler(args)
> 
> 
> This fails miserably if you have other plugins that implement the 
> truncatelist callback and want to do other things.  For example, I have 
> a wbgpager plugin that implements truncatelist to provide paging and the 
> above cb_truncatelist would hose that.
> 
Should it be added to the documentation? (cb_truncatelist that is)
Or is it too likely to cause problems?


> I almost added a sort callback for 1.5.  I'm pretty sure blosxom has 
> one.  If any of you think it'd be useful to have, I can add it in a 
> jiffy for 1.5.
> 
Well I do I suppose.  :-)

-- 
Chris Green

Re: [pyblosxom-users] Flavours and templates

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

On Sun, Jan 31, 2010 at 10:14:49PM -0500, will kahn-greene wrote:
> On 01/31/2010 05:04 AM, Chris G wrote:
> >
> > A working example (for me at least) is worth a thousand words of
> > documentation, if one could just install one of the flavours, do what
> > it says in its README file and have a working flavour that really
> > would be all that's necessary I think (at least I'd have had less
> > trouble!).
> 
> The default flavours that get put in your flavourdir when you run:
> 
>      pyblosxom-cmd create <path-to-blog>
> 
> should provide the best examples because they come with PyBlosxom 1.5.
> 
They provide (if my pyblosxom-cmd was working):-

    atom.flav  error.flav  html.flav  rss.flav  rss20.flav

I don't think any of these are 'different html' flavours are they?  I
think an alternative flavour to look at with a browser would be good.


> It's possible that the bug you ran into last week with "pyblosxom-cmd 
> create ..." also didn't copy over the flavour files, so you might not 
> have seen them yet.  That's fixed now.
> 
> I'll try to get to updating the flavour packs soon.  In the meantime, 
> would it be better to remove them until I get the time to spend on them?
> 
No, I think they're a useful resource still.

> 
> > I'm quite happy to put some time into doing minor fixes to the
> > flavours and adding to/changing the README files.
> 
> I'm seriously thinking about organizing a PyBlosxom documentation sprint 
> this week.  I'd probably organize it something along these lines:
> 
> 1. create a bunch of PiratePad pads--one per chapter that needs work in 
> the manual
> 
> 2. send a list of chapter -> PiratePad URLs to the develop list
> 
> 3. anyone who wants to work on a chapter goes to the URL for that 
> chapter and starts typing
> 
> 4. at the end of next week, I'd go through the changes, edit them, and 
> pull them into svn
> 
> Does that sound interesting to anyone?  It alleviates the pain of not 
> having svn checkin access and seriously lowers the barriers to entry for 
> helping with the documentation.
> 
Sounds interesting to me, I'd try and put some time in, shall I join
the developer list?

> 
> > ... and thank you Will for continuing to maintain pyblosxom and
> > listening to my ramblings patiently.  :-)
> 
> Thank you for taking an interest and all the help you've been!
> 
> I do want to apologize for being overly curt and rude.  I went through 
> all the replies I've sent over the last couple of weeks and there are 
> several places I didn't communicate very effectively.  I work for PCF on 
> Miro as my day job and we're pushing hard for a release right now.  So 
> I'm managing two big releases of software projects at the same time and 
> I haven't been spending as much time on replies as I should be.
> 
That's absolutely fine, I have no problems with directness, I was a
little worried that I might be 'complaining' too much so maybe we
actually hit about the right balance.  :-)

-- 
Chris Green

Re: [pyblosxom-users] Flavours and templates

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

On 01/31/2010 05:04 AM, Chris G wrote:
>
> A working example (for me at least) is worth a thousand words of
> documentation, if one could just install one of the flavours, do what
> it says in its README file and have a working flavour that really
> would be all that's necessary I think (at least I'd have had less
> trouble!).

The default flavours that get put in your flavourdir when you run:

     pyblosxom-cmd create <path-to-blog>

should provide the best examples because they come with PyBlosxom 1.5.

It's possible that the bug you ran into last week with "pyblosxom-cmd 
create ..." also didn't copy over the flavour files, so you might not 
have seen them yet.  That's fixed now.

I'll try to get to updating the flavour packs soon.  In the meantime, 
would it be better to remove them until I get the time to spend on them?


> I'm quite happy to put some time into doing minor fixes to the
> flavours and adding to/changing the README files.

I'm seriously thinking about organizing a PyBlosxom documentation sprint 
this week.  I'd probably organize it something along these lines:

1. create a bunch of PiratePad pads--one per chapter that needs work in 
the manual

2. send a list of chapter -> PiratePad URLs to the develop list

3. anyone who wants to work on a chapter goes to the URL for that 
chapter and starts typing

4. at the end of next week, I'd go through the changes, edit them, and 
pull them into svn

Does that sound interesting to anyone?  It alleviates the pain of not 
having svn checkin access and seriously lowers the barriers to entry for 
helping with the documentation.


> ... and thank you Will for continuing to maintain pyblosxom and
> listening to my ramblings patiently.  :-)

Thank you for taking an interest and all the help you've been!

I do want to apologize for being overly curt and rude.  I went through 
all the replies I've sent over the last couple of weeks and there are 
several places I didn't communicate very effectively.  I work for PCF on 
Miro as my day job and we're pushing hard for a release right now.  So 
I'm managing two big releases of software projects at the same time and 
I haven't been spending as much time on replies as I should be.

/will

Re: [pyblosxom-users] A simple question about ordering of posts

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

On 01/31/2010 11:16 AM, Chris G wrote:
> Yes, I've got this done, I have a cb_filelist which essentially
> duplicates blosxom_file_list_handler() but without the reverse of the
> sort order.

You could cheat and use the truncatelist callback which kicks of after 
the entrylist is sorted in blosxom_file_list_handler.

It'd look something like this:

from Pyblosxom.pyblosxom import blosxom_truncate_list_handler

def cb_truncatelist(args):
     entrylist = args["entry_list"]
     entrylist.reverse()
     args["entry_list"] = entrylist

     return blosxom_truncate_list_handler(args)


This fails miserably if you have other plugins that implement the 
truncatelist callback and want to do other things.  For example, I have 
a wbgpager plugin that implements truncatelist to provide paging and the 
above cb_truncatelist would hose that.

I almost added a sort callback for 1.5.  I'm pretty sure blosxom has 
one.  If any of you think it'd be useful to have, I can add it in a 
jiffy for 1.5.

/will

Re: [pyblosxom-users] A simple question about ordering of posts

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

On Sun, Jan 31, 2010 at 06:54:46PM +0000, chombee wrote:
> On Sun, Jan 31, 2010 at 06:23:14PM +0000, chombee wrote:
> > Having said all this, cb_entryparser doesn't really seem like the right
> > callback for what you want to do. You don't really want to change how
> > the entry is parsed from file, just how the entry is rendered. Maybe a
> > cb_postformat plugin that adds a 'template_name' key to the entry_data
> > dict.
> 
> No, wait! I think you want the cb_story callback, the same one that the
> readmore plugin uses. Like the readmore plugin does, you can get the
> entry dict with:
> 
>     entry = args['entry']
> 
> then use 'bl_type' to see if we're dealing with an index or a permalink
> page:
> 
>     if  entry['bl_type'] == 'file':
>         # This is a 'file' page, showing a single entry.
>         pass
>     else:
>         # This is an index page (front page or year, month, day, or
>         # category etc. page) showing multiple entries.
>         entry['template_name'] = 'story-index'
> 
> As a matter of fact, a 'use different story templates for file
> pages and index pages' plugin would be much simpler and more flexible
> than the readmore plugin. If you wanted to provide a preview or summary
> text for each entry like the readmore plugin does, you could just use a
> metadata field for that.
> 
Thanks for all the thoughts, I'm just about off to bed now but I'll
re-read tomorrow.

I agree that switching templates makes more sense and is more
flexible. 

-- 
Chris Green

Re: [pyblosxom-users] A simple question about ordering of posts

[chombee <ch...@la...>]

On Sun, Jan 31, 2010 at 06:23:14PM +0000, chombee wrote:
> Having said all this, cb_entryparser doesn't really seem like the right
> callback for what you want to do. You don't really want to change how
> the entry is parsed from file, just how the entry is rendered. Maybe a
> cb_postformat plugin that adds a 'template_name' key to the entry_data
> dict.

No, wait! I think you want the cb_story callback, the same one that the
readmore plugin uses. Like the readmore plugin does, you can get the
entry dict with:

    entry = args['entry']

then use 'bl_type' to see if we're dealing with an index or a permalink
page:

    if  entry['bl_type'] == 'file':
        # This is a 'file' page, showing a single entry.
        pass
    else:
        # This is an index page (front page or year, month, day, or
        # category etc. page) showing multiple entries.
        entry['template_name'] = 'story-index'

As a matter of fact, a 'use different story templates for file
pages and index pages' plugin would be much simpler and more flexible
than the readmore plugin. If you wanted to provide a preview or summary
text for each entry like the readmore plugin does, you could just use a
metadata field for that.

Re: [pyblosxom-users] A simple question about ordering of posts

[chombee <ch...@la...>]

On Sun, Jan 31, 2010 at 06:12:53PM +0000, chombee wrote:
> No, I'm talking about the entrydata dict that the parse method
> implemented by a cb_entryparser plugin should return to pyblosxom. This
> dict is not passed to your plugin from pyblosxom, your plugin creates
> the dict from scratch and returns it to pyblosxom. Look at the parse
> method in this example:
> 
> http://pyblosxom.sourceforge.net/1.5/dev_writing_plugins.html#writing-an-entryparser
> 
> It constructs and returns a dict `entrydata` with the keys 'title' and
> 'body'. You could also add any other keys you wanted to this dict, and
> their values could be used by your flavours or your other plugins. And
> you can add the 'template_name' key, which is used by pyblosxom:
> 
> "You can also specify the template to use by setting the "template_name"
> variable in the returned dict. If the template specified doesn’t exist,
> PyBlosxom will use the story template for the specified flavour."
> 
> So if you put 'template_name' = 'story-title-only' in the dict, then
> pyblosxom will look for a template file called 'story-title-only' in
> your flavour instead of using the default template file 'story'.

Having said all this, cb_entryparser doesn't really seem like the right
callback for what you want to do. You don't really want to change how
the entry is parsed from file, just how the entry is rendered. Maybe a
cb_postformat plugin that adds a 'template_name' key to the entry_data
dict. cb_postformat gets an entry_data dict already parsed from file and
the request object as its arguments, so it seems well placed to add or
not add a 'template_name' key to entry_data based on the contents of the
request.

Also, if you write a cb_postformat plugin then you might be able to
contribute something to the currently empty 'Writing a postformatter
plugin' section in the docs!

http://pyblosxom.sourceforge.net/1.5/dev_writing_plugins.html#writing-a-postformatter

Maybe there are some examples of postformatter plugins in the plugin
registry, I'm not sure.

Re: [pyblosxom-users] A simple question about ordering of posts

[chombee <ch...@la...>]

On Sun, Jan 31, 2010 at 04:16:29PM +0000, Chris G wrote:
> > Or perhaps it could be a cb_entryparser plugin that changes the value of
> > 'template_name' in the entrydata dict if the request is for an index
> > view, using a different story template for index views and for permalink
> > pages. See:
> > 
> > http://pyblosxom.sourceforge.net/1.5/dev_writing_plugins.html#writing-an-entryparser
>
> Ah, it's 'template_name' in the 'entry' dictionary, I was looking for
> 'template' rather unsuccessfully.  No, just tried that, there's no
> 'template name' in there either.  I've just looked through the entry
> dictionary that you get in cb_story and there's no template, only the
> flavour.  There is a 'template' argument but that's the actual
> template as a string, maybe one could modif that and return in in the
> args. 

No, I'm talking about the entrydata dict that the parse method
implemented by a cb_entryparser plugin should return to pyblosxom. This
dict is not passed to your plugin from pyblosxom, your plugin creates
the dict from scratch and returns it to pyblosxom. Look at the parse
method in this example:

http://pyblosxom.sourceforge.net/1.5/dev_writing_plugins.html#writing-an-entryparser

It constructs and returns a dict `entrydata` with the keys 'title' and
'body'. You could also add any other keys you wanted to this dict, and
their values could be used by your flavours or your other plugins. And
you can add the 'template_name' key, which is used by pyblosxom:

"You can also specify the template to use by setting the "template_name"
variable in the returned dict. If the template specified doesn’t exist,
PyBlosxom will use the story template for the specified flavour."

So if you put 'template_name' = 'story-title-only' in the dict, then
pyblosxom will look for a template file called 'story-title-only' in
your flavour instead of using the default template file 'story'.

> It's just as easy to empty (or not) the 'body'.

Yeah, but I consider this solution less optimal. You might want your
items on your index views to appear different from how they look on
their permalink pages in ways other than just not having a body. Using
separate story templates for the two views is more flexible.

Re: [pyblosxom-users] A simple question about ordering of posts

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

On Sun, Jan 31, 2010 at 03:36:59PM +0000, chombee wrote:
> On Sun, Jan 31, 2010 at 02:27:41PM +0000, Chris G wrote:
> > On Sun, Jan 31, 2010 at 01:24:28PM +0000, chombee wrote:
> > > On Sun, Jan 31, 2010 at 10:09:54AM +0000, Chris G wrote:
> > > > I know it's probably totally back to front for a blog but how easy
> > > > would it be to get pyblosxom to display posts in increasing date
> > > > order?  Is the ordering set at just one place in the code?  I'm quite
> > > > happy to just patch my installed pyblosxom code as I realise this
> > > > won't be a common requirement.
> > > > 
> > > > For what it's worth I want to create a [not]blog where the story
> > > > template will just display the date and title so one sees just a list
> > > > of entries - in increasing date order.
> > > 
> > > Could you write a plugin to do this? Using the cb_filelist callback
> > > maybe:
> > > 
> > > http://pyblosxom.sourceforge.net/1.5/dev_architecture.html#cb-filelist
> > > 
> > You could well be right!  It would certainly be more elegant to do it
> > with a plugin rather than by patching the code directly.  I probably
> > need to write a plugin anyway as I need to do things at cb_story()
> > time to enable me to click on my list and view individual posts.
> 
> You shouldn't need a plugin to click on items in your list and view
> individual posts. Just make the items hyperlink to the permalink pages
> for each post. Take a look at the permalinks in the default flavour.
> 
> I think your plugin needs to do two things (maybe two different
> plugins):
> 
> 1. Reverse the sort order of items, maybe a cb_filelist plugin.
> 
Yes, I've got this done, I have a cb_filelist which essentially
duplicates blosxom_file_list_handler() but without the reverse of the
sort order.

> 2. Make it so that on index pages (such as the front page) only
> the title of each item is displayed and not the full contents (I think
> this is what you want?).
> 
You have it in one!  :-)

> I think there are a lot of ways to achieve 2. You could do it easily by
> using one flavour for the index pages and having that flavour hyperlink
> to another flavour for the permalink pages. Probably there would be much
> shared code between the two flavours, differing only in the story
> template, so one flavour could consist mostly of symlinks to the other
> flavour's files but with its own story file. I've done this before and
> it works, but I feels a little inelegant.
> 
> It might be more elegant to write a plugin. This could be a cb_story
> plugin that changes the 'body' field of a story to an empty string if
> the request is for an index view. This would be similar to the readmore
> plugin:
> 
This is the way I have done it.  Fairly simple in the end after
[re]learning various bits of python.

> http://bluesock.org/~willg/cgi-bin/devtrac.cgi/browser/trunk/pyblosxom/readmore.py#latest
> 
> Or perhaps it could be a cb_entryparser plugin that changes the value of
> 'template_name' in the entrydata dict if the request is for an index
> view, using a different story template for index views and for permalink
> pages. See:
> 
> http://pyblosxom.sourceforge.net/1.5/dev_writing_plugins.html#writing-an-entryparser
> 
> I'm a plugin-writing newbie, so my suggestions might not be the best or
> easiest way of doing things. Will would know better.
> 
Ah, it's 'template_name' in the 'entry' dictionary, I was looking for
'template' rather unsuccessfully.  No, just tried that, there's no
'template name' in there either.  I've just looked through the entry
dictionary that you get in cb_story and there's no template, only the
flavour.  There is a 'template' argument but that's the actual
template as a string, maybe one could modif that and return in in the
args. 

It's just as easy to empty (or not) the 'body'.
-- 
Chris Green

Re: [pyblosxom-users] A simple question about ordering of posts

[chombee <ch...@la...>]

On Sun, Jan 31, 2010 at 02:27:41PM +0000, Chris G wrote:
> On Sun, Jan 31, 2010 at 01:24:28PM +0000, chombee wrote:
> > On Sun, Jan 31, 2010 at 10:09:54AM +0000, Chris G wrote:
> > > I know it's probably totally back to front for a blog but how easy
> > > would it be to get pyblosxom to display posts in increasing date
> > > order?  Is the ordering set at just one place in the code?  I'm quite
> > > happy to just patch my installed pyblosxom code as I realise this
> > > won't be a common requirement.
> > > 
> > > For what it's worth I want to create a [not]blog where the story
> > > template will just display the date and title so one sees just a list
> > > of entries - in increasing date order.
> > 
> > Could you write a plugin to do this? Using the cb_filelist callback
> > maybe:
> > 
> > http://pyblosxom.sourceforge.net/1.5/dev_architecture.html#cb-filelist
> > 
> You could well be right!  It would certainly be more elegant to do it
> with a plugin rather than by patching the code directly.  I probably
> need to write a plugin anyway as I need to do things at cb_story()
> time to enable me to click on my list and view individual posts.

You shouldn't need a plugin to click on items in your list and view
individual posts. Just make the items hyperlink to the permalink pages
for each post. Take a look at the permalinks in the default flavour.

I think your plugin needs to do two things (maybe two different
plugins):

1. Reverse the sort order of items, maybe a cb_filelist plugin.

2. Make it so that on index pages (such as the front page) only
the title of each item is displayed and not the full contents (I think
this is what you want?).

I think there are a lot of ways to achieve 2. You could do it easily by
using one flavour for the index pages and having that flavour hyperlink
to another flavour for the permalink pages. Probably there would be much
shared code between the two flavours, differing only in the story
template, so one flavour could consist mostly of symlinks to the other
flavour's files but with its own story file. I've done this before and
it works, but I feels a little inelegant.

It might be more elegant to write a plugin. This could be a cb_story
plugin that changes the 'body' field of a story to an empty string if
the request is for an index view. This would be similar to the readmore
plugin:

http://bluesock.org/~willg/cgi-bin/devtrac.cgi/browser/trunk/pyblosxom/readmore.py#latest

Or perhaps it could be a cb_entryparser plugin that changes the value of
'template_name' in the entrydata dict if the request is for an index
view, using a different story template for index views and for permalink
pages. See:

http://pyblosxom.sourceforge.net/1.5/dev_writing_plugins.html#writing-an-entryparser

I'm a plugin-writing newbie, so my suggestions might not be the best or
easiest way of doing things. Will would know better.

Re: [pyblosxom-users] A simple question about ordering of posts

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

On Sun, Jan 31, 2010 at 01:24:28PM +0000, chombee wrote:
> On Sun, Jan 31, 2010 at 10:09:54AM +0000, Chris G wrote:
> > I know it's probably totally back to front for a blog but how easy
> > would it be to get pyblosxom to display posts in increasing date
> > order?  Is the ordering set at just one place in the code?  I'm quite
> > happy to just patch my installed pyblosxom code as I realise this
> > won't be a common requirement.
> > 
> > For what it's worth I want to create a [not]blog where the story
> > template will just display the date and title so one sees just a list
> > of entries - in increasing date order.
> 
> Could you write a plugin to do this? Using the cb_filelist callback
> maybe:
> 
> http://pyblosxom.sourceforge.net/1.5/dev_architecture.html#cb-filelist
> 
You could well be right!  It would certainly be more elegant to do it
with a plugin rather than by patching the code directly.  I probably
need to write a plugin anyway as I need to do things at cb_story()
time to enable me to click on my list and view individual posts.


> (love the new sphinx documentation).
> 
Yes, quite agree, it looks good doesn't it.

-- 
Chris Green

Re: [pyblosxom-users] A simple question about ordering of posts

[chombee <ch...@la...>]

On Sun, Jan 31, 2010 at 10:09:54AM +0000, Chris G wrote:
> I know it's probably totally back to front for a blog but how easy
> would it be to get pyblosxom to display posts in increasing date
> order?  Is the ordering set at just one place in the code?  I'm quite
> happy to just patch my installed pyblosxom code as I realise this
> won't be a common requirement.
> 
> For what it's worth I want to create a [not]blog where the story
> template will just display the date and title so one sees just a list
> of entries - in increasing date order.

Could you write a plugin to do this? Using the cb_filelist callback
maybe:

http://pyblosxom.sourceforge.net/1.5/dev_architecture.html#cb-filelist

(love the new sphinx documentation).

Re: [pyblosxom-users] A simple question about ordering of posts

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

On Sun, Jan 31, 2010 at 10:09:54AM +0000, Chris G wrote:
> I know it's probably totally back to front for a blog but how easy
> would it be to get pyblosxom to display posts in increasing date
> order?  Is the ordering set at just one place in the code?  I'm quite
> happy to just patch my installed pyblosxom code as I realise this
> won't be a common requirement.
> 
> For what it's worth I want to create a [not]blog where the story
> template will just display the date and title so one sees just a list
> of entries - in increasing date order.
> 
Taking to myself - sign of madness - but still.....

Is this the relevant bit, from pyblosxom.py :-

    entrylist = [(e._mtime, e) for e in entrylist]
    entrylist.sort()
    entrylist.reverse()
    entrylist = [e[1] for e in entrylist]

If I take the entrylist.reverse() will I get what I want, with no
serious untoward consequences?


-- 
Chris Green

[pyblosxom-users] A simple question about ordering of posts

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

I know it's probably totally back to front for a blog but how easy
would it be to get pyblosxom to display posts in increasing date
order?  Is the ordering set at just one place in the code?  I'm quite
happy to just patch my installed pyblosxom code as I realise this
won't be a common requirement.

For what it's worth I want to create a [not]blog where the story
template will just display the date and title so one sees just a list
of entries - in increasing date order.

-- 
Chris Green

Re: [pyblosxom-users] Flavours and templates

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

On Sat, Jan 30, 2010 at 12:13:04PM -0500, will kahn-greene wrote:
> > 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.
> 
Well I'm definitely a developer/techie, I've been working
professionally as a programmer since the early 1970s.  I'm most
certainly not a Web/HTML guru though, most of my work has been in low
level (assembler) programming on microprocessors and more recently C
and Java comms programming on Sun Solaris systems.  I'm mostly retired
now. 


> 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!)
> 

[snip lots more discussion]

I think my fundamental problem is that some/most of the flavours in
the flavour registry don't work as supplied so they don't provide
working examples to aid understanding the documentation.

Going through them we have:-

    1024px - This does actually work if you simply unpack it in the
    flavours directory and set the default flavour to 1024px.  It
    doesn't actually say this in the README.txt file though although
    it outlines lots of other things you need to do.

    Blue and blue - this unpacks to a directory called template in
    which it places flavour/template files with a .html suffix.  So to
    make it work you have either to replace the default html flavour
    with it or you have to give it a different flavour name.

    Gray - this unpacks to a directory called pyblosxom-gray, same
    requirements as for Blue and blue.

    Mainly Green - actually extracts to a directory called html.flav
    but then the content_type.html is missing so it fails for another
    reason. 

If Blue and blue, Gray and Mainly Green all did the same thing (i.e.
either extract to html.flav *or* extract to abcd.flav and have .abcd
template suffixes) it would be much easier to use the above to help
follow the documentation.

A working example (for me at least) is worth a thousand words of
documentation, if one could just install one of the flavours, do what
it says in its README file and have a working flavour that really
would be all that's necessary I think (at least I'd have had less
trouble!).

I'm quite happy to put some time into doing minor fixes to the
flavours and adding to/changing the README files.

... and thank you Will for continuing to maintain pyblosxom and
listening to my ramblings patiently.  :-)

-- 
Chris Green

Re: [pyblosxom-users] Flavours and templates

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

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

[pyblosxom-users] I've got the "Mainly Green" flavour working

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

Well after a bit of rather ham-fisted debugging I have worked out what
was wrong with the Mainly Green flavour.  It needs a content_type.html
file in its flavour directory and it doesn't come with one.

Simply copying a trivial content_type.html file to its flavour
directory gets it to work and it's actually rather 'cleaner' than some
of the other flavours in that it doesn't have any/many hard links to
things that don't exist.

-- 
Chris Green

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

Re: [pyblosxom-users] A returning user - having installation problems

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

On Fri, Jan 29, 2010 at 01:27:22PM -0500, will kahn-greene wrote:
> On 01/28/2010 08:15 PM, will kahn-greene wrote:
> > On 01/28/2010 03:51 PM, Chris G wrote:
> >>
> >> After a clean installation if I run 'pyblosxom-cmd create<dir>' in
> >> the installed pyblosxom directory (i.e. the directory where there is a
> >> data directory and the Pyblosxom directory) then the create works, but
> >> if I run it anywhere els it fails with the error I reported.
> >
> > Ahh... that might be a bug in the setup.py code. I just ditched the
> > MANIFEST.in file and maybe that's still needed. I'll take a look at it
> > tomorrow.
> 
> I re-added the MANIFEST.in file and update it and that fixes this issue.
> 
> Thank you for noticing this and reporting it!
> 
Hey, I found a bug!  :-)

-- 
Chris Green

Re: [pyblosxom-users] A returning user - having installation problems

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

On 01/28/2010 08:15 PM, will kahn-greene wrote:
> On 01/28/2010 03:51 PM, Chris G wrote:
>>
>> After a clean installation if I run 'pyblosxom-cmd create<dir>' in
>> the installed pyblosxom directory (i.e. the directory where there is a
>> data directory and the Pyblosxom directory) then the create works, but
>> if I run it anywhere els it fails with the error I reported.
>
> Ahh... that might be a bug in the setup.py code. I just ditched the
> MANIFEST.in file and maybe that's still needed. I'll take a look at it
> tomorrow.

I re-added the MANIFEST.in file and update it and that fixes this issue.

Thank you for noticing this and reporting it!

/will

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

[pyblosxom-users] Flavours and templates

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

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

    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.

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.

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?

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

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.
    


Phew!  :-)

N.B. I *have* managed to change flavours after a little perseverence,
it's not *that* difficult.


-- 
Chris Green