From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753000AbaFPEgl (ORCPT ); Mon, 16 Jun 2014 00:36:41 -0400 Received: from mail-wg0-f41.google.com ([74.125.82.41]:41503 "EHLO mail-wg0-f41.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751192AbaFPEgh (ORCPT ); Mon, 16 Jun 2014 00:36:37 -0400 Message-ID: <539E6E93.6070102@gmail.com> Date: Mon, 16 Jun 2014 06:12:03 +0200 From: "Michael Kerrisk (man-pages)" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:24.0) Gecko/20100101 Thunderbird/24.5.0 MIME-Version: 1.0 To: John Stultz CC: mtk.manpages@gmail.com, David Herrmann , lkml , Ryan Lortie , Linus Torvalds , Andrew Morton , "linux-mm@kvack.org" , "linux-fsdevel@vger.kernel.org" , Linux API , Greg Kroah-Hartman , Lennart Poettering , Daniel Mack , Kay Sievers , Hugh Dickins , Tony Battersby , Andy Lutomirski Subject: Re: [PATCH v3 3/7] shm: add memfd_create() syscall References: <1402655819-14325-1-git-send-email-dh.herrmann@gmail.com> <1402655819-14325-4-git-send-email-dh.herrmann@gmail.com> In-Reply-To: Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On 06/13/2014 06:20 PM, John Stultz wrote: > On Fri, Jun 13, 2014 at 7:20 AM, Michael Kerrisk (man-pages) > wrote: >> >> The general notion these days is that a (comprehensive) manual page >> _should_ come *with* the system call, rather than after the fact. And >> there's a lot of value in that. I've found no end of bugs and design >> errors while writing (comprehensive) man pages after the fact (by >> which time it's too late to fix the design errors), and also found >> quite a few of those issues when I've managed to work with folk at the >> same time as they write the syscall. Bottom line: you really should >> write formal documentation now, as part of the process of code >> submission. It improves the chance of finding implementation and >> design bugs, and may well widen your circle of reviewers. > > I very much agree here. One practical issue I've noticed is that > having separate targets for both the code changes and the manpages can > be an extra barrier for folks getting changes correctly documented as > the change is being submitted. Reviewers may say "be sure to send > updates to the man pages" but its not always easy to remember to > follow up and make sure the submitter got the changes (which match the > merged patches) to you as well. > > I've been thinking it might be nice to have the kernel syscall man > pages included in the kernel source tree, then have them > copied/imported over to the man-pages project (similar to how glibc > imports uapi kernel headers). They could even be kept in the > include/uapi directory, and checkpatch could ensure that changes that > touch include/uapi also have modifications to something in the > manpages directory. This way folks would be able to include the man > page change with the code change, making it easier for developers to > do the right thing, making it easier for reviewers to ensure its > correct, and making it easier for maintainers to ensure man page > documentation is properly in sync. > > Or is this something that has been hashed over already? I do admit > this would disrupt your process a bit. It's more a less a FAQ from my point of view, so I wrote this: https://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source In short, I agree that the current process is not optimal, but lacking (a lot) more time, it'd be hard to make any change to the current process. In any case, I think there's room for a lot of improvement even without changing the current process. (For example, while I agree that having man pages in a separate location from the kernel source does create some barriers, I don't think it's the reason most developers don't update the man pages. One just has to look at the patchy state Documentation/filesystems/proc.txt as one example to support that view point.) Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/