[Doc-SIG] Re: POD (resend)

[Tim Peters]

[Ken Manheimer]
> ...
> 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:

    object->attribute

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.