Hardware notes

[Bruce A. Mah]

Hi all--

Here's a crazy idea for the hardware notes...hopefully it won't turn 
into a huge bikeshed.

The problem is that our hardware notes are just too darn hard to 
maintain.  A lot of times, updating this document means trolling commit 
messages for updates to manpages, driver commits, and so on.  Due to 
the way we mark up the document, additions are fairly labor-intensive.  
Because we currently list individual models of NICs, disk controllers, 
and so on, the list is extremely long, and prone to error, especially 
for non-i386 platforms.

I propose to gut out the "supported devices" section of the hardware
notes, down to the level of device drivers in most cases.  So instead of
trying to give an exhaustive list of devices supported, we'd list a
class of device (e.g. "DEC/Intel 21143 Fast Ethernet controllers and
compatibles"), a pointer to the manpage, and some remarks.  Essentially
the hardware notes would become an annotated list of pointers to device
drivers (plus the platform-specific information, which would remain
intact).  It would become (remain?) incumbent on the manual pages to
have lists of individual devices...most of them do this anyways.

This has the advantage of not needing to track manpage updates for
information which is kind of redundant anyways.  The list becomes much
shorter and easier to use, as well as easier to maintain.

A disadvantage is that if someone has a random device (where they don't
know anything about it other than its name), it's not immediately
obvious what driver would support it.  Perhaps more descriptive
annotations would help here.

Thoughts?

Bruce.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 223 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20030808/f78cb4fe/attachment.sig>