[Doc-SIG] suggestions for a PEP

[Edward D. Loper]

> > I think that a bunch of programmers would be willing to do global
> > markup (special places to describe arguments, etc).  I don't think
> > they would do formal coloring markup..
> 
> No, no - I meant in *new* code, rather than in old. I want documentation
> in new code as well! 

Um.  So did I.  I'm not sure where you got the impression that I
didn't.  Hopefully having special places to describe arguments is
useful in new code?  I wasn't even thinking about the std library..

> Aagh! Quick, do a "from __future__ import docutils" 'cos that's all
> being addressed in the alpha release and *it's already coded*.

So, my main objection to this format (given that I'm the one that
has to formalize it) is that it means we're giving meaning to
yet another character: ':'.  I read through the list archives, but
didn't seem to find eventual consensus.  But if we're going to have
it, here's how I would *like* it to be defined:

  1. *Any* paragraph starting with '\w+:' is a "label paragraph."  
  2. Any ':' in any other location is treated as a normal ':'
  3. It is illegal for a label paragraph to contain a newline.
  4. If a label paragraph has (non-space) content after the ':',
     then that is parsed as the only subparagraph of the label
     paragraph. 
  5. If a label paragraph does not have content after the ':',
     then following indented paragraphs are subparagraphs.
  6. If a label paragraph has content after ':' *and* is followed
     by indented paragraphs, then... I'm not sure.  Could be illegal.
     Could all that the following paras are children of the para
     that's on the same line..  Ideas?

> 
> OK. The rules for "paragraph labels" (I changed the term) are fairly
> simple. Basically, there are two dictionaries::
> 
> 	label_dict = { "Label" : "xml-label" }

If we're going to be xml-like in specifying contents, then we
might want to consider using actual xml DTD-like strings to 
specify this (so "Label" : "ANY").  :)

> I decided *not* to complicate matters
> by allowing::
> 
> 	Label:
> 	    Only indentation makes this look like a paragraph.
> 
> because there are already enough rules about when paragraphs start.

Agreed.  Although this is bound to confuse people.. :)  But 
according to my rules, it will produce an error if they have
error checking turned on..

> This fits in reasonably well with David Ascher's original ideas
> (thrashed out at the end of 1999), and to my eye the use of a colon is
> more natural than overloading descriptive lists.

Again, I don't like giving even more meaning to ':' when we could
just give '--' the same meaning, and say it's a "tool issue" to
decide whether a key has special meaning..  But as long as we
give ':' special meaning *only* and *always* when it appears directly
after the first word in a paragraph, I can accept it.

> More explanation can (please) wait until the alpha release, which I
> *hope* will be end of next week, with the PEP.

Looking forward to it.  If my emails take too much time to answer, 
just punt them for now. :)  I've been trying to get some answers
out of your source code, but I don't have the time to figure out
everything that's going on in there..

> > I think it will be helpful to people if we can get this streight now.
> 
> Yes, but can now be next week, 'cos then I won't have to explain things
> *quite* so many times, please?

Yes, I was thinking of "now" as "before the PEP is accpeted." :)

> > >> dosctrings inherit like any other value, surely?
> > Um.. yes, but that's not always what you want.  Basically, if
> > I define::
> >
> >   class A:
> >      def f(x):
> >         "this if f(x)"
> >         return 1
> >
> >   class B(A):
> >      def f(x):
> >         return 2
> >
> > Then I might want B.f to inherit its docs from A.f.  This would be
> > especially nice for things like UserList, so my classes will have
> > docs for its methods without me having to duplicate explanations.
> 
> Then assign them. __docs__ is a perfectly valid "slot" to assign to (and
> is the precursor to the whole idea of function values - see the relevant
> PEP).

I didn't think this was possible, because the following fails::

  B.f.__doc__ = A.f.__doc__

But really you have to do this:

  B.f.im_func.__doc__ = A.f.__doc__

It might be worth mentioning this in documentation, because I think that
the whole idea is not quite intuitive, and it's something that the
code writers would have to do..  So we should suggest that they do it
when applicable! :)

> See, as I said, time machines...

Time travel's fun! :)  But I'm sure you've been through all this too many
times to count.  I'm a bit new to all these issues, so if I seem dense
sometimes, please forgive.. :)

-Edward