From owner-freebsd-doc Sat Aug 17 11:45:15 2002 Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.FreeBSD.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 1DFBB37B400 for ; Sat, 17 Aug 2002 11:45:13 -0700 (PDT) Received: from abigail.blackend.org (blackend.org [212.11.50.35]) by mx1.FreeBSD.org (Postfix) with ESMTP id 1A80F43E4A for ; Sat, 17 Aug 2002 11:45:11 -0700 (PDT) (envelope-from marc@blackend.org) Received: from marduk.blackend.org (marduk.blackend.org [192.168.1.202]) by abigail.blackend.org (8.12.3/8.12.3/ - 15/04/02) with ESMTP id g7HIhKK5066419; Sat, 17 Aug 2002 20:43:20 +0200 (CEST) (envelope-from marc@abigail.blackend.org) Received: from marduk.blackend.org (localhost [127.0.0.1]) by marduk.blackend.org (8.12.5/8.12.5) with ESMTP id g7HIj2Vw001822; Sat, 17 Aug 2002 20:45:02 +0200 (CEST) (envelope-from marc@localhost.blackend.org) Received: (from marc@localhost) by marduk.blackend.org (8.12.5/8.12.5/Submit) id g7HIj1sb001821; Sat, 17 Aug 2002 20:45:01 +0200 (CEST) (envelope-from marc) Date: Sat, 17 Aug 2002 20:45:01 +0200 From: Marc Fonvieille To: Ceri Davies Cc: doc@FreeBSD.org Subject: Re: cvs commit: doc/en_US.ISO8859-1/books/handbook/advanced-networking chapter.sgml doc/en_US.ISO8859-1/books/handbook/linuxemu chapter.sgml doc/en_US.ISO8859-1/books/handbook/ppp-and-slip chapter.sgml Message-ID: <20020817204500.A1479@marduk.blackend.org> References: <200208152105.g7FL5Lv6014947@freefall.freebsd.org> <20020816084433.GD20494@idoru.tenten> <20020816214856.D59091@abigail.blackend.org> <20020817163021.GA2666@idoru.tenten> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5.1i In-Reply-To: <20020817163021.GA2666@idoru.tenten>; from setantae@submonkey.net on Sat, Aug 17, 2002 at 05:30:21PM +0100 X-Useless-Header: blackend.org X-Operating-System: FreeBSD 4.6-STABLE Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org On Sat, Aug 17, 2002 at 05:30:21PM +0100, Ceri Davies wrote: [...] > > I removed it only from Handbook as it covers the 4.X branch, to be > > consistent with the examples given by sysctl(8), the commands used in > > rc.* files and also all manual pages mentioning sysctl (natd(8) for > > example). > > Yeah, I know that ;) > > What I'm asking is whether folks think it might be an idea to keep the -w > since then anyone with a pre-4.5 (ish?) machine will be able to follow the > examples as well, since at the moment sysctl just ignores -w. I have a 4.4 that does not use -w > > If nobody does, that's cool too, but you obviously don't agree else you > wouldn't have committed the change ! > Look at "6.8 Tuning with sysctl" the examples don't use -w and that section is not really recent. I did not check but according to the date on the cvs it was added between 4.3 and 4.4, and I'm not sure 4.3 did not use -w flag. So some part of the Handbook told -w and some others not. If I am a 4.2 user, with the Handbook instructions : sometimes it works sometimes not. Is it good? Now, I removed all the remaining -w, so the 4.2 user can't apply any of the sysctl commands from the Handbook. Is it better? Well, many people are going to think that I'm crazy :) but the 2nd solution is better from my point of view. Why? just cause the doc is consistent, it will avoid things like "Well your FreeBSD (doc) is no really reliable cause sometimes it works sometimes not...", and as the website claims it is the Handbook for 4.6.2-R, the user could understand that there are some differences. Of course, the best thing would be to add each time "For older versions you have to add -w etc." In fact we are just talking about a problem of the Handbook: where is the "backward compatibility" limit? Many of things that the user can find in the Handbook (instructions, ports, etc.) can't be used directly without any changes on older versions. Each release comes with his own set of docs, I mean the 4.4 comes with the Handbook version tagged at the release time. The website says "Welcome to FreeBSD! This handbook covers the installation and day to day use of FreeBSD 4.6.2-RELEASE." When it's possible we can add notes related to older versions, but I don't think keeping deprecated options/commands/etc., is a good thing, it's not the best way to push people to use new ones and it leads often to problems when the option is finally removed. Marc To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message