perl.pod-people...Re: POD doesn't capture code semantics by Adriano Ferreira- March 5, 2008 On Wed, Mar 5, 2008 at 4:57 PM, Andy Armstrong <andyhexten.net> wrote:> On 5 Mar 2008, at 19:53, Mark Overmeer wrote:> >> So now we just need to backport that to Perl 5 and convert every> >> extant POD parsing tool. What could possibly go wrong> >> > Damian has made an implementation in Perl5:> > http:search.cpan.orgdconwayPerl6-Perldoc-v0.0.5>>> That doesn&39;t help with parsing it though does it Although presumably> it contains.http://www.nntp.perl.org/group/perl.pod-people/2008/03/msg1330.html Re: POD doesn't capture code semantics by Andy Armstrong- March 5, 2008 On 5 Mar 2008, at 19:53, Mark Overmeer wrote:>> So now we just need to backport that to Perl 5 and convert every>> extant POD parsing tool. What could possibly go wrong>> Damian has made an implementation in Perl5:> http:search.cpan.orgdconwayPerl6-Perldoc-v0.0.5That doesn&39;t help with parsing it though does it Although presumably it contains a POD6 parser that could be repurposed.-- Andy Armstrong, Hextenhttp://www.nntp.perl.org/group/perl.pod-people/2008/03/msg1329.html Re: POD doesn't capture code semantics by Andy Armstrong- March 5, 2008 On 5 Mar 2008, at 19:36, Adriano Ferreira wrote:> The S26 (Synopsis 26) is the official document: latest version here> http:feather.perl6.nlsynS26.htmlHeh. And there it all is under "Semantic blocks" :)So now we just need to backport that to Perl 5 and convert every extant POD parsing tool. What could possibly go wrong-- Andy Armstrong, Hextenhttp://www.nntp.perl.org/group/perl.pod-people/2008/03/msg1328.html Re: POD doesn't capture code semantics by Adriano Ferreira- March 5, 2008 On Wed, Mar 5, 2008 at 4:28 PM, Andy Armstrong <andyhexten.net> wrote:> On 5 Mar 2008, at 19:23, Adriano Ferreira wrote:> > =for method> >> > has the least impact (if the next paragraph is left blank). According> > to the specs, it should be understood as leave the paragraph alone if> > you (POD processor) does not know about &39;method&39;.>> Ah, OK. Thanks.>>> >> That&39;s all legal POD that shouldn&39;t mess up existing...http://www.nntp.perl.org/group/perl.pod-people/2008/03/msg1327.html Re: POD doesn't capture code semantics by Andy Armstrong- March 5, 2008 On 5 Mar 2008, at 19:23, Adriano Ferreira wrote:> =for method>> has the least impact (if the next paragraph is left blank). According> to the specs, it should be understood as leave the paragraph alone if> you (POD processor) does not know about &39;method&39;.Ah, OK. Thanks.>> That&39;s all legal POD that shouldn&39;t mess up existing parsers.>> POD is a little verbose and mixes content with markup as noticed by > Andy with>> =item C<foo>>>...http://www.nntp.perl.org/group/perl.pod-people/2008/03/msg1326.html Re: POD doesn't capture code semantics by Adriano Ferreira- March 5, 2008 On Wed, Mar 5, 2008 at 3:35 PM, David Golden <xdaveggmail.com> wrote:> On Wed, Mar 5, 2008 at 1:06 PM, Ian Malpass <ianindecorous.com> wrote:> > How about:> >> > =for method> >> > =head2 C<foo>> >> > Bit ugly, but it should work. Additional stuff after "method" could> > provide more metadata, etc.>> A simpler option might be to use the X<> indexing mark:>> =head2...http://www.nntp.perl.org/group/perl.pod-people/2008/03/msg1325.html Re: POD doesn't capture code semantics by Andy Armstrong- March 5, 2008 On 5 Mar 2008, at 19:05, David Golden wrote:> Unfortunately, I just tested this and it isn&39;t passed through to a> parser automatically -- so this will only work for metadata, not> actual documentationSo=for :method <metadata>=head2 C<my_method>=cutsub my_method seems to work. And perlpodspec allows text after that form of =for.-- Andy Armstrong, Hextenhttp://www.nntp.perl.org/group/perl.pod-people/2008/03/msg1324.html Re: POD doesn't capture code semantics by Andy Armstrong- March 5, 2008 On 5 Mar 2008, at 18:59, chromatic wrote:> On Wednesday 05 March 2008 10:52:11 Andy Armstrong wrote:>>> I wonder how you&39;d tag a subroutine that can be called as a method or>> a regular subroutine.>> :horrible_evil_delete_this_entire_file_to_be_safeme makes notes.-- Andy Armstrong, Hextenhttp://www.nntp.perl.org/group/perl.pod-people/2008/03/msg1323.html Re: POD doesn't capture code semantics by Andy Armstrong- March 5, 2008 On 5 Mar 2008, at 18:50, Ian Malpass wrote:> The backwards-compatibility thing is important if you want your docs > to be widely read by a disparate audience. Your suggested syntax > renders a document near-useless (totally missing headers, plus error > messages) if the POD reader isn&39;t "enhanced POD" capable. That > doesn&39;t sound like a recipe for gaining traction.... The drawback of > extra verbosity is that it requires documenters to remember to use ...http://www.nntp.perl.org/group/perl.pod-people/2008/03/msg1322.html Re: POD doesn't capture code semantics by Andy Armstrong- March 5, 2008 On 5 Mar 2008, at 18:35, David Golden wrote:> Also, more generally, consider that formats that begin with a colon> are treated as POD and parsed as normal (c.f. perlpodspec and the "=> :biblio" example). So consider this in combination with the X<> tag> mentioned above :>> =begin :method>> =head2 X<C<foo>>>> Documentation of foo() here...>> =end :method>> That&39;s all legal POD that shouldn&39;t mess up existing.http://www.nntp.perl.org/group/perl.pod-people/2008/03/msg1321.html |