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

early draft proposal for POD footnote syntax

Thread Next
David Nicol
August 29, 2009 15:18
early draft proposal for POD footnote syntax
Message ID:
On Fri, Aug 28, 2009 at 4:29 PM, brian d foy<> wrote:
> In article
> <>, Flavio
> Poletti <> 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

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

Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About