Kudos to documentors: (popen2)

[Robb Shecter]

Hi,

I really didn't intend to attack you in a back-door kind of way.  I
actually first thought about posting this to a perl group to show the
problems I see.  I guess my decision was colored by negative previous
experiences I've had with strong perl-fans who love the perl system
and perldoc just as it is.  

That was probably a mistake of mine to not post in a perl group.  

Anyhow, to my comments - part of the problem here is also the perl
language, which exagerates any problems in less than perfect
documentation.  So, I know that what I'm going to say may not have
100% to do with the docs themselves:


Tom Christiansen wrote:
>
> >http://www.perl.com/CPAN/doc/manual/html/lib/IPC/Open2.html
> 
> The standard documentation for Perl is found in manpages, not
> on the web. 

It ought to be.  Or at least, well-linked "info" pages.  (This is
surely easily agreed upon, right?)  But this is a moot issue, because:

> 
>     man IPC::Open2
> 

...has apparently the same text that bothered me.  


> 
> :(Just notice how much is implicit, and not documented, and with no
> :links to other needed info.)
> 
> I have no idea what you're talking about, or what links you're
> looking for, but as the original author of that module, I am
> always happy to accept documentation suggestions.

Well, you really have to put yourself in the shoes of someone who uses
perl sometimes, even frequently, but can't always remember all of
perl's (very numerous) special cases, symbols, and objects:

1)  It will not create these file handles for you.  You have
       to do this yourself.  So don't pass it empty variables
       expecting them to get filled in for you. 

My question: how do I create these file handles?  What document would
I look in to find out?  (Aside: this to me is a case of the complex
perl language aggrevating the work of the documentor: The user must
understand "file handles", a sort of special perl-entity, as well as
cope with a lib designed with in-out parameters.  (???)  Compare the
Python version for ease of use.)

2) If $rdr is a string (that is, a bareword filehandle rather
       than a glob or a reference) and it begins with ">&"...

Woof!  Complicated!  I would have liked to use the feature talked
about (if I understand it correctly), but now there's another special
entity discussed, which I also don't know how to create.  A "bareword
filehandle"?  I wanted to hook up stdin and stdout... how do I get a
bareword filehandle out of one of those?  (It's ok - I don't need the
answers to these anymore - I'm using Python, but these are the
problems I had.)


> Or is this just another case of pissing on something that you didn't
> understand out of the way of the people responsible?  If so, you lose,
> because *I'm* responsible.  What's your biggest problem?

No; that document was really the item that sent me to Python.  Sure,
it was the straw that broke the camel's back (Hmm!) - I had been
fighting with Perl for a good hour or so, getting "irrelevant" error
messages, and then seeing docs that posed more questions for me than
they answered caused me to give Python a try.

BTW, I did appreciate your notes about deadlocks.  That -was- easy to
understand for the typical experienced unix programmer.  


> 
> And remember, Perl's documentation is NOT WEB-BASED.

OK - got it.  But how do you feel about that?  I think it ought to be
- it should take a look at what Javadoc and Python's doc system do
right, and do it better.  Ie: starting with semantic markup, not just
formatting markup.


> 
>            use FileHandle;
>            use IPC::Open2;
>            $pid = open2(*Reader, *Writer, "cat -u -n" );
>            Writer->autoflush(); # default here, actually
>            print Writer "stuff\n";
>            $got = <Reader>;

...This is even more confusing.  How are the filehandles being created
beforehand?  Is that part skipped?  Or do they not really need to be? 
Also, here I see that they're written like *Reader and not \*Reader as
the Open2 synopsis has it.  Not sure what that means.  (Again -  I
think that Perl's complexity sabotages the documentor... if everything
were simply objects, and also objects used in an OO way, then there
would be much less need to document.)


 
> Next time, please try the manpages, and send the authors mail or file a
> bug report.  But please don't just piss on people where you think they
> can't see you.  Sheesh.
> 

I certainly will.  Sorry,

- Robb