[Python-Dev] Pydoc Improvements / Rewrite

[Ka-Ping Yee]

On Thu, 4 Jan 2007, Talin wrote:
> One issue that needs to be worked out, however, is the division of
> responsibility between markup processor and output formatter. Does a
> __markup__ plugin do both jobs, or does it just do parsing, and leave
> the formatting of output to the appropriate HTML / text output module?
> How does the HTML output module know how to handle non-standard metadata?
[...]
> I guess the markup processor has to deliver some kind of DOM tree, which
> can be rendered either into text or into HTML. CSS can take over from
> that point on.

If the markup processor is going to deliver a tree, let me just point
out that it would be a pretty major project to define the format of
that tree -- about as large as inventing ReST or any other markup
language, except that the design of such an intermediate format has
to foresee future changes to the input and be flexible enough to target
multiple output formats.  The design would also have to tackle the
question of whether the intermediate format should contain semantic
information (what about cross-references?) and what types of such
information should be allowed (e.g. names of modules, arguments,
exceptions, Python expressions, etc.)


-- ?!ng