[Doc-SIG] A promise

[Tony J Ibbs (Tibs)]

Laurence Tratt commented on what I wrote (and Outlook <fx:spit> helped
mangle the result):

> > 2. We want to get the solution into Python 2.1, which means
> > we need to get *something* going soon - not least so people
> > can try it and get any bugs out.
>
> In my opinion, trying to rush this for the sake of speed
> alone is likely to create a bad tool which will alienate
> people to the point that noone will want to *ever* use
> the tool - a bad initial release can put people
> off even when the tool becomes useable. By all means develop
> *alongside* Python, but wanting to get something - no matter
> how good or bad - into the distribution isn't the way
> to get everyone to play along. It'll look unprofessional to
> include crappy software alongside a main Python release.

Agreed in so far as it goes... (polite way of saying "aha - obviously I
didn't explain myself well enough last time").

Given the history of getting nowhere with this, having a release date
planned is a Good Thing. I think that the distutils work shows that. It
concentrates the mind.

I would *not* advocate accepting something crappy. If the consensus is
that whatever I produced was crappy, I would not want it included (of
course, I don't *believe* that will be the consensus, but if it were I
would defend that stance).

One of my earlier goals was to work out what STNG was trying to do. One
of the simplest ways for me to do that was to try some things out
(that's the way the insides of my head work). I now have the choice of
writing more documents based on that, or producing some code and
documenting it and using the code to turn said comments into the
document I would have written anyway. Oh dear. But you see what I mean.

If we don't have a solution for Python 2.1, I will be sad, but not
devastated. On the other hand, if we don't have a solution for 2.2, I
shall be angry.

One other point, though, is that I am also predefending against
arguments of the nature "but that is hard to do, so we'll ignore it" -
it's easiest for me to do that with working code. I also hope some of it
might be of use to the Zope people, who *have* put a lot of work into
this.

> You might be able to get something out by March (when I wrote
> Crystal, most of the work was done in 2 months and that includes
> things that wouldn't be necessary for a tool that is only intended
> to deal with  Python) but there again
> you might not.

Agreed. And I know how little spare time I have. (Truth to tell, I had
considered just trying to modify Crystal, or HappyDoc, but they *are*
both trying to be more sophisticated than we need in some ways, and less
so in others).

> > 4. We need a tool that runs with bog-standard Python
> > (preferably 1.5.2, since that's "old technology", and
> > also 'cos it's what I've got available at work and at home!)
>
> Bad idea. IMHO, the only way to create a professional tool is
> to get it to use Pythons parse trees ("import"ing the modules
> is at best mickey mouse even if it solves one or two problems
> that static analysis can't hope to) and that really means that
> the tool has to track the latest release. As you seem to want
> to tie it to the main release anyway, this doesn't seem like a
> problem <wink>.

On this one you undoubtedly have more experience than me, but I would
*like* to be able to use the same tool for 1.5.2 as for later versions
of Python, even if in a less sophisticated manner - there are a
significant number of firms (read one, the one I work for!) who have
only just gone up to 1.5.2 (from 1.3 - can you say "hurray!" - is Eddy
watching this?) and aren't likely to go up again soon.

But again, I won't weep too much if that isn't feasible.

> > Is this a Good Thing To Do?
>
> Yes and no. If what you're producing will be extendable
> enough to become the perfect tool, yes. If it's not extendable
> enough and is going to be another brick on the way to creating
> the perfect tool, I wouldn't bother - current bricks include
> gendoc, pythondoc, Crystal, pydoc and happydoc. We have enough
> "nearly" examples to go on.

I write simple code, 'cos I don't understand the complicated stuff. I've
never been accused of undercommenting (hmm - maybe not always a
recommendation).

The thing will probably come as an "STNG-clone" supporting class with a
pre-built example of extending it to be "our tool" ('cos that's a fairly
easy way to do it and to make it possibly more useful for Zope-readers).

It will use REs <fx:spit> because that's "standard" and I don't want to
fight the "getting a parser into Python" battle.

I *don't* expect it to be "perfect", but I do expect it to be "useful".
And I don't want to go another round of the Doc-SIG docstring tool
"game", so I'm motivated to be awkward...

> You might run into what I did - people actually seem
> surprisingly disinterested when a tool is actually produced.
> I know - I produced such a tool and it's probably extendable
> enough to cope with all this stuff <wink>. "Maybe this
> time"... but we've seen that several times before and people
> seem to get less interested as the discussions get increasingly
> anal and removed from getting anything done which is what's
> always happened before - a hint maybe for me to wrap this
> message up <wink>.

Oh, the message is OK and it ends well!

I don't expect *other* people to get "excited" about this (but heh, I've
had three responses, which is about, ooh, two more than I expected!).
Ultimately, the only response that *counts* will be Guido's (and I
*suspect* that also means Frank's) when something gets finished and
presented as "can we put it into a distribution, please?". Personally, I
don't *care* if people *like* the tool - I think it needs to be
invisible, just a component. There's enough egoboo in taking part (or
being allowed to take part).

Definitely more than enough wittering, I need to stop and go collect
children

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