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

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

Thread Previous | Thread Next
From:
Tim Jenness
Date:
December 14, 2000 12:53
Subject:
Re: =code language ... =back in POD
Message ID:
Pine.LNX.4.30.0012141051290.1806-100000@lapaki.jach.hawaii.edu
On Thu, 14 Dec 2000, Nicholas Clark wrote:

> 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.
>

Parsing is not the issue - that will work fine. If you want the examples
to appear in any translated pod document you will have to make sure the
translators treat it in a special way. Code examples that do not appear
are not that helpful.

-- 
Tim Jenness
JCMT software engineer/Support scientist
http://www.jach.hawaii.edu/~timj



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