Proposed improvements to the Khronos OpenCL man pages package

[Giuseppe Bilotta]

Hello,

I've been working these past days in trying to produce better man
pages from the DocBook sources by Khronos, and while at it I've also
prepared a few changes to the way the packages are assembled and
created. The final touches are still missing (I always have troubles
when adding files for the packaging, so maybe it's better if somebody
else does it?), but the result of my current work can be found on
http://git.oblomov.eu/debian/khronos-opencl-man/

The outline of the changes is the following:

* the DocBook sources are retrieved with svn, including the xhtml
files produced by the Khronos Group itself (in the xhtml/ directory).
I think that the original xhtml files can be packaged directly, it
shouldn't be necessary to rebuild them.

* the man pages are created in a separate man/ directory

* a Makefile and a couple of xslt files are included. Following the
previous work by Mathie Malaterre, there are two .xsl files:

++ `opencl-manpages-pre.xsl` does some heavy-duty preprocessing of the
source .xml files to align them to both the DocBook standard and what
man expects. Changes include moving elements around, adding a couple
of elements, and making some changes such as using manvolnum 3clc (clc
= OpenCL C) instead of just 3, to avoid conflicts with the C stdlib
man pages. Links to the specification are preserved, and the Ruby
script Khronos uses to fixup the links in the .html files is used to
generate a lookup table for textual information which is used in the
man pages.

++ `opencl-manpages.xsl` does the actual man production, overriding a
couple of functions to cope with some irregularities remaining in the
source files.

Finally, sed is used to cleanup some whitespace issues left over by
the docbook to man coversion.

The result still has a couple of rough corners and can be improved in
a variety of ways, but it's much more usable than before. It's
probably worth making a new package released based on this.

Improvements that remain to be done:

* smooth out the remaining issues in the original sources (some of
these changes should be proposed for upstream inclusion, by the way);

* turn links and olinks into  "seealso" elements

* symlink additional function names to the defining man page

Best regards,

--
Giuseppe "Oblomov" Bilotta