Menu
▾
▴
glsdk-devel — Main development list for the OpenGL SDK
You can subscribe to this list here.
| 2008 |
Jan
|
Feb
|
Mar
|
Apr
|
May
|
Jun
|
Jul
|
Aug
(248) |
Sep
(51) |
Oct
(9) |
Nov
(3) |
Dec
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2009 |
Jan
|
Feb
(1) |
Mar
|
Apr
|
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
(1) |
Nov
|
Dec
|
|
From: Branan R. <br...@gm...> - 2008-09-03 01:53:33
|
I should have been more specific. When we'll need to have converted the DocBook sources into HTML, PDF, or whatever we decide on. Do we want to have this system in place before the pre-alpha release, or can it wait? On Tue, Sep 2, 2008 at 6:46 PM, Jason McKesson <ko...@gm...> wrote: > As far as documentation is concerned, I'm not aware that we have a doc > generator at all. What does it generate and how does it pick the source > files? |
|
From: Jason M. <ko...@gm...> - 2008-09-03 01:47:31
|
We can give it a shot. If we don't like it, we can just shut it off later. On Tue, Sep 2, 2008 at 1:14 PM, Branan Riley <br...@gm...> wrote: > Would anyone here find it useful it we started using the SF.net task > tracker to help manage our TODO lists? If so I'd like a list of TODOs > from everyone (not necessarily just on their own projects), and I'll > set it up. If not I'm going to just disable the task tracker. > > Branan |
|
From: Jason M. <ko...@gm...> - 2008-09-03 01:46:34
|
On GLE, I have some of the code generation stuff done. Headers containing enums are generated (and checked into SVN). I'm still working on the function loading. As far as documentation is concerned, I'm not aware that we have a doc generator at all. What does it generate and how does it pick the source files? On Tue, Sep 2, 2008 at 12:32 PM, Branan Riley <br...@gm...> wrote: > I'd like to take a moment to see where we are on creating a pre-alpha > release that tutorials and examples can be written against. I'd like > as much feedback as possible on this, so we really know where we > stand. > > GLM: A few functions aren't working yet; documentation in progress; OK > for an early release > GLS: Cube and Teapot nearly done (not yet in SVN); needs a > GL3-compatible drawing function (not difficult); OK for an early > release once all that is comitted > GLE: I have no idea. This one is important though > GLFW: Has support for GL3 on windows. Needs to be integrated with our > buildsystem > DOC: We need a doc generator in SVN that will work on Windows > eventually. For now I think we can generate the docs on Linux, or just > have Korval do it; I guess OK for an early release > > > Also, I'm taking votes on whether I should integrate GLFW or finish > GLS first. I don't really care either way, though I think GLFW > integration is more important towards getting a base platform that > tutorials can be written against. > |
|
From: Jason M. <ko...@gm...> - 2008-09-03 01:41:10
|
I'm not sure what the right way to handle this is. However, I can give one explaination for choosing C over C++. Nobody agrees on what is the best style for writing C++. I don't mean irrelevant things like where braces go or naming conventions. I mean complicated things: - When to use inheritance instead of containment. - The use of Resource Acquisition Is Initialization. - The use of exceptions. - The use of Pimpl. - How much templating to use. - How much operator overloading to use. I have my own ideas about what good C++ style is. I like them, and I have a pretty good defense of them. I even have a rarely-updated Blog about what I consider to be good C++ coding style. But programmers are a very, VERY picky lot. C++ programmers are pickier than most, because choosing a library that clashes with your preferred coding style is very painful. If you're not using exceptions and RAII, trying to use a library that does can be nightmarish. The takehome point being this: C isn't nice. It isn't as clean as C++ can be. But it's *standard*. Everyone knows what good C code looks like. Everyone understands it, even if things like "typedef struct" are confusing to C++ programmers. And it will never hurt you the way that using exceptions when your user doesn't want to will. On Tue, Sep 2, 2008 at 2:37 PM, Branan Riley <br...@gm...> wrote: > We're getting a lot of flac for choosing C over C++, especially now > that people have had a chance to see the math library. I still think C > was the right decision, but it's very hard to convince everyone of > this. C gives beter access to under-the-hood stuff for the curious > neophyte than a complicated C++ class/template library would. > > We should, however, better articulate our reasons for choosing C, and > get a better answer on the subject in the FAQ. The current answer just > won't cut it in the long term, especially since C is percieved as an > old, crusty language by many (Knackered's comments in the forum thread > illustrate this quite vividly). > > Any thoughts on how we should handle this would be appreciated. I may > be the de facto PR guy, but that doesn't mean I'm actually any good at > PR :-P > > Branan |
|
From: H. H. <hen...@gm...> - 2008-09-03 01:28:05
|
Hello all, I have been away from this project for few days now. There are things happening in my 'real life' that needs my attention and I will have less time to contribute. However, I am still with you and I hope I have time to contribute every now and then. The mathlib is 'almost' ready; few functions need fixing and documentations written, but despite these, the mathlib is intact. What goes beyond the mathlib and my involvement with the SDK is still open. I don't have a GL3 class hardware so it's a little troublesome for me to contribute with the actual tutorials. And about the C issue: There is not much to say in this matter as the choice of language is also a personal opinion of people. I myself am a fan of C language (due to it's simplicity) so choosing C for the GLM was a natural choice for me. -- Henri 'henux' Häkkinen |
|
From: Branan R. <br...@gm...> - 2008-09-02 22:03:00
|
That's a difference in how CMake assumes libraries are named on Windows and Linux. on Linux, it's lib<name>.a on Windows, it's <name>.lib so on Windows, it needs to link against "libcunit" rather than just "cunit". This is actually CUnit's fault, not ours - It doesn't follow the standard naming conventions across platforms. Branan On Tue, Sep 2, 2008 at 2:58 PM, Orhun Birsoy <orh...@gm...> wrote: > the first two glm warnings are due to M_PI usage. It has to be cast to float. > the last glm warning is due to use of tan(). tanf() should have been used. > > I've already build the tests before, just not lately. I have CUnit is > already on my home machine. I am at work, I don't have CUnit here. > > Note that, under windows I had to change several build settings to > build the tests. I don't exactly remember but the library name was not > what glsdk was trying to link with. I think the CUnit Visual Studio > project generated "libcunit.lib" and glsdk was trying to link with > cunit.lib. I can provide a better explanation when I have access to my > home machine. > > -- > Orhun Birsoy > > ------------------------------------------------------------------------- > 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 > |
|
From: Orhun B. <orh...@gm...> - 2008-09-02 21:58:08
|
the first two glm warnings are due to M_PI usage. It has to be cast to float. the last glm warning is due to use of tan(). tanf() should have been used. I've already build the tests before, just not lately. I have CUnit is already on my home machine. I am at work, I don't have CUnit here. Note that, under windows I had to change several build settings to build the tests. I don't exactly remember but the library name was not what glsdk was trying to link with. I think the CUnit Visual Studio project generated "libcunit.lib" and glsdk was trying to link with cunit.lib. I can provide a better explanation when I have access to my home machine. -- Orhun Birsoy |
|
From: Branan R. <br...@gm...> - 2008-09-02 21:44:56
|
Those warnings are probably just from missing 'f's on floating-point constants. Easy enough to fix. The "unknown pragma" in gls.c got committed by accident. I was trying to make GCC silence a warning that's not going to actually matter anymore. That will go away with my next commit. You can build the tests if you want. Make sure you have CUnit installed in a location that your vcvars.bat will pick up, otherwise it'll fail miserably. On Tue, Sep 2, 2008 at 2:40 PM, Orhun Birsoy <orh...@gm...> wrote: > It builds with Visual Studio 2008. I am getting the following warnings... > 2>..\..\..\glsdk\src\glm\angles.c(32) : warning C4244: 'return' : > conversion from 'double' to 'GLfloat', possible loss of data > 2>..\..\..\glsdk\src\glm\angles.c(38) : warning C4244: 'return' : > conversion from 'double' to 'GLfloat', possible loss of data > 2>..\..\..\glsdk\src\glm\mat4f.c(535) : warning C4244: '=' : > conversion from 'double' to 'GLfloat', possible loss of data > > 2>..\..\..\glsdk\src\gls\gls.c(27) : warning C4068: unknown pragma > > I didn't build the test, which I can try building (and running) it > tonight, and report back. > > -- > Orhun Birsoy > > ------------------------------------------------------------------------- > 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 > |
|
From: Orhun B. <orh...@gm...> - 2008-09-02 21:40:15
|
It builds with Visual Studio 2008. I am getting the following warnings... 2>..\..\..\glsdk\src\glm\angles.c(32) : warning C4244: 'return' : conversion from 'double' to 'GLfloat', possible loss of data 2>..\..\..\glsdk\src\glm\angles.c(38) : warning C4244: 'return' : conversion from 'double' to 'GLfloat', possible loss of data 2>..\..\..\glsdk\src\glm\mat4f.c(535) : warning C4244: '=' : conversion from 'double' to 'GLfloat', possible loss of data 2>..\..\..\glsdk\src\gls\gls.c(27) : warning C4068: unknown pragma I didn't build the test, which I can try building (and running) it tonight, and report back. -- Orhun Birsoy |
|
From: Branan R. <br...@gm...> - 2008-09-02 21:36:57
|
We're getting a lot of flac for choosing C over C++, especially now that people have had a chance to see the math library. I still think C was the right decision, but it's very hard to convince everyone of this. C gives beter access to under-the-hood stuff for the curious neophyte than a complicated C++ class/template library would. We should, however, better articulate our reasons for choosing C, and get a better answer on the subject in the FAQ. The current answer just won't cut it in the long term, especially since C is percieved as an old, crusty language by many (Knackered's comments in the forum thread illustrate this quite vividly). Any thoughts on how we should handle this would be appreciated. I may be the de facto PR guy, but that doesn't mean I'm actually any good at PR :-P Branan |
|
From: Branan R. <br...@gm...> - 2008-09-02 20:28:39
|
Has anyone been building the SDK on Windows lately? Is it still compiling? The code should all work from what I've seen, but I'd like some confirmation of that. I can cross-compile it with MinGW and/or build it in my VM, if a test is needed. Branan |
|
From: Branan R. <br...@gm...> - 2008-09-02 20:14:14
|
Would anyone here find it useful it we started using the SF.net task tracker to help manage our TODO lists? If so I'd like a list of TODOs from everyone (not necessarily just on their own projects), and I'll set it up. If not I'm going to just disable the task tracker. Branan |
|
From: Branan R. <br...@gm...> - 2008-09-02 19:32:22
|
I'd like to take a moment to see where we are on creating a pre-alpha release that tutorials and examples can be written against. I'd like as much feedback as possible on this, so we really know where we stand. GLM: A few functions aren't working yet; documentation in progress; OK for an early release GLS: Cube and Teapot nearly done (not yet in SVN); needs a GL3-compatible drawing function (not difficult); OK for an early release once all that is comitted GLE: I have no idea. This one is important though GLFW: Has support for GL3 on windows. Needs to be integrated with our buildsystem DOC: We need a doc generator in SVN that will work on Windows eventually. For now I think we can generate the docs on Linux, or just have Korval do it; I guess OK for an early release Also, I'm taking votes on whether I should integrate GLFW or finish GLS first. I don't really care either way, though I think GLFW integration is more important towards getting a base platform that tutorials can be written against. |
|
From: Branan R. <br...@gm...> - 2008-09-02 14:39:18
|
Awesome! If the ARB doesn't get their act together soon, I might end up putting a Windows partition back on my computer so I can work on GL3 stuff. I'm rapidly running out of excuses. Branan On Tue, Sep 2, 2008 at 6:06 AM, Camilla Berglund <cam...@gm...> wrote: > Hullo everyone, > > If I've missed some recent development making GLFW off-topic for this > list, then I'm sorry and you can ignore this. > > I've added partial WGL_ARB_create_context support to my personal > 2.x-lite branch[1] of GLFW, enough that you should be able to create > forward-compatible contexts. I don't have any means of testing this, > however. Feedback with and without patches is very welcome. > > [1] https://glfw.svn.sourceforge.net/viewvc/glfw/branches/2.x-lite/ > > Note that this branch uses CMake and lacks the deprecated thread, > texture, image and sleep support. I believe that, at least for now, > it's the branch most appropriate for GLSDK to use. > > Regards, > elmindreda (GLFW developer) > > ------------------------------------------------------------------------- > 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 > |
|
From: Camilla B. <cam...@gm...> - 2008-09-02 13:06:30
|
Hullo everyone, If I've missed some recent development making GLFW off-topic for this list, then I'm sorry and you can ignore this. I've added partial WGL_ARB_create_context support to my personal 2.x-lite branch[1] of GLFW, enough that you should be able to create forward-compatible contexts. I don't have any means of testing this, however. Feedback with and without patches is very welcome. [1] https://glfw.svn.sourceforge.net/viewvc/glfw/branches/2.x-lite/ Note that this branch uses CMake and lacks the deprecated thread, texture, image and sleep support. I believe that, at least for now, it's the branch most appropriate for GLSDK to use. Regards, elmindreda (GLFW developer) |
|
From: Jason M. <ko...@gm...> - 2008-08-30 06:27:34
|
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? |
|
From: H. H. <hen...@gm...> - 2008-08-30 02:57:43
|
v71: I copied your code into our code base and ran the tests for it but it seems that there is something wrong with your calculations. It does not provide correct kind of results. At the moment, there is not a concensus on what kind of matrix should the glmMatRotateYPR functions actually generate; a Z*X*Y or Y*X*Z rotation? My idea is that it should generate Z*X*Y rotation because OpenGL treats vertices as vertical row vectors. OpenGL therefore transforms vertices as Mv, where M is the current modelview matrix and v is the vertex. Z*X*Y*v therefore generates in my opinion a rotation (in this order) around the Y-axis, followed a rotation around the X-axis, and followed by a rotation followed by the Z, which is the correct yaw-pitch-roll rotation. Y*X*Z*v rotation would be in the reverse order. This is at least my idea, correct me if I am wrong. I tested the code that you posted to me with both Y*X*Z and Z*X*Y models. In both cases your code resulted into a matrix which was different what would a serie of glRotatef calls result. The reference data which I use in my test cases to check the correctness of the glmMatRotateYPR results has been generated by the following OpenGL calls: // for the Z*X*Y model glLoadIdentity (); glRotatef (30.0f, 0.0f, 0.0f, 1.0f); glRotatef (30.0f, 1.0f, 0.0f, 0.0f); glRotatef (30.0f, 0.0f, 1.0f, 0.0f); // for the Y*X*Z model glLoadIdentity (); glRotatef (30.0f, 0.0f, 1.0f, 0.0f); glRotatef (30.0f, 1.0f, 0.0f, 0.0f); glRotatef (30.0f, 0.0f, 0.0f, 1.0f); In any case, your code is still in our code base but commented out. If you or somebody else would like to take a look at this, you may find it in the file src/glm/mat4f.c (lines 402-458) and the test case in tests/glm/mat4f.c (lines 286-298) in revision 58. The issue is still open. -- Henri 'henux' Häkkinen |
|
From: H. H. <hen...@gm...> - 2008-08-30 01:15:24
|
On Fri, Aug 29, 2008 at 7:41 PM, Rob Barris <rb...@bl...> wrote: > > Hello Henri , yep I'm still here.. > > I think the #1 goal has to be "walk developers step by step through > use of the API". I think to keep focus that we may need to set some > explicit *non*-goals for a period of time, and here are a few I would > suggest, since they don't help teach the API. > > a) SIMD optimization for the math lib. <- fun, but off course. > b) anything that would tip the balance towards "web site authoring > and maint" and away from making code. > c) 3D geometry/math tutorials - we can link to any number of books/ > sites for this stuff > d) anything else that consumes calendar time at the expense of demo > code. > Yes I generally agree on these points. At this moment I am writing the GLM API reference which I consider to be important to the SDK (a library is not usable unless it has documentation). I am not sure do we need a separate programming guides and/or tutorials for the mathlib and other baselibs at all, but either way, these can wait. DirectX SDK does not have a programming guide as far as I know for their D3DX library either. -- Henri 'henux' Häkkinen |
|
From: H. H. <hen...@gm...> - 2008-08-30 01:06:16
|
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 |
|
From: Jason M. <ko...@gm...> - 2008-08-30 00:05:19
|
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. |
|
From: Jason M. <ko...@gm...> - 2008-08-29 23:50:57
|
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. |
|
From: Branan R. <br...@gm...> - 2008-08-29 23:50:16
|
I've just set all the files currently in SVN to use eol-style=native. I think everyone should set their SVN client to automatically set that property on all added files. The instructions to do that are here: http://www.zope.org/DevHome/Subversion/SubversionConfigurationForLineEndings Branan |
|
From: H. H. <hen...@gm...> - 2008-08-29 23:25:39
|
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 |
|
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 |
|
From: Jason M. <ko...@gm...> - 2008-08-29 23:01:59
|
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. |
1 message has been excluded from this view by a project administrator.
