Date: Mon, 18 Dec 2000 09:41:45 -0800 From: "Bruce A. Mah" <bmah@FreeBSD.ORG> To: jim@osd.bsdi.com Cc: doc@FreeBSD.ORG Subject: Re: Supported hardware list(s) Message-ID: <200012181741.eBIHfjt94333@bmah-freebsd-0.cisco.com> In-Reply-To: <20001215133609.A23331@envy.geekhouse.net> References: <20001215133609.A23331@envy.geekhouse.net>
next in thread | previous in thread | raw e-mail | index | archive | help
--==_Exmh_754907370P Content-Type: text/plain; charset=us-ascii If memory serves me right, Jim Mock wrote: > Once again, I've been tasked with getting the handbook up-to-date and > ready to print a 2nd edition. It needs quite a bit of work, most of > which I'll address in another message later. For now, I'd like to get > the hardware list down to *one* place. Right now we have different > lists in 3 places -- the install chapter, the appendix, as well as > HARDWARE.TXT. The last is probably the most likely candidate to be kept > up-to-date, so, I think we should take advantage of it. Jim-- You asked for it, you got it... First, there are actually six different places where we list hardware: The install chapter in the handbook, the appendix in the handboox, src/ release/texts/HARDWARE.TXT, src/release/texts/i386/RELNOTES.TXT, src/ release/texts/alpha/ RELNOTES.TXT, and src/release/texts/alpha/ HARDWARE.TXT. The "generic" HARDWARE.TXT and the platform-specific RELNOTES.TXT files are probably the two that get updated the most frequently; the alpha-specific HARDWARE.TXT file deals with which alpha hardware platforms we can run on. Note that some of these files are even organized differently (i.e. section headers, etc.). It's ugly, and I'll freely assume my share of the blame for making it so. > Here's what I propose: > > 1) Nuke the hardware compatibility appendix. It's quite out of date, > and since no one has taken an interest in "claiming" it as their > own, we should get rid of it. Well, it's out of date, but at least on first glimpse, it appears to have some useful information that isn't found anywhere else in our documentation. > 2) In the install chapter, do as we do elsewhere -- link to > HARDWARE.TXT on ftp.FreeBSD.org, or to the one on the reader's > system at /usr/src/release/texts/HARDWARE.TXT. Granted, the 2nd > will only work if the reader has source installed, but we could > provide a link to both to make that a non-issue. A possibility... > I'm interested in hearing what others think -- I know there are a lot of > folks who'd like to see one hardware list, and I'm one of them :-) > Comments? I think the end goal is a good one. I was working on this issue from a slightly different angle. I talked with a few people at BSDCon about the subject of fixing up the *.TXT files, specifically, doing them up in DocBook. The goal of this exercise would be to produce a smaller set of files for the release notes (e.g. one file total, not one per platform) and hardware lists which is customized when output is generated to apply to different plaforms. Also, we could do "better looking" release notes in PDF, PS, HTML, TXT, and so forth, possibly with some help from the stylesheet gurus amongst us. I got some weak agreement to this idea, then I went off and did some DocBook coding, and then got bogged down in Real Work (TM). (Note: I'm still in that mode.) I've put a snapshot of my work at: http://people.freebsd.org/~bmah/relnotes.tar.gz (Don't laugh too hard at my markup...I don't know what the heck I'm doing. But thanks to nik for pointing me at a way of doing this using marked sections.) This directory tree lives in /usr/doc/en_US.ISO_8859-1/articles on my workstation; I don't know enough about the document build process to make it build anywhere else. The idea is that you edit the files in relnotes/common (especially relnotes/common/new.sgml and relnotes/ common/hw.sgml). Then you'd actually do the builds of the release notes in relnotes/i386, relnotes/alpha, or whereever. My goal was to be able to nuke HARDWARE.TXT and throw everything into new.sgml and hw.sgml; these would then generate an architecture-specific RELNOTES.TXT (or relnotes.pdf or relnotes.html or...). I still haven't figured out the ramifications for the release-building process yet; it looks like this makes having release notes dependent on both a doc tree plus the DocBook toolchain. Someone (dougb?) suggested putting a placeholder RELNOTES.TXT in src/ release/texts/${arch} that gets overwritten by the "real" release notes if we actually generate them. Other things I'm stalled on: Lack of time (of course), and experience at doing the SGML markup. Also the myriads of hardware info lists would need to be consolidated. Finally, the doc tree as it stands is not branched (a la CVS), but putting release notes in the doc tree would mandate it. (Putting it in the src tree doesn't automatically solve the problem, because I think there's some dependencies on some files, such as style sheets or entity definitions, that only live in the doc tree.) So...if we got this to work, one thing the handbook *could* do would be just to include some version of this file. But on the other hand, maybe it could just point to the end product of this thing I've been tinkering with. Is this helpful? Comments? Bruce. --==_Exmh_754907370P Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.4 (FreeBSD) Comment: Exmh version 2.2 06/23/2000 iD8DBQE6PkxZ2MoxcVugUsMRAvb2AKCRX+LOnJZQcXfmLNE7MLTtW8DNeQCeI4TX BpWO6qoZKWVSro6Gc/enKwc= =Qqqz -----END PGP SIGNATURE----- --==_Exmh_754907370P-- 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?200012181741.eBIHfjt94333>