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

[Allen Day]

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
> > >
> > >
> > >
> >
> 
>