I had an idea for reorganizing the configuration files, that might
just work. Although a bit complex to describe, I think it will be
simple to use in practice. Here are the worked-out details so far:
* Components will define their interrelationships. For example, the
"pep_html" writer will define itself as derivative of the
"html4css1" writer, and generic "writers", via a class attribute
(perhaps "config_bases", a list of strings corresponding to config
* We create sections in the config file corresponding to Docutils
components (module name or alias). See below for a list.
* Together, these will define flat namespaces that can be applied in
order as defined by the components themselves, overlaying each
successive namespace. For example, if the "pep_html" writer is
used, effectively the "stylesheet" setting found from most specific
section will be used. The implementation is simpler: these sections
are applied in order: "[general]", "[writers]", "[html4css1]",
"[pep_html]". The last "stylesheet" wins.
* The order of precedence for config sections will be the same as that
of settings specs (general, components [parser, reader, writer],
then front end) _.
..  This is actually the precedence of settings *overrides*. The
full precedence is: first the front end's settings spec, then
component settings specs [parser, reader, writer], then component
overrides, finally the front end's overrides. But config files
can be considered as overriding the defaults.
* If more than one config file is applicable, the process is completed
and repeated for each one.
* The Docutils ConfigParser will keep track of which sections have
already been applied (in each config file) and not repeat them.
This would also allow component-specific definitions of general or
other-component-specific settings, such as writer-specific overrides
for parser settings. Front-ends could also have their own sections,
as could DocFactory and other applications of Docutils.
The full complement of sections would be as follows:
- [restructuredtext] or [restructuredtext parser] _
- [standalone] or [standalone reader]
- [pep] or [pep reader]
- [python] or [python reader] (eventually)
- [html4css1] or [html4css1 writer]
- [latex2e] or [latex2e writer]
- [pep_html] or [pep_html writer]
- [docutils_xml] or [docutils_xml writer]
- [pseudoxml] or [pseudoxml writer]
- [docbook_xml] or [docbook_xml writer] (eventually)
- [tools] (maybe, maybe not)
- [buildhtml] or [buildhtml tool] (contains some
tool-specific settings & cmdline options)
- [DocFactory] or [DocFactory tool] _
..  I prefer the second, verbose alternatives for
component-specific sections; they're unambiguous and
..  Instead of "tool" for DocFactory, perhaps "application"? This
would serve to differentiate complex apps from simple wrappers. Or
does it matter?
Several of these sections wouldn't be useful at first (e.g.
"[parsers]"; there's only one now). But "[writers]" makes sense, so I
don't think it would be premature generalization.
Or *do* component-group sections make sense? Each publisher always
uses a parser, a reader, and a writer, so all group sections will
always be applied. It may be justified if it serves a useful function
for users, to group settings by component type.
Anything I'm missing? Comments?
David Goodger http://starship.python.net/~goodger
For hire: http://starship.python.net/~goodger/cv
(includes reStructuredText: http://docutils.sf.net/rst.html)