[Doc-SIG] suggestions for a PEP

[Tony J Ibbs (Tibs)]

(hmm - I keep hitting reply-to-all, and obviously you do the
equivalent - partly 'cos it means a copy *does* definitely go to the
doc-sig. But do we really want copies directly to ourselves as well?
(I'm unfussed either way))

Edward D. Loper wrote:
> 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#..

Hmm. Odd. Maybe something to ask over on the Python list per-se (if no
one else, Alex Martelli might explain something at long around it)

> 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.-_:]*

Hmm. I might prefer to say "a Python identifier", then, as I don't need
the "namespace" bit (which is what the colon is for).

> W(although
> I still don't understand its semantic value -- how do you identify
> things as targets of these links?

If one looks at a modified version of a PEP, for instance, then one
would have something like::

	This, of course, is discussed at length in Fredricksen [F1],
      but you can find that yourselves - of course, Jimson [J2]
      refutes it emphatically

	..[F1] Fredricksen and Cohorts, The magazine magazine,
        Some Publishing House, 1978, vol3 issue 97

	..[J2] Jimson, archived at http://www.jimson.notspam/j2.pdf

This *may* have been defined in the last-but-one round of docstring
syntax, rather than the last one (memory fails me).

The "target" of the references is <start of line> <indentation> <dot>
<dot> (etc. - you get the idea). I would imagine that in alpha1 they
don't trigger a new paragraph, but later on they probably should (same
arguments as ':' labels).

I'll need to dig up my paper copies of the relevant discussion, 'cos on
the face of it it would be nice to be able to do [1] as well (like the
PEPs do), but that can't be so if we're enforcing identifier-syntax for
the "footnote" ref.

There was a justification for it, but that's in the same place as the
rest. Short term, it lets me "emulate" a PEP, which is a Good Example to
be able to emulate. I know there was a better reason as well...

> > 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 agree on the leaving it. (and why wouldn't the reference docs for a
package be in package/reference.stpy, then?)

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

I would *guess* it started out as "stx" or "stxt" and the latter never
caught on.

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

Hmm. Messy to think about in the implementation (and in this sort of
thing, I'm beginning to trust how easy it is to do in Python, as a
guideline to how easy it is to think about). But worth bearing in mind.

There is an outstanding conceptual problem with indentation and lists,
anyway. If one has::

	Some non-list text, followed by
	1. A list

then it is clear how the list is indented - i.e., not specially. On the
other hand, if one has::

	Some non-lists text, followed by
	   1. A list

then STpy leaves it fuzzy what happens, and currently docutils will put
a block around the list, causing it to be indented "extra". On the other
hand, sometimes people want that effect (the difficulties of mixing
presentation and markup, and not being specificallty a typesetting
language - ho hum).

I think this whole sort of thing will need addressing either at
alpha/beta time, or possibly post-1.0.

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

I *should* know what I *want* to have happen by the alpha release (even
if the "example application" doesn't yet do it). And I am *fairly* sure
that what I will *want* to have happen is what Eddy wants as well. But
we'll see.

Tibs

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