[Bioperl-l] Bio::Root::Version functionality is in.

[Brian Osborne]

Aaron,

OK, I've made the changes we've discussed. One oddity though, which you
could surely explain. I could get
s/@@VERSION@@/$Bio::Root::Version::VERSION/g (or
s/\@\@VERSION\@\@/$Bio::Root::Version::VERSION/g) to work from the command
line, but neither worked for me from within makedoc.PL. The File::Find was
working, the $version variable was found in Bio::Root:Version, but the
substitution itself didn't work. It had to do with "@@", other substitutions
worked fine. So, the situation now is that the string being substituted is
"==VERSION==", not "@@VERSION@@". I'll fix this if someone gives me a hint.
A Cygwin anomaly?

I also modified Makefile.PL, everything seems to work, except that
bio*.pod.bak files are automatically created, don't know how to get around
this. Those who pay attention to the Makefile.PL might want to double-check
my changes, letting me edit that file is a bit like letting the gardener
tune the Bentley.


Brian O.

-----Original Message-----
From: bioperl-l-bounces at bioperl.org [mailto:bioperl-l-bounces at bioperl.org]On
Behalf Of Aaron J Mackey
Sent: Sunday, March 09, 2003 9:41 AM
To: Bioperl
Cc: Brian Osborne
Subject: [Bioperl-l] Bio::Root::Version functionality is in.


Bio::Root::Version is in, and Bio::Root::RootI is the only module to use
it directly (but see below).

> On Sat, 8 Mar 2003, Brian Osborne wrote:
>
> > I could do the following:
> >
> > Add 'use Bio::Root::Version;' to modules as needed (including
bioperl-run,
> > but would it include bioperl-pipeline? bioperl-db?).
> > Add Bio::Root::Version to @ISA as needed.

None of this is needed; if a module uses/requires (directly or
indirectly) Bio::Root::RootI, then the version will kick in (unless the
module already has their own VERSION defined).  I didn't want to stomp on
a lot of different territory; those who wish to use this in their modules
can simply remove their own $VERSION setting code.

> > Make the 4 new *pods from the old *PLs, including a @@VERSION@@ string.

Yep, then you need a "makedoc.PL" script that looks something like this:

#!/usr/bin/perl

use lib "./";
use strict;

require Bio::Root::Version;
require File::Find;

File::Find::find(\&wanted, '.');

sub wanted {
    next unless m/^.*\.pod\z/os; # add .pm to be able to use @@VERSION@@
                                 # within module docs as well
    `perl -pi -e 's/\@\@VERSION\@\@/$Bio::Root::Version::VERSION/g;' $_`;
}

__END__

Then, alter Makefile.PL to use makedoc.PL to do the substitutions.


End result, from Hilmar's wish list:

a) makes it relatively difficult to have stale version numbers in
documentation upon releases (which was the original problem Allen was
trying to solve),

Yep; doc's should use @@VERSION@@

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,

Check; docs are written in plain old POD, nothing else to worry about.

c) is simple enough to enable a willing documenter to create a conforming
file from scratch without having to take a class,

Check; we've done the class-work for them.

d) doesn't break documentation containing code snippets nor causes running
make to fail, and

Yep, I checked (but you should too).

e) doesn't require a user to install esoteric packages for solely this
purpose

Check.  No esoterics involved

-Aaron

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