[Doc-SIG] A couple quick comments

[Edward D. Loper]

I haven't had as much time as I wanted to work on docstring stuff
lately.  But a couple quick comments:

  1. I think we should try to concentrate on building a markup
     language for docstrings.  I think that trying to create a
     general-purpose markup language, which is simple and easy and
     wonderful etc., is going to be too hard of a project.  We'll make
     more progress if we just try to concentrate on docstrings.

  2. Given that I would almost never use sections in a docstrings, I
     don't really care how we do sectioning, or if we have it at all.
     But I suggest we not exhaust too much of our energy on it..

  3. I think we should try to direct some energy at figuring out the
     details of the DPS.  If we're to accept David's proposed
     approach, then markup decisions should be made pretty far down
     the road: first we create the DPS, then we construct a number of
     actual markups, so we can play with them and try them out, and
     *then* we'll have more experience with which to make decisions
     about which markup features we want.  If all my playing with
     different docstring markups has taught me anything, it's that
     there can be very subtle consequences to decisions you make about
     the markup.  I won't be happy accepting any argument about
     whether X or Y is "better" until I can really try them both out
     in the context of everything else we've decided.

  4. I don't see a good reason to specify the interfaces used between
     DPS pieces using DOM.  Using/manipulating DOM can be much more of
     a pain than using/manipulating Python objects.  I think that we
     should define a set of classes for representing documentation
     (which would basically have a 1-to-1 correlation with a DTD).
     These classes should implement a toDOM() method (or some such),
     and maybe even have a fromDOM() type function..  I think it's
     much more convenient to say things like::

        myclassdoc.methods()[3]

     than::

        myclassdoc.findElements("method")[3].data

     or whatever it would be in DOM (sorry, it's been a little while).

Anyway, that's all the time I have for now.  I'm glad to see so much
activity on the sig again.  

-Edward