MIT X11R4 man pages glitches?

[Tom Christiansen]

> After installing the man pages of MIT-supplied X11R4 (including patches 1-18),
> I have noticed some problems with Xlib and Xt man pages.

> 1. The Xlib man pages are installed as <something>.3X. Doing 'man <something>'
>    or 'man 3 <something>' will fail. Doing 'man 3X <something>' will work, but
>    IMHO it's a little convoluted...

>    Xt man pages are installed as <something>.3Xt which will NEVER work,
>    since 'man' treats its first argument as a section number ONLY if it 1-
>    or 2-character long. Thus 'man 3Xt foo' will say 'no manual entry for 3Xt'.

>    I solved these kinks by renaming all pages to <something>.3.

> 2. The man pages do not contain 
>       '\" et
>    as their first line, thus 'man' command does not know that it has to use
>    'tbl' and 'eqn' before [t/n]roff-ing the file. (this what 'man man' says).

>    I solved this by prepending each file with the above line.

> 3. Most man pages files contain descriptions of more than one routine or macro (example:
>    AllPlanes.3X). After creating the 'whatis' database, doing 'apropos BlackPixel'
>    will show it, together with AllPlanes, but 'man BlackPixel' will fail.

>    I solved this by writing a script that will create BlackPixel.3 (and all the other
>    routines/macros described in a man page). All of them contain just one line:
>       .so man3/AllPlanes.3   (or whatever)

All the above problems are taken care of by my perl rewrite of the man
program.  You can get the package via anon ftp from convex.com in
/pub/man.shar.Z, or I can mail it to you.  Here is the FEATURES file:

--tom

Features include but are not limited to:

    *   almost always faster than standard man (try 'man me')

    *	take much less diskspace for catpages

    *	supports per-tree tmac macros
    
    *	compressed man and cat files

    *	user-definable man path via $MANPATH or -M optoin
    
    *  $MANPATH autoconfigged based on $PATH if not set

    *   user-definable section search order via -S or $MANSECT.  Thus
	programmers can get stty(3) before stty(1).
    
    *	$PAGER support

    *	show all the places you would find a man page (-w option)
	and in what order.

    *   display all available man page on a topic (-a option)
    
    *   no limits on what subsections go where (if you want to add 7x, ok)

    *   support for multi-char sections like man1m/*.1m or manavs/*.avs

    *   man -K for regexp apropos

    *   grep through all the man pages in $MANPATH

    *   section and subsection indexing for long man pages

    *   support for alternate architectures docs on same machine

    *	ability to run man on a local file 

    *	ability to easily troff (or preview) a man page

    *	recognizes embedded filter directives for tbl and eqn

    *	does the right thing for man tree that don't have DBM whatis files

    *   support for connecting online problem reports to right man page
   
    *   there's an extended usage message (man -U) for further help
	and to show current defaults.


Here are some features of this version of makewhatis:

    *	it's faster.

    *	tries hard to make pretty output, stripping troff directives.

    *   doesn't blow up on more files in a man directory 
	than the shell will glob.  

    *   accepts troff string macros for the dashes in the
	the NAME section.

    *   prints a diagnostic for a malformed NAME section.

    *   detects linked (hard, soft, or via .so) man pages

    *   finds *all* references in the NAME section.

    *   recognizes MH's man macros (and .Sh from lwall).

    *   many other things that makewhatis used to do wrong

Here are some supporting utilities that are included:

    *   catman -- new version that groks compressed files

    *   catwhatis -- display the whatis databases

    * 	straycats -- find cat pages with no man page ancestor

    *   countman -- find how many man pages you can get at

    *   cfman -- find bad SEE ALSO references in man pages