--- Felix Geerinckx <[EMAIL PROTECTED]> wrote: > on Mon, 10 Jun 2002 17:37:46 GMT, John Brooking > wrote: > > > [...] > > If it's something about the internals that only > > the developer needs to know, such as more > explanation > > of a particularly gnarly algorithm, then it > needn't > > and probably shouldn't be POD. Don't confuse your > > audience with things they don't need to know. > > But then you could always use > > =for those_interested_in_the_nifty_algorithm > > Explanation of the nifty algorithm > > =cut > > # rest of code > > which will never show up in a pod2something > translation. > I tend to use this only to (temporary) comment out > large chunks of code > though. For 'real' comments, I always use #. > > -- > felix
Hey! The Camel book (am I right in assuming that is the Perl community's nickname for O'Reilly's "Programming Perl"?) says that "comment", when used as a translator keyword following "=for", is by convention ignored by all translators. So in my mind, "=for comment" would be a Safe and Acceptable way to begin a multiple line comment that you don't want your public to see. Or, if you are commenting only for yourself or other future developers, you could use something like "=for developers", and write a translator that responds to that word. But maybe not, because a "translator" by definition translates to a particular output format, whereas this "translator" is named not for the output format it creates but for the POD sections it selects. So it kind of gets away from the intended purpose. Maybe the standard POD syntax ought to have an "audience" directive, and include a command line flag on perldoc to indicate what audiences to include. (Drat, second time today I've regretted missing the Perl 6 comment period!) - John ===== "Now it's over, I'm dead, and I haven't done anything that I want; or, I'm still alive, and there's nothing I want to do." - They Might Be Giants, http://www.tmbg.com __________________________________________________ Do You Yahoo!? Yahoo! - Official partner of 2002 FIFA World Cup http://fifaworldcup.yahoo.com -- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
