glsdk-devel

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

Re: [Glsdk-devel] Problems with glm documentation

[H. H. <hen...@gm...>]

Thanks I will fix this.

On Sat, Aug 30, 2008 at 2:02 AM, Jason McKesson <ko...@gm...> wrote:

> 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.
>
>
-- 
Henri 'henux' Häkkinen

Re: [Glsdk-devel] Problems with glm documentation

[H. H. <hen...@gm...>]

On Sat, Aug 30, 2008 at 2:02 AM, Jason McKesson <ko...@gm...> wrote:

>
> 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".
>
>
So I have have glmVecSet2f, 3f and 4f, should I put them into the same or
separate 'funcsynopsis' elements?

-- 
Henri 'henux' Häkkinen

Re: [Glsdk-devel] Problems with glm documentation

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

On Fri, Aug 29, 2008 at 4:25 PM, Henri Häkkinen <hen...@gm...> wrote:

> On Sat, Aug 30, 2008 at 2:02 AM, Jason McKesson <ko...@gm...> wrote:
>
>>
>> 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".
>>
>>
> So I have have glmVecSet2f, 3f and 4f, should I put them into the same or
> separate 'funcsynopsis' elements?
>
> --
> Henri 'henux' Häkkinen
>

The same.

Re: [Glsdk-devel] Problems with glm documentation

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

BTW, something more, depending on what you use to write your files.

There is an "nXML mode" plugin for emacs available that provides syntax
competition and verification for any XML format that has a RELAX NG schema
for it. And DocBook has such (nXML mode comes with one, but I don't know if
it comes with one for v5.0) that can be found as part of the DocBook
distribution here: http://www.docbook.org/xml/5.0/. I've always found that
one of the best ways to find out what DocBook can do is to let
content-completion guide your elements.

Also, xmllint is a commandline tool that can be used to verify that an XML
file conforms to a particular schema (it supports RELAX NG and a few
others). It's error reporting is... somewhat lacking (often, the actual
problem element will be not quite in the place it points to, much like C/C++
errors), but it can be useful for detecting problems.

Re: [Glsdk-devel] Problems with glm documentation

[H. H. <hen...@gm...>]

Could you do or instruct me how to do a sort of index page that would list
each GLM API entry-point with a link to the correct page?

On Sat, Aug 30, 2008 at 3:05 AM, Jason McKesson <ko...@gm...> wrote:

> BTW, something more, depending on what you use to write your files.
>
> There is an "nXML mode" plugin for emacs available that provides syntax
> competition and verification for any XML format that has a RELAX NG schema
> for it. And DocBook has such (nXML mode comes with one, but I don't know if
> it comes with one for v5.0) that can be found as part of the DocBook
> distribution here: http://www.docbook.org/xml/5.0/. I've always found that
> one of the best ways to find out what DocBook can do is to let
> content-completion guide your elements.
>
> Also, xmllint is a commandline tool that can be used to verify that an XML
> file conforms to a particular schema (it supports RELAX NG and a few
> others). It's error reporting is... somewhat lacking (often, the actual
> problem element will be not quite in the place it points to, much like C/C++
> errors), but it can be useful for detecting problems.
>
> -------------------------------------------------------------------------
> This SF.Net email is sponsored by the Moblin Your Move Developer's
> challenge
> Build the coolest Linux based applications with Moblin SDK & win great
> prizes
> Grand prize is a trip for two to an Open Source event anywhere in the world
> http://moblin-contest.org/redirect.php?banner_id=100&url=/
> _______________________________________________
> Glsdk-devel mailing list
> Gls...@li...
> https://lists.sourceforge.net/lists/listinfo/glsdk-devel
>
>


-- 
Henri 'henux' Häkkinen

Re: [Glsdk-devel] Problems with glm documentation

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

That's the great thing about DocBook: you don't need an index. Or 
rather, you don't need an explicit one.

I arranged the documentation in a very specific way. In the root of the 
docs folder is a single, short document called 
"glsdk_documentation.xml." All it is is a series of <xi:include> 
elements. These are very special XML elements; what they do is cause the 
referenced XML file to be included in this document at that location, as 
though the document in question were written there. And those documents 
will include other parts. What this means is that essentially, all our 
documentation gets put into one huge file that gets processed as a block.

There is a file in the docs/reference directory called 
"sdk_reference.xml". I have just checked in a change to this file that 
includes the file, "docs/reference/glm.xml". That file should be a 
gigantic list of <xi:include> entries that include every other .xml file 
in that directory. It might even be a good idea to write a simple script 
to automatically generate this file. I'll include a few includes as 
examples.

The process of generating documentation will take care of creating a 
table of contents and so forth.

Henri Häkkinen wrote:
> Could you do or instruct me how to do a sort of index page that would 
> list each GLM API entry-point with a link to the correct page?