PDA

View Full Version : Man pages source available in Khronos Subversion



Jon Leech (oddhack)
09-12-2008, 04:20 PM
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/

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/ 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.

dor00
09-12-2008, 11:41 PM
nice, thanks for info

Stephen A
09-13-2008, 06:01 AM
Thanks, this is great!

Mike C. Fletcher
09-13-2008, 03:27 PM
Thanks Jon and Khronos, much appreciated.

Korval
09-13-2008, 08:05 PM
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">" 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.

mbien
09-15-2008, 08:43 AM
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.

Brolingstanz
09-15-2008, 09:26 AM
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.

mbien
09-16-2008, 09:24 AM
>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 ;) 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 (https://netbeans-opengl-pack.dev.java.net/source/browse/*checkout*/netbeans-opengl-pack/trunk/glsl-editor/src/net/java/nboglpack/glsleditor/resources/GlslVocabulary.xml?content-type=text%2Fplain&rev=446)

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

Brolingstanz
09-16-2008, 10:06 AM
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.

Jon Leech (oddhack)
09-19-2008, 01:41 PM
SGI has updated their FreeB license (http://www.sgi.com/company_info/newsroom/press_releases/2008/september/opengl.html), 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.

canada87
06-02-2011, 12:01 PM
Absolutely amazing. Although I agree it won't pass a strict xml test, where are you gonna find one of those nowadays? Thanks again.

Alfonse Reinheart
06-02-2011, 12:09 PM
Where would one go to find the man pages for the GLSL, 3.3, and 4.1 repositories?

krOoze
06-10-2011, 08:29 AM
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...

Dark Photon
06-10-2011, 10:25 AM
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...
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'

Jon Leech (oddhack)
09-01-2011, 03:59 AM
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 :-)

Dark Photon
09-01-2011, 05:41 PM
Thanks, Jon!