>Number:         9627
>Category:       misc
>Synopsis:       Manual pages sometimes aren't well cross referenced.
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    misc-bug-people (Misc Bug People)
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Thu Mar 16 18:39:00 2000
>Last-Modified:
>Originator:     Ben Wong
>Organization:
Georgia Institute of Technology
>Release:        1.4.1
>Environment:
	
System: NetBSD ursula.wongs.net 1.4.1 NetBSD 1.4.1 (AMNESIAC) #13: Wed Mar 15 23:03:03 EST 2000 root@:/usr/src/sys/arch/i386/compile/AMNESIAC i386


>Description:

While the NetBSD manual pages are generally excellent they are
occasionally not well cross-referenced (particularly for new or
platform specific programs) which makes it hard to learn about
features one might not have heard of.

For example, the man page for disklabel(8) doesn't mention mbrlabel(8)
in the SEE ALSO section.

>How-To-Repeat:

Just poke around in the man pages:

man sd			# It doesn't refer to scsictl(8). 
man scsi		# Nor does this.
man 2 wait  		# Somehow neglects to reference fork(2). 
man scsictl		# Does refer to sd(4) but not scsi(4).
man fork		# Does refer to wait(2).

>Fix:

The fix may not be as hard as it appears. Most of the missing
references, do exist in the reverse direction (e.g., sd <-- scsictl).
It would not be difficult to create a script to update all SEE ALSO
section references to be bidirectional.

I don't think blindly changing everything is desirable so I'd suggest
instead a script to show, for a given man page, if the man pages in
its SEE ALSO section refer back to it. Someone could run that program
on every man page and then make the modifications by hand. That person
could also decide when a reference shouldn't be two-way.

Here is the program described in the previous paragraph:

-------- CUT HERE --------
#!/bin/sh
# Usage: checkref title [section]
#
# Checks if a man page is listed in the SEE ALSO section of the man
# pages listed in its SEE ALSO section. That is, do the man pages that
# X points to, point back to X? 
# 
# Example:
# $ checkref groff
# groff(1) refers to
# 	grog(1)
# 	troff(1)
# 	tbl(1)
# 	pic(1) which does not refer back.
# 	eqn(1)
# 	soelim(1) which does not refer back.
# 	refer(1) which does not refer back.
# 	grops(1)
# 	grodvi(1)
# 	grotty(1)
# 	gxditview(1) which does not have a man page.
# 	groff_font(5) which does not refer back.
# 	groff_out(5) which does not refer back.
# 	groff_ms(7)
# 	me(7) which does not refer back.
# 	groff_char(7)
# 	msafer(7)
#
# Ben Wong
# hackerb9@nospam.wongs.net
# 2000 March 15

# The function getxref() returns the cross references.
# Input: $1 == title, $2 == section (optional).
# Output: $XREFS, $TITLE, $SECTION
getxref () {
    # Find out where the source for the requested manpage is stored.
    FILE=`man -w $1 2>/dev/null | grep man/man$2 | head -1`
    if [ -z "$FILE" ]; then 
	if [ "$3" != "noexit" ]; then
	    echo "checkref: Can't find man page for $1${2:+(}${2}${2:+)}"; 
	    exit 2; 
	else
	    return 1;
	fi
    fi

    # Set the return values for this function.
    TITLE=$1
    SECTION=`echo $FILE | sed 's/^.*man//
			       s#/.*$##'`
    XREFS=`cat $FILE | sed -n '1,/^\.S[Hh].*SEE ALSO/d
			       /^\.S[Hh]/,$d
			       /^\.[XBI][Rr] *[^ ]* [ (]*[0-9][0-9]*[) ,]*$/!d
			       s/[(),]//g
			       s/^\.[XBI][Rr]//p'`

    # The sed program for XREFS simply strips of everything until the
    # SEE ALSO line, removes any garbage, and then prints out lines
    # which are cross references. The "garbage" removed are parens,
    # commas, and lines which aren't of the form ".Xr groff (1) ,".

    # NetBSD's man pages are inconsistent about which macro to use to
    # specify a cross reference. Most of them use .Xr to mark the
    # cross references. However, GNU man pages (such as for groff) use
    # .BR, and some old NetBSD man pages (such as vmstat) use .Ir, so
    # I've allowed those to work too. There are some man pages (such
    # as top(1)) which do not mark the crossreference. This script
    # does not deal with those.

    # If making changes to the above sed program, be sure to test out
    # checkref on the following man pages: mdoc.samples, MFREE, groff,
    # and vmstat.

}


# Main part of program begins here.

if [ -z "$1" ]; then echo "Usage: checkref title [section]"; exit 1; fi

getxref $1 $2
T=$TITLE; S=$SECTION

if [ -z "$XREFS" ]; then
    echo "$T($S) doesn't use .Xr, .Br, or .Ir to refer to any other man pages."
else
    echo "$T($S) refers to"
    set $XREFS
    while [ ! -z "$2" ]
    do
	echo -n "	$1($2)"
	if getxref $1 $2 noexit; then
	    if echo $XREFS | egrep -q "$T *$S"; then
		echo
	    else
		echo " which does not refer back."
	    fi
	else
	    echo " which does not have a man page."
	fi
	shift; shift
    done
fi

# Fin
>Audit-Trail:
>Unformatted: