Part of the Khronos Group
OpenGL.org

The Industry's Foundation for High Performance Graphics

from games to virtual reality, mobile phones to supercomputers

Page 1 of 2 12 LastLast
Results 1 to 10 of 16

Thread: Man pages source available in Khronos Subversion

  1. #1
    Administrator Contributor
    Join Date
    Jan 2002
    Location
    Mt. View, CA
    Posts
    97

    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/og...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/og...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_s..._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_s...TML_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.
    Jon Leech
    Khronos API Registrar
    ARB Ecosystem TSG Chair
    GL/EGL/GLES Spec Editor
    ...and suchlike

  2. #2
    Intern Contributor
    Join Date
    Nov 2007
    Posts
    72

    Re: Man pages source available in Khronos Subversion

    nice, thanks for info

  3. #3
    Member Regular Contributor
    Join Date
    Oct 2006
    Posts
    352

    Re: Man pages source available in Khronos Subversion

    Thanks, this is great!
    [The Open Toolkit library: C# OpenGL 4.4, OpenGL ES 3.1, OpenAL 1.1 for Mono/.Net]

  4. #4

    Re: Man pages source available in Khronos Subversion

    Thanks Jon and Khronos, much appreciated.

  5. #5
    Senior Member OpenGL Guru
    Join Date
    Mar 2001
    Posts
    3,576

    Re: Man pages source available in Khronos Subversion

    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.

  6. #6
    Junior Member Newbie
    Join Date
    Jan 2008
    Posts
    9

    Re: Man pages source available in Khronos Subversion

    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.

  7. #7
    Senior Member OpenGL Pro
    Join Date
    Sep 2004
    Location
    Prombaatu
    Posts
    1,386

    Re: Man pages source available in Khronos Subversion

    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.

  8. #8
    Junior Member Newbie
    Join Date
    Jan 2008
    Posts
    9

    Re: Man pages source available in Khronos Subversion

    >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

    screen shot (scroll half down)
    https://netbeans-opengl-pack.dev.jav...tProcess?tab=1

  9. #9
    Senior Member OpenGL Pro
    Join Date
    Sep 2004
    Location
    Prombaatu
    Posts
    1,386

    Re: Man pages source available in Khronos Subversion

    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.

  10. #10
    Administrator Contributor
    Join Date
    Jan 2002
    Location
    Mt. View, CA
    Posts
    97

    Updated SGI FreeB license

    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.
    Jon Leech
    Khronos API Registrar
    ARB Ecosystem TSG Chair
    GL/EGL/GLES Spec Editor
    ...and suchlike

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •