[Doc-SIG] suggestions for a PEP

[Edward D. Loper]

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

I'm actually on the digest mailing list, so if you want me to get
it faster, cc it to me.  If you don't care, you can just send it
to the mailing list.  I've started sending my replies to you to the
mailing list.

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

If we also like things like [2], why don't we just say that it's
'\w+'?

> 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

Ahh.  Ok, now I know what we're talking about.  In STpy.html, you
say that the syntax is "name":[link]... And the "footnote" 
syntax is::
 
    ..[link] http://foo/bar

If we're implementing this, is there a chance that we could just
ditch the in-line hrefs altogether, in favor of out-of-line ones?
It would mean that we wouldn't have to deal with such issues as
"what counts as a url", etc.

Of course, some of my previous questions still apply.. E.g., can
you say: "this name *contains* 'markup'":[link]?

Oh, one other question: how does it make sense to ever use relative
urls inside documentation strings??  I can see how it would be
useful in other contexts..  but not in doc strings.

> I agree on the leaving it. (and why wouldn't the reference docs for a
> package be in package/reference.stpy, then?)

reference.stpy sounds like a fine name to me.

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

With "stx" it's not obvious anyway, so I wouldn't worry about it.

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

Hm.  I disagree.  I don't think that the user should have that much
control over formatting, anyway.  I tend to think that ST should
be a markup language, not a typesetting language..

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

Too bad for them. :)  If they really need *that much* control over
their typesetting, they shouldn't be using ST.

-Edward