From owner-freebsd-doc Sat Jan 6 10:11: 7 2001 From owner-freebsd-doc@FreeBSD.ORG Sat Jan 6 10:11:03 2001 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from post.mail.nl.demon.net (post-11.mail.nl.demon.net [194.159.73.21]) by hub.freebsd.org (Postfix) with ESMTP id 5689237B400; Sat, 6 Jan 2001 10:11:02 -0800 (PST) Received: from [212.238.54.101] (helo=freebie.demon.nl) by post.mail.nl.demon.net with smtp (Exim 3.14 #4) id 14Exnw-000L4s-00; Sat, 06 Jan 2001 18:11:00 +0000 Received: (from wkb@localhost) by freebie.demon.nl (8.11.1/8.11.1) id f06IBvB76333; Sat, 6 Jan 2001 19:11:57 +0100 (CET) (envelope-from wkb) Date: Sat, 6 Jan 2001 19:11:57 +0100 From: Wilko Bulte To: "Bruce A. Mah" Cc: freebsd-doc@freebsd.org, wilko@freebsd.org Subject: Re: RELNOTESng update Message-ID: <20010106191157.F76196@freebie.demon.nl> References: <200101051950.f05Jo0H24919@bmah-freebsd-0.cisco.com> <20010106001658.A70625@freebie.demon.nl> <200101061735.f06HZUg34503@bmah-freebsd-0.cisco.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2i In-Reply-To: <200101061735.f06HZUg34503@bmah-freebsd-0.cisco.com>; from bmah@freebsd.org on Sat, Jan 06, 2001 at 09:35:30AM -0800 X-OS: FreeBSD 4.2-STABLE X-PGP: finger wilko@freebsd.org Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Sat, Jan 06, 2001 at 09:35:30AM -0800, Bruce A. Mah wrote: > If memory serves me right, Wilko Bulte wrote: > > > 2. The Supported Hardware lists from HARDWARE.TXT and RELNOTES.TXT > > > have been combined. > > > > For alpha I have my doubts about this. There is far too much > > untested hardware on alpha, and experience has shown that x86 != alpha > > even when would expect no cpu-port specifics. This is fundamental > > problem because we lack a wide alpha user base. And hence lack widespread > > testing of hardware. > > Perhaps I was unclear. The problem I was trying to address was that a > device we support could show up in at least four places: > > src/release/texts/HARDWARE.TXT > src/release/texts/alpha/RELNOTES.TXT > src/release/texts/i386/RELNOTES.TXT > doc/en_US.ISO_8859-1/books/handbook/install > > Ergo, if we start supporting a new device, we need to edit as many as > four files, and that's *before* the translation teams get to the > handbook. Agreed, this stinks. > Jim Mock was talking about nuking the section of the handbook with this > information. I support this. For the remaining three TXT files, my I support this as well. > goal was to take the union of HARDWARE.TXT and i386/RELNOTES.TXT (which > should be, but are not, consistent), and to use conditionals to make the > result consistent with alpha/RELNOTES.TXT when we build for that > platform. The result is that we only have *one* source file for our > Supported Hardware list. (Note that this doesn't preclude the > information showing up in multiple documents, should we want this.) > > If you're concerned that some people have been adding devices to the > alpha list without actually verifying whether or not they work, mea > culpa, I've probably done this. In the future, new devices get > surrounded by the appropriate conditional unless there's strong reason > to believe they've actually been tested on multiple architectures. An Sounds like the way to go. > example of where (I think) this is done right is the Adaptec SCSI > controllers, as well as the newer RAID controllers. Mike tends to test on Alpha, so that is good quality control. I'd like to go like: if it has not been tested on alpha it is not in the alpha version of the docs. > > Good idea. > > Except that our release notes are now 40+ pages long in PDF format. :-p Hmm. I myself (YMMV) don't like relnotes the size of Encyclopedia Brittanica. But I *hate* incomplete release notes. > > > like to know people's thoughts about folding this in as well > > > (particularly from Wilko, since he's maintaining it). > > > > I'm more than willing to convert alpha/HARDWARE.TXT into the right > > input format. Assuming I'm allowed to bug someone about the right formatting > > tools etc ;-) > > I learned from reading Nik's FDP Primer. IMHO, DocBook/SGML is like > HTML with different (and more) tags. (Pause for groans from the "real" > -doc committers.) If you bug me, at least you'll get another newbie's > perspective. We'll see. I'll wait a bit till we have other people's inputs. > > I do not want to pull the HW.TXT into the Relnotes. I don't think that this > > is a good idea. For me release notes are a thing that should be as small and > > comprehensive as possible. More static info, like details on hardware > > support etc, should be kept seperate. > > I was leaning towards putting everything in a single file, but my > enthusiasm for this is starting to wane. It sounds like you would like > the Supported Hardware list out of the release notes and have the users > read this in exactly one document, which would be analogous to > HARDWARE.TXT (and which would also contain the content from alpha/ > HARDWARE.TXT). Is that right? I think I could go for that, but I'd Yes, let's not overload relnotes. > like to hear from Nik and Jordan as well. Seconded. > that it can handle multiple documents. But that's not necessarily bad. > While we're at it, we could think about supporting eventual > translations. (Pause for groans from the translation teams.) There should not be much translation work in lists of supported hardware. > > > 3. At some point, I'll need to talk to someone who's familiar with > > > "make release" to see about how to integrate this into the build. It'll > > > > You want someone to look at that, no doubt. I've had some, um, interesting > > discussions with David when I screwed up the release makefile during > > introduction of alpha's HW.TXT. My bad, but not something to repeat. > > Oh yeah, gonna try real hard not to break release or world. Good luck! -- | / o / / _ Arnhem, The Netherlands email: wilko@freebsd.org |/|/ / / /( (_) Bulte http://www.freebsd.org http://www.nlfug.nl To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message