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

[Aaron J Mackey]

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