On Wed, Apr 11, 2012 at 12:31 PM, Michael Kerrisk (man-pages) <mtk.manpages@xxxxxxxxx> wrote: > On Sat, Apr 7, 2012 at 8:28 AM, Jonathan Corbet <corbet@xxxxxxx> wrote: >> On Fri, 6 Apr 2012 13:01:17 -0700 >> Andrew Lutomirski <luto@xxxxxxx> wrote: >> >>> This has been bugging me for awhile. Is there any interest in moving >>> the manpages into the kernel source tree? Then there could be a >>> general requirement that new APIs get documented when they're written. >> >> Man page (or other documentation) requirements for patch acceptance are a >> regular kernel summit feature. People seem to think it's a good idea, but >> actual enforcement of such requirements always seems to be lacking. Lots >> of people have kind of given up trying. I don't really see that adding >> the man pages to the tree would help, but I could be wrong... > > I largely consider this (moving man pages to kernel.org) a technical > solution to what is fundamentally a social problem (developers > reluctant to write documentation), and doubt that the technical > solution would make much difference. I'd love to be proved wrong, but > the experiment would require significant start-up effort. (My > collected thoughts on this can be found here: > http://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source. > Note the alternative idea of patch tags mentioned at the end of that > text.) > > Unless, or until there's a paid maintainer, I don't expect things to > get significantly better than what they currently are. The quite > significant improvements in man-pages since 2004, when I became > maintainer were in small part due to the fact that I was for a short > period paid to do the work, but in much larger part due to a huge > private effort over those years which over the last couple of years is > no longer unsustainable for me (man-pages is in competition with > requirements for my attention from family, working life, and > (seriously!) seismic events), Hrm. Maybe someone could convince Andrew and Linus not to pull new syscalls or major ABI features unless the patchset includes full docs. Anyway, I'll write up a detailed description of PR_SET_NO_NEW_PRIVS, stick it in the changelog, and cc linux-doc. --Andy -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
