[Bioperl-l] bug #1396: *.PL to *.pod conversion is broken, makebailsout

[Aaron J Mackey]

I'm sorry, I'm obviously coming in late to the party, so I'm not entirely
sure what happened before I got here.  Looking at the repository, it looks
like (correct me if I'm wrong):

* we wanted to have a one-stop location for setting a few "global" values
(like $VERSION and I guess, @AUTHORS)

* we use Makefile.PL to write to bioperl.conf (so VERSION is set only in
Makefile.PL and cascades to everything else)

* LocalConfig reads bioperl.conf to grab the values

* we use LocalConfig when we want access to $VERSION.

* we have some .pod docs in which we want to have $VERSION (so we turn the
.pod's into .PL scripts, and need to jump through interpolation hoops to
only get $VERSION interpolated and nothing else).

This all seems very baroque, but I understand the complexities involved.
My suggestion re: Pod::Constants is not applicable in this situation,
since we want to get code into POD, not vice versa.

RE: version numbers, it'd actually be very useful if the top-level
$VERSION could be propagated throughout the entire object hierarchy (so I
could say "use Bio::SeqIO 1.2" if I needed).  If $VERSION is really the
only reason for the entire system outlined above, then I think there must
be a better way to do this ... (various source filters come to mind).

Something to think about for 1.3 ...

-Aaron

On Thu, 6 Mar 2003, Hilmar Lapp wrote:

> I don't quite understand how this would work in reality, but I trust
> Brian and you can work out something that
>
> 	a) makes it relatively difficult to have stale version numbers in
> documentation upon releases (which was the original problem Allen was
> trying to solve),
>
> 	b) does not make a documenter's life more miserable by requiring him
> to pay attention to otherwise unnecessary things like hand-escape all
> variables in the text,
>
> 	c) is simple enough to enable a willing documenter to create a
> conforming file from scratch without having to take a class,
>
> 	d) doesn't break documentation containing code snippets nor causes
> running make to fail, and
>
> 	e) doesn't require a user to install esoteric packages for solely this
> purpose
>
> I'll appreciate and welcome whatever Brian and you suggest and
> accomplishes this; if I remain silent on a particular suggestion, it
> doesn't mean that I don't like it, I may just not understand it.
>
> 	-hilmar
>
> On Thursday, March 6, 2003, at 06:39  AM, Aaron J Mackey wrote:
>
> >
> > Let me just toss in a small recommendation that you might want to
> > consider
> > "reversing" the problem; instead of reading/interpolating variable
> > values
> > in POD, try providing the values in regular POD format, and using
> > Pod::Constants to extract and set the corresponding variables:
> >
> > use vars qw($VERSION);
> > use Pod::Constants VERSION => sub { eval };
> >
> > =pod
> >
> > =head2 VERSION
> >
> > $VERSION = 1.1
> >
> > =head2 SYNOPSIS
> >
> >   # perl code that will not be interpolated
> >   my @foo = blah_blah('blah');
> >
> > =cut
> >
> > On Thu, 6 Mar 2003, Brian Osborne wrote:
> >
> >> Lincoln,
> >>
> >> You'd mentioned something about using @@VERSION@@ but my searches
> >> using this
> >> word or "@@" didn't turn up anything. Can you direct me to a man page
> >> or Web
> >> page or application that discusses this?
> >>
> >> Brian O.
> >>
> >>
> >> -----Original Message-----
> >> From: Hilmar Lapp [mailto:hlapp at gnf.org]
> >> Sent: Thursday, March 06, 2003 2:33 AM
> >> To: Allen Day
> >> Cc: Bioperl; Lincoln Stein; brian_osborne at cognia.com
> >> Subject: Re: [Bioperl-l] bug #1396: *.PL to *.pod conversion is
> >> broken,
> >> makebailsout
> >>
> >>
> >> On Wednesday, March 5, 2003, at 08:20  PM, Allen Day wrote:
> >>
> >>> Hey, sorry, I wasn't following this thread.  Has there been a
> >>> resolution
> >>> on this, or do I need to fix it?
> >>>
> >>> There had been some variables in other of the converted .pod files, I
> >>> tried to separate the pod into two types of sections:
> >>>
> >>> (1) those where i needed to do variable interpolation from LocalConf
> >>> were
> >>>     put in <<"HEREDOC" blocks
> >>> (2) everything else (including variables in pseudocode) were put in
> >>>     non-interpolated <<'HEREDOC' blocks
> >>>
> >>
> >> I'm not sure how a non-interpolated HERE-document looks, but as a
> >> matter of fact biodesign.PL and biodatabases.PL were all one document,
> >> and variables were interpolated all over the place.
> >>
> >> Lincoln fixed this by manually escaping all variables.
> >>
> >>> I don't get any errors during the make, but it might just be my
> >>> system.
> >>
> >> Most of the interpolated variables do not yield errors. Only the
> >> arrays
> >> (@arr) do. Scalars silently result in emptiness.
> >>
> >> I guess you noticed the move to pub.open-bio.org meanwhile.
> >>
> >>         -hilmar
> >>
> >> --
> >> -------------------------------------------------------------
> >> Hilmar Lapp                            email: lapp at gnf.org
> >> GNF, San Diego, Ca. 92121              phone: +1-858-812-1757
> >> -------------------------------------------------------------
> >>
> >>
> >> _______________________________________________
> >> Bioperl-l mailing list
> >> Bioperl-l at bioperl.org
> >> http://bioperl.org/mailman/listinfo/bioperl-l
> >>
> >
> > --
> >  Aaron J Mackey
> >  Pearson Laboratory
> >  University of Virginia
> >  (434) 924-2821
> >  amackey at virginia.edu
> >
> >
> >
>

-- 
 Aaron J Mackey
 Pearson Laboratory
 University of Virginia
 (434) 924-2821
 amackey at virginia.edu