On Tue, 15 Jan 2019 22:37:01 +0200 "Joel Nider" <JOELN@xxxxxxxxxx> wrote: > Jonathan Corbet <corbet@xxxxxxx> wrote on 01/15/2019 08:08:54 PM: > > The intent behind the user-space API manual is to document the user-space > > API; it's meant to be read by people writing applications and such. > > Perhaps they find it with a web search, but it will be there for them, one > > hopes, when they want it. > > So is the intent then to duplicate what is already in 'man'? Why would we > want 2 different locations for basically the same information? Wouldn't it > make more sense to just put these few details into appropriate 'man' > pages? We are not attempting to duplicate the man pages; there's been occasional talk of bringing them into the kernel tree, but enthusiasm for that is scarce for a number of good reasons. But there's a lot of information about the user-space API that isn't in the man pages, including the piece you are converting to RST. For a huge example, look at the massive v4l2 UAPI documentation that's in the kernel; that will never really fit into the man-page model. (And yes, it belongs in the userspace-api directory but isn't there for $REASONS). > It looks like I misunderstood the purpose of the "userspace API" section > then. So is there a section that is meant for a guide on how to write an > interface function? For something like this, driver-api seems like the right place. Someday, in some glorious future, it could contain a full manual on how these drivers are written, using all of the nice kerneldoc comments that already exist under drivers/infiniband. > OK, just to be clear - you are asking me to leave the original file as-is > (well, after .rst conversion) but move it to the new location > (Documentation/userspace-api), and put my new content into a new file in > the old location (Documentation/infiniband)? I'd rather see you put the new stuff under Documentation/driver-api, either in a standalone file or in a new subdirectory. Thanks for your patience with this! We really do want people to contribute more documentation, and I feel bad when it seems like I'm making it harder. My hope is that it will pay off in the long run; I think there are signs already that this is happening. Thanks, jon
