>Number:         5551
>Category:       misc
>Synopsis:       machine independent device driver man page organization
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    misc-bug-people (Misc Bug People)
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Jun  7 03:35:01 1998
>Last-Modified:
>Originator:     Erik E. Fair
>Organization:
International Organization of Internet Clock Watchers
>Release:        NetBSD-current 19980601
>Environment:
	
System: NetBSD digital.clock.org 1.3 NetBSD 1.3 (DIGITAL) #1: Mon May 25 14:16:49 PDT 1998 fair@digital.clock.org:/usr/src/sys/arch/sparc/compile/DIGITAL sparc


>Description:
	NetBSD's section 4 manual pages come in two flavors:

	1. utterly machine dependent, will never see this device
	on any other platform.

	2. machine independent, seen on many other platforms; usually
	a common driver is used, with appropriate bus glue.

	For the latter case, we should be writing man pages for
	the top level of section 4, instead of several different
	copies for each machine in the subdirectories, because it
	is easier to maintain one file with complete information,
	than several different copies with substantially the same
	information.

>How-To-Repeat:
	cd /usr/share/man/man4
	ls -l */le.4
	-r--r--r--  1 root  wheel  3870 Mar 18 02:36 amiga/le.4
	-r--r--r--  1 bin   bin    3695 Oct 23  1997 hp300/le.4
	-r--r--r--  1 root  wheel  2106 Mar 18 02:36 i386/le.4
	-r--r--r--  1 root  wheel  3760 Mar 21 08:11 pmax/le.4
	-r--r--r--  1 bin   bin    3716 Oct 17  1997 sparc/le.4
	-r--r--r--  1 bin   bin    2790 Oct 17  1997 sun3/le.4
>Fix:
	For an example of a man page for multiple platforms done
	up in the top level, see si(4).

	I suggest that all drivers which exist on more than one
	platform (e.g. le(4), esp(4), etc) be redone that way.
>Audit-Trail:
>Unformatted: