'''Short description'''

## Tell your story here.
## What is the problem you are trying to solve?
## Is this features useful to most users or just to specific users?

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 ''class''es if it sees multiple, rather than replacing.  Same with ''style'' attribute.

-- DeronMeranda <<DateTime(2006-01-12T19:14:11Z)>>

= Patches =

I've created a set of patches which I believe implements this feature.
See [[MoinMoinPatch/FormatterApiConsistencyForHtmlAttributes]] -- DeronMeranda <<DateTime(2006-01-12T20:13:40Z)>>

= Discussion =

----
CategoryFeatureImplemented