Short description
The formatter class and it's derivitives (html, etc) define a variety of different methods for outputting different kinds of formatting. Especially in the HTML formatter (text_html.py) many of these are responsible for creating XML/HTML elements (tags). A small number of these methods allow passing in optional parameters, for instance to allow adding css classes or id attributes. But not all the methods allow this, nor are the calling conventions consistent.
Solving this also makes it much easier to solve a lot of CSS issues; as well as allowing extensions much more flexibility in what they output. This also could go a long way to helping get the HTML output up to XHTML strict rather than the sloppy 4.0 transitional.
Proposed solution strategy
Basically at the interface level (base.py), all the methods should support passing in any number of optional keyword arguments (this technique was already used for some, but not all methods). Then the specific formatter being used can decide whether to use those or ignore them. As a simple example consider the formatting method strong(); it's signature should be changed as follows:
- def strong(self, on): + def strong(self, on, **kw):
For the HTML formatter specifically, there should be some simple conventions which allow the caller of the formatter to basically add any XHTML valid attribute. So the following calling code:
formatter.strong(1,id="123",css_class="red")
formatter.text('Hello')
formatter.string(0)could result in the following HTML fragment:
<strong id="123" class="red">Hello</strong>
To get around a few problems, some extra conventions should be employed:
- To avoid Python reserved words and variable naming restrictions, use these substitutions:
Use content_type in place of type
Use css_class in place of class
Use http_equiv in place of http-equiv
Use z_index in place of z-index
- To allow any XML namespace-qualified attribute:
Use __ in place of :, such as xml__lang in place of xml:lang
Also all such keyword-arguments can use an html__ prefix if you want to insure that only the HTML formatter sees it and no other formatter.
Some extra things the HTML formatter could do:
If it sees an alt attribute but no title, set the title the same as the alt.
If it sees a lang attribute, also set xml:lang.
Intelligently append css classes if it sees multiple, rather than replacing. Same with style attribute.
-- DeronMeranda 2006-01-12 19:14:11
Patches
I've created a set of patches which I believe implements this feature. See MoinMoinPatch/FormatterApiConsistencyForHtmlAttributes -- DeronMeranda 2006-01-12 20:13:40