[Doc-SIG] DPS components
David Goodger
goodger@users.sourceforge.net
Thu, 20 Sep 2001 23:29:59 -0400
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