[Doc-SIG] suggestions for a PEP

[Edward D. Loper]

> Hmm - trying (also in 1.5.2):
> 
>    >>> class fred:
>    ...     def f1():
>    ...        """f1"""
>    ...
>    >>> class jim:
>    ...     def j1():
>    ...        pass
>    ...     j1.__doc__ = fred.f1.__doc__
>    ...
>    >>> jim.j1.__doc__
>    'f1'
> 
> Well, that's what I was thinking of - I can't imagine it's broken in 2.n

Hm..  That works.  It seems very strange and magical to me that 
*within* jim, you can say #j1.__doc__ = foo#, but *outside* of
jim, you have to say #j1.im_func.__doc__ = foo#..  

> Not even one word - it will have to be an identifier (in the XML sense,
> a <I forget the details> name - which is, I think, much the same as a
> Python identifier).

XML defines::
  Name = (Letter | '_' | ':') (NameChar)*
  NameChar = Letter | Digit | '.' | '-' | '_' | ':' |
             CombiningChar | Extender
  (CombinindChar and Extender are for international support, I think)

So the regexp would be something like::

  [a-zA-Z_:][a-zA-Z0-9.-_:]*

Which is not quite the same as a python identifier..  But if that's
what we want, then I'll go ahead and add it to STminus (although
I still don't understand its semantic value -- how do you identify
things as targets of these links?

> (btw, Edward (L), I *think* it should be possible to make dodgy and
> erroneous constructions emerge in the DOM tree marked up as such - that
> is, for instance, "badpara" instead of "para" or "dlist" or whatever -
> or maybe as an attribute - so that a renderer can highlight things
> appropriately - I've some notes I want to compare with the source code
> this weekend to see how feasible it is.)

Sounds good.  Currently, the STminus implementation will tell you 
what character it failed at, but not much more than that.  (Of course,
I don't think anyone will actually *use* the current STminus
implementation, so...)

> > >> - documenting Packages
> > > There definitely need to be provisions for that.
> > erm ... we already have __init__.py, so a __doc__.py might be cool ?
> > Possibly alongside __doc__.stng or some such containing the ref docs ?
> 
> I would say that the package docstring is the docstring in __init__.py.

Hm..  I think the package (API) docstring is different from the
reference docs for the package.  So maybe the reference docs could
go in __doc__.stpy, maybe they could go elsewhere..  I think we
should leave that to a future project (the one that figures out
where all the docs that are not inline API docs go).

> I hereby propose:
> 
> 	'.stx'  -- the file contains text compatible with either
> 	           STClassic or, more usefully, STminus
> 	'.stng' -- the file contains STNG text. It may or may not
> 	           be parsable by ST<other> parsers
> 	'.stpy' -- the same position for STpy text
> 
> Is this worth "formalising" by also posting it onto the ZWiki? Or is it
> just overcomplex? Is it a bad thing we've lost any reference to "tx" in
> the string?

Sounds good to me.  Why do we care about losing "tx"?  The only 
association I have with "tx" is "transfer"..

> Hmm - I'm well aware of how far Eddy will take the elision of vertical
> whitespace to keep stuff compact.
> 
> Strangely enough, the example Eddy gives (in Edward form) *is*
> legitimate STpy, since the list items start new paragraphs. If it were
> cast in my form:
> 
> 	Document information
> 	   Author: Guido
> 	   Verision: 3.14
> 
> then it doesn't work, since labelled paragraphs don't start a new
> paragraph.

Hmm.. here's an idea that was (I think) inspired by something 
Eddy said earlier..
  1. list items (and maybe labels) can start without preceeding
     whitespace.
  2. it's an error to have a set of list items "at the same level"
     as paragraphs -- the entire list must be indented.

The result being that the following is illegal:

   I do not intend to start a new list item but I like the number
   12.  It's a good number.

That might keep people from accidentally starting list items..
Instead, if they wanted the list item, they'd have to say:

   I do intend to start a new list item and I like the number 
   12.
       12. This is a list item.

Or something like that..

> For the moment, tough. However, I do tend to share the view that this is
> unnatural - I *think* that most people will expect the above to work,
> because that "word followed by colon" thingy is something we're used to.

Hmm.. If you can decide what you're eventually going to do, I'd
appreciate it, so I can code that into STminus..  STminus is going
to be a formal description, so will be much less easy to change
than STpy (well, not technically difficult to change, but if it
becomes an accepted standard and programs are written assuming that
it is "correct"...)  But if it's going to stay a subset of STpy, it 
needs to know where STpy is going..

-Edward