'''Comment on style.
I am a huge proponent of the `Python-style guide`_, mostly because it's
reasonable, Guido wrote it, and I'd like all Python code to be consistent.
Unfortunately, I am not in a position to suggest an HTML style guide since
there is no obvious standard. (Nonetheless, I do heartily recommend DTD
compliance.) Last of all, there is no official Cheetah style guide.
Hence, I *recommend* the following:
* When a line contains HTML, placeholders, or directives that do *not* continue
to the end of the line, indent the text using your choosen HTML style guide.
* When the line contains a single directive that continues to the end of the
line, indent the text using the Python style guide.
* The above two statements suggest that the indentation of a line should depend
on whether it's mostly HTML or Python. Python indentation has no affect
on HTML indentation, and vice versa. This approach was inspired by Mason.
* The Python style guide has very specific recommendations for Python docs.
However, the Cheetah equivalent of triple quoted strings will result in
extraneous HTML whitespace when naively applied, which is occasionally a very
bad thing. For the same reason, the body of a Cheetah method should start
its indentation at the left column. Hence, I suggest the following::
|#def __call__
|#*doc-method: Single line.
|
|More text.
|
|*##slurp
|<p>
| Hello, there!
|</p>
|#end def
* Likewise, if you use ``#implements foo``, blank lines between methods will
end up in the ``foo`` method. Hence, it's easier not to use ``#implements``
but to instead define an explicit ``foo`` method. This rule may be broken if
HTML whitespace is irrelevent. For example, you may want to constrain
Cheetah to just the top two lines of an otherwise HTML-only file.
* A screen should document the arguments that it expects. However, if it is
expecting a bean (see aquarium.screen.ScreenAPI_), the description of the
bean itself should be left in the bean's class.
* When using gettext, do the following::
|<ul>
| <li>$_("Indent one line strings inline.")</li>
| <li>
| $_("""\\
|Because indentation matters when doing a gettext lookup, don't indent
|multi-line blocks of text. Otherwise, if you need to change the
|indentation, you'll have to update the translation catalog.""")
| </li>
.. _Python-style guide: http://www.python.org/doc/essays/styleguide.html
.. _aquarium.screen.ScreenAPI: aquarium.screen.ScreenAPI-module.html
'''
__docformat__ = "restructuredtext"
# Created: Tue Mar 30 14:52:01 PST 2004
# Author: Shannon -jj Behrens
# Email: jjinux@users.sourceforge.net
#
# Copyright (c) Shannon -jj Behrens. All rights reserved.
|