From rfg@monkeys.com Wed Oct 27 17:06:38 1999
Return-Path: <rfg@monkeys.com>
Received: from monkeys.com (i180.value.net [206.14.136.180])
	by hub.freebsd.org (Postfix) with ESMTP id 0A23814CEB
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 27 Oct 1999 17:06:25 -0700 (PDT)
	(envelope-from rfg@monkeys.com)
Received: (from rfg@localhost)
	by monkeys.com (8.9.3/8.9.3) id RAA64183;
	Wed, 27 Oct 1999 17:06:22 -0700 (PDT)
Message-Id: <199910280006.RAA64183@monkeys.com>
Date: Wed, 27 Oct 1999 17:06:22 -0700 (PDT)
From: "Ronald F. Guilmette" <rfg@monkeys.com>
Reply-To: rfg@monkeys.com (Ronald F. Guilmette)
To: FreeBSD-gnats-submit@freebsd.org
Subject: Wrong manpage produced by `man 4 fd'
X-Send-Pr-Version: 3.2

>Number:         14563
>Category:       docs
>Synopsis:       Wrong manpage produced by `man 4 fd'
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Oct 27 17:10:01 PDT 1999
>Closed-Date:    Wed Jun 21 14:57:57 PDT 2000
>Last-Modified:  Wed Jun 21 14:58:16 PDT 2000
>Originator:     Ronald F. Guilmette
>Release:        FreeBSD 3.3-RELEASE i386
>Organization:
E-Scrub Technologies, Inc.
>Environment:

>Description:

	Typing "man 4 fd" produces a man page talking generally about UNIX
	file descriptors.

	This is in conflict with the established convention that `man 4 foo'
	produces documentation for the `foo' device type (and its driver).

	`man 4 fd' should produce documentation relating to the `fd' (floppy
	disk) device type.  (See `man 4 fdc')

>How-To-Repeat:

	man 4 fd

>Fix:

	Use `man 4 fdc' instead.

>Release-Note:
>Audit-Trail:

From: Nik Clayton <nik@freebsd.org>
To: "Ronald F. Guilmette" <rfg@monkeys.com>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/14563: Wrong manpage produced by `man 4 fd'
Date: Sun, 12 Dec 1999 10:46:42 +0000

 On Wed, Oct 27, 1999 at 05:06:22PM -0700, Ronald F. Guilmette wrote:
 > >Synopsis:       Wrong manpage produced by `man 4 fd'
 >
 > >Description:
 > 
 > 	Typing "man 4 fd" produces a man page talking generally about UNIX
 > 	file descriptors.
 > 
 > 	This is in conflict with the established convention that `man 4 foo'
 > 	produces documentation for the `foo' device type (and its driver).
 > 
 > 	`man 4 fd' should produce documentation relating to the `fd' (floppy
 > 	disk) device type.  (See `man 4 fdc')
 > 
 > >How-To-Repeat:
 > 
 > 	man 4 fd
 > 
 > >Fix:
 > 
 > 	Use `man 4 fdc' instead.
 
 Sorry, I don't understand.  The situation is as you say it is.  Are you
 documenting the fact, or do you want it fixed?
 
 If you want it fixed, did you have anything in mind?
 
     % apropos fd
 
 works, with the fdc manual page being the third thing it lists.  As things
 stand, section 4 of the manuals seems to be the right place to put both
 the fd and fdc manual pages.
 
 N
 -- 
     If you want to imagine the future, imagine a tennis shoe stamping
     on a penguin's face forever.
         --- with apologies to George Orwell
 

From: "Ronald F. Guilmette" <rfg@monkeys.com>
To: Nik Clayton <nik@freebsd.org>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/14563: Wrong manpage produced by `man 4 fd' 
Date: Mon, 13 Dec 1999 01:48:04 -0800

 In message <19991212104642.B82758@catkin.nothing-going-on.org>, you wrote:
 
 >On Wed, Oct 27, 1999 at 05:06:22PM -0700, Ronald F. Guilmette wrote:
 >> >Synopsis:       Wrong manpage produced by `man 4 fd'
 >>
 >> >Description:
 >> 
 >> 	Typing "man 4 fd" produces a man page talking generally about UNIX
 >> 	file descriptors.
 >> 
 >> 	This is in conflict with the established convention that `man 4 foo'
 >> 	produces documentation for the `foo' device type (and its driver).
 >> 
 >> 	`man 4 fd' should produce documentation relating to the `fd' (floppy
 >> 	disk) device type.  (See `man 4 fdc')
 >> 
 >> >How-To-Repeat:
 >> 
 >> 	man 4 fd
 >> 
 >> >Fix:
 >> 
 >> 	Use `man 4 fdc' instead.
 >
 >Sorry, I don't understand.  The situation is as you say it is.  Are you
 >documenting the fact, or do you want it fixed?
 
 I'd like to see it fixed.
 
 >If you want it fixed, did you have anything in mind?
 
 I thought that the solution I was proposing was abundantly clear in what
 I wrote:
 
 >>      `man 4 fd' should produce documentation relating to the `fd' (floppy
 >>      disk) device type.
 
 >As things
 >stand, section 4 of the manuals seems to be the right place to put both
 >the fd and fdc manual pages.
 
 I agree completely, but `man 4 fd' *should* yield a man page that talks
 about floppy disk device files... *not* one that talks about UNIX file
 descriptors.  (You can just trash the one that talks about file descrip-
 tors as far as I'm concerned.  If people want to know about those, they
 should go buy a general book about UNIX/C programming.)
 

From: Nik Clayton <nik@freebsd.org>
To: rfg@monkeys.com
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/14563: Wrong manpage produced by `man 4 fd'
Date: Tue, 14 Dec 1999 13:29:52 +0000

 On Mon, Dec 13, 1999 at 01:48:04AM -0800, Ronald F. Guilmette wrote:
 > >If you want it fixed, did you have anything in mind?
 > 
 > I thought that the solution I was proposing was abundantly clear in what
 > I wrote:
 > 
 > >>      `man 4 fd' should produce documentation relating to the `fd' (floppy
 > >>      disk) device type.
 > 
 > >As things
 > >stand, section 4 of the manuals seems to be the right place to put both
 > >the fd and fdc manual pages.
 > 
 > I agree completely, but `man 4 fd' *should* yield a man page that talks
 > about floppy disk device files... *not* one that talks about UNIX file
 > descriptors.  (You can just trash the one that talks about file descrip-
 > tors as far as I'm concerned.  If people want to know about those, they
 > should go buy a general book about UNIX/C programming.)
 
 Yeah, but the problem is that different people have different ideas about
 what the default should be.
 
 /dev/fd is a directory of file descriptors, not a floppy disk device control
 node, so making fd(4) give information about the floppy disk device would
 then leave /dev/ and the manual pages inconsistent, which would be bad.
 
 Note, also, that manual pages like sa(4) or da(4) all stem from 'device'
 lines in the kernel config file, whereas the floppy disk entries stem
 from 'disk' lines in the kernel config file.
 
 Your best bet is probably to take this up with the -hackers mailing list,
 and see what the prevailing sentiment there is.
 
 N
 -- 
     If you want to imagine the future, imagine a tennis shoe stamping
     on a penguin's face forever.
         --- with apologies to George Orwell
 
State-Changed-From-To: open->closed 
State-Changed-By: nik 
State-Changed-When: Wed Jun 21 14:57:57 PDT 2000 
State-Changed-Why:  
Executive decision.  I think the man page assignment is OK. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=14563 
>Unformatted:
