docs/80611: Missing items in supported hardware list on your site for FreeSD 4.11 and 5.x

[Simon L. Nielsen]

On 2005.06.27 10:57:29 +0200, Roman Neuhauser wrote:
> # joel at automatvapen.se / 2005-06-21 18:37:30 +0200:
> > On Tue, 2005-06-21 at 11:01 -0400, John Baldwin wrote:
> > > Aren't the hardware notes supposed to be generated from the man pages for most 
> > > drivers now?  If ata's man page isn't being used to generate the hardware 
> > > notes for ata(4) then perhaps the PR should be reopened with the goal of 
> > > fixing that.
> > 
> > I've discussed this with simon and brueffer, and I have a patch that:
> > 
> > 1.  Adds a standard HARDWARE section to the ata(4) manual page.
> > 2.  Makes the hardware notes use the ata(4) manual page for automatic
> > generation.
> > 3.  Adds a bunch of supported chipsets that's missing in the ata(4)
> > manual page.
> > 
> > I'm not going to commit it however.
> 
>     Out of curiosity: why not?

OK, this one is really for me (sorry about the delay in commenting on
the thread)...

The main problem here is, what exactly is worth documenting?  In
general almost all ATA chipsets will just work (note ATA RAID is a
different issue) so most of the time you don't really need any
hardware notes for ATA.  If we ignore that for a moment, I see the
follow options:

- Document all supported chipsets.

  Pro: It's probably possible to keep this more or less up-to-date by
       following ata(4) commits.

  Con: It's not really useful in most cases since you often do not
       know, and can't find out, which chipset is on some motherboard
       or controller card before purchasing the device and looking at
       which chip really is on the card.

- Document all supported motherboards and cards.

  Pro: You get a usable list.

  Con: It would be impossible to keep such a list up-to-date and it
       would be huge.

As you probably see neither option is really good, which is why
nothing has really been done about it.  I actually did convert ata(4)
when doing the original automatically generated hardware notes so it
had a HARDWARE section and had automatic generation of the Hardware
Notes for ata(4), but I did not commit it since it did not really seem
useful.

Basically I'm not really sure what's the best thing to do and neither
are the people I have disussed this with, e.g. brueffer and joeld.
Hence the current status-quo.

If someone has a good idea on how to handle this please speak
up.  Also note that I don't object to someone converting the current
ata(4) manual page to the "new" format, I just don't find it too
useful.

-- 
Simon L. Nielsen
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20050627/eec8fbc9/attachment.sig>