[Doc-SIG] Re: Ease of use is #1

[David Ascher]

From: Jack Jansen <jack@oratrix.nl>

> Recently, Moshe Zadka <moshez@math.huji.ac.il> said:
> > While I admire the way you markup by "guessing", I must admit I have my
> > qualms about this approach: too little control for the documenter.
> > Possibly, a mix of the two approaches is in order.
>
> I think I agree with this. Now that I've seen the wonderful stuff Ping
> can do it may indeed be worthwhile to try and get more than simple
> help-notes out of docstrings (as was my previous position:-).
>
> It would be nice to be able to somehow override the guessing when you
> (the author) know that it's wrong. Examples of this are mapping of
> foo() in the text to a certain foo() in the code, but there are
> probably many others (one that comes to mind is generated methods, as
> in xmllib.py).

FWIW, that concern is the source of my three objections to StructuredText.
Quoted strings get 'verbatim'ified, __init__ get italicized, and
StructuredText never complains of a parse error, so if you screw up the
output is screwed up but you'll never know it.

--david