Front page | perl.libwww |
Postings from March 2001
From: Robert Urban
March 27, 2001 16:53
Message ID: 200103280052.CAA0000012581@hell.spielwiese.de
Randal L. Schwartz wrote:
> >>>>> "Robert" == Robert Urban <urban@UNIX-Beratung.de> writes:
> Robert> For example, it's not clear whether a local filename can be
> Robert> given as '$html_document'. Examples can reduce 1/2 hour of
> Robert> trial and error and swearing to 15 seconds of simple
> Robert> comprehension.
> Hmm. Whenever the docs don't do it for me, I simply type
> perldoc -m HTML::Form
> to look at the source, and I can probably still have the answer closer
> to 15 seconds, not a 1/2 hour.
umm, while I am capable of figuring out from the source, given enough
time, that's not really the point, is it? I mean, what you seem to
be saying is the source is the doc. If that's the case, why bother
with manpages at all? I guess the question a module writer should
ask h(im|er)self is, who is my audience? if it's 100% Perl-jocks,
forget the manpage, a 2-liner README will do. If, however, the module
writer wants to make h(is|er) stuff available to a wider audience,
a good manpage is worthwhile, no?
> I've also never seen a Perl function accept either a filename or
> a string in the same parameter... since that would be ambiguous, since
> any filename could be a string, and any string could be a filename.
> So I would have looked for a different function already.
> This is not to say that more examples wouldn't be nice, but I don't
> think they're necessary, at least for the question you cited above.
you're right. Although the manpage begs for examples, in this case
it wasn't clear (at least not to me) what was meant by "HTML document",
scalar (string), filehandle, filename?
My suggesting the use of examples, in retrospect, was a request for
a second source of information, because the first source ("DESCRIPTION")
didn't do it for me.
Beggers can't be choosers, and I'm glad Gisle went to the trouble of
writing this stuff. The manpage just seems a little dense...