[Glsdk-devel] Problems with glm documentation

[Jason M. <ko...@gm...>]

The documentation we have for the math library is not valid DocBook.

First, the root element of any DocBook v5.0 document must have a "version"
attribute set to "5.0". It also must use the DocBook namespace. So the root
element should look like:

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">

Second, "refsynopsisdiv" does not directly contain "funcprototype". It
contains one or more "funcsynopsis", which can contain one or more
"funcprototype". And if you have multiple prototypes for the same function,
they should go into the same "funcsynopsis".

Third, don't use any of the "sect1", "sect2", etc divisions. Even the "ref"
versions. These are hold-overs from the days of SGML and DSSSL; it is almost
always better to use general "section" and "refsection" elements. These can
be nested infinitely.

Fourth, "refsection" elements don't mean what you think they do. A
"refsection" is just a block of text with a title. Elements like "param"
cannot be used there.

Fifth, for ease-of-use purposes, you should give all "refentry" elements an
xml:id attribute value that is unique. I suggest something like: "ref_glm_*"
where * is the name of the function without the glm prefix (and without the
InterCaps naming, instead using "_" as word separators). This will allow
tutorials and other documentation to directly reference HTML pages referring
to that function.

As an example, I took your documentation for glmDegToRadf and fixed it:

<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng"
type="xml"?>
<?oxygen SCHSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng"?>
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="ref_glm_deg_to_rad_f">
  <refnamediv>
    <refname>glmDegToRadf</refname>
    <refpurpose>Converts angles in degrees to radians</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
      <funcsynopsis>
          <funcprototype>
              <funcdef>GLfloat <function>glmDegToRadf</function></funcdef>
              <paramdef>GLfloat <parameter>degrees</parameter></paramdef>
          </funcprototype>
      </funcsynopsis>
  </refsynopsisdiv>


  <refsection>
      <title>Description</title>
      <para>This function takes the parameter
<parameter>degrees</parameter>, representing an angle
          in degrees, and converts it to radians.</para>
  </refsection>
</refentry>

Appropriate reference material for DocBook is available here:
http://www.docbook.org/tdg5/en/html/docbook.html. Only look at the reference
section; the manual parts are old, from DocBook v4.