RFC 217 (v1) POD needs comment command. POD needs a reorder command.
This and other RFCs are available on the web at http://dev.perl.org/rfc/ =head1 TITLE POD needs comment command. POD needs a reorder command. =head1 VERSION Maintainer: Kenneth C. Rich [EMAIL PROTECTED] Date: 12 Sep 2000 Mailing List: [EMAIL PROTECTED] Number: 217 Version: 1 Status: Developing =head1 ABSTRACT When you process POD, all POD material prints. Sometimes that is undesirable. Podders need to have the option of not printing their POD. Also, it would be nice to have the order of output differ from the order in the source, sometimes. =head1 DESCRIPTION =head2 Syntax suggestions: C=clip Ioptional-label ...text... C=cut ...code... C=print Irequired-label-from-clip C=cut The "=clip" would only need a label if an "=print" needs to refer to it. I am not suggesting that "=clip" and "=print" are the best strings to use. "=say" and "=see", "=in" and "=out", "=cook" and "=serve", "=think" and "=float", etc. Someone come up with something poddishly terse please? I do not like "=comment" because it's misleading and it breaks the implicit 5-letter POD command length rule. =head2 Motivations: =over =item Comment out documentation Sometimes I want a chunk of documentation to stick around but not be visible to the casual user. It may be tentative, half-baked, plain wrong, still in development, a comment about the docs. =item Reorder the document Sometimes I want a chunk of documentation to hang out near a chunk of code, but the order of the code is not a good order for a man page. All right, so maybe this is really 2 proposals. =item Multiline comment for Perl I am not formally suggesting this as a multiline comment syntax. I already like Perl's current "multiline comment syntax" because it is so easy to edit-macro-ize. But I'd probably use it if it were there, cuz I am a bad, undisciplined programmer. =back I'd make "=clip" cover everything to the next "=command". But that may be considered un-POD-like, oh well. I'd probably require that "=print" may only occur after the matching "=clip." But I can imagine writing POD processors that deal with "=print" references preceding "=clip" assertions, so I retract that sentence. The "=print" would evaluate into a plain paragraph, so mostly you'd want to use "=print" after another "=command" like "=head1", and so on. For flexibility, an "=print" starting a pod section should effectively evaluate into an "=pod" paragraph. =head1 IMPLEMENTATION ... =head1 REFERENCES RFC 5: Multiline Comments for Perl
Re: RFC 217 (v1) POD needs comment command. POD needs a reorder command.
On Wed, Sep 13, 2000 at 07:18:56AM -, Perl6 RFC Librarian wrote: =item Comment out documentation Sometimes I want a chunk of documentation to stick around but not be visible to the casual user. It may be tentative, half-baked, plain wrong, still in development, a comment about the docs. =for nobody Some POD POD readers will currently ignore =for and =begin/=end blocks with a name they don't recognize. =item Reorder the document Sometimes I want a chunk of documentation to hang out near a chunk of code, but the order of the code is not a good order for a man page. All right, so maybe this is really 2 proposals. This part... I regularly intersperse POD with code, and I've always found that where I want the docs is also where I want the code, but YMMV. So if one were to implement this, you could do: =for later blabitty blah ...later that same file... =print later The only change to POD would be to define a =print tag which takes the name of a =for/=being/=end block to output. Multiple blocks with the same name would be concatenated together and outputed as one chunk. =item Multiline comment for Perl I am not formally suggesting this as a multiline comment syntax. I already like Perl's current "multiline comment syntax" because it is so easy to edit-macro-ize. But I'd probably use it if it were there, cuz I am a bad, undisciplined programmer. How is this different than the current? =for comment a block of comments Personally, I've found M-x comment-region in emacs to be Good Enough and never had an urgent need for a multiline comment (but I've heard rumor that still people use lesser editors). The # syntax is simple and doesn't involve any of the nesting or accidentally run-on ambiguities of multi-line comments. Its also alot easier to parse. PS Keep in mind that =for can be replaced with =begin/=end in all cases. -- Michael G Schwern http://www.pobox.com/~schwern/ [EMAIL PROTECTED] Just Another Stupid Consultant Perl6 Kwalitee Ashuranse MORONS!
Re: RFC 217 (v1) POD needs comment command. POD needs a reorder command.
POD readers will currently ignore =for and =begin/=end blocks with a name they don't recognize. Thanks, that is a good idea. RTM, Kenny. Guess I am so allergic to the foreign formatter stuff that my eye slides right off that paragraph. And the labelless =clip grew out of the =print rather than the order presented. On the further note, though, I dislike the idea of overloading the =for label for =print purposes. I will modify the RFC. On the problem end of an =clip-like feature is that the creeping featurist in me will start wanting an =endclip type of thing so that more complex pod can be =printed. -- -ken rich
Re: RFC 217 (v1) POD needs comment command. POD needs a reorder command.
On Wed, Sep 13, 2000 at 07:04:26AM -0400, Ken Rich wrote: On the further note, though, I dislike the idea of overloading the =for label for =print purposes. I will modify the RFC. Well, its not like the =for label is used much anyway... (yes, that is a troll for someone to tell me otherwise). In fact, I like "=for somewhere else" :) -- Michael G Schwern http://www.pobox.com/~schwern/ [EMAIL PROTECTED] Just Another Stupid Consultant Perl6 Kwalitee Ashuranse Like you've never accidentally spanked a midget. -- Siobain http://www.goats.com/archive/index.html?000106
