From owner-freebsd-doc@FreeBSD.ORG Tue Aug 12 14:08:03 2003 Return-Path: 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 D04D137B409 for ; Tue, 12 Aug 2003 14:08:02 -0700 (PDT) Received: from a.smtp-out.sonic.net (a.smtp-out.sonic.net [208.201.224.38]) by mx1.FreeBSD.org (Postfix) with SMTP id A14184400D for ; Tue, 12 Aug 2003 14:07:31 -0700 (PDT) (envelope-from bmah@intruder.kitchenlab.org) Received: (qmail 1690 invoked from network); 12 Aug 2003 19:23:15 -0000 Received: from turbo.sonic.net (208.201.224.26) by a.smtp-out.sonic.net with SMTP; 12 Aug 2003 19:23:15 -0000 Received: from intruder.kitchenlab.org (adsl-64-142-29-77.sonic.net [64.142.29.77]) by turbo.sonic.net (8.11.6p2/8.8.5) with ESMTP id h7CJNF412133; Tue, 12 Aug 2003 12:23:15 -0700 X-envelope-info: Received: from intruder.kitchenlab.org (bmah@localhost [127.0.0.1]) h7CJNEmh067291; Tue, 12 Aug 2003 12:23:14 -0700 (PDT) (envelope-from bmah@intruder.kitchenlab.org) Received: (from bmah@localhost) by intruder.kitchenlab.org (8.12.9/8.12.9/Submit) id h7CJNE0S067290; Tue, 12 Aug 2003 12:23:14 -0700 (PDT) (envelope-from bmah) Date: Tue, 12 Aug 2003 12:23:14 -0700 From: "Bruce A. Mah" To: "Simon L. Nielsen" Message-ID: <20030812192314.GB67179@intruder.kitchenlab.org> References: <200308082326.h78NQpmh056949@intruder.kitchenlab.org> <20030809000230.GA53916@FreeBSD.org> <20030810000622.GF396@FreeBSD.org> <20030812152843.GA64916@intruder.kitchenlab.org> <20030812185410.GA7418@FreeBSD.org> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="CdrF4e02JqNVZeln" Content-Disposition: inline In-Reply-To: <20030812185410.GA7418@FreeBSD.org> User-Agent: Mutt/1.4.1i X-Image-Url: http://www.employees.org/~bmah/Images/bmah-cisco-small.gif X-url: http://www.employees.org/~bmah/ cc: "Bruce A. Mah" cc: freebsd-doc@FreeBSD.org cc: Ruslan Ermilov cc: Mark Linimon Subject: Re: Hardware notes X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 12 Aug 2003 21:08:03 -0000 --CdrF4e02JqNVZeln Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable If memory serves me right, Simon L. Nielsen wrote: > On 2003.08.12 08:28:43 -0700, Bruce A. Mah wrote: > >=20 > > I'm not totally convinced either. With my "devil's advocate" hat on: > >=20 > > 1. The manpages you wrote up (dc/asr/twe) seem to be some of the > > better-maintained manpages in the tree. Examples of manpages that > > aren't quite ready for this yet are an(4) and ahc(4). >=20 > Yes, there will certainly be some pages which require some work before > they can be used this way, but I think that should be a doable task. I admit I don't have a good handle on the magnitude of the work that'd be involved. > > 2. If we do this, I'd definitely like the option to turn off the > > lists of devices and just keep the descriptions. One concern I >=20 > Yes, I also think this should be fairly simple to do if the lists > extracted from the manual pages are used in the Hardware notes as SGML > entities. We could just generate some dummy empty entities for a > hardware list without the details. Sounds good. > > have about the hardware notes is that they're too long, and it's > > really hard to get an overall feel for what we support. >=20 > Perhaps both the full hardware notes and the brief version could both be > generated, and linked to each other, like the single/split HTML files. Hmmm...that's a thought. > > 3. Only half an objection, but building the hardware notes now > > requires an up-to-date checked-out copy of the manpage sources. >=20 > AFAIR it currently requires the doc/ tree, so I don't see this as much > of a problem to also require src/share/man/man4. Well, I said it was only half of an objection. It would change my operating procedures, and the Web site build scripts would work differently. > > So my first inclination would be to hold off on this, at least for the > > first pass of a cleanup plan. (Maybe we could add the device lists as > > a build-time option later?) >=20 > I actuall think it would be simpler to do this if the hardware notes > aren't as "cluddered" with the device lists, so waiting should be no > problem. OK. > BTW, I noticed that the hardware notes for some drivers actually > contained more supported devices than the manual pages, so somebody > should probably try to update the manual pages with the missing devices. > (A task on http://www.freebsd.org/docproj/current.html perhaps)? Sure, sounds good. Besides the hardware notes, possible places to troll for supported device information include the source code for the drivers themselves (looking for the probe/attach messages) and src/sys/dev/usb/usbdevs. Also bugging the driver maintainers has been known to work. :-) Bruce. --CdrF4e02JqNVZeln Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.2 (FreeBSD) iD8DBQE/OT6i2MoxcVugUsMRArAfAKC8qpqSB5ZcIGw4cIDLYav6Ib3/HwCgkMix Zz6NgcWgr2NFfpREeQ9fUqM= =CaQG -----END PGP SIGNATURE----- --CdrF4e02JqNVZeln--