[Doc-SIG] formalizing StructuredText

[Edward Welbourne]

>    * Apostrophes can appear in the middle of a word or at the end
>      of a word, like "isn't" and "dogs'".  Is it illegal to have
>      multiple apostrophes in the same word?  There are no English
>      words that use multiple apostrophes, but I'm not sure about

oh no.  Excuse me while I switch into <mode perversion=counterexample>

Imagine someone's written a document, of which a prominent chunk is a
sequence of declarations all sharing a pivotal use of isn't (The King
isn't any better at running the country than we are; his chancellor
isn't any more financially adept than our merchants; ...).  Someone else
ends up writing about this document.  They're mainly discussing the
declarations.  So they end up using

   isn'ts

to refer to the uses of isn't
and obviously their possessive is

   isn'ts'

Now, when you've persuaded yourself I'm crazy, go check a database of
Anglic usage and discover how much more perverted the actual
counter-examples are.  And please don't inflict them on me, coming up
with that one hurt. </mode>

But I think we can safely say that authors of docstrings will be
prepared to retract anything that perverse, once the tools complain.
You should apply the same reasoning to some of your other worries.

(well bugger me - my #inline(code)# proposal got implemented !)

>      i.e., a series of letters followed by a dot, a series of
>      numbers followed by a dot, or a number followed by space.
... a few counter-cases ...
and what about

  2a. subsidiary cases

not to mention

  3: some of us like colons

but, to be quite frank, ([0-9]+\.)+ sounds fine to me.  And don't bother
refining that to ([1-9][0-9]*\.)+ 'cos some of us *do* count from zero,
OK ?

>        * What do you do with things like::
>
>            This *is "too* confusing":http://some.url

Find author, apply pain (to taste).
Give them the opportunity to retract.
If they refuse, apply lethal doses of pain.
Then they won't repeat the offence.
No problem.

	Eddy.
--
Those wishing to be literal-minded about applying pain to taste may feel
free to deploy hot chilli sauce.  In the eyes.