Date: Sat, 6 Jan 2001 19:11:57 +0100 From: Wilko Bulte <wkb@freebie.demon.nl> To: "Bruce A. Mah" <bmah@freebsd.org> Cc: freebsd-doc@freebsd.org, wilko@freebsd.org Subject: Re: RELNOTESng update Message-ID: <20010106191157.F76196@freebie.demon.nl> In-Reply-To: <200101061735.f06HZUg34503@bmah-freebsd-0.cisco.com>; from bmah@freebsd.org on Sat, Jan 06, 2001 at 09:35:30AM -0800 References: <200101051950.f05Jo0H24919@bmah-freebsd-0.cisco.com> <20010106001658.A70625@freebie.demon.nl> <200101061735.f06HZUg34503@bmah-freebsd-0.cisco.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010106191157.F76196>