From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.org/gmane.linux.lib.musl.general/3581 Path: news.gmane.org!not-for-mail From: Michael Kerrisk Newsgroups: gmane.linux.lib.musl.general Subject: Re: Re: Linux manpages (was Re: [musl] Request for volunteers) Date: Tue, 09 Jul 2013 02:18:21 +0200 Message-ID: <51DB56CD.6050306@gmail.com> References: <20130701174411.GA1631@gauss> <20130706215227.GC26987@newbook> <20130707000324.GU29800@brightrain.aerifal.cx> Reply-To: musl@lists.openwall.com NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1373329119 10112 80.91.229.3 (9 Jul 2013 00:18:39 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 9 Jul 2013 00:18:39 +0000 (UTC) Cc: musl@lists.openwall.com, "Michael Kerrisk (man-pages)" To: Rich Felker Original-X-From: musl-return-3585-gllmg-musl=m.gmane.org@lists.openwall.com Tue Jul 09 02:18:40 2013 Return-path: Envelope-to: gllmg-musl@plane.gmane.org Original-Received: from mother.openwall.net ([195.42.179.200]) by plane.gmane.org with smtp (Exim 4.69) (envelope-from ) id 1UwLde-0004nW-Tb for gllmg-musl@plane.gmane.org; Tue, 09 Jul 2013 02:18:38 +0200 Original-Received: (qmail 24037 invoked by uid 550); 9 Jul 2013 00:18:38 -0000 Mailing-List: contact musl-help@lists.openwall.com; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: Original-Received: (qmail 24029 invoked from network); 9 Jul 2013 00:18:38 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=message-id:date:from:user-agent:mime-version:to:cc:subject :references:in-reply-to:content-type:content-transfer-encoding; bh=6KB8t1PPS56EWSjMY3LLf1RANmJM8cRRU1xq9uVYtE8=; b=Hh0EnXaNq2lfNZMXyxcZlsvwB5UORw+7e9XMF1lRckuX1070Hbh+wjKQQl49aESiHA hOGN7TpvXCd8rSE6G+ZUnaloZVo5C/fNhtCHLi3jAyMAtHwYt80s+PrV4DtkEuDj8fUL LBB3nc+W10geD3uWXCMZh50TDcMivg1bG/RQyfvXISW/IfIs+3U9YoK9BxX32thPOjBE ShLgs+5Z0m/X3cRzNqsasgJSMp21DkyejkZmd8HIqZf+jbbBC97BK7vyYY8a/ng63lP7 m5DIdeO1panC+UZnopjUgNzBvo3rrAgFyjBVV1/ia/8MG8w1FNtIWzNDbjtZkVsSUZYv p/2g== X-Received: by 10.66.226.111 with SMTP id rr15mr25444632pac.122.1373329106059; Mon, 08 Jul 2013 17:18:26 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130311 Thunderbird/17.0.4 In-Reply-To: <20130707000324.GU29800@brightrain.aerifal.cx> Xref: news.gmane.org gmane.linux.lib.musl.general:3581 Archived-At: Rich, On 07/07/13 02:03, Rich Felker wrote: > On Sun, Jul 07, 2013 at 12:04:04AM +0100, Justin Cormack wrote: >>>> On a slightly related note, would you be interested in patches for the >>>> Linux manpages briefly documenting places where musl differs from glibc >>>> (in the NOTES section, along the same lines as the notes about >> libc4/libc5)? >>> >>> Historically, man-pages has primarily documented glibc + syscalls, but >>> there's nothing firm about that. It's more been about limited time >>> resources and the fact that glibc is the most widely used libc. I'd >>> have no objection to musl-specific notes in the man-pages. Perhaps a >>> patch to libc(7) would be a good place to start. > > I'm not sure how much effort would be involved. My ideal outcome would > be for the man pages to evolve to document what applications can > _portably_ expect from the interfaces, This is what the man pages endeavor to do. (I consider cases where non-portable behavior is not clearly indicated to be bugs.) > with appropriate notes on > caveats where certain libc versions or kernel versions give you > less-than-conforming behavior, and where nonstandard extensions are > available. That's more or less what the pages do, with the proviso that "certain libc versions" currently means just glibc, and in a few odd cases, ancient Linux libc. > However my feeling is that this would be a very big project > and I'm not sure if Michael would want to go in that direction. I do > think it would greatly improve the quality of Linux software > development, though. > >> The man(2) section is rather glibc specific and makes the syscall details >> rather subsidiary. I will try to send some patches if these would be >> welcome. > > I think it's an error to have anything glibc-specific in section 2 of > the manual, which should be documenting the kernel, not userspace. > What would be useful in the section 2 man pages is to document where ("useful" to who? Few users care about the naked syscall behavior.) > the syscall is insufficient to provide POSIX semantics, which are left > to userspace to provide. Such section 2 pages could then have > corresponding section 3 pages that document the library behavior. See https://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source I think it would be a retrograde step to split syscall pages into Sections 2 and 3. Users want to get the documentation in one place. Note that the approach in man-pages (consolidating info on the syscall plus any libc additions in one page) is not unique to Linux. From some (offlist) discussions with the BSD man pages maintainers, it appears that at least some (all?) of the BSDs do the same. Cheers, Michael