#292: [CAGE] Update all Pod documentation to use sane, modern headings
---------------------+------------------------------------------------------
Reporter: allison | Owner: jkeenan
Type: cage | Status: assigned
Priority: normal | Milestone: 1.0
Component: docs | Version: trunk
Severity: medium | Keywords:
Lang: | Patch:
Platform: all |
---------------------+------------------------------------------------------
Comment(by allison):
1. The Perl 5 conventions were developed for Perl more than 10 years ago.
It made sense for the time and the context. But, a lot has changed since
then. The fact that we're using Pod syntax (which is really just a very
lightweight markup language) doesn't mean we have to also adopt all the
Perl 5 conventions. We'll keep what makes sense for us, but we aren't (and
shouldn't be) chained to Perl 5 culture.
2. Good point. I updated the coding standards after I first saw this
ticket, in, let's see... r37253.
3. Yes, Pod::Simple follows the Perl 5 conventions slavishly (I'd even go
so far as to say "stupidly", which I can do without insulting anyone since
I'm the maintainer, and therefore it's my decision to keep it focused on
Perl 5). But, Pod::Simple will also be deprecated and replaced with the
PGE-based Pod parser as soon as we finish it. In the mean time, we're
pretty safe either subclassing Pod::Simple (which we already do in several
places) or just not testing for description sections.
You probably didn't mean r37191, since that was a commit by coke. Perhaps
you meant r37193 which seems to be a large set of Pod-related fixes made
by you.
--
Ticket URL: <https://trac.parrot.org/parrot/ticket/292#comment:5>
Parrot <https://trac.parrot.org/parrot/>
Parrot Development
_______________________________________________
parrot-tickets mailing list
[email protected]
http://lists.parrot.org/mailman/listinfo/parrot-tickets
