[Bioperl-l] bug #1396: *.PL to *.pod conversion is broken,
makebailsout
Aaron J Mackey
ajm6q at virginia.edu
Fri Mar 7 08:52:29 EST 2003
That should be my $i = 0 and export_to_level($i+1) ... then it works (at
least for any package that uses Bio::Root::Version) ... but still testing
-Aaron
On Fri, 7 Mar 2003, Aaron J Mackey wrote:
> package Bio::Root::Version;
> use vars qw(@ISA $VERSION @EXPORT);
> @ISA = qw(Exporter);
> $VERSION = 1.2;
> @EXPORT = qw($VERSION);
>
> sub import {
> # handle multiple levels of inheritance:
> my $i = 1;
> my $pkg = caller($i);
> while($pkg &&
> $pkg =~ m/^Bio/o &&
> !defined ${"$pkg::VERSION"}) {
> Bio::Root::Version->export_to_level($i);
> $pkg = caller(++$i);
> }
> }
>
> 1;
>
> 3. add "use Bio::Root::Version" to any (base) classes you want versioned
> (Bio::Root::RootI should take care of most all of BioPerl), and add
> Bio::Root::Version to their @ISA.
>
> This is all just a bit off the top of my head, but wouldn't an approach
> like this:
>
> * keep $VERSION being defined in one logical place
> * not force developers to run an external script to synchronize version
> numbers
> * allow Makefile.PL to do a VERSION_FROM => 'some::module'
>
> In terms of the original doc.PL => doc.pod problem, perhaps the better
> solution would be:
>
> PL_FILES => [ docversion.pl => [ qw(biodatabases.pod biodesign.pod ...) ]]
>
> Leave all the docs in bio*.pod, using Lincoln's suggested @@VERSION@@
> "tag".
>
> docversion.pl simply finds all .pod docs (or maybe goes recursively
> through the entire directory tree, working on all files), and does a
> s/\@\@VERSION\@\@/$Bio::Root::Version::VERSION/g; on everything.
>
> Thoughts? A tad less baroque (if a bit more arcane?)
>
> -Aaron
>
> On Thu, 6 Mar 2003, Allen Day wrote:
>
> > yes, i think you've summed it up pretty well.
> >
> > > 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).
> >
> > maybe the bioperl class templates in bioperl.lisp could have some special
> > versioning strings added to them, and at the end of the make process do
> > something analogous the cvs-repository switch:
> >
> > find . -name 'Root' -type f -exec perl -i -p -e 's/dev\./pub\./' {} \;
> >
> > ? but it would fail on windows, i believe. i'll try to just get the main
> > pod docs working first, then maybe worry about tagging all the other docs
> > once we solve this problem.
> >
> > -allen
> >
> >
> >
> > > 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
> > > > >
> > > > >
> > > > >
> > > >
> > >
> > >
> >
> > _______________________________________________
> > 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
More information about the Bioperl-l
mailing list