From owner-freebsd-doc@FreeBSD.ORG Sun Aug 29 21:08:56 2004 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 93E5A16A4CE; Sun, 29 Aug 2004 21:08:56 +0000 (GMT) Received: from tigra.ip.net.ua (tigra.ip.net.ua [82.193.96.10]) by mx1.FreeBSD.org (Postfix) with ESMTP id DBB2B43D41; Sun, 29 Aug 2004 21:08:55 +0000 (GMT) (envelope-from ru@ip.net.ua) Received: from heffalump.ip.net.ua (heffalump.ip.net.ua [82.193.96.213]) by tigra.ip.net.ua (8.12.11/8.12.11) with ESMTP id i7TL8pft051493 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 30 Aug 2004 00:08:52 +0300 (EEST) (envelope-from ru@ip.net.ua) Received: (from ru@localhost) by heffalump.ip.net.ua (8.13.1/8.13.1) id i7TL8uv0040427; Mon, 30 Aug 2004 00:08:56 +0300 (EEST) (envelope-from ru) Date: Mon, 30 Aug 2004 00:08:56 +0300 From: Ruslan Ermilov To: Tom Rhodes Message-ID: <20040829210856.GB40369@ip.net.ua> References: <20040827180724.GZ24054@arved.at> <20040827182012.GD774@zaphod.nitro.dk> <1093631012.634.5.camel@tl.kom.tuwien.ac.at> <20040827184829.GE774@zaphod.nitro.dk> <20040827202755.GZ37255@submonkey.net> <20040828013249.7b3f1de7@localhost.pittgoth.com> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="qcHopEYAB45HaUaB" Content-Disposition: inline In-Reply-To: <20040828013249.7b3f1de7@localhost.pittgoth.com> User-Agent: Mutt/1.5.6i X-Virus-Scanned: by amavisd-new cc: Tilman Linneweh cc: Ceri Davies cc: freebsd-doc@FreeBSD.org cc: "Simon L. Nielsen" Subject: Re: ar.4 missing 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: Sun, 29 Aug 2004 21:08:56 -0000 --qcHopEYAB45HaUaB Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sat, Aug 28, 2004 at 01:32:49AM -0400, Tom Rhodes wrote: > On Fri, 27 Aug 2004 21:27:55 +0100 > Ceri Davies wrote: >=20 > > On Fri, Aug 27, 2004 at 08:48:29PM +0200, Simon L. Nielsen wrote: > > > On 2004.08.27 20:23:32 +0200, Tilman Linneweh wrote: > > > > Am Fr, den 27.08.2004 schrieb Simon L. Nielsen um 20:20: > > > > > On 2004.08.27 20:07:25 +0200, Tilman Linneweh wrote: > > > > > > Hello, > > > > > >=20 > > > > > > Noticed that ar.4 is missing, although mentioned in ata.4, plea= se commit or > > > > > > approve this small diff: > > > > > >=20 > > > > > > http://people.freebsd.org/~arved/stuff/ar.diff > > > > >=20 > > > > > That's unfortunatly not the right solution... since we have anoth= er > > > > > ar(4) device, which is a NIC driver: :-/ > > > > >=20 > > > > > ar -- synchronous Digi/Arnet device driver > > > > >=20 > > > > > It is very unfortunate IMO, but I think it's way to late to fix. > > > >=20 > > > > Oops, you are right, i was confused because the NIC driver is i386 = only, > > > > and i tried "man 4 ar" on amd64. > > > > So maybe add the MLINKS only on !i386? > > >=20 > > > I'm not really sure if that would break POLA (as in, confusing people > > > more). I have CC'ed ru, perhaps he (or someone else) has a good idea > > > on how to make this situation better. > >=20 Note that actual devices aren't "ar", "acd", "ad", "afd", "ast", but "ataraid", "atapicd", "atadisk", "atapifd", and "atapist" (and the SYNOPSIS section of the manpage gets this right). I personally think that former MLINKS can be replaced by real device MLINKS. We have many other manpages with similar situation: - the sio(4) manpage documents "device sio" but is not MLINK'ed to "cuaa", "ttyd", etc.; - the psm(4) manpage documents "device psm" but is not MLINK'ed to "bpsm"; - and so on. I mean, it's very good when /dev entries match device driver name, but it's not required and not always possible. The /dev entries should be documented in the FILES section of the manpage. The SYNOPSIS should show the actual device driver names, not the /dev entries. > > Personally, I don't see a problem with having "man 4 ar" give you > > something different on, say, sparc64 and i386; I vaguely remember a > > similar discussion when the second ar driver was added, and the > > conclusion was that this wouldn't be a problem, I believe. >=20 "device ataraid" is MI, according to sys/conf/{NOTES,files}. > Put a note in the description: >=20 > If you are looking for ... please see .Xr blah. >=20 This is pointless: referencing to ar(4) when you're reading ar(4). Cheers, --=20 Ruslan Ermilov ru@FreeBSD.org FreeBSD committer --qcHopEYAB45HaUaB Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.5 (FreeBSD) iD8DBQFBMkXoqRfpzJluFF4RAuTRAKCb2cDSesvKafifMIS+qHzz2ff3IwCcCIhG r1mmy1LKFb43clWqor/DdsQ= =Ha5d -----END PGP SIGNATURE----- --qcHopEYAB45HaUaB--