develooper Front page | perl.perl5.porters | Postings from December 2000

Re: =code language ... =back in POD

Thread Previous | Thread Next
From:
Nicholas Clark
Date:
December 14, 2000 10:54
Subject:
Re: =code language ... =back in POD
Message ID:
20001214185435.D97909@plum.flirble.org
On Thu, Dec 14, 2000 at 08:45:12AM -1000, Tim Jenness wrote:
> On Thu, 14 Dec 2000, Tels wrote:
> > On 13-Dec-00 Nicholas Clark tried to scribble about:
> > > On Wed, Dec 13, 2000 at 03:15:43PM +0000, Simon Cozens wrote:
> > >> On Wed, Dec 13, 2000 at 11:10:27AM +0000, Nicholas Clark wrote:
> > >> > But I don't think it's safe to use =back as the end:
> > >>
> > >> Why use anything? The code section ends at the beginning of the next
> > >> non-verbatim paragraph.
> > >
> > > Could be a lot of typing if you've got several verbatim paragraphs
> > > interspersed with bits of code with the same options.
> >
> > What about my proposed:
> >
> > =begin code perl
> >
> > Some examples:
> >
> >         Use Foo qw/blah/;
> >         print blah();
> >
> > end more:
> >
> >         print blah(8);
> >
> > =end
> >
> > Would be the easiest way to extend pod without breaking it.
> 
> It wouldn't break the pod but remember that =begin/=end blocks are not
> normally displayed by the pod translators unless they recognize it [eg
> pod2latex only displays "=begin latex" blocks and not "=begin html"
> blocks]. The pod translators will have to be modified to recognize this
> new block if you intend the code examples to be displayed.

unless you use the =begin code =end blocks as instructions to the code checker

=begin code perl

use strict;
require 5.6;

=end

... all examples checked as perl with above pre-able.

=begin code perl

use Foo;
sub bar {wantarry ? ("foo", "foo") : "bar"}

=end

... you can define common bits your code needs.

=begin code

=end

... examples now not checked at all

=cut

I think that this would parse (and pass) 100% cleanly on the existing pod
tools, and the code checker would know when to check (and how), and when
to leave well alone.

Nicholas Clark

Thread Previous | 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