Re: Perl secret operators manual page

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 
(minor?) suggestions:

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, 
too.

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?