Date: Mon, 27 Jun 2005 21:20:43 +0200 From: "Simon L. Nielsen" <simon@FreeBSD.org> To: Roman Neuhauser <neuhauser@sigpipe.cz> Cc: freebsd-doc@freebsd.org, John Baldwin <jhb@FreeBSD.org>, pgabriel@grex.cyberspace.org Subject: Re: docs/80611: Missing items in supported hardware list on your site for FreeSD 4.11 and 5.x Message-ID: <20050627192042.GD958@zaphod.nitro.dk> In-Reply-To: <20050627085729.GA38502@isis.sigpipe.cz> References: <200506210623.j5L6NR3B004615@freefall.freebsd.org> <20050621063304.GL3346@pcwin002.win.tue.nl> <20050621064402.GP3352@kaiser.sig11.org> <200506211101.09214.jhb@FreeBSD.org> <1119371850.523.16.camel@dude.automatvapen.se> <20050627085729.GA38502@isis.sigpipe.cz>
next in thread | previous in thread | raw e-mail | index | archive | help
--7iMSBzlTiPOCCT2k
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
On 2005.06.27 10:57:29 +0200, Roman Neuhauser wrote:
> # joel@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=20
> > > drivers now? If ata's man page isn't being used to generate the hard=
ware=20
> > > notes for ata(4) then perhaps the PR should be reopened with the goal=
of=20
> > > fixing that.
> >=20
> > I've discussed this with simon and brueffer, and I have a patch that:
> >=20
> > 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.
> >=20
> > I'm not going to commit it however.
>=20
> 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.
--=20
Simon L. Nielsen
--7iMSBzlTiPOCCT2k
Content-Type: application/pgp-signature
Content-Disposition: inline
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (FreeBSD)
iD8DBQFCwFGKh9pcDSc1mlERAgIfAJ0T3ZDrrafn8V5/c4AAqSyIwEs/8wCfbhlp
26swLvH/UZy0tvZw7gu87g4=
=/1v6
-----END PGP SIGNATURE-----
--7iMSBzlTiPOCCT2k--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20050627192042.GD958>