[PyOpenGL-Users] PyOpenGL Documentation, Ports & Future Features

[Tarn W. B. <twb...@ma...>]

Just thought I'd update everyone on a few PyOpenGL issues.

First if you've visited the PyOpenGL documentation page at
http://pyopengl.sourceforge.net/documentation/ you may have noticed that the
PyOpenGL2 User's manual is a bit different from the one with the latest
distribution.  Two sections have been added: a "reference" section and a
"ports" section.

The reference section is an outgrowth of an idea that Mike had about
creating an integrated set of manpages which had the Python function
prototypes listed in addition the to C prototypes.  The proof of concept
that he originally created used some OpenGL 1.1 HTML manpages created by
SGI.  After some discussions with SGI it became clear that marking up the
HTML source with our own local notes was probably not going to work in the
long run since these sources were out of date and producing new versions was
difficult at best.  SGI also expressed an interest in converting the
original manpage source to a more modern format, probably some kind XML
format.  So on a lark I whipped up a Python script to convert the manpages
into DocBook XML, which is the format that the PyOpenGL manual is in.  I've
spun that effort off as the man2dbk project at http://man2dbk.sf.net

man2dbk is far from complete, but it is complete enough for the more
immediate task of converting the GL, GL, GLUT and GLE manpages.  I've done
this and the results are now in the "reference" section of the manual.  Alot
of work remains to be done on this section, namely the rather tedious final
formatting and addition of Python notes, but visible progress is being made.

These manpages are based on OpenGL 1.2 and contain a fair number of
equations.  For DocBook and HTML this ends up meaning that MathML is needed.
Right now only Amaya and Mozilla support MathML natively.  For these
browsers the web server will deliver XHTML pages with MathML.  For all other
browsers the web server will deliver HTML pages with inline images.  Note
that the standard distribution of Mozilla does not include MathML and since
there is no way for the web server to tell which version of Mozilla is
requesting a page it just always assumes that Mozilla is MathML enabled.
For more information on Mozilla MathML support see
http://www.mozilla.org/projects/mathml/   For more information on Amaya see
http://www.w3.org/Amaya/

As mentioned before, I've added a "ports" section to the manual which
attempts to list all the current ports of PyOpenGL and any specific building
or installation notes which pertain to each port.  This section woefully
incomplete at the present time, but its a start.  If anyone has information
on any other platforms which are not listed or more notes for listed
platforms please drop me a line.  I'd like to see this list become as
complete as possible.  Along with the status of ongoing ports and platform
specific notes I've also included the entries "maintainer" and "verified by"
If you've compiled PyOpenGL successfully on a platform than please tell me
so that at least I can indicate this with the "verified by" entry.  I'm also
looking for platform maintainers so we can make sure that new versions
PyOpenGL run on existing platforms.

Now as to future directions of PyOpenGL.  The PyOpenGL SF project page has
various item trackers, one of which is a feature request tracker.  I
encourage people to submit items to this list or make comments on the
existing items.  Although it is far to early to make statements about what
new features will be in 2.1, the following items are, in my mind, of top
priority:

1) integrated manpages
2) OpenGL 1.2 & 1.3 support
3) Mac port

Comments are welcome.  Note that the Mac port is currently stalled since
PyOpenGL setup requires the ability to compile executables, not just
dynamic/static libs.  I've talked to a few people about this but I haven't
heard any word about progress yet.  Fixing this involves adding some
capabilities to distutils.mwerkscompiler.  I can provide more details to
anyone who is interested.

thanks all,
Tarn