Subject: linux-doc: Missing man page references
From: Wilf <[email-masked]>
To: [email-masked]
Date: Fri, 28 Jul 1995 11:13:00 +0000 (GMT)

> Lars Wirzenius ([email-masked])
> 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: [email-masked]