develooper Front page | perl.perl5.porters | Postings from August 2009

early draft proposal for POD footnote syntax

Thread Next
From:
David Nicol
Date:
August 29, 2009 15:18
Subject:
early draft proposal for POD footnote syntax
Message ID:
934f64a20908291518t4c045c4k84b382a7decf140e@mail.gmail.com
On Fri, Aug 28, 2009 at 4:29 PM, brian d foy<brian.d.foy@gmail.com> wrote:
> In article
> <aeba50980908270831q17c8da1crcf073f71039c6f3f@mail.gmail.com>, Flavio
> Poletti <polettix@gmail.com> wrote:
>
>> For example, in perldiag I found the following example:
>>
>>     open(OUT,">$ARGV[0]") or die "Can't write to $ARGV[0]: $!";
>
>> I think that, were this example written today, it would be more like this:
>>
>>     open my $out, '>', $ARGV[0] or die "Can't write to $ARGV[0]: $!";
>
> I've been doing this for the perlfaq when I run across things.
>
> If we need a documentation  pumpking to pay attention to these sorts of
> things, apply the doc patches, and so on so other people can work on
> the other favorite parts, I herby volunteer :)

Once an editor, always an editor.

Speaking as someone who recently had to edit out a bunch of 3-arg
opens to make something work on a legacy perl 5.5.2, I'd like to see
some kind of systematic notation in documentation of features that
were introduced at some point and did not work before -- footnotes,
perhaps -- stating what at version the recommended syntax became
available and what the old way to do it was.

I think this wishlist item implies adding a footnote syntax to POD.
how about "=foot" to identify a paragraph that will be a footnote, and
f<> to indicate where the footnote asterisk goes.  Multiple paragraph
footnotes are acomodated by =foot text always continuing to the next
=cut., with labels, as an optional =foot LABEL, when provided getting
associated with text inside f<LABEL> and unlabeled footnotes lining up
sequencewise.


-- 
"Yes to health care, no to wealth care!"

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About