upstream-doc/man3/README.txt

   1 Khronos has released the OpenGL man page XML sources. This was done
   2 mostly at the request of people wishing to adapt the man pages to other
   3 output formats or language bindings.
   4
   5 You will need to have a reasonable understanding of Subversion, Docbook,
   6 XML, XSLT, Linux package management (if using Linux), and other
   7 components of the toolchain used to generate the man pages, before
   8 you're likely to have much success with them. A great deal of Docbook,
   9 XML, and XSL infrastructure may need to be installed on your system
  10 first.
  11
  12 The directory tree containing the man pages is available for anonymous,
  13 read-only checkout in Khronos' Subversion server, at
  14
  15     https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/man/
  16
  17 If you have the Subversion command-line client installed, you should be
  18 able to check out the man pages into the directory 'man' by executing
  19 the command
  20
  21     svn co --username anonymous --password anonymous https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs/man/ man
  22
  23 Under 'man' you'll find the OpenGL 2.1 man pages, both the Docbook XML
  24 source in this directory and generated XHTML+MathML in xhtml/ , and some
  25 supporting build and XSL infrastructure. There are two files in the
  26 OpenGL.org Wiki containing additional documentation:
  27
  28 http://www.opengl.org/wiki/index.php/Getting_started/XML_Toolchain_and_Man_Pages#Toolchain
  29   - Description of the tools used to build the man pages; how to install
  30     and make use of them if you want to build them yourself; and how to
  31     report problems.
  32
  33 http://www.opengl.org/wiki/index.php/Getting_started/Viewing_XHTML_and_MathML
  34   - Some notes on viewing XHTML+MathML documents in different browsers.
  35
  36 ------------------------------------------------------------------
  37
  38 Special note on DTDs: the normal Docbook build process generates a
  39 DOCTYPE header with references to the DTD
  40
  41     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
  42
  43 While in principle this is only a namespace identifier, Internet
  44 Explorer nonetheless downloads the DTD, and the entity files referenced
  45 from within it, on every page loaded. This contributes to creating
  46 unacceptable load on www.w3.org, and the IE user agent has been blocked
  47 for these URLs. Ideally Microsoft would fix IE, but in the meantime, the
  48 only workaround within our control is to cache copies of the DTD and
  49 entity files locally in the generated xhtml/ directory and postprocess
  50 the generated XHTML to refer to them. This explains the presence of the
  51 files
  52
  53     xhtml/xhtml1-transitional.dtd
  54     xhtml/xhtml-lat1.ent
  55     xhtml/xhtml-special.ent
  56     xhtml/xhtml-symbol.ent