NetBSD Problem Report #9627

Received: (qmail 4677 invoked from network); 17 Mar 2000 02:36:20 -0000
Message-Id: <200003170235.VAA25057@ursula.wongs.net>
Date: Thu, 16 Mar 2000 21:35:56 -0500 (EST)
From: (Ben Wong) hackerb9@wongs.net
Reply-To: hackerb9@wongs.net
To: gnats-bugs@gnats.netbsd.org
Subject: Manual pages sometimes aren't well cross referenced.
X-Send-Pr-Version: 3.95

>Number:         9627
>Category:       misc
>Synopsis:       Manual pages sometimes aren't well cross referenced.
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    misc-bug-people
>State:          closed
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Thu Mar 16 18:39:00 +0000 2000
>Closed-Date:    Sun Nov 20 07:12:59 +0000 2016
>Last-Modified:  Sun Nov 20 07:12:59 +0000 2016
>Originator:     Ben Wong
>Release:        1.4.1
>Organization:
Georgia Institute of Technology
>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
>Release-Note:
>Audit-Trail:

From: Tim Rightnour <root@garbled.net>
To: (Ben Wong) <hackerb9@wongs.net>
Cc: gnats-bugs@gnats.netbsd.org
Subject: RE: misc/9627: Manual pages sometimes aren't well cross referenc
Date: Fri, 17 Mar 2000 08:47:23 -0700 (MST)

 On 17-Mar-00 Ben Wong wrote:
 > 
 >>Number:         9627
 ># Example:
 ># $ checkref groff
 ># groff(1) refers to
 >#      grog(1)

 Why not change the code to spit out a .Xr section (including ones listed in the
 .Xr section so nothing is lost) so that a simple cut & paste can solve the
 problem.

 Even better would be one that just fixes them.

 Just a thought.  The other option is of course, just check out a source tree,
 run your program, edit the manpages, and send us diffs.

 ---
 Tim Rightnour <root@garbled.net>
 NetBSD: Free multi-architecture OS http://www.netbsd.org/
 NetBSD Mailing lists on the web: http://mail-index.netbsd.org/

From: Ben <hackerb9@wongs.net>
To: root@garbled.net
Cc: gnats-bugs@gnats.netbsd.org
Subject: Re: misc/9627: Manual pages sometimes aren't well cross referenc
Date: Fri, 17 Mar 2000 13:10:22 -0500 (EST)

 >>>>> "Tim" == Tim Rightnour <root@garbled.net> writes:

     Tim> On 17-Mar-00 Ben Wong wrote:
     Ben>>Number:         9627
     Ben># Example:
     Ben># $ checkref groff
     Ben># groff(1) refers to
     Ben>#      grog(1)

     Tim> Why not change the code to spit out a .Xr section (including
     Tim> ones listed in the .Xr section so nothing is lost) so that a
     Tim> simple cut & paste can solve the problem.

 Good question. The answer is that I didn't want to start fixing the
 man pages until I was sure the change was warranted (or in case my
 suggestion was shot down by something I overlooked). I think of
 checkref (the program I sent) as a preview of what sort of changes
 would be made.

 By the way, not all man pages use .Xr. Some use .Br, a few use .Ir,
 and some use nothing at all. Probably the last two categories of man
 pages should be changed to use .Xr before fixing the cross-references.

     Tim> Even better would be one that just fixes them.

 Are you suggesting a fully automated program? It's an appealing idea
 but I think this job may require human intervention (at least to
 authorize changes). I don't know how often there will be cases where
 it is worse to make a reference point both ways. 

 Would you mind trying out checkref and telling me if you feel that
 full automation is reasonable?

 Thanks.

 --Ben
From: David Holland <dholland-bugs@netbsd.org>
To: gnats-bugs@netbsd.org
Cc: 
Subject: Re: misc/9627: Manual pages sometimes aren't well cross referenced.
Date: Mon, 29 Aug 2016 05:38:48 +0000

 From: "David A. Holland" <dholland@netbsd.org>
 To: source-changes@NetBSD.org
 Subject: CVS commit: othersrc/usr.bin/manxref
 Date: Mon, 29 Aug 2016 05:36:31 +0000
 Mail-Followup-To: source-changes-d@NetBSD.org

 Module Name:	othersrc
 Committed By:	dholland
 Date:		Mon Aug 29 05:36:31 UTC 2016

 Added Files:
 	othersrc/usr.bin/manxref: Makefile array.c array.h exceptions.c
 	    exceptions.h main.c manxref.1 mem.c mem.h page.c page.h pagename.h
 	    pathnames.h readpage.c readpage.h

 Log Message:
 Add manxref, a tool for analyzing man-page crossreferences across a
 whole system's worth of man pages.

 Pursuant to PR 9627, and a much simpler script therein, where it was
 suggested that man page crossreferences mostly ought to be
 bidirectional.

 This does not appear to be the case. There are a lot of cases where a
 reference in one direction does not imply a reference back; for
 example, make(1) refers to chdir(2) for good reasons, but there's no
 sensible reason for chdir(2) to refer to make(1). Likewise, lots of
 driver pages refer to bus pages for buses they attach to, but the
 reverse links aren't necessarily useful as there are a lot of them.

 Note: this program is not related to the Isle of Man.


 To generate a diff of this commit:
 cvs rdiff -u -r0 -r1.1 othersrc/usr.bin/manxref/Makefile \
     othersrc/usr.bin/manxref/array.c othersrc/usr.bin/manxref/array.h \
     othersrc/usr.bin/manxref/exceptions.c \
     othersrc/usr.bin/manxref/exceptions.h othersrc/usr.bin/manxref/main.c \
     othersrc/usr.bin/manxref/manxref.1 othersrc/usr.bin/manxref/mem.c \
     othersrc/usr.bin/manxref/mem.h othersrc/usr.bin/manxref/page.c \
     othersrc/usr.bin/manxref/page.h othersrc/usr.bin/manxref/pagename.h \
     othersrc/usr.bin/manxref/pathnames.h othersrc/usr.bin/manxref/readpage.c \
     othersrc/usr.bin/manxref/readpage.h

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

From: David Holland <dholland-bugs@netbsd.org>
To: gnats-bugs@netbsd.org
Cc: 
Subject: Re: misc/9627: Manual pages sometimes aren't well cross referenced.
Date: Sun, 20 Nov 2016 07:06:59 +0000

 Reply-To: 

 (commits to PRs < 10000 aren't autoforwarded any more)

    ------

 From: "David A. Holland" <dholland@netbsd.org>
 To: source-changes@NetBSD.org
 Subject: CVS commit: src/share/man/man4
 Date: Sun, 20 Nov 2016 07:02:21 +0000
 Mail-Followup-To: source-changes-d@NetBSD.org

 Module Name:	src
 Committed By:	dholland
 Date:		Sun Nov 20 07:02:21 UTC 2016

 Modified Files:
 	src/share/man/man4: scsi.4

 Log Message:
 Add crossreference to scsictl per note in PR 9627.


 To generate a diff of this commit:
 cvs rdiff -u -r1.30 -r1.31 src/share/man/man4/scsi.4

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

 From: "David A. Holland" <dholland@netbsd.org>
 To: source-changes@NetBSD.org
 Subject: CVS commit: src/sbin/scsictl
 Date: Sun, 20 Nov 2016 07:04:15 +0000
 Mail-Followup-To: source-changes-d@NetBSD.org

 Module Name:	src
 Committed By:	dholland
 Date:		Sun Nov 20 07:04:15 UTC 2016

 Modified Files:
 	src/sbin/scsictl: scsictl.8

 Log Message:
 Add crossreference to scsi(4) per note in PR 9627.


 To generate a diff of this commit:
 cvs rdiff -u -r1.28 -r1.29 src/sbin/scsictl/scsictl.8

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.


 From: "David A. Holland" <dholland@netbsd.org>
 To: source-changes@NetBSD.org
 Subject: CVS commit: src/lib/libc/sys
 Date: Sun, 20 Nov 2016 07:05:20 +0000
 Mail-Followup-To: source-changes-d@NetBSD.org

 Module Name:	src
 Committed By:	dholland
 Date:		Sun Nov 20 07:05:20 UTC 2016

 Modified Files:
 	src/lib/libc/sys: wait.2

 Log Message:
 Add crossreference to fork(2) per note in PR 9627.


 To generate a diff of this commit:
 cvs rdiff -u -r1.37 -r1.38 src/lib/libc/sys/wait.2

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

State-Changed-From-To: open->closed
State-Changed-By: dholland@NetBSD.org
State-Changed-When: Sun, 20 Nov 2016 07:12:59 +0000
State-Changed-Why:
I think the conclusion is that trying to automate this isn't going to work.
I committed a manxref tool to othersrc if anyone wants to use it to prepare
lists of potentially missing references and review them; also any specific
suggestions can of course be handled. (The ones cited in the original
report are all fixed now.)


>Unformatted:

Home	PR Database Search