[Doc-SIG] DPS DTDs

[David Goodger]

Tony J Ibbs (Tibs) wrote:
> Heh, asking questions is a Good Thing!

Yes, the answers often turn into good docs. They certainly help us to
understand each other.

> The structure for the "Python" parts of the tree
> is not fixed - that is, you wrote a DTD for it, but I'm afraid I've
> strayed from it rather (erm, yes, well), and am building a new
> ad-hoc structure instead

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?

I think this is fine, for internal use, but I don't see the need to add all
the 'py_*' elements to the DTD. I was envisioning a parse tree data
structure carrying docstring 'leaves', each of which gets parsed into a DPS
nodes tree and interpreted according to the namespace context of its part of
the parse tree (e.g., interpreted text "`b`" in Fred.__init__'s docstring
gets resolved to a 'parameter' node, because that's what 'b' is in
Fred.__init__'s namespace). I think that the parse tree data should remain
distinct from the docstring data. The parse tree deserves and requires a
data structure of its own (and this one doesn't need to be anywhere near
XML).

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. The
two types of tree represent fundamentally different information. Forcing the
parse tree to share a schema with the document tree is hypergeneralization.

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.

I see the parse tree data distilling down to a tree of local namespace
dictionaries, mapping names to objects in the parse tree. Combining the
namespace dicts correctly results in the overall namespaces of each object
in the parse tree.

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

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