From owner-freebsd-chat@FreeBSD.ORG Wed Jul 29 14:41:52 2009 Return-Path: Delivered-To: freebsd-chat@FreeBSD.ORG Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id D7934106564A for ; Wed, 29 Jul 2009 14:41:52 +0000 (UTC) (envelope-from olli@lurza.secnetix.de) Received: from lurza.secnetix.de (lurza.secnetix.de [IPv6:2a01:170:102f::2]) by mx1.freebsd.org (Postfix) with ESMTP id 59C6A8FC08 for ; Wed, 29 Jul 2009 14:41:52 +0000 (UTC) (envelope-from olli@lurza.secnetix.de) Received: from lurza.secnetix.de (localhost [127.0.0.1]) by lurza.secnetix.de (8.14.3/8.14.3) with ESMTP id n6TEfU5g082559; Wed, 29 Jul 2009 16:41:46 +0200 (CEST) (envelope-from oliver.fromme@secnetix.de) Received: (from olli@localhost) by lurza.secnetix.de (8.14.3/8.14.3/Submit) id n6TEfUhD082558; Wed, 29 Jul 2009 16:41:30 +0200 (CEST) (envelope-from olli) Date: Wed, 29 Jul 2009 16:41:30 +0200 (CEST) Message-Id: <200907291441.n6TEfUhD082558@lurza.secnetix.de> From: Oliver Fromme To: freebsd-chat@FreeBSD.ORG, freebsd-chat-local@be-well.ilk.org In-Reply-To: <444osvbnwd.fsf@be-well.ilk.org> X-Newsgroups: list.freebsd-chat User-Agent: tin/1.8.3-20070201 ("Scotasay") (UNIX) (FreeBSD/6.4-PRERELEASE-20080904 (i386)) MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-2.1.2 (lurza.secnetix.de [127.0.0.1]); Wed, 29 Jul 2009 16:41:46 +0200 (CEST) Cc: Subject: Re: [ fbsd_chat ] Re: sh(1) documentation_set X-BeenThere: freebsd-chat@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: freebsd-chat@FreeBSD.ORG, freebsd-chat-local@be-well.ilk.org List-Id: Non technical items related to the community List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 29 Jul 2009 14:41:53 -0000 Lowell Gilbert wrote: > spellberg_robert writes: > > > dear mr. fromme --- > > > > > man_pages need to be, at least, "substantially_complete". > > > > > > I agree that the sh(1) manual page should be complete, > > > and I think it is indeed complete. Do you think some > > > piece of reference information is missing? > > > > ah_ha, you have arrived at my thesis. > > > > the man_page author states that it is not complete, in the first paragraph. > > Not really. What it says is that the man page is not a complete > *specification*. That is not the same thing as being incomplete as a > user manual. When appropriate information is noticed to be missing, it > does get added (as you can confirm from looking at the checkin log for > sh.1). Right. In particular, a complete specification should include a formal grammar of the language accepted by the shell. This is missing from the manual page, but it isn't really necessary for normal use of the shell. On the other hand, I do have to agree with Robert that some parts of the man page are very terse, sometimes up to the point that you actually have to try things out (or examine the source) in order to find out how something works. For example, the man page fails to mention which operators are supported in arithmetic expressions, and how they evaluate their arguments, exactly. (I noticed this just today.) Certainly, if someone writes up a paragraph for inclusion in the manual page, it will be gratefully accepted and comitted if appropriate. Best regards Oliver -- Oliver Fromme, secnetix GmbH & Co. KG, Marktplatz 29, 85567 Grafing b. M. Handelsregister: Registergericht Muenchen, HRA 74606, Geschäftsfuehrung: secnetix Verwaltungsgesellsch. mbH, Handelsregister: Registergericht Mün- chen, HRB 125758, Geschäftsführer: Maik Bachmann, Olaf Erb, Ralf Gebhart FreeBSD-Dienstleistungen, -Produkte und mehr: http://www.secnetix.de/bsd "I started using PostgreSQL around a month ago, and the feeling is similar to the switch from Linux to FreeBSD in '96 -- 'wow!'." -- Oddbjorn Steffensen