[Bioperl-l] Comments on new PDOC documentation

[Torsten Seemann]

Hello all,

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.

http://doc.bioperl.org/bioperl-live/

Now for some comments...

1. CSS

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

2. FRAMES

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 
browsing bioperl-run.

Is there any chance of creating a "merged" bioperl-doc page somehow?

4. STYLE

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 
  their version.

5. CONCLUSION

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