From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: Daniel Mack <daniel@zonque.org>, David Herrmann <dh.herrmann@gmail.com>
Cc: mtk.manpages@gmail.com, Tom Gundersen <teg@jklm.no>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
Arnd Bergmann <arnd@arndb.de>,
"Eric W. Biederman" <ebiederm@xmission.com>,
One Thousand Gnomes <gnomes@lxorguk.ukuu.org.uk>,
Jiri Kosina <jkosina@suse.cz>,
Andy Lutomirski <luto@amacapital.net>,
Linux API <linux-api@vger.kernel.org>,
LKML <linux-kernel@vger.kernel.org>,
Djalal Harouni <tixxdz@opendz.org>,
Johannes Stezenbach <js@sig21.net>,
"Theodore T'so" <tytso@mit.edu>,
christoph Hellwig <hch@infradead.org>
Subject: Re: [PATCH 01/13] kdbus: add documentation
Date: Wed, 28 Jan 2015 11:46:17 +0100 [thread overview]
Message-ID: <54C8BDF9.7080802@gmail.com> (raw)
In-Reply-To: <54C7D573.7080809@zonque.org>
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/
next prev parent reply other threads:[~2015-01-29 2:57 UTC|newest]
Thread overview: 86+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-01-16 19:16 [PATCH v3 00/13] Add kdbus implementation Greg Kroah-Hartman
2015-01-16 19:16 ` [PATCH 01/13] kdbus: add documentation Greg Kroah-Hartman
2015-01-20 13:53 ` Michael Kerrisk (man-pages)
2015-01-20 14:31 ` David Herrmann
2015-01-20 14:42 ` Josh Boyer
2015-01-20 14:53 ` Djalal Harouni
2015-01-20 16:08 ` Johannes Stezenbach
2015-01-20 17:00 ` David Herrmann
2015-01-20 22:00 ` Johannes Stezenbach
2015-01-21 10:28 ` Michael Kerrisk (man-pages)
2015-01-20 18:23 ` Daniel Mack
2015-01-21 10:32 ` Michael Kerrisk (man-pages)
2015-01-21 15:19 ` Theodore Ts'o
2015-01-21 16:58 ` Daniel Mack
2015-01-22 10:18 ` Michael Kerrisk (man-pages)
2015-01-22 13:46 ` David Herrmann
2015-01-22 14:49 ` Austin S Hemmelgarn
2015-01-23 16:08 ` Greg Kroah-Hartman
2015-01-26 14:46 ` Michael Kerrisk (man-pages)
2015-01-27 15:05 ` David Herrmann
2015-01-27 16:03 ` Andy Lutomirski
2015-01-29 8:53 ` Daniel Mack
2015-01-29 11:25 ` Andy Lutomirski
2015-01-29 11:42 ` Daniel Mack
2015-01-29 12:09 ` Andy Lutomirski
2015-02-02 9:34 ` Daniel Mack
2015-02-02 20:12 ` Andy Lutomirski
2015-02-03 10:09 ` Daniel Mack
2015-02-04 0:41 ` Andy Lutomirski
2015-02-04 2:47 ` Eric W. Biederman
2015-02-04 3:14 ` Greg Kroah-Hartman
2015-02-04 6:30 ` Eric W. Biederman
2015-02-04 23:03 ` Andy Lutomirski
2015-02-05 0:16 ` David Herrmann
2015-02-08 16:54 ` Andy Lutomirski
2015-01-27 18:03 ` Michael Kerrisk (man-pages)
2015-01-23 11:47 ` Michael Kerrisk (man-pages)
2015-01-23 15:54 ` Greg Kroah-Hartman
2015-01-26 14:42 ` Michael Kerrisk (man-pages)
2015-01-26 15:26 ` Tom Gundersen
2015-01-26 16:44 ` christoph Hellwig
2015-01-26 16:45 ` Michael Kerrisk (man-pages)
2015-01-27 15:23 ` David Herrmann
2015-01-27 17:53 ` Michael Kerrisk (man-pages)
2015-01-27 18:14 ` Daniel Mack
2015-01-28 10:46 ` Michael Kerrisk (man-pages) [this message]
2015-01-20 13:58 ` Michael Kerrisk (man-pages)
2015-01-20 17:50 ` Daniel Mack
2015-01-21 8:57 ` Michael Kerrisk (man-pages)
2015-01-21 9:07 ` Daniel Mack
2015-01-21 9:07 ` Michael Kerrisk (man-pages)
2015-01-21 9:12 ` Daniel Mack
2015-01-23 6:28 ` Ahmed S. Darwish
2015-01-23 13:19 ` Greg Kroah-Hartman
2015-01-23 13:29 ` Greg Kroah-Hartman
2015-01-25 3:30 ` Ahmed S. Darwish
2015-01-16 19:16 ` [PATCH 02/13] kdbus: add header file Greg Kroah-Hartman
2015-01-16 19:16 ` [PATCH 03/13] kdbus: add driver skeleton, ioctl entry points and utility functions Greg Kroah-Hartman
2015-01-16 19:16 ` [PATCH 04/13] kdbus: add connection pool implementation Greg Kroah-Hartman
2015-01-16 19:16 ` [PATCH 05/13] kdbus: add connection, queue handling and message validation code Greg Kroah-Hartman
2015-01-16 19:16 ` [PATCH 06/13] kdbus: add node and filesystem implementation Greg Kroah-Hartman
2015-01-16 19:16 ` [PATCH 07/13] kdbus: add code to gather metadata Greg Kroah-Hartman
2015-01-16 19:16 ` [PATCH 08/13] kdbus: add code for notifications and matches Greg Kroah-Hartman
2015-01-16 19:16 ` [PATCH 09/13] kdbus: add code for buses, domains and endpoints Greg Kroah-Hartman
2015-01-16 19:16 ` [PATCH 10/13] kdbus: add name registry implementation Greg Kroah-Hartman
2015-01-16 19:16 ` [PATCH 11/13] kdbus: add policy database implementation Greg Kroah-Hartman
2015-01-16 19:16 ` [PATCH 12/13] kdbus: add Makefile, Kconfig and MAINTAINERS entry Greg Kroah-Hartman
2015-01-16 19:16 ` [PATCH 13/13] kdbus: add selftests Greg Kroah-Hartman
2015-01-16 22:07 ` [PATCH v3 00/13] Add kdbus implementation Josh Boyer
2015-01-16 22:18 ` Greg Kroah-Hartman
2015-01-17 0:26 ` Daniel Mack
2015-01-17 0:41 ` Josh Boyer
2015-01-19 18:06 ` Johannes Stezenbach
2015-01-19 18:38 ` Greg Kroah-Hartman
2015-01-19 20:19 ` Johannes Stezenbach
2015-01-19 20:31 ` Greg Kroah-Hartman
2015-01-19 23:38 ` Johannes Stezenbach
2015-01-20 1:13 ` Greg Kroah-Hartman
2015-01-20 10:57 ` Johannes Stezenbach
2015-01-20 11:26 ` Greg Kroah-Hartman
2015-01-20 13:24 ` Johannes Stezenbach
2015-01-20 14:12 ` Michael Kerrisk (man-pages)
2015-01-26 21:32 ` One Thousand Gnomes
2015-01-19 18:33 ` Johannes Stezenbach
2015-01-20 14:05 ` Michael Kerrisk (man-pages)
2015-01-20 14:15 ` Michael Kerrisk (man-pages)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=54C8BDF9.7080802@gmail.com \
--to=mtk.manpages@gmail.com \
--cc=arnd@arndb.de \
--cc=daniel@zonque.org \
--cc=dh.herrmann@gmail.com \
--cc=ebiederm@xmission.com \
--cc=gnomes@lxorguk.ukuu.org.uk \
--cc=gregkh@linuxfoundation.org \
--cc=hch@infradead.org \
--cc=jkosina@suse.cz \
--cc=js@sig21.net \
--cc=linux-api@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=luto@amacapital.net \
--cc=teg@jklm.no \
--cc=tixxdz@opendz.org \
--cc=tytso@mit.edu \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).