From: H. H. <hen...@gm...> - 2008-08-29 23:17:45
|
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 |