The Answer to All Man's Problems (part 0 of 6)

[Tom Christiansen]

Here is a deluxe man program and associated utilities written in perl.
It does everything any other man program does that I've ever seen,
plus quite a bit more.  There is documentation in the form of man 
pages as well as the paper I presented at the USENIX Large 
Installation Systems Administrations conference.  

There will be six parts to the distribution.  Cat them together
and then unshar.  Here is a list of features.  Note that the
whatis databases are stored in ndbm format for rapid access, so 
you'll need ndbm.  

Changes since the last posting include:

    *   extra utils

    *   grep feature

    *   online problem report feature

    *   dynamic determination of MANPATH

    *   bug fixes

Thanks to everyone who's sent me bug reports or fixes.

--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
--
Tom Christiansen                tchrist at convex.com      convex!tchrist

    Perl programming is an *empirical* science!  
            --Larry Wall in <10226 at jpl-devvax.JPL.NASA.GOV>