RE: [Docutils-develop] Custom node types (was Re: pdf writer)

[Tony J I. (Tibs) <to...@ls...>]

David Goodger wrote a detailed critique of my wanderings upon a theme
from Engelbert Gruber - thanks, David, that makes it make more sense to
me.

A couple of specific points to reply to:
> In the case of PySource, an example of (a), I would expect to have a
> transform reduce any custom nodes to standard node structures; tables
> may suit the current code.  Then a standard HTML writer, perhaps in
> conjunction with a specialized stylesheet, could produce HTML very
> different from that produced from standalone reStructuredText.  (Not
> having worked though the code yet, I wouldn't be surprised if this
> isn't enough.  That's OK; we'll fix it in time.)

Ah. The way pysource works is to build an internal structure
representing the Python code, insofar as it cares (i.e., it doesn't try
to represent stuff it's not interested in), and then transform *this*
into DPS nodes.

This means that (within pysource) I have no need of "custom" nodes - the
DPS datastructures are purely being built for consumption by a Writer
(it's obviously a little bit more complex than that, because docstrings
become DPS fragment trees within my "python" datastructure, but that
makes sense in terms of treating individual docstrings as entire
documents for the purposes of footnotes, headers, etc.).

> The Writer itself works entirely with existing Docutils nodes, and any
> nodes specific to its format.  Readers know about input contexts
> (PySource, PEP, standalone file, etc.), but Writers are intentionally
> ignorant of context.

If I understand that correctly, that is exactly what I am aiming for.

> > (Briefly, my reason for liking option (1) is that with the single
> > addition of a new "style" attribute to all nodes, I can get 80% of
> > what I want ... and "style" translates, in HTML, to "class"
>
> There's already a "class" attribute on all nodes, which remains on the
> HTML generated from the node.  For example, see how the ``topic`` node
> is handled in ``transforms.parts.Contents``.
>
> > and with a new node called "group", I get 100% - where "group"
> > translates, in HTML, to <DIV> or <SPAN> as appropriate
>
> I think there's a danger in an overly generic node like "group", which
> is why I'm resisting.  If you look (once again) at
> http://docutils.sf.net/spec/pysource.dtd, you'll see my first cut at a
> structure for representing the custom Python-source-related nodes
> needed (probably out of date).

...deletia...

> But since I haven't gone through the pysource code, my arguments may
> not hold water.  My gut says "group" is an evil generalization.
> Perhaps my head just needs to see it in action to override my gut.

As I indicated above, I don't store Python structure "as such" in the
DPS node tree (what *is* the current correct term for these entities, by
the way, now that DPS has gone away?) - I just store the document that
"talks about" the Python structure. Since the pysource.dtd is talking
about DPS nodes, I'm not particularly interested (after all, they're not
nodes a Writer is required to recognise).

The reason I want "group" is that one of the things I want to be able to
do is to group together, visually, for instance, a section heading and
some text thereafter (the layout is wrong, to get the idea across in
ASCII art)::

    Class Fred                          <-- a "section heading"
    fullname: jimbob.clancy.Fred        <-- a paragraph or somesuch
    subclasses: BigClass                <-- ditto

but not the text that follows *that* - which might, for instance, be a
docstring. Now, I may be able to do that with CSS just by use of the
"class" values, but I had thought not - whereas (a I understand it?)
this is exactly the sort of thing that <DIV> (or is it <SPAN>?) is aimed
at in HTML. And I'm pretty sure I could do the same sort of thing in TeX
(it's really the TeX concept of "group" - i.e., ``{\something .. }`` -
that I'm after, I think!).

It may be that my aims are evil, but they are certainly simply and
easily met by provision of the equivalent of a "group" node (which may,
of course, be translated into a table in a non-CSS environment).

Anyway, I'm away all next week (school half-term holiday, and off to the
sun), and maybe will be able to think about this more after that.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)