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

From: Thierry Reding <thierry.reding@avionic-design.de>
To: David Herrmann <dh.herrmann@googlemail.com>
Cc: dri-devel@lists.freedesktop.org
Subject: Re: [PATCH libdrm 0/4] Overview man-pages for libdrm
Date: Mon, 24 Sep 2012 21:51:42 +0200	[thread overview]
Message-ID: <20120924195142.GA29294@avionic-0098.mockup.avionic-design.de> (raw)
In-Reply-To: <1348411208-3943-1-git-send-email-dh.herrmann@googlemail.com>

[-- Attachment #1.1: Type: text/plain, Size: 1914 bytes --]

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

[-- Attachment #1.2: Type: application/pgp-signature, Size: 836 bytes --]

[-- Attachment #2: Type: text/plain, Size: 159 bytes --]

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel