[PATCH libdrm 0/4] Overview man-pages for libdrm

[David Herrmann]

Hi Thierry

On Mon, Sep 24, 2012 at 9:51 PM, Thierry Reding
<thierry.reding at avionic-design.de> wrote:
> On Sun, Sep 23, 2012 at 04:40:03PM +0200, David Herrmann wrote:
>> Hi
>>
>> This tries to continue the effort to document libdrm. I actually removed the
>> X11-like man-page generation code as autotools now support man_MANS. The
>> previous approach required every manpage to be in the same man-group. However,
>> API calls belong in man3 and overview pages into man7. So I just use the simpler
>> approach without all the replacements. It turns out, no man-page did use them so
>> we can add it again if one really needs them.
>>
>> The other 3 patches add a generic drm.7 overview page, a drm-kms.7 overview page
>> and a drm-memory.7 overview page. Also some aliases are installed, including
>>   drm-gem.7 => drm-memory.7
>>   drm-ttm.7 => drm-memory.7
>> Please note that you cannot open the aliased pages with "man ./man/drm-gem.7".
>> You must install them before they work correctly as they require the directory
>> to be "man7" not "man".
>
> You should be able to do "man -l ./man/drm-gem.7" without the need to
> install.

Ah, thanks, that works.

>> Anyway, any comments are welcome. This is really just something to start on and
>> any corrections are appreciated.
>>
>> I have also added many dead-links to some other overview pages, including
>>   drm-prime.7: Short introduction to the PRIME API
>>   drm-intel.7,
>>   drm-radeon.7,
>>   drm-noueveau.7: Driver-dependent DRM API
>> And many links to undocumented API calls. Feel free to write short stub-pages
>> for any of them. It's better than nothing.
>>
>> I am also no groff/troff expert, but I think the pages look quite nice. And I
>> recommend reading the pages with "man ./man/drm*.7" if you want to review them.
>> Plain troff is really ugly to read.
>
> Did you consider rewriting the man-pages in docbook? Generating the
> manpages is usually more involved but it also allows other forms of
> documentation (PDF, HTML, ...) to be generated easily.

I played with docbook today to create some wayland man-pages. Apart
from an install-bug for aliases that I had to fix with a short SED
script, it works nicely. I think I will convert it to XML files in the
next revision.

Thanks!
David