Man pages source available in Khronos Subversion

Khronos has released the OpenGL man page XML sources. This was done mostly at the request of people wishing to adapt the man pages to other output formats or language bindings.

You will need to have a reasonable understanding of Subversion, Docbook, XML, XSLT, Linux package management (if using Linux), and other components of the toolchain used to generate the man pages, before you’re likely to have much success with them. A great deal of Docbook, XML, and XSL infrastructure may need to be installed on your system
first.

The directory tree containing the current (OpenGL 4.x) API man pages is available for anonymous, read-only checkout in Khronos’ Subversion server, at

[https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/man4/](https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/man4/)

If you have the Subversion command-line client installed, you should be able to check out the man pages into the directory ‘man4’ by executing the command

svn co --username anonymous --password anonymous [https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/man4/](https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/man4/) man4

Under ‘man4’ you’ll find the OpenGL 4.2 man pages, both the Docbook XML source in this directory and generated XHTML+MathML in xhtml/ , and some supporting build and XSL infrastructure.

There are several other directories parallel to man4/ which may also be of interest:

  • man3 - OpenGL 3.x API man pages
  • man - OpenGL 2.1 API man pages
  • manglsl - OpenGL Shading Language man pages
  • mancommon - common infrastructure used by all the other man* directories

These can be checked out from Subversion using a similar ‘svn co’ command but replacing man4 with the corresponding directory name.

There are two files in the OpenGL.org Wiki containing additional documentation:

http://www.opengl.org/wiki/Getting_started/XML_Toolchain_and_Man_Pages

  • Description of the tools used to build the man pages; how to install and make use of them if you want to build them yourself; and how to report problems.

http://www.opengl.org/wiki/Getting_started/Viewing_XHTML_and_MathML

  • Some notes on viewing XHTML+MathML documents in different browsers.

Please read both the Wiki pages above completely and try doing what they suggest before asking for help. If you’re only having setup problems (as opposed to finding actual bugs in the man pages), you should probably post in this thread where other people may be having the same problems.

nice, thanks for info

Thanks, this is great!

Thanks Jon and Khronos, much appreciated.

This is pretty interesting. However, there is something odd in the files.

"<!DOCTYPE book PUBLIC “-//OASIS//DTD DocBook MathML Module V1.1b1//EN”
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd"&gt;" is prefaced at the beginning of all of your files. That’s all well and good, but the DOCTYPE’s first parameter is the root element of this particular document. And virtually none of them start with the element “book”. While the document is still well-formed by the rules of XML, it means that the document is considered invalid by a strict XML DTD validator.

thats great, but the GLSL doc converted into XML would be even better since most GL.next code will be in shaders anyway this would allow better IDE integration.

Thing is the GLSL doc is actually a implementation specification, so it probably doesn’t make as much sense to XML-ize it like regular user documentation.

>Thing is the GLSL doc is actually a implementation specification

Yes, but is this a problem? It covers everything and explains every function/token, restructure it to anything… well structured :wink: and we have a pretty decent machine indexable doc.

Integrating it into an IDE is trivial (at least in java land, i don’t know “the other side” good enough to speak for them)

I converted around 1 year ago parts of the spec to xml, it covers all token/functions but only around 30% of them are documented.

https://netbeans-opengl-pack.dev.java.ne…2Fplain&rev=446

screen shot (scroll half down)
https://netbeans-opengl-pack.dev.java.net/servlets/ProjectProcess?tab=1

My hunch is that it would be as easy or easier to just generate new content in documentation format as it would be to reformat existing specifications. Plus there may be some benefit in rewording some of the spec language, to make it more easily digestible by those new to OpenGL.

SGI has updated their FreeB license, which applies to many of the man pages Khronos distributes. Version 2.0 of FreeB is just an X11/MIT-style license.

This doesn’t have any substantive effect on the man pages - and they don’t even need to be changed to take advantage of it, since they incorporate the FreeB license by reference - but it does make it more convenient for people with a strong FSF/Debian-style Free Software stance to modify and/or distribute those man pages.

Absolutely amazing. Although I agree it won’t pass a strict xml test, where are you gonna find one of those nowadays? Thanks again.

Where would one go to find the man pages for the GLSL, 3.3, and 4.1 repositories?

OpenGL 3.3 seems to be https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/man3/
and 4.1 https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/man4/
I just dont know if they are open to anonymous user on purpose…
Analogicaly I guess GLSL would be manglsl subdirectory, but this one is not open…

Got my interest (I’d like updated Linux man pages) so I grabbed them and browsed. In here:

man3/docs/XML_Toolchain_and_Man_Pages.html

says:

"This document has been moved to the public OpenGL.org Wiki at http://www.opengl.org/wiki/index.php/Getting_started/XML_Toolchain_and_Man_Pages#Toolchain "

That’s a dead link, but the apparent correct link is:

http://www.opengl.org/wiki/Getting_started/XML_Toolchain_and_Man_Pages

which says its intentional. In the svn command, just change the end from “sdk/docs/man/ man” to “sdk/docs/man3/ man3” (or man4).

HOWEVER, that the GLSL man pages aren’t fetchable by everyone does seem like an oversight/bug:


> svn co --username anonymous --password anonymous https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/manglsl/ manglsl
svn: Server sent unexpected return value (403 Forbidden) in response to OPTIONS request for 'https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/manglsl'

We’ve opened up the directories containing GLSL (manglsl/) and common utility files (mancommon/) for anonymous SVN access as well - sorry for the oversight. The first post in this thread has been updated with the details and valid Wiki links as well.

(Now I just need to get my Wiki login fixed so I can update the Wiki pages themselves :slight_smile:

Thanks, Jon!