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-api" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
