[Doc-SIG] DPS components

[David Goodger]

Garth T Kidd wrote:
> Could another word for 'designer' be 'filter'?

It does transformations and augmentations to the data, not just
filtering as in reduction. What I originally meant by the
'designer' was literally something that took the parsed document
trees and did something almost artistic.

> Oh, hang on. I thought the reader just passed the document to the
> parser and the designer did the hyperlink resolution and footnote
> numbering?

Trying to rationalize away the need for a designer/synthesist in
contexts other than Python source, I lumped those functions into the
reader. Maybe there should be a universal 'linker' between the input
side (reader & parser) and the output side (filer & writer)::

    +--------+      +--------+      +-------+
    | reader | ---> | linker | ---> | filer |
    +--------+      +--------+      +-------+
        |                               |
        |                               |
        |                               |
    +--------+                      +--------+
    | parser |                      | writer |
    +--------+                      +--------+

Or just a bunch of functions available for the reader to use if it
so desires.

> I'm getting completely lost there, I have to admit. I'm sure you
> have excellent reasons for making it that complex, but you should be
> prepared to write an IBG Dummy's Guide to Using the RST Parser in
> Your Simple Python Applications to explain it to the rest of us. :)

Fear not, this is just brainstorming, not final decisions. My own
brain is too puny to deal with complex issues for long so the end
product cannot be that mind-warping. I can deal with at most one
complex issue at a time, which is why I'll continue to do a lot of
refactoring of the reStructuredText parser: I'd like to be able to
understand what it's doing once its complexities have fled these
cramped confines.

I'm trying to form a good model of how this thing will work in a
generic and flexible way. Following the XP way, though, I won't be
coding for the general case before it's necessary.

> > IOW we pass a parser class (or instance) in to the reader because
> > the parser might be called repeatedly for each doclet
>
> ... such as when the contents of a directive are re-parsed so that
> we have a directive containing marked up ReST?

No, what I meant was that the parser will be used multiple times,
called once for each docstring in a module or package, instead of just
once overall (which is what ``Parser.parse(Reader())`` implies). The
integration of documents happens after they're all parsed
individually.

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net