Proposed improvements to the Khronos OpenCL man pages package

[Mathieu Malaterre]

On Thu, May 30, 2013 at 3:20 PM, Giuseppe Bilotta
<giuseppe.bilotta at gmail.com> wrote:
> 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.

Done:

http://packages.debian.org/sid/ocl-icd-opencl-dev

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

No IMHO. Debian uses whatever docbook-xsl package will provide will
upstream could leave on the edge and use docbook from -say- svn. Which
means man pages and/or html generated will be different.

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

True, the transformations are beasty.

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

Sure, why not.

-M