[HOpenGL] Re: haskell.org/HOpenGL/

[Claus Reinke]

> I admit being guilty of not updating the pages for a long time...
> *sigh* Having up-to-date web pages is quite important for a project,
> I know, so I'll improve this when I find some time in the near future.

if you're short on time, a few minor changes might help - cvs HOpenGL 
was ahead of its time, and Haskell implementation releases have caught 
up, so the main problem is just to remove caveats and future plans
that no longer hold or have already been implemented. examples:

- home page and README refer explicitly to old version numbers.
    that's the first stop for anyone browsing for a binding, so perhaps
    remove these numbers and refer to some part of the source/haddocks
    that automatically has the correct numbers? eg

http://www.haskell.org/ghc/docs/latest/html/libraries/OpenGL/Graphics.Rendering.OpenGL.html

http://www.haskell.org/ghc/docs/latest/html/libraries/GLUT/Graphics.UI.GLUT.html

    also, is there a HOpenGL function that returns the version numbers 
    of current installations one could refer to? lest they try to compile
    new versions of examples with old haskell installations.

- change references to "current" and "new" API to "old" and "current"
    (links to tutorials, tar-balls vs cvs packages, ghc-only vs ghc&hugs)

- as a stop-gap: just stating explicitly on the home page that the web 
    pages lag behind actual development would help, eg. refer to your 
    HOpenGL entry in the current Haskell Communities report, which 
    is already written and clarifies some of the issues (and there's a new 
    one coming up soon;-):

http://www.haskell.org/communities/11-2004/html/report.html#sect4.6.2

- docs page: yes, the GLUT docs are more extensive, and the GL/GLU
    docs may be terse, but even those are a lot better than nothing, 
    especially since you've invested a lot of time on 

    - keeping a close match (and cross links) between
        HOpenGL structure and OpenGL specs
    - translating red book examples

    so, instead of only admitting the current state of docs and pointing
    to an old (?) tutorial, why not provide the interim strategy all your users
    have followed more or less successfully: 

    1. start with opengl docs (red book and online specs)
    2. use examples to find translation of red book concepts
    3. use haddocks to find translation of spec concepts
    4. if there's anything one still can't find, ask on the mailing list, 
        which might (a) give one an answer and (b) lead to an incremental
        improvement of the docs

    oh, and link to the current haddocks for GLUT/HOpenGL (see above), 
    as well as the examples dir in GLUT cvs:

http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/libraries/GLUT/examples/

- releases page: this should all be marked as *old*, with pointers
    to cvs (cvs.haskell.org nowadays has access instructions,
    so you can point to that and the OpenGL/GLUT dirs) and ghc 
    haddocks instead

http://cvs.haskell.org
http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/libraries/OpenGL/
http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/libraries/GLUT/

- status page: i think you've done much of what you describe as
    goals here? so many of the comments on this page are misleading
    and could simply be removed.

hmm, okay, there are a few of these minor changes. but perhaps this
list will help anyway (if only because it will show up in the list archive;-)

cheers,
claus