[Doc-SIG] suggestions for a PEP
Tony J Ibbs (Tibs)
Fri, 16 Mar 2001 16:09:37 -0000
(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::
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).
> 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  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
> 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
> 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. 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
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.)