KMS documentation for userspace

[Simon Ser]

On Thursday, June 27, 2019 4:59 PM, Jani Nikula <jani.nikula at linux.intel.com> wrote:

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

After all these months, I've started converting the man pages to
rst [1]. Better late than never!

I've used this command to convert xml to rst:

    pandoc -s -f docbook -t rst -o man/drm.rst man/drm.xml

This mostly works but needs some rework to fixup references and
headings. You can see the final result in the MR.

[1]: https://gitlab.freedesktop.org/mesa/drm/-/merge_requests/72