[Doc-SIG] more user testing

[Greg Ward]

On 04 February 2000, Moshe Zadka said:
> I've tested both painfullness and time of my inline docs suggestion.
> On a whim (with no relation to the doc-sig) I wrote a small generic dict
> module. Then I decided to document it and see how much it puts me off. I
> discovered that it was pretty easy. (This was with vi -- if you're using 
> an editor that's less friendly it might be harder). 

I hate to chime in with the second negative feedback of the day, but I
don't like it either.  You don't have to look much further than this
paragraph to see why:

> Functions [function filename()], [function lineno()] return the
> filename and cumulative line number of the line that has just been
> read; [function filelineno()] returns its line number in the current
> file; [function isfirstline()] returns true iff the line just read is
> the first line of its file; [function isstdin()] returns true iff the
> line was read from [var sys.stdin].  Function [function nextfile()]
> closes the current file so that the next iteration will read the first
> line from the next file (if any); lines not read from the file will
> not count towards the cumulative line count; the filename is not
> changed until after the first line of the next file has been read.
> Function [function close()] closes the sequence.

In a word, yuck.  I'll grant that this is a long way from XML in terms
of sheer unreadability, but it's still pretty opaque.  I'm going to take
a risk by putting on a Tom Christiansen hat (along with some asbestos
underwear) and make a bold assertion:

    The doc parser should know that 'filename', 'lineno', etc. are
    function names and act accordingly.

I.e., it shouldn't be up to the module author to say "foo is a function
name", when he has already *done so* by typing "def foo" somewhere in
the file.  This implies a lot of cooperation between the parse tree and
the documentation processor.  So be it.  This is Python, at least there
*is* a parse tree available to mere mortals.

I would much prefer to write that paragraph as

    Functions 'filename()', 'lineno()' return the filename and
    cumulative line number of the line that has just been read;
    'filelineno()' returns its line number in the current file;
    'isfirstline()' returns true iff the line just read is the first
    line of its file; 'isstdin()' returns true iff the line was read
    from 'sys.stdin'.  Function 'nextfile()' closes the current file so
    that the next iteration will read the first line from the next file
    (if any); lines not read from the file will not count towards the
    cumulative line count; the filename is not changed until after the
    first line of the next file has been read.  Function 'close()'
    closes the sequence.

...although I am perfectly willing to entertain delimiters other than ''
for identifiers (or code snippets, or whatever you want to call them).

> Attached are the results of this test.
> It rather suprised me, because it reminded me more of writing LaTeX then
> writing HTML or XML: I did both pretty heavily be hand, and LaTeX writing
> is much easier.

I agree there: I'd rather type (and read) markup closer in spirit and
conciseness to LaTeX than to *ML.

        Greg