[Doc-SIG] Formalizing ST

[Tony J Ibbs (Tibs)]

Peter Funk wrote:
> Last weekend I installed MoinMoin 0.8 here on a Server in our
> companies intranet and played around with the markup.  Wiki
> markup contains some clever ideas but IMO this is not really
> intuitive markup useful for Python inline doc strings.

I've read the markup documentation on several Wikis (including CLisp,
which is fascinating), and none of them are interested in human readable
markup - they're all really interested in presenting web pages.

> I would prefer to use indentation to markup different levels (borrow
> this idea from ST) and use simple underlining for marking single
> lines as headings:

Indentation for structure is contentious with many people, and whilst it
*sounds* like a good idea (especially to Python people) many object to
ending up with the bulk of their text indented.

> However the url detection without requiring '<' and '>'
> delimters around the http:// ... string is a nice feature
> of MoinMoin markup.

You haven't been following the me and Edward Loper (and Edward
Welbourne) flurry of emails over recent weeks, have you?

The trouble with finding *bare* URIs in a text document written by
humans with punctuation is that, in the general case, you can't do it.
For instance, a URI is allowed to end with a dot ('.'). So how do you
cope with a sentence that ends with http://www.tibsnjoan.co.uk/. Is that
last do part of the URI or not? There are other issues about what can go
inside the URI, as well. Yes, people can come up with ad-hoc solutions
(docutils/stpy.py works reasonably well), but they are ad-hoc and not
guaranteed to work. This disturbs some people (I'm not *too* fussed, but
then I'd err on the side of detecting *too many* URIs, I think, which I
know would upset some people).

The *only* safe way (and note that this is an option in MoinMoin also)
is to delimit the URIs with some mechanism, and '<..>' is at least a
fairly traditional solution.

> Ping has implemented something similar in pydoc already
> and this works just fine.

See above - it's "modulo just fine" I'm afraid (Ping is happy with
approximate solutions that find too many instances - somewhat more than
myself - so *of course* pydoc does what it does (and of course it
should)).

> I have a similar feeling with the email address recognition

Erm - email addresses should be presented as URIs, honest.

> About lists and numbered lists I'm still not sure what I would like.
> I bullet item list (LaTeX itemize) seems to be enough for most cases.

No, that is not sufficient. There are too many of us who *want* (no,
*need*) more sorts of list (believe me, I've been using a too-simple
internal markup tool for C function header comments for years, and it
has only one type of list, delimited by '@' - it's not sufficient -
people end up writing lists out "by hand", which rather circumvents the
point).

> A few days ago Guido gave a similar statement.

I'm not sure he exactly said that, but if he did, he was wrong (it *is*
possible, he just normally uses the time machine to go back and alter
the records after he changes his mind).

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