[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Public WebGL] WebGL Reference Pages

On 12/08/13 19:15, Benoit Jacob wrote:
On the one hand, we have markup language that make it easy to write documents. On the other hand we have XML which gives automation but is a pain to write by hand. The only document writing system that combines convenient markup with good large-document-structuration-and-automation features, that I know of, is LaTeX. From the looks of the OpenGL [ES] PDF spec, it seems that it's made in LaTeX, for example (maybe someone can confirm). But compared to a wiki, this will increase the barrier to entry quite a bit.
I don't think enabling trivial modifications at the expense of creating an immense amount of manual labor is the right trade-off.

The OpenGL {,ES} specifications are done in LaTeX.

The man pages are done in docbook and writing or editing those is no harder than html. The entry barrier comes in previewing the result as you need various docbook tools and available Unix-like make and scripting to generate the xhtml output. But we could probably run a post-commit script that rebuilds the man pages either on github or khronos.org.

It should also be possible to get the xml source to display directly in some (most) browsers. Currently the files do not reference the necessary xsl files though. Then we just need a server that allows the pages to be edited.

"The Docbook XML source for the OpenGL man pages is available for anonymous checkout in Khronos' Subversion server, and you can build a man page distribution of your own using open source tools. See the OpenGL.org technical Wiki pages describing the XML Toolchain and Man Pages for more information. " says the intro page of the man pages on opengl.org.

The URL is
If you look in e.g., man4 for example, you can see the source xml files. The output files are in, e.g., man4/xhtml.

I expect we can persuade Khronos to make the OpenGL ES man page sources similarly available possibly even on github.

On 12/08/14 10:16, Chris Marrin wrote:

Currently, the IDL file is extracted from the spec (see https://github.com/KhronosGroup/WebGL/blob/master/specs/latest/extract-idl.py). Seems like the text for man pages could be similarly extracted. This might involve tagging additional elements in the spec, or adding some hidden elements with additional data. Then maybe the simplest thing to do would be to add this text to the IDL in Doxygen format so we can use those tools to generate various formats of man pages?

If it wasn't for the issue that a lot of information will be duplicated between this and the OpenGL ES man pages and the related issue that the WebGL spec is not a complete standalone specification, I'd say go for it.