Proposed improvements to the Khronos OpenCL man pages package

[Giuseppe Bilotta]

Hello,

On Thu, May 30, 2013 at 2:51 PM, Mathieu Malaterre <malat at debian.org> wrote:
>
> Typically you can simply do:
>

[snip instructions]

Thanks, I'll try that on my next iteration of fixes

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

Well, I think the public svn access is rather recent. That package
should probably be updated too to make use of the svn access that has
been made available.

Additionally, I think debian could start packaing the Khronos opencl
ICD dispatcher (khronos-libopencl1) as an alternative to the
proprietary ones from amd and nvidia. I'll look into opening and RFP
for this too.

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

Well, I guess that's a point where I disagree with the Debian policy,
but then again it does make some sort of sense. I assume we could at
least check if the generated ones match the original ones, since in
this case they should?

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

Absolutely. I started from your files, since the separation of the two
steps made perfect sense.

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

For the time being I've only reported some unrelated patches (typos
and corrections like that). I'll try to find the time to clean up the
transformation isolating only the DocBook-relevant parts and then
submit that. Of course I'll also have to check that the HTML
generation doesn't get busted by the new format.

>> * turn links and olinks into  "seealso" elements
>
> sure, why note

I was actually thinking about keeping the note mechanism, since a
couple of pages refer to the specification in-text and not just at the
end in the Specification section. My plan is to hack the
note-producing template of the manpage docbook template to put those
notes inside the specification section. The prospected output would be
something like this:

... yadda yadda OpenCL Specification[1] yadda yadda

SPECIFICATION

OpenCL Specification, section whatever, page NNN (<- this refers to
man page itself)

Notes:

[1] OpenCL Specification, section referred to in [1], page whatever