[Doc-SIG] Re: POD (resend)
Thu, 29 Mar 2001 18:50:01 -0500
> i really dislike the stuff in the source. Take a look in particular
> at the last paragraph in my excerpt - such markup may be a necessary
> evil, but i'm really hoping we don't have to put something of the
> sort in function docstrings.
I figure the last paragraph is here:
> B<Perl*Handler>s can obtain a reference to the request object when it
> is passed to them via C<@_>. However, scripts that run under
> B<Apache::Registry>, for example, need a way to access the
> request object. B<Apache::Registry> will make a request object
> available to these scripts by passing an object reference to
> C<Apache-E<gt>request($r)>. If handlers use modules such as
> B<CGI::Apache> that need to access C<Apache-E<gt>request>, they
> too should do this (e.g. B<Apache::Status>).
Without the markup,
Perl*Handlers can obtain a reference to the request object when it is passed
to them via @_. However, scripts that run under Apache::Registry, for
example, need a way to access the request object. Apache::Registry will make
a request object available to these scripts by passing an object reference to
Apache->request($r). If handlers use modules such as CGI::Apache that need
to access Apache->request, they too should do this (e.g. Apache::Status).
So the first lesson I take from that is that the doc author was markup-happy:
I can read it just fine without *any* markup (and POD is such that it won't
muck with anything I wrote there, apart from reflowing the text -- I don't
even have to *think* about running afoul of its heuristics, because there
aren't any <wink>).
The worst ugliness is specific to Perl:
is a common code construct in Perl, so if you feel compelled to wrap all
examples in C<> or B<> markup, you have to get ugly to escape the embedded
">" via "E<gt>" instead. That wouldn't come up often in Python docstrings.