>Number:         4377
>Category:       misc
>Synopsis:       various manual pages have bad titles (.Dt)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    misc-bug-people (Misc Bug People)
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Tue Oct 28 17:20:03 1997
>Last-Modified:
>Originator:     Chris G. Demetriou
>Organization:
Kernel Hackers 'r' Us
>Release:        NetBSD-current as of October 27, 1997
>Environment:
System: NetBSD brick.demetriou.com 1.3_ALPHA NetBSD 1.3_ALPHA (BRICK) #8: Mon Oct 27 22:40:17 PST 1997 cgd@brick.demetriou.com:/usr/src/sys/arch/i386/compile/BRICK i386


>Description:
	Various manual pages have bogus titles (or other related
	problems), which are then incorporated into the whatis.db
	which is the used by apropos.  The output of apropos for those
	pages is less useful than it should be.  In general, if you
	"apropos" a term, you should be able to 'man' the result.
	For instance 'apropos catenate' yields:

	114 [brick] 0.unwritten % apropos catenate
	cat (1) - concatenate and print files
	ccd (4) - Concatenated Disk Driver
	ccdconfig (8) - configuration utility for the concatenated disk driver
	strcat (3) - concatenate strings

	You should be able to, and can, look up any of those manual
	pages in those sections, e.g. via "man 1 cat".

	Some pages end up having bogus entries in the whatis.db which
	prevent this from being possible.  Those problem entries
	(along with the locations of their manual pages) are:

	 (mi_switch) - switch to another process context

		from src/share/man9/ctxsw.9

		* bogus section, presumably because the manual
		  page uses "CONTEXT SWITCH" for its .Dt entry
		  (given the name of the page, CTXSW would probably
		  be more correct),
		* doesn't include cpu_switch() which is also described
		  by the page and has a manual page link,
		* the title (i.e. what appears in the page headers,
		  "CONTEXT SWITCH") is unrelated to the manual page
		  name(s), making it harder than it should be to
		  look the manual page if you're looking at a
		  printed version, etc.

	ARP (9) - externally visible ARP functions

		from src/share/man9/arp.9

		* should be 'arp', since that's the name of the page.
	
	Chess (GNU) - GNU Chess

		from src/gnu/games/chess/DOCUMENTATION/MAN-PAGE

		* Manual page name (upper case) and section (there is no GNU
		  section) are wrong.

	ETHERSUBR (9) - Ethernet and FDDI driver support functions and macros

		from src/share/man9/ethersubr.9

		* should be 'ethersubr', since that's the name of the page.

	GNU as (1) - the portable GNU assembler.

		from src/gnu/usr.bin/gas/as.1

		* should just be "as" not "GNU as" since 'man "GNU as"'
		  doesn't (probably can't!) work.

	LIST_ENTRY, LIST_HEAD, LIST_HEAD_INITIALIZER, LIST_INIT, LIST_INSERT_AFTER, LIST_INSERT_BEFORE, LIST_INSERT_HEAD, LIST_REMOVE, SIMPLEQ_ENTRY, SIMPLEQ_HEAD, SIMPLEQ_HEAD_INITIALIZER, SIMPLEQ_INIT, SIMPLEQ_INSERT_HEAD, SIMPLEQ_INSERT_TAIL, SIMPLEQ_INSERT_AFTER, SIMPLEQ_REMOVE_HEAD, TAILQ_ENTRY, TAILQ_HEAD, TAILQ_HEAD_INITIALIZER, TAILQ_INIT, TAILQ_INSERT_AFTER, TAILQ_INSERT_BEFORE, TAILQ_INSERT_HEAD, TAILQ_INSERT_TAIL, TAILQ_REMOVE, CIRCLEQ_ENTRY, CIRCLEQ_HEAD, CIRCLEQ_HEAD_INITIALIZER, CIRCLEQ_INIT, CIRCLEQ_INSERT_AFTER, CIRCLEQ_INSERT_BEFORE, CIRCLEQ_INSERT_HEAD, CIRCLEQ_INSERT_TAIL, CIRCLEQ_REMOVE (3) - implementations of lists, tail queues, and circular queues

		from src/share/man3/queue.3

		* the header is correct, but the manual page links
		  aren't.  The manual page links create manual entries
		  like list_entry(3), etc., when they really _should_ be
		  LIST_ENTRY(3).

	MBUF (9) - functions and macros for managing memory used by networking

		from src/share/man9/mbuf.9

		* should be 'mbuf' since that's the name of the manual page.

	TP (4) - ISO Transport Protocol

		from src/share/man4/tp.4

		* shoul dbe 'tp' since that's the name of the manual page.

>How-To-Repeat:
	apropos any of the above things.  try to look up their
	manual pages from the apropos output.

>Fix:
	Fixes suggested above.
>Audit-Trail:
>Unformatted: