[Doc-SIG] DPS components

Tony J Ibbs (Tibs) tony@lsl.co.uk
Fri, 21 Sep 2001 10:02:20 +0100


David Goodger wrote:
> 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).

It may be as simple as allowing a later stage to "call" an earlier stage
to "refine" an aspect of the document. But it's the sort of thing that
normally becomes clear when you write it once, then look at it for a
while and go "no, that's wrong, the *obvious* way is to do it like
this...".

> > I've got the refactoring bug now, I'm afraid
>
> Glad to hear it.

Oh, wanting to rewrite code to make it better isn't new - I've liked
working that way since I started! What's new is that there is now some
respectability to the idea - it isn't (necessarily) just seen as
programmer's wasting time by either wanting to refine something that's
"good enough" (by someone else's criteria, which don't take into account
things like maintenance), or even (!) by "not writing it right in the
first place".

In this instance, though, your ideas have tipped me over from being a
little bit unsure that the tack I had taken for output was right into
thinking that it is definitely inelegant, and I can see a more elegant
route (with other benefits as well - but then, that's one of the
definitions of "elegance" in programming).

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

Oh, for sure - but the easiest way to find out is to try!

I know for a start that I will likely want to able to add a "style"
attribute to most things (optionally, of course), and also that we will
need a ``Span`` Element node - c.f. the <span> tag in HTML, etc. - this
allows one to identify a segment of the tree (I'll settle for a
subtree!) as being linked for stylistic purposes.

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

The Hairdresser class may still be in front of us.

More seriously, I'm still unsure of *how* one chooses a particular style
and implements its details - but again, this sort of thing comes clear
in the wash...

> > >     .. quickreftable:: Directives (http://link-to-text)
> > >
> > >        For instance:
> > >
> > >        .. image:: images/ball1.gif
>
> 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.

Ah - all is clear. You're right - no problem.

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

"linker" stitches together references and such?

"transforms" should, of course, be "transformers", to be the same part
of speech.

I'm still unhappy with the *name* "filer", especially since your game
plan for it involves generating memory structures "half" the time -
"output manager" is slightly more accurate, if too verbose. But it
doesn't matter enough to worry about, I think.

Tibs

(today's "drat" moment - work has IE4 and Netscape4.07 (don't ask), so
there's no easy way I can look at the transformed XML output. Humph.
I'll have to wait until tonight at home...)
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
.. Haskell is the most Pythonic of all the languages that are entirely
.. unlike Python <0.9 wink> (Tim Peters)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)