[Bioperl-l] bug #1396: *.PL to *.pod conversion is broken,
makebailsout
Brian Osborne
brian_osborne at cognia.com
Fri Mar 7 12:01:41 EST 2003
Aaron,
This sounds good. Much much better. I understood that having version numbers
distributed about was a good idea but I didn't understand why it was only
applied to the *pod files.
Brian O.
-----Original Message-----
From: Aaron J Mackey [mailto:ajm6q at virginia.edu]
Sent: Friday, March 07, 2003 8:28 AM
To: Allen Day
Cc: Hilmar Lapp; Lincoln Stein; Brian Osborne; Bioperl
Subject: Re: [Bioperl-l] bug #1396: *.PL to *.pod conversion is broken,
makebailsout
I prefer the "inside-out" approach over an "outside-in" like yours:
1. strip $VERSION = <blah> from all code.
2. Add something like this to Bio/Root/Version.pm:
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