[PyOpenGL-Devel] Building the documentation (status)

[Mike C. F. <mcf...@ro...>]

Okay, I think basically I have the build process working properly, but 
the results are... annoying.  Mozilla is able to view the resulting 
xhtml/xml pages properly (including basic MathML if you install that 
option).  Unfortunately, IE 5.5 isn't able to view the xml pages at all 
(it's complaining about the DTD AFAICS), and when simply renamed to 
.html, it can render them, but is unable to provide even the most basic 
of equation support, rendering everything as a stream of 
undifferentiated text, so the documentation is pretty hard to read for 
any sections which use equations.

As mentioned before, I haven't been able to find anything to create PNGs 
from the MathML fragments, so I am not sure there is a particularly good 
way to fix the problem.  Things I would consider fixes:

    * a free (as in root-beer), readily installable and reputable
      plug-in for IE that can handle the MathML
    * a scriptable mechanism for generating .pngs from MathML fragments
      (preferably also with automated fixing of the source documents,
      but I suppose I can do that if necessary)

Anyway, generation seems to work for HTML, XML, and HTMLHelp with just 
the reference section.  I'm currently working on splitting out the 
license section into stand-alone HTML files in the OpenGL/doc directory.

To be quite honest I don't know how Tarn ever had the patience to 
develop this little subsystem, even running it for two days has given me 
a strong and abiding hatred of all things XML.  On the plus side, the 
xhtml documents generated by the newer docbook-xsl system are much 
cleaner-looking than the old documents (in Mozilla).  I've also done 
some minor modifications to the style sheet to make the reference 
harmonize somewhat with the PyOpenGL and OpenGLContext web sites.

Enjoy yourselves,
Mike

_______________________________________
  Mike C. Fletcher
  Designer, VR Plumber, Coder
  http://members.rogers.com/mcfletch/