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

[Thierry Reding]

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.

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

Thierry
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/dri-devel/attachments/20120924/5d889810/attachment.pgp>