Re: pyarchives_enhanced.py updated package

>> I've also thought about flavour templates. For this plugin I prefer
>> not to
>> have templates, because it is simpler without; As it is, the plugin is
>> 100%
>> compatible with the old archives plugin, i.e. you don't need to make any
>> customizations if you don't want to. With the default html template, the
>> default version should well integrate into most blogs even if users don't
>> define the CSS classes. My opinion is that flavour templates aren't relly
>> needed for it.
> 
> interesting. for plugins with very simple html, or if the html isn't
> customized much, i agree. for plugins with more complex html, though,
> flavours are helpful. some plugins include default HTML, but support
> customization through flavours, which allows backward compatibility and
> means that users can try them out without dealing with flavour templates.
> 
> compared to flavour templates, putting HTML in config variables and
> rendering pages using those variables is brittle. i don't feel too
> strongly in this case, but if the HTML was ever expanded, or more
> variables were added, i'd expect us to port it to a template.

Yes, I agree we should introduce flavour templates if the html becomes
more complex. At the moment, however I think that most people don't even
want to customize the html as they will have no need for it. They will
rather change the look over the css classes.

I just made it similar to pycategories.py. It doesn't use flavour
templates either, but five config variables instead (category_start,
category_begin, category_item, category_end, category_finish).
However, I (and I expect most people also) don't care about it because
the default values are reasonable. So I don't even need to pollute my
config.py with any additional variables.


>> I've added two sentences to the README. I like it, when the actual plugin
>> file contains all information needed to deploy it correctly. On the other
>> hand I think the README tells the reader briefly what the plugin is
>> about,
>> so replicating the documentation from pyarchives.py doesn't make too much
>> sense, as the last sentence is referring to the documentation in
>> pyblosxom.py.
> 
> yeah, understood. i don't particularly like duplication either. my
> motivation was users who aren't programmers, though. they'll know to
> read README files, but they won't always know to read actual source code
> files.

In the last sentence in README, I refer to `the documentation in the top
section of the file pyblosxom.py". So I really don't expect people to
read actual source code.
If you want more documentation in the README, I'd propose to copy the
documentation from the top docstring into README. So information would
be duplicated, but we had only one documentation to maintain.

To me it is only important that all the documentation is available in
the plugin files' top docstring, because mostly I don't know where I
have put the README files because I didn't care about them.

Do what you think it is the best!


Finally, I'm glad that the two plugin versions can be united back to one!


Kind regards,

Klaus



Ryan Barrett wrote:
> thanks for the response!
> 
> On Sun, 5 Oct 2008, Klaus Trainer wrote:
> 
>> I've also thought about flavour templates. For this plugin I prefer
>> not to
>> have templates, because it is simpler without; As it is, the plugin is
>> 100%
>> compatible with the old archives plugin, i.e. you don't need to make any
>> customizations if you don't want to. With the default html template, the
>> default version should well integrate into most blogs even if users don't
>> define the CSS classes. My opinion is that flavour templates aren't relly
>> needed for it.
> 
> interesting. for plugins with very simple html, or if the html isn't
> customized much, i agree. for plugins with more complex html, though,
> flavours are helpful. some plugins include default HTML, but support
> customization through flavours, which allows backward compatibility and
> means that users can try them out without dealing with flavour templates.
> 
> compared to flavour templates, putting HTML in config variables and
> rendering pages using those variables is brittle. i don't feel too
> strongly in this case, but if the HTML was ever expanded, or more
> variables were added, i'd expect us to port it to a template.
> 
>> I've added two sentences to the README. I like it, when the actual plugin
>> file contains all information needed to deploy it correctly. On the other
>> hand I think the README tells the reader briefly what the plugin is
>> about,
>> so replicating the documentation from pyarchives.py doesn't make too much
>> sense, as the last sentence is referring to the documentation in
>> pyblosxom.py.
> 
> yeah, understood. i don't particularly like duplication either. my
> motivation was users who aren't programmers, though. they'll know to
> read README files, but they won't always know to read actual source code
> files.
> 
> -Ryan
> 
> -- 
> http://snarfed.org/

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/