[Doc-SIG] DPS components

[David Goodger]

Tony J Ibbs (Tibs) wrote:
> *But* what about a synthesist component to (for instance) generate
> a contents list? In some cases that would be done via a directive
> (i.e., the author decides to "provide" it), but in other cases the
> person transforming the document may decide that they want a
> contents inserting. That sounds like a synthesis job to me, not a
> writer job...

Good point. TOC generation itself is an example of what I'd call a
filter. Index generation too. I don't know where to put those types
of document augmentation steps (putting the TOC or index back into
the document).

> I've got the refactoring bug now, I'm afraid

Glad to hear it.

> I may give in and make the next thing I work on a refactoring of
> pydps so that it *does* generate a "pure" DPS node tree as the input
> to the writer.

Please note that the tree described by dps.nodes & gpdi.dtd is
probably not sufficient for the writer to do a proper job. Extensions
to the elements (layout and formatting attributes) may be needed.

(Maybe we need 'stylists' after all! ;-)

> > I would rewrite that as::
> >
> >     .. quickreftable:: Directives (http://link-to-text)
> >
> >        For instance:
> >
> >        .. image:: images/ball1.gif
>
> Ah - but the above doesn't fail as gracefully (imagine if I want to
> be able to have invalid constructs in my example, and the poor
> person trying to format my text doesn't have the right plugin).

It's up to the directive to parse its contents. No parsing is done
automatically. If the 'quickreftable' directive isn't there, a warning
will be generated with the directive source as a literal block. If the
directive parses part of its contents normally, and *that* contains an
unknown directive, then the parsed result will contain a system
warning. I don't see the problem.

> Also, whilst I thought about folding the link in as you've done, I
> didn't, to allow for a link in parentheses to appear in the title,
> if I so wished (yep, being awkward again).

The directive can be made to extract only the *last* parenthesized
link as the "details" link.

> Ah - I've worked out why I don't see the need for Filer now.
>
> Looking at your four examples, the first two (single file or
> multi-file) are likely candidates for HTML output (for instance) -
> but if so, the HTML writer needs to know what it is doing, it can't
> be left up to an external "body" to do it (since the HTML writer
> needs to insert appropriate links, generate an index file, etc., in
> the multiple file case).

OK, so the 'filer' is just an option to the writer. That's cool too.
Implementation details. ;-)

So now the diagram looks something like this::

    +--------+      +--------+      +------------+      +--------+
    | READER | ---> | linker | ---> | transforms | ---> | WRITER |
    +--------+      +--------+      +------------+      +--------+
        |                             TOC, index,           |
        |                             etc.                  |
        |                             (optional)            |
    +--------+                                          +-------+
    | PARSER |                                          | filer |
    +--------+                                          +-------+

UPPERCASE names are major DPS components, and lowercase names are
groups of common services used as required. If synthesists and/or
stylists are also needed, I'll have to rotate the diagram.

-- 
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