Date: Wed, 29 Jul 2009 16:41:30 +0200 (CEST) From: Oliver Fromme <olli@lurza.secnetix.de> To: freebsd-chat@FreeBSD.ORG, freebsd-chat-local@be-well.ilk.org Subject: Re: [ fbsd_chat ] Re: sh(1) documentation_set Message-ID: <200907291441.n6TEfUhD082558@lurza.secnetix.de> In-Reply-To: <444osvbnwd.fsf@be-well.ilk.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Lowell Gilbert <freebsd-chat-local@be-well.ilk.org> wrote: > spellberg_robert <emailrob@emailrob.com> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200907291441.n6TEfUhD082558>