ar.4 missing

[Ruslan Ermilov]

On Sat, Aug 28, 2004 at 01:32:49AM -0400, Tom Rhodes wrote:
> On Fri, 27 Aug 2004 21:27:55 +0100
> Ceri Davies <ceri at submonkey.net> wrote:
> 
> > 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,
> > > > > > 
> > > > > > Noticed that ar.4 is missing, although mentioned in ata.4, please commit or
> > > > > > approve this small diff:
> > > > > > 
> > > > > > http://people.freebsd.org/~arved/stuff/ar.diff
> > > > > 
> > > > > That's unfortunatly not the right solution... since we have another
> > > > > ar(4) device, which is a NIC driver: :-/
> > > > > 
> > > > >      ar -- synchronous Digi/Arnet device driver
> > > > > 
> > > > > It is very unfortunate IMO, but I think it's way to late to fix.
> > > > 
> > > > 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?
> > > 
> > > 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.
> > 
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.
> 
"device ataraid" is MI, according to sys/conf/{NOTES,files}.

> Put a note in the description:
> 
> If you are looking for ... please see .Xr blah.
> 
This is pointless: referencing to ar(4) when you're reading ar(4).


Cheers,
-- 
Ruslan Ermilov
ru at FreeBSD.org
FreeBSD committer
-------------- 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/20040830/c089b03f/attachment.sig>