Re: Secret POD docs

If it's not POD and it's not code, perhaps you just want a fat comment, using POD triggers, as in:

=head2 glarb() 
 
The C<glarb()> function takes care of all your glarbing needs. 
 
=cut 
 
sub glarb() { 
    # Do the glarbing 
    _glarb_internals(); 
} 
 
=begin INTERNAL_USE_ONLY

_glarb_internals(...)
 
Does the real work of glarbing.   
 
=end INTERNAL_USE_ONLY

=cut
 
sub _glarb_internals() { 
    # Do the interesting stuff 
}
[download]

-- Randal L. Schwartz, Perl hacker

Comment on Re: Secret POD docs Download Code

Replies are listed 'Best First'.
Re: Re: Secret POD docs by frag (Hermit) on May 07, 2001 at 19:49 UTC
Along the same lines: `=begin private _benjamin(...) Movie starring Goldie Hawn. =end private` [download] Not like there's any functional difference, but I've always found `=for` to be a bad choice, both esthetically and because I think it'd be confusing to future maintainers, who may not immediately get what you're doing here. Also, according to perlpod you're misusing `=for` in that example. There shouldn't be a blank line between the `=for FOO` and the POD you're for'ing. pod2html, for instance, will let the 'private' POD be displayed if you do that. Also, `=for` doesn't take an `=end`, which will also kill pod2html/Pod::Html with the error "Unmatched begin/end". (At least, it will for version 1.02 that comes with the Perl 5.005.03 that I'm using right now...) Update: There is one functional difference that bears mentioning: using begin/end like this will let you hide multiple paragraphs. (Update #2: cleaned up some confusing word choices in one sentence, that I just couldn't stand to let stand.) -- Frag.	[reply] [d/l]
Re: Re: Secret POD docs by petdance (Parson) on May 07, 2001 at 19:37 UTC
The bummer here is that the `=for` only works for the next paragraph. In the example above, the 2nd line ("Does the real work of glarbing") would still show up. xoxo, Andy %_=split/;/,".;;n;u;e;ot;t;her;c; ". # Andy Lester 'Perl ;@; a;a;j;m;er;y;t;p;n;d;s;o;'. # http://petdance.com "hack";print map delete$_{$_},split//,q< andy@petdance.com >	[reply]