KMS documentation for userspace

[Jani Nikula]

On Sat, 22 Jun 2019, Daniel Vetter <daniel at ffwll.ch> wrote:
> On Wed, Jun 19, 2019 at 10:16 PM Jani Nikula
> <jani.nikula at linux.intel.com> wrote:
>>
>> On Wed, 19 Jun 2019, Daniel Vetter <daniel at ffwll.ch> wrote:
>> > - figure out what to do with the libdrm manpages. Some stuff we really
>> > want to also document there. But geez nroff. Maybe we need to stuff
>> > libdrm into the kernel, dunno.
>>
>> How would people feel about converting libdrm man pages to rst, and
>> using rst2man in the build? We did that for igt man pages [1]. Looking
>> at the diff, I think it's plain to see how that could lower the bar for
>> contributing. And perhaps it would be easier to refactor and move
>> documentation around too.
>
> I think that'd be very nice.
>
>> I forget, I probably used pandoc or something to do the bulk of the igt
>> conversion, and added some manual polish on top. I'm not volunteering
>> for the libdrm man page conversion though. ;)
>
> Hm, maybe dig out the old tools you used and point Simon at them?

I could swear I did it with pandoc only, but the pandoc I have on my
distro right now does not support man input. Upstream documentation
claims it does, so I don't know what gives.

If that fails, first man2html and then pandoc from html to rst works to
an extent.

Regardless, I think the hardest part is deciding what style to use in
the rst files (all the headings and synopsis and references etc.) and
then tediously do the manual cleanup after the conversion. It's a
one-time effort, so there are limits to the ROI on polishing the
toolchain.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Graphics Center