[Doc-SIG] What docs should be in the source file?

[Tony J Ibbs (Tibs)]

Edward Welbourne wrote a long missive on the subject, to which I add:

	what he said.

Being me, I can't refrain from a couple of comments:

> The maintainer's needs call for simplicity of format, the
> interrogator's call for richness, albeit with some cross-over
> both ways; good tools can make a big difference to the richness
> (e.g. all that stuff about trawling base classes for matching
> methods, providing default doc strings, etc.).  The
> client-author's needs call for standardisation (hence Tibs' work
> on labels).

(although I may be working myself towards an argument against them, on
the "simplicity" stance - we'll see)

> Practical experience in the field of software maintenance says
> unambiguously that simplicity is a very serious issue,
> especially if one is to have enough standardised semantic
> markup to ensure that tools can do a good job for the client
> author.

And this, of course, is why Edward Loper and I are having such a long
discursion on the SIG, and particularly why Edward Loper keeps pushing
for more formalism and less complexity - he rightly worries that too
much complexity will make our markup too difficult to use, and too
ambiguous to work with, whilst I fret about users typing things that
they feel *should* work...

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)