Date:	Wed, 28 Jan 2015 11:46:17 +0100
From:	"Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
To:	Daniel Mack <daniel@...que.org>,
	David Herrmann <dh.herrmann@...il.com>
CC:	mtk.manpages@...il.com, Tom Gundersen <teg@...m.no>,
	Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
	Arnd Bergmann <arnd@...db.de>,
	"Eric W. Biederman" <ebiederm@...ssion.com>,
	One Thousand Gnomes <gnomes@...rguk.ukuu.org.uk>,
	Jiri Kosina <jkosina@...e.cz>,
	Andy Lutomirski <luto@...capital.net>,
	Linux API <linux-api@...r.kernel.org>,
	LKML <linux-kernel@...r.kernel.org>,
	Djalal Harouni <tixxdz@...ndz.org>,
	Johannes Stezenbach <js@...21.net>,
	Theodore T'so <tytso@....edu>,
	christoph Hellwig <hch@...radead.org>
Subject: Re: [PATCH 01/13] kdbus: add documentation

Hello Daniel,

On 01/27/2015 07:14 PM, Daniel Mack wrote:
> Hi Michael,
> 
> On 01/27/2015 06:53 PM, Michael Kerrisk (man-pages) wrote:
>> On 01/27/2015 04:23 PM, David Herrmann wrote:
> 
>>> I only expect a handful of users to call the ioctls directly. The
>>> libraries that implement the payload-marshaling, in particular. It's a
>>> similar situation with netlink.
>>
>> Thanks, David, for the clarification. I think it would have been helpful
>> to have that more clearly stated up front, especially as some comments 
>> in this thread, such as the above, could be interpreted to mean quite 
>> the opposite. Can I suggest that some text on this point be added to 
>> kdbus.txt?
> 
> We're currently working on an a set of comprehensive man pages to
> document all the commands in the API, along with every struct, enum etc.
> We do that so that developers are able to actually understand every
> detail of the API, even though most people - as David explained - will
> not use that interface directly in the first place but let one of the
> high-level libraries help them integrate D-Bus functionality into their
> applications.

(I suggest that some text about this text go into the kdbus(7) page.)

> If you want, have a look at the upstream repository for a 	preliminary
> version of the new docs.

That's at https://code.google.com/p/d-bus/ , right? This looks like a 
good direction to go in. Thanks for tackling that.

I hope to take a longer look sometime soon, but a few general conventions
for man-pages that you might want to consider following:

* When listing errors, I think you should change your 
  language/formatting somewhat. Examples here from kdbus.endpoint.7:
   
  (1) The man page says

          RETURN VALUE
               On success, all mentioned ioctl commands return 0.

       Better to write this from a user-space point of view:

          RETURN VALUE
               On success, all mentioned ioctl commands return 0; on 
               error, -1 is returned, and errno is set to indicate 
               the error.

  (2) I would change the wording in the ERRORS sections from
       "may return the following errors"
       to
       "may fail with the following errors"

  (3) When listing the errors, drop the minus signs; that's not 
      what user-space sees. They see a positive value in errno.

  (4) The usual formatting convention for constants, including 
      error constants in man pages is boldface, rather than 
      underline/emphasis.

  (5) Insofar as it's possible, it would be good to make all
      pages format nicely within 80 columns. Some of the literal
      text and ASCII art could, I think, be narrowed.

Thanks,

Michael
-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

Powered by blists - more mailing lists