Documentation
Cliff Wells
1) Remove framework-specific information from core docs.
2) Create specific sections for major frameworks that covers
installation, configuration and framework-specific usage.
3) Fix errors and omissions.
4) Better examples.
The work-in-progress for the core documentation is here:
http://breve.twisty-industries.com/documentation
Other sections will follow soon.
I'm interested in hearing suggestions:
- Are parts unclear?
- Were there features of Breve you found hard to learn?
- Do you have examples or recipes you'd like to see added to the docs?
- Did you have problems getting Breve to work with your framework of
choice?
Let me know!
Regards,
Cliff
cbrain
I've typed this response as I was reading the documentation at the URL
that you supplied in your post. Here are my comments:
- In the "Using variables" section, you don't actually supply the code
of the template that you speak about in the text :-) This makes it
confusing for people who can't imagine what the template would have to
look like themselves.
- I would suggest moving the part about the underscore on attribute
name that conflict with reserved keywords to a separate section, out
of the "Template inheritance" section, which has nothing to do with
it. That makes it easier to find if people are specifically looking
for this information.
- In the section about "Conditional expressions", please put a remark
in there somewhere that all expressions are evaluated, except in a
boolean operator context. This is especially true for the "dictionary
as a selector" example, which evaluates both the keys and their
values, even though only one of them is actually used.
- The list comprehension example in the same section actually has
nothing at all to do with conditional expressions, so it should
probably be placed into a section that talks about repetition.
- The "dictionary as a selector" example is useful as it is, but
perhaps you could add an example that allows for a default value in
case the tested values in not amongst the keys, like:
{ "key1": "Hello", "key2": "Goodbye" }.get(value_to_test, "Some
default message")
- In the section about "Custom flatteners", perhaps you should mention
that the way that types are matched is actually done by comparing the
type EXACTLY, and not with something like isinstance().
- Perhaps it should be mentioned somewhere that a Template instance
can only be used safely once to render a template?
This is all so far, I think the documentation is quite good! The
documentation is where I got the good feeling about Brevé in the first
place. After reading it I remember thinking "this is absolutely great,
so clean, so Pythonic ... I'm definitely going to use this template
engine". And I still do exactly that :-)
--
Thanks for all your efforts!
Sven
cbrain
There should be something about Unicode and UTF-8 in the
documentation. The way I use Brevé, the render() call gets me a
Unicode string, which I have to encode as UTF-8 just before sending it
to my remote client using the .encode("utf-8") call. Others may use
Brevé to get already-UTF-8-encoded 'str' strings, which can then be
sent off without any further conversion.
You should also warn against mixing UTF-8 and Unicode strings in the
templates themselves, because that will cause problems unless the
global system's encoding setting is set to UTF-8. If it isn't, the
result will not be what you would expect them to be.
--
Cliff Wells
On Thu, 2008-04-10 at 14:04 -0700, cbrain wrote:
> Hello Cliff,
>
> I've typed this response as I was reading the documentation at the URL
> that you supplied in your post. Here are my comments:
>
> - In the "Using variables" section, you don't actually supply the code
> of the template that you speak about in the text :-) This makes it
> confusing for people who can't imagine what the template would have to
> look like themselves.
It was there, but an error in my restructured text syntax made it
disappear. Fixed.
> - I would suggest moving the part about the underscore on attribute
> name that conflict with reserved keywords to a separate section, out
> of the "Template inheritance" section, which has nothing to do with
> it. That makes it easier to find if people are specifically looking
> for this information.
Fixed. I moved it to the section "Basic HTML Generation" where it seems
to fit best.
> - In the section about "Conditional expressions", please put a remark
> in there somewhere that all expressions are evaluated, except in a
> boolean operator context. This is especially true for the "dictionary
> as a selector" example, which evaluates both the keys and their
> values, even though only one of them is actually used.
I added a note with a short example at the end.
> - The list comprehension example in the same section actually has
> nothing at all to do with conditional expressions, so it should
> probably be placed into a section that talks about repetition
Point taken. I've added a new section. I've decided to keep the tag
multiplication, but the macro method you've suggested will be added once
the code is commited to svn.
> - The "dictionary as a selector" example is useful as it is, but
> perhaps you could add an example that allows for a default value in
> case the tested values in not amongst the keys, like:
>
> { "key1": "Hello", "key2": "Goodbye" }.get(value_to_test, "Some
> default message")
I've added another example to illustrate this.
>
> - In the section about "Custom flatteners", perhaps you should mention
> that the way that types are matched is actually done by comparing the
> type EXACTLY, and not with something like isinstance().
Hm. I wonder if this is a misfeature. The exact match makes for an
efficient lookup, but I wonder if this has actually bitten anyone? I'll
make a note of it, since that does reflect the current state, but I
think we should discuss this further.
> - Perhaps it should be mentioned somewhere that a Template instance
> can only be used safely once to render a template?
Good point. It's in the FAQ, but I've added it to the API section
(which needs far more docs anyway).
> This is all so far, I think the documentation is quite good! The
> documentation is where I got the good feeling about Brevé in the first
> place. After reading it I remember thinking "this is absolutely great,
> so clean, so Pythonic ... I'm definitely going to use this template
> engine". And I still do exactly that :-)
Thanks for the thorough review! Ironically, it's often difficult to
document things you are too familiar with, so reviews like yours are
invaluable.
Regards,
Cliff