[Bioperl-l] bug #1396: *.PL to *.pod conversion is broken,
makebailsout
Hilmar Lapp
hlapp at gnf.org
Fri Mar 7 09:32:43 EST 2003
Sounds good to me. Could there possibly be knock-on effects from having
RootI inherit from this?
-hilmar
On Friday, March 7, 2003, at 05:28 AM, Aaron J Mackey wrote:
>
> 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
>
>
>
--
-------------------------------------------------------------
Hilmar Lapp email: lapp at gnf.org
GNF, San Diego, Ca. 92121 phone: +1-858-812-1757
-------------------------------------------------------------
More information about the Bioperl-l
mailing list