[Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long)

[Tony J Ibbs (Tibs)]

(Apologies to Moshe, to whom I inadvertently sent a separate copy of this -
the perils of hitting "Reply" instead of "Reply All" in Outlook <fx:spit>)


Either I'm terminally confused (I hope that's it), or else several people
must have been murdered at IPC8...

If I'm understanding things, Moshe is proposing (officially) a
text-intensive form of markup for use within doc strings. This is designed
to be easily mapped to (for instance) XML, and is nearly as verbose. If I
have understood that correctly, then I have two immediate comments:

1. Why don't we just use XML? - the proposed format is almost as verbose,
and has the disadvantage that it is a new format "for the sake of it" [1].

2. What happened to all the people who were going to refuse to use such a
format if it were more verbose than the proposal being circulated pre-IPC8
(which I thouhgt was generally agreed on)? There's been no explanation of
why they've suddenly reversed position, if they indeed have.

As a smaller note, Moshe seems to be leaving out "cross references" as
unwanted in the inline documentation, whereas I would have thought it's as
necessary there as out of line...

[1] If we're going to have our own format, it has to give *significant*
benefits to readability/typability/etc, because having to translate into
something else to determine if it is legitimate (in the "valid XML" sense)
already makes it that much harder to correlate errors back to the original
text. I don't see those benefits here.

If this proposal is serious, can we please have an explanation of why the
various points raised in the pre-IPC8 discussion are being junked (things
like wanting list elements not to be separated by blank lines, wanting to
keep the typing/markup mode limited, Tim Peters' points about not needing to
markup code blocks if they had >>>/... markers, etc.).

Desperately hoping I've missed LOTS of points,
Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.demon.co.uk/
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)
[I've read it twice. I've thought it over. I'm sending it anyway.]