Return-Path: owner-linux-doc@vger.rutgers.edu
Received: from kantti.helsinki.fi (root@kantti.Helsinki.FI [128.214.4.16]) by keos.cs.Helsinki.FI (8.6.10/H46) with ESMTP id RAA05919 for <wirzeniu@cs.Helsinki.FI>; Fri, 28 Jul 1995 17:14:43 +0300
Received: from vger.rutgers.edu (majordomo@vger.rutgers.edu [128.6.190.2]) by kantti.helsinki.fi (8.6.12+Emil1.1/8.6.5) with SMTP id RAA08718 for <wirzeniu@cc.helsinki.fi>; Fri, 28 Jul 1995 17:09:22 +0300
Received: (from majordomo@localhost) by vger.rutgers.edu (8.6.12/8.6.12) id GAA00589 for linux-doc-outgoing; Fri, 28 Jul 1995 06:19:29 -0400
Message-Id: <m0sbmPd-0000y3C@bilbo.ee.surrey.ac.uk>
Subject: linux-doc: Missing man page references
To: linux-doc@vger.rutgers.edu
Date: Fri, 28 Jul 1995 11:13:00 +0000 (GMT)
From: Wilf <G.Wilford@ee.surrey.ac.uk>
Organization: University of Surrey, Guildford, England
X-Mailer: ELM [version 2.4 PL23]
Sender: owner-linux-doc@vger.rutgers.edu
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Content-Length: 3276
Status: RO
X-Status: 

> Lars Wirzenius (wirzeniu@cc.helsinki.fi)
> Sun, 23 Jul 1995 13:53:49 +0300 (EET DST)
> 
> I don't have any ideas for missing manual pages, but the request reminded
> me of one thing that has occasionally annoyed me:
> 
> It is sometimes somewhat difficult to find the correct page. Sometimes
> this is because the names by which man(1) searches the page do not
> include the "intuitive" name by which I'm searching it. Many pages are
> known by many names (e.g., if open(2) and close(2) were combined to one
> page, the page could be known by both names). I sometimes stumble upon
> pages where one or more of the potential alternate names are missing.
> Alas, I haven't made any note about which pages they are (I'm not even
> sure they're part of the LDP pages). Perhaps someone eager could go
> through all our pages and check that all the references are there?

There is an alternative.

I noticed the problem of missing whatis references a while back and
introduced the concept of `whatis referenced' man page pointers into
mandb-2.3.x.

However, it would be relatively trivial to extract a list of the whatis
referred pages found in man-pages-x.y from the man page database. These
could then be turned into symbolic, hard or ROFF `.so' links to the
real pages...

Wilf> whatis -M /usr/man -w '*' | grep '([234579]) \[.*\]'
alphasort (3) [scandir] - scan a directory for matching entries
endutent (3) [getutent] - access utmp file entries
execlp (3) [exec]    - execute a file
getutid (3) [getutent] - access utmp file entries
getutline (3) [getutent] - access utmp file entries
hosts_ctl (3) [hosts_access] - access control library
pututline (3) [getutent] - access utmp file entries
setutent (3) [getutent] - access utmp file entries
sigmask (2) [sigblock] - block signals
utmpname (3) [getutent] - access utmp file entries

Hmmm, not that many...  The manual page on the left is referred to by
the physical manual page in square brackets, but *only* via its whatis
section.

By trying another test, this time searching in all sections and all
hierarchies on this machine, I would suggest that non LDP manual pages
are the real culprits:

Wilf> whatis -w '*' | grep '([1-9]) \[.*\]' |wc -l
    251

of which tk and tcl account for most.
 
> Another thing that would be nice is a mechanism by which it would be
> possible to find a page via other than the explicitly listed names.
> This, however, needs to be done in the browser. Something like a "man
> -k" that searches through the whole page, not just the NAME section.

Ouch.  The reason that `man -k' is relatively fast is that it searches
a prebuilt text file (database in the case of mandb) filled with a
parsed version of the NAME section of each manual page.  To search as
suggested would require either

(a) a prebuilt file containing all of the relevant parts of the man
    page (with references to the name of the actual man page)

(b) a realtime search through 1000s of possibly compressed manual
    pages! 

Neither is practical.

Wilf.

ps. The latest version of mandb is 2.3.10 and can be found in 
ftp://theora.ee.surrey.ac.uk/pub/Wilf/mandb

-- 
	Dept. of Electronic Eng.	Phone: 01483-300800 x3425
	University of Surrey		Fax: 01483-34139    
	Guildford GU2 5XH.		email: g.wilford@ee.surrey.ac.uk

