[Doc-SIG] suggestions for a PEP

[Tony J Ibbs (Tibs)]

Edward Welbourne wrote:
> > I think "keep it simple" is required here
> to me that needs to include:
>    * case insensitive
>    * digits

Unfortunately, I strongly disagree. I may be *wrong*, but I disagree.

> because authors of doc-strings are going to be shocked if it behaves
> otherwise.

Well, it's how *I'd* expect it to work (and, of course, neither you nor
I are exactly representative examples).

> The former means your dictionary-based approach is not
> satisfactory - string.tolower the apparent label, then check to see
> whether the result appears in some list (or other implementation of
> `collection') of known labels.

> Otherwise, your builder.label_dict is
> going to need further entries for, at least:
>
> 			  "Pep":"pep",
>                           "Post-history":"post-history",
>                           "Discussions-to":"discussions-to",
>
> since some folk using the keys you gave *will* use them in the forms
> shown; and you'll probably also need

Erm - PEP 1 is quite clear over what it wants (it doesn't say one can
use case variants, so why should one assume one can?)

(((I probably won't do it unless more convinced, but of course doing a
string.lower *would* be simple (before doing the dictionary lookup).)))

> Have canonical forms generally be in Capitalised-Word form
> (like RFC 822
> labels).  Indeed, a good way to implement the aforementioned
> `collection' would indeed be a mapping which is exactly the reverse of
> the ones you showed us - mapping from the tolower form to the
> canonical
> form for each key - so that one recognises a key using:
>
>     try: canon = labels[string.tolower(text)]
>     except KeyError: ... # it isn't a real label
>
> I am entirely happy to have the present *actual dialects* of
> ST use only
> letters and dash; however, allow ST-generic to permit numbers, e.g. so
> that ST variants *can* use
>        "rfc2954-char-set": "RFC2954-Char-Set"
> in their label dicts, or similar.
> (No, I have no idea what RFC 2984 is, nor even whether it exists.)

Hmm. OK - we're looking for compatibilty with emails, he guessed wildly.

Unfortunately, there is *no way* that I can see of unambiguously and
obviously allowing paragraph labels to *start* a paragraph (it just
leads to too many pitfalls - we use colons in english too freely). So
trying to parse bare emails with STpy is always going to be a problem.

However, the case for allowing digits is there, I suppose. I'll think
about it (he begrudged).

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