[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