[Bioperl-l] Comments on new PDOC documentation
torsten.seemann at infotech.monash.edu.au
Mon Jun 26 22:57:47 EDT 2006
I am very happy to see the PDOC software has been improved, as I use the
online web documentation frequently. Thanks to Jason, Raphael and
Patrick for making this happen.
Now for some comments...
It uses CSS which is excellent, reducing HTML size and allowing easy
tweaks to the design. However its current implementation has some issues:
A. it seems to only use ID, rather than CLASS, to specify styles.
ID values must be unique in a page, and are for one-off styles.
CLASS may be re-used throught a page. eg "sub" and "subArea".
Many browsers do not enforce this however...
B. it seems to be doing unusual, but possibly deliberate, things with
the POD when determining what CSS ID to give it, but perhaps this is
more to do with how Bioperl formats the POD on some subheadings
<a name="_pod_Reporting Bugs" id="_pod_Reporting Bugs">
<a name="_pod_AUTHOR - Ewan Birney" id="_pod_AUTHOR - Ewan Birney">
C. the "Description" sections etc are in a proportional font, but
I think it should be "font-family: monospace" as many authors have
exploited the traditional monospace of most editors to format
their comments, which are now lost
I notice it still uses HTML Frames. Although this reduces code size
also, it makes it impossible to LINK directly to a specific
documentation page with all the frames intact. It may be better to use 3
DIV elements which are part of each page, and they could be server-side
included so there is no HTML duplication.
3. MERGING OF BIOPERL DOCS
One facet of the docs I find frustrating is that bioperl-live and
bioperl-run (and the others) are separate! This means that you have to
keep switching between them, and more importantly, class-names to
classes in other packages are not present; this is particularly bad when
Is there any chance of creating a "merged" bioperl-doc page somehow?
Choice of colours and layouts is such a personal thing.
I guess people can download http://doc.bioperl.org/css/perl.css
and re-edit it, and get their Browser to over-ride the supplied CSS with
Please don't get the wrong idea, I love the new PDOC, I would just like
to love it more. And yes I understand the nightmare that is parsing
Perl/POD and generating compatible CSS :-)
Dr Torsten Seemann http://www.vicbioinformatics.com
Victorian Bioinformatics Consortium, Monash University, Australia
More information about the Bioperl-l