[Doc-SIG] Making reST more useable with HTML templates

[David Goodger]

Simon Budig wrote:
> With my python knowledge coming mainly from 1.5.x I am not sure if I
> got the idea behind the packages correctly. Could somebody point me
> to a resource, why it is a good idea to have different classes with
> the same name (there are writers.Writer, html4css1.Writer and
> docutils_xml.Writer in docutils, why aren't they named after what
> they actually write?) I most probably miss something here since this
> technique is also used in the "encodings" package from the core
> python.

I did it that way out of practicality.  The front-end tells Docutils
which format it wants.  Docutils looks up that format name in a
mapping, to determine the actual module name ({'html': 'html4css1'}).
The docutils.writers module (docutils/writers/__init__.py) imports the
module, and returns the Writer class.  If each Writer class had a
different name, there would be one more level of indirection, one more
variable.  Of course, each writer could be given the same name as its
module, but I prefer lowercase module names and StudlyCaps class
names.  If done that way, it wouldn't be possible pass around the
module; the class itself would have to be passed.

It may be an arbitrary decision, but it works well for Docutils and
hasn't presented any problems.  Plus, I find the uniformity of API
elegant.

>>> Also the class names used in some <span>'s should be
>>> customizeable, maybe a dictionary with a native <--> target
>>> mapping of the class names.
>> 
>> I don't follow.  Examples?
> 
> In processed reST output you find class names like '<a
> class="reference"' or '<p class="field-name">'. If you want to
> include reST output as part of a larger website these class names
> might clash with the names in the system-wide css file.

I see.  It's not our problem.  If an application has this problem, it
can deal with it; Docutils doesn't need to.  If a real example of
conflict ever appears, we can deal with it then.  Until then, think
XP: "always do the simplest thing that could possibly work" and "never
add functionality before it's needed."

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/