[Bioperl-l] bioperl-db & biosql documentation
Brian Osborne
brian_osborne at cognia.com
Fri Apr 16 11:36:37 EDT 2004
Dave,
Very good suggestions, thank you. In fact my basic response to all this
documentation was the same as yours. I will try to do what I can to simplify
this collection of files but it may be that a single HOWTO is also part of
the solution. Unfortunately I'm not the best person to do this because I'm
not a regular user of these packages but I could do a decent first pass by
trans-splicing existing files, then an expert/user would have to step in.
Like you! ;-)
Brian O.
-----Original Message-----
From: bioperl-l-bounces at portal.open-bio.org
[mailto:bioperl-l-bounces at portal.open-bio.org]On Behalf Of Dave Howorth
Sent: Friday, April 16, 2004 10:57 AM
To: BioPerl
Subject: [Bioperl-l] bioperl-db & biosql documentation
I've just installed bioperl-db and thought I'd offer some comments about
my experience as a contribution to the project. The installation went
well (with the exception of a self-inflicted test failure) so my
thoughts are centred around the documentation.
There seem to be lots of (fairly) small files that describe different
aspects of bioperl-db and biosql, particularly installation. They are
all incomplete and all give slightly different instructions (e.g for the
version of MySQL 3.23.? that is required). Most of them don't have
dates or version numbers or authors or any other indication of their
name or origin. It would be better to condense them into a smaller
number of more comprehensive documents, IMO.
From the point of view of a bioperl user, it isn't clear why it's
necessary to go to three/four sites, download separate tarballs etc and
read as many sets of documentation (biosql, bioperl-db, bioperl, cpan,
mysql) to do what from the user's point of view should in an ideal world
all have been transparently installed when 'bioperl' was installed. The
current distribution mechanism seems to be designed more for the
developers' convenience than the users'.
Files
-----
bioperl-db/INSTALL
bioperl-db/README
bioperl-db/README-MYSQL
bioperl-db/docs/HOWTO-MySQL.html
bioperl-db/docs/HOWTO-make_test.pod
biosql-schema/INSTALL
biosql-schema/README
biosql-schema/doc/README
biosql-schema/doc/biosql-ERD.pdf
biosql-schema/doc/biosql.html
biosql-schema/doc/schema-overview.txt
biosql-schema/sql/README
biosql-schema/sql/biosql-ora/README
biosql-schema/sql/biosql-ora/INSTALL
http://bioperl.org/Core/Latest/biodatabases.html
Version numbers
---------------
Why aren't there explicit version numbers? (in the name of the tar file,
for example, or explicitly stated in the README or INSTALL files)
The docs have a number of places where small improvements might be made:
bioperl-db/INSTALL
------------------
1/ Doesn't actually say how to install bioperl-db (ideally make
Makefile.PL; make; make test; make install but in reality more
complicated because the schema is shipped separately)
2/ It mentions DBHarness.markerdb.conf but it's not clear why. This file
doesn't appear to be mentioned elsewhere.
3/ Within the conf scripts, these lines mystified me
# The name of the database within bioperl-db
# There is right now only one possible value:
# 'biosql' for the biosql adaptors
'database' => 'biosql',
It wasn't clear what the difference is from the previous dbname line. I
changed the dbname to biosql_test (which is what I had created) and left
database as biosql, and that worked but I don't know why.
4/ Refers to MySQL 3.23.52
5/ Discusses whether a pre-existing database should be used for testing.
Allowing the bioperl-db test script to create a temporary database seems
dangerous since it requires the user be given wide-ranging powers over
any database (unless there's a way to allow a user to just create a
database named '_test_*').
bioperl-db/docs/HOWTO-MySQL.html
--------------------------------
1/ Full marks for author, date and version number!
2/ Document is excellent at creating a warm fuzzy feeling so I
understood what was going on.
3/ Refers to MySQL 3.23.41, which apparently worked!!!
4/ It does list 'make Makefile.PL; make; make install', but it omits
'make test'! (which would be after step 7, I guess)
bioperl-db/docs/HOWTO-make_test.pod
-----------------------------------
1/ This says to copy the conf file to the bioperl-db home directory,
whilst the INSTALL doc says to leave them in the bioperl-db/t directory
(and that works)
2/ This file should be deleted and the content incorporated in the
INSTALL doc, IMO. The point about a user name is a useful reminder.
biosql-schema/INSTALL
---------------------
1/ Lots of good stuff about biosql
2/ Also includes stuff about bioperl, including hints about preloading
the taxonomy tables that isn't available in the bioperl docs themselves
as far as I can see.
biosql-schema/README
--------------------
1/ Full marks for author, date and version number!
2/ Refers to MySQL 3.23.50
biosql-schema/doc/README
------------------------
1/ This seems just to be a note about how the (obsolete) biosql.html was
generated, so should be deleted (or stated directly in an updated
version of biosql.html)
biosql-schema/doc/biosql-ERD.pdf
--------------------------------
1/ A very useful document.
2/ I'm not sure how the version number ties in with that of the
biosqldb-mysql.sql script, for example.
biosql-schema/doc/biosql.html
-----------------------------
1/ This would be a useful document but it appears to be obsolete (again,
no version number, but it's inconsistent with the SQL)
biosql-schema/doc/schema-overview.txt
-------------------------------------
1/ This is a very useful file because it provides design description and
rationale not found anywhere else.
2/ It appears to be obsolete though still useful (no version number)
3/ It could be improved, IMO, if the section headings matched those of
the coloured blocks in the ERD and if diagrams of the relevant subsets
of the ERD were used to illustrate it.
biosql-schema/sql/README
------------------------
1/ This file is short and contains some useful information; it's not
clear why it isn't simply part of biosql-schema/README.
http://bioperl.org/Core/Latest/biodatabases.html
------------------------------------------------
1/ A useful overview.
2/ The link below is broken (the full stop shouldn't be part of the link):
http://cvs.open-bio.org/cgi-bin/viewcvs/viewcvs.cgi/?cvsroot=bioperl.
3/ The links to the Bio::DB::SQL::SeqAdaptor manpage, the
Bio::DB::SQL::QueryConstraint manpage, the Bio::DB::SQL::CommentAdaptor
manpage, and the Bio::DB::SQL::BioQuery manpage don't work.
Just to be clear that this is meant to be constructive suggestions: a
big thank you to everybody who has put in effort on these great projects.
Thanks and regards,
Dave
--
Dave Howorth
MRC Centre for Protein Engineering
Hills Road, Cambridge, CB2 2QH
01223 252960
_______________________________________________
Bioperl-l mailing list
Bioperl-l at portal.open-bio.org
http://portal.open-bio.org/mailman/listinfo/bioperl-l
More information about the Bioperl-l
mailing list