Xref: utzoo comp.windows.x:35623 comp.unix.questions:30676 Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!sun-barr!newstop!texsun!convex!newsadm From: tchrist@convex.COM (Tom Christiansen) Newsgroups: comp.windows.x,comp.unix.questions Subject: Re: MIT X11R4 man pages glitches? Keywords: manual,troff,nroff,xlib,xt Message-ID: <1991Apr24.010946.14464@convex.com> Date: 24 Apr 91 01:09:46 GMT References: Sender: newsadm@convex.com (news access account) Reply-To: tchrist@convex.COM (Tom Christiansen) Distribution: comp Organization: CONVEX Software Development, Richardson, TX Lines: 118 Nntp-Posting-Host: pixel.convex.com > 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 .3X. Doing 'man ' > or 'man 3 ' will fail. Doing 'man 3X ' will work, but > IMHO it's a little convoluted... > Xt man pages are installed as .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 .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