[Doc-SIG] DPS DTDs
Tony J Ibbs (Tibs)
tony@lsl.co.uk
Tue, 11 Sep 2001 10:59:50 +0100
David Goodger wrote:
> Looking at your example, I think I see what you've done.
> You've combined the parse tree with the docstring tree,
> into one unified structure. Correct?
Yep. Or maybe no (I said 'yep' originally, but by the bottom of my reply
I'm not sure).
> I think this is fine, for internal use, but I don't see the
> need to add all the 'py_*' elements to the DTD.
<<Lots of deletia>>
I'll try to explain my point of view, since I'm not sure I see yours(!).
I see that we are producing a "document" (in some sense - normally
actually a *real* document, suitable for printing, or if one must,
viewing with a browser). Thus for a Python package or module, that
document should provide the information about that module. Some of the
components of that information (tree) are indeed docstrings, and some of
those docstrings will be DPS/reST structured. To me it doesn't make
sense to have an artificial boundary at any level - so a docstring that
is not parsed would be <literal> text (is that the right tag?), and one
that is parsed will be full of DPS nodes, and both will occur within a
<py_docstring>. Yes, we *could* say there is a special watermark between
the Python-esque stuff and the docstring innards, but I don't see the
point.
Now, in ``dps/specs`` you have ``ppdi.dtd``, which certainly *looks* to
me as if it is doing the same job as I am doing with my <py_xxx> tags -
that is, extending the DPS nodes tree "outwards" from the docstring into
the Python code. Of course, given my predilections, I may be
misinterpreting your original intent.
My point was simply that I am not, particularly, following that DTD -
but I obviouslY (trivially, since I can output XML!) am following *some*
(virtual) DTD. And it would be nice to write that down (be it as DTD or
XML Schema or whatever) at some point.
> I was envisioning a parse tree data structure carrying docstring
> 'leaves', each of which gets parsed into a DPS nodes tree
I think that's what I've been doing...
> and interpreted according to the namespace context
> of its part of the parse tree
...and that's obviously on my ToDo list! (i.e., putting in all those
nice links we want to have throughout the document.
Note that the fact that the DPS/reST (gosh, I feel like someone
insisting on saying GNU/Linux!) will *contain* references out to the
Python is another reason I feel that this is all one continuous
datastructure - I don't want to distinguish (in my mind) between links
intra-docstring and links between the docstring elements and the Python
code.
> The parse tree deserves and requires a data structure of its own
which it has, in that produced by Jeremy's compiler tool, but in fact
it's quite advantageous to turn that into a DPS node tree fragment as
well.
(hmm - and I just realised *why* - if the two components (inner and
outer, for want of better term) are *discontinuous* in structure, then
it makes it harder to write a Formatter/Writer - it would need to know
about the Python bits and the docstring bits independently - it's *much*
easier (conceptually and implementationally (?yuck)) to have a baseclass
that understands DPS and a subclass that *adds in* how to understand the
"surrounding" Python.
> The DTD is intended as the document tree, to be built up out
> of smaller trees grafted together using the knowledge gleaned
> from the parse tree.
That's the DPS DTD. But there's no reason that the Python DTD shouldn't
reference the DPS DTD - indeed, that's how things are *meant* to work
(at least in the XML Schema world - and that's why I wittered for a bit
about namespaces earlier as well).
Remember, of course, we are *not* producing XML except when we ask the
DPS node tree to do so!
> The two types of tree represent fundamentally different
> information.
I see we disagree - it's all document (erm - serialisation of
information).
> Forcing the parse tree to share a schema with the document
> tree is hypergeneralization.
I really think we might be talking past each other, because what I'm
doing is so simple and obvious that I find it hard to call it
hypergeneralisation - I'm not losing anything, and I'm gaining quite a
lot.
I'm using the compiler parse tree to hold the parse tree, and generating
documenation (as part of a DPS node tree) from it. That's obvious to me.
Are we just confusing each other with words?
> In dps/spec/ppdi.dtd you'll see the "Additional Structural
> Elements" provide the major *documentation* structures necessary
> for describing Python packages, modules, classes, methods, functions,
> and their attributes. They're not intended to hold the parse tree.
They are clearly a start on holding the information one needs to report
on in a document. They didn't do enough for me, which is why I'm not
using them.
However, do note that, at the moment, I am performing a simple serial
"dump" of information (well, it's a tree walk, of course, but you know
what I mean) to produce the HTML (that's why I call it quick-and-dirty),
so I don't see that I'm putting any extraneous information into the DPS
nodes tree.
As to dictionaries and namespaces - that's for the future - at the
moment I'm still trying to represent the fundamentals of the Python
information that we want to output in a helpful document (such as
function signatures).
(ooh, ooh, another argument - if we get Grouch integrated at some future
stage, then it is *quite* likely that tools *will* want to use the
"innards" of a docstring and the "outers" of a function definition in a
coherent manner)
> > (I made the mistake of trying to represent
> > ``restructuredtext/states.py``, which has a Getattr node in
> > one of the argument lists)
>
> I don't follow. Can you point the way?
Oh - sorry, implementation wittering. If one has a function/method
defines as::
def fun( a = x.y.z):
...
then one needs to know how to represent the right hand side of the
assignment, to be able to describe the function signature. And you had
some, erm, interesting function definitions.
Tibs
(who must stop hacking on this message and
do some paid work)
--
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.)