Re: [PyOpenGL-Devel] Building the documentation (status)

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

Well, I think I have a partial solution, but it's one of those "I have 
no idea what Tarn did, but it does seem to work" things.  From what I 
can see, there must be an Apache rewrite or rule that's making the 
"manual" directory on the web-server rewrite requests from Mozilla for 
.html pages to get the .xml pages, while IE gets the .html pages.

I've reworked the post-processing so that MathPlayer is thunked into 
instantiating on the .html files, and nothing is changed for the XML 
files.  That works for Mozilla and IE 5.5 w/ MathPlayer (I assume also 
IE 6.0 w/ MathPlayer).  Still have no way to generate PNG images, so 
nothing yet to support browsers that don't know MathML *and* don't 
support MathPlayer.  Sigh.

You can try it out by browsing to the following URL:
    http://pyopengl.sourceforge.net/documentation/manual/glRotate.3G.html
Better solutions welcome.

Okay, I'm tired and off to bed, have fun all,
Mike

Mike C. Fletcher wrote:

> Okay, apparently the only somewhat-usable MathML viewer for IE is this 
> one:
> http://www.dessci.com/en/products/mathplayer/
>
> Supporting it would require some annoying thunkery (basically adding 
> an object tag and a *processing instruction* (of all things) to the 
> head of all documents with MathML), but I may wind up doing just that 
> if nothing better comes along.
>
> Licenses are now broken out to their own (single) HTML page in the 
> OpenGL/doc directory.  The extraneous reference to the SGI license has 
> been removed (with explanation for that in the HTML page).
>
> Enjoy yourselves,
> Mike
>
> Mike C. Fletcher wrote:
>
>> 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.
>>
...

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