another docs problem - imp

[rurpy at yahoo.com]

"Fredrik Lundh" <fredrik at pythonware.com> wrote in message
news:mailman.306.1136963981.27775.python-list at python.org...
> rurpy at yahoo.com wrote:
>
> > > from the find_module documentation:
> > >
> > >           find_module( name[, path])
> > >
> > >     Try to find the module _name_ on the search path _path_.
> > >     If _path_ is a list of directory names, each directory is
> > >     searched for files /.../. Invalid names in the list are
> > >     silently ignored (but all list items must be strings).
> > >     If _path_ is omitted or None, the list of directory names
> > >     given by _sys.path_ is searched /.../
> > >
> > > it's not obvious how anyone can interpret the alternatives "a
> > > list where all items are strings / omitted / None" as "not a hint
> > > that a list is expected" and "a single string *should* work (i.e.
> > > be treated as a pathname, rather than a sequence)".
> >
> > Well, I interpreted the if's as describing special cases
> > addtional to the first sentence.
>
> The first sentence says that the _path_ argument is a search path.
> It does not say that it can be a string; that's something you made
> up all by yourself.

Correct it does not say it's a string.  But your implication that
one can therefore conclude that it is not a string is silly.
>From unittest:
> assert_( expr[, msg])
> failUnless( expr[, msg])
> Signal a test failure if expr is false; the explanation for the error
> will be msg if given, otherwise it will be None.
I should conclude that msg is not a string because
it doesn't say it is a string?

> > May I suggest that the problem is easily fixed simply
> > by removing the first "if".
>
> Like
>
>     Try to find the module _name_ on the search path _path_.
>     _path_ is a list of directory names, each directory is searched
>     for files.
>
> ?  So what happens when pupry reads this, and gets annoyed that he
> always has to pass in a list ?  It's probably better if you learn to read
> technical documentation a bit more carefully.

Reading more carefully is always useful.  But that does
not remove the obligation of the writer to write clearly and
unambiguously.  Why would pupry think s/he always has
to pass in a list when the syntax description clearly shows
the arument is optional, and the following "if" sentence states
it is optional?  But perhaps you are right; perhaps something
like "_path_is a optional list of..." would be clearer.

> ... and don't give me any "you're defending the status quo" crap in
> response to this.  There are lots of things to do in the library reference,
> and a few of us are working on it (using different approaches), but
> trust me, optimizing for a few

"optimize": to make as perfect, effective, or functional as possible.
(Merriam Webster New Collegiate)

"few" has nothing to do with it.
If this required a huge amount of work, your resistance
would be understandable.  Since the wording changes
are petty minor your flamage over this is puzzling.

>     1 - I think I know how this works
Wrong, I had no idea how it worked and read the docs
first.
>     2 - oh, it didn't work.  let's check the documentation
Yes, read it a second time, didn't see the alternate interpretation.
>     3 - I think I've found a way to interpret the documentation as if
>         it allows me to do what I'm doing.  it doesn't explicitly say that
>         I can do this, but it doesn't explicitly rule it out either, so I'm
>         probably right.  I'll try again.  maybe it works this time.
Nope.  It was "hmm, seems to clearly state that it
takes a path argument."  Since I was dealing with a
single directory, and (this stuff dealing with imports
and all) had just before been thinking about sys.path
solutions, I was primed to accept that the argument
was a string and assumed I must be doing something
wrong."  <later> "Is there any source?  Nope
must be C." <later> "How about google".  Oh here
is someone with same problem, Damn, no answer.
Ohh here is some one else, different problem but
he tried both find_module(..,"xxx") and (..,"[xxx]")
and the latter didn't generate the error message.
>     4 - (2 hours later) maybe I should try one of the alternatives that
>         is mentioned in the documentation.  oh, it did work if I follow the
>         instructions.  now I'm REALLY pissed, and am going to spend
>         another hour arguing about this on the internet.
No.  As I said, I did not see your way of interpreting the
documentation until you posted.  And I had no plans
to argue about it.  I posted for the reasons I gave,
and made a suggestion about how the documention
could be improved.
Well, in your attempt at mind reading you at least
got one out of four.

> practitioners, over the
>     1 - I think I know how this works
>     2 - oh, it didn't work.  let's check the documentation.
>     3 - it says "can be a list" or "can be omitted".  let's try one of
>         those.  oh, it worked.

How about
1 - read some clear unambiguous documentation.
2 - write the code and it works as described.

My grandfather used to own a hardware store.
He frequently said he took every customer
complaint very seriously.  "For every customer
who complains, there are a 100 that just take their
business elsewhere."
I wonder how many people had a problem with
this and lost time.  Not as extreme as my case,
maybe just rereading it a few times.  And of course
this particular piece of documentation  is not an
isolated instance.  If you are happy with the status
quo, if it is "good enough" fine.   I am not.

...snipped long anacdote about busses...