[Doc-SIG] DPS components

[Tony J Ibbs (Tibs)]

David Goodger coined the terms:
> "readers" (what I'd called "input modes") that understand
> the data source

Of course, the "reader" for plain .rst files is *ever so* simple!

By the way, the duality "input mode" -> "reader" is still a natural one,
I think, since I think the user would think about setting an input mode
more than choosing a reader, in many cases.

> "parsers" understand the syntax itself (just "reStructuredText"
> for now).

Hmm - *maybe* we need to be careful to say "reST parser" here, since
there may be other parsers hanging around as part of the "reader".

> "designers" take the output from a reader and transform it.
> Content transformations (moving stuff around, grouping,
> separating) as well as cosmetic transformations (?) happen
> here.

Actually, I think this is the interesting stage to have identified. I
agree it's difficult to think of a name for it.

> "Writers" (formerly "formatters") produce the final output (HTML, XML,
> TeX, etc.). Writers merely do translations from one data format to
> another; they don't do any content transformations. Their input may be
> an augmented form of the current schema, with color and layout
> information added.

Yes, I like these terms (well, the *particular* names aren't as
important to me, but the existence of the terms/concepts is a good
pedagogy, I think).

So I have a *reader* that uses Tools/compiler, I use the *parser* on the
docstrings I find, my *designer* phase takes all of that and produces
something I can pass to the HTML *writer*.

I assume that you are thus hinting that the output of the designer
should be "pure" DPS nodes - that is, using only DPS tree nodes that are
defined in dps/nodes.py, so that *any* DPS writer can be slotted in.

At the moment, my code doesn't work like that - the designer is
producing "extended" nodes, and the writer understands what to do with
them. I *think* that the "pure" approach is probably better, but am a
*little* concerned about how I would convey some of the distinctions
that DPS doesn't discern (and no, I don't have concrete examples yet),
but that are useful in a writer (e.g., I use lots of colours in my
current HTML output, but if I were printing it I would need to move back
to monochrome (it's not fair to assume access to colour printers!)).

> It appears to me that there will be strong links between readers and
> designers, whereas parsers and writers are more independent and
> interchangeable.

Yes, that sounds like an advantage.

The example I would use to think about the flow through the system would
be that of a simple table in the quick reference, which could use a
directive::

    .. quickreftable:: Directives
       :link: http://link-to-text
       ::

         For instance:

           .. graphic:: images/ball1.gif

We would need a plugin for the DPS parser (to understand the content).
The "example" literal text would need to be fed back to the parser
(presumably by the designer phase - neat) to generate the right hand
column of the table. Now, given I want the table header to be in pale
blue, with the word "Directives" in strong italics, and I want the table
body to be split 50/50 between the two columns, with a pale yellow
background, *if* I'm outputting to HTML - how do I do that? Bearing in
mind that if I'm outputting to PDF, I want an entirely different set of
details.

My *suspicion* is that we have three sets of plugins for a directive
(and maybe for other things, but directives are nice and obvious):

1. a plugin for the parser - this just enables it to be read
   "properly", and would be optional for simple directives
   (indeed, I think it's not needed for the above example).
2. a plugin for the designer - this, in my example, does the
   reparsing of the example, and again would be optional.
3. a plugin for the writer - again, only needed in *some*
   cases, but this would allow the user to set a "style"
   for the table or whatever.

Now, in the HTML world, case 3 might merely mean that we set the "name"
for a table, and have appropriate CSS defined to say how to display it.
In TeX we would assume that the name indicated a particular macro. It
*may* be that such a "style name" is all that we *do* need, and that the
writer just needs to be given a lookup table of style names versus
styles. Hmm...

Despite the witterings above, I'm not too concerned about this as yet -
I have the feeling that it will all come clear in the attempt to
implement a "clean" system[1]_.

Tibs

.. [1] Having done a little bit of Tai Chi, including some
   "pushing hands", I tend to think of trying to solve this
   sort of problem as akin to finding one's partner's balance
   point, the point where one pushes gently and they go flying
   off into the distance. And in pushing hands, that often
   involved "feeling" around their centre until one found it
   (or they found yours!). So if one keeps being flexible and
   feeling around for the centre of the problem, one will
   eventually cause it to "fall over" in the natural and, in
   hindsight, obvious manner.

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
.. "equal" really means "in some sense the same, but maybe not
.. the sense you were hoping for", or, more succinctly, "is
.. confused with". (Gordon McMillan, Python list, Apr 1998)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)