|| ||Darin McBride <dmcbride-AT-cpan.org> |
|| ||perl5-porters-AT-perl.org |
|| ||Re: Perl secret operators manual page |
|| ||Wed, 23 May 2012 10:33:20 -0600|
|| ||Article, Thread
On Wednesday May 23 2012 4:30:35 PM Philippe Bruhat wrote:
> On Mon, Apr 02, 2012 at 10:25:39AM +0200, Philippe Bruhat (BooK) wrote:
> > After some work on github, I have pushed (during the Perl QA Hackathon
> > in Paris) a book/perlsecret branch that contains a new manual page
> > (perlsecret.pod, not referenced in the main perl.pod) and a new test
> > script (secret.t, under t/japh, so that it's only run during torturetest).
> > Thanks for considering it for inclusion in a future Perl release.
> Now that 5.16 is out, I'd like to discuss the inclusion of this minor
> (and hidden) addition to the Perl documentation.
It'd be nice to have it all in one place, but I'd like to make a couple of
1. Label the "secret" operators that are encouraged (Venus, Bang bang, Eskimo
greeting, and maybe Babycart, I think) to distinguish them from the "obscure
to the uninitiated".
I get this is a judgement call, and exactly which ones get "acceptable" status
is open to interpretation, but our docs already detail suggestions on
readability, maintainability, etc., so I think such suggestion is valid here,
2. I know what =()= is normally called. But as soon as you put "don't google
this", you know what's going to happen. At a bare (no pun intended) minimum,
it should be labelled as Not Safe For Work. I would prefer that for official-
like documentation, we simply avoid it altogether. The "Saturn" moniker is
better anyway, could we just use that here?
to post comments)