Proposed improvements to the Khronos OpenCL man pages package

[Mathieu Malaterre]

Hi,

On Thu, May 30, 2013 at 10:57 AM, Giuseppe Bilotta
<giuseppe.bilotta at gmail.com> wrote:
> 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/

Fantastic ! Typically you can simply do:

  svn co svn://svn.debian.org/svn/pkg-nvidia/packages/khronos-opencl-man/trunk/debian
  make -f ./debian/rules get-orig-source
  tar xfz khronos-opencl-man_1.0\~svn21772.orig.tar.gz
  cd khronos-opencl-man-1.0\~svn21772
  mv ../debian .

And then either:

  quilt push/pop/refresh/edit

Or directly:

  dpkg-buildpackage -rfakeroot -us -uc
  ...
  fakeroot make -f ./debian/rules binary

> The outline of the changes is the following:
>
> * the DocBook sources are retrieved with svn, including the xhtml

Neat ! I could not find where those were hosted. I assumed there were
no svn since other opencl package retrieved them using wget:

http://anonscm.debian.org/viewvc/pkg-nvidia/packages/khronos-opencl-headers/trunk/debian/rules?view=markup

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

No :) Those are so-called Generated Files (it's a well known REJECT
case). We are required to generate them. So it is the opposite: why
waste disk space shipping upstream ones.

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

neat, much cleaner than my hack.

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

ok.

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

ok

This follows what I had already, so it is easy to follow.

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

ok

> 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);

If you do report them upstream, we need to update the DEP-3 header
(Forwarded entry) of each patch. Eg:

http://anonscm.debian.org/viewvc/pkg-nvidia/packages/khronos-opengl4-man/trunk/debian/patches/addingmanpages.patch?view=markup

> * turn links and olinks into  "seealso" elements

sure, why note

> * symlink additional function names to the defining man page

ok

I am rebuilding the entire package right now and will re-upload to NEW.

2cts