amir@taux01.nsc.com (Amir J. Katz (Xpert)) (04/23/91)
After installing the man pages of MIT-supplied X11R4 (including patches 1-18),
I have noticed some problems with Xlib and Xt man pages.
Two files that exhibit the symptoms are 'AllPlanes.3X' and 'XCreateGC.3X', but many
others (actually most of them) have the same problems.
The problems are:
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)
4. Some man pages files contain .R macros that as far as I understand say 'use Roman font'
when used with -ms package. With -man package they create the registered symbol
(an small 'R' inside a circle). This is not mentioned in the man(7) man page.
The .R is also mentioned inside some macros within the man page itself, so I have
not removed them yet because of possible side effects.
What is this .R guy?
5. Something is wrong with the page footers. On some pages I get one line:
X Version 11 Last change: Release 4 .ie t
and on the others I get two lines:
X Version 11 Last change: Release 4 .ie t
Release 4X Version 11 % % %Last change: Release 4X Version 11 % %
I have not tested it to see whether there is odd/even rule, but I don't think
it makes any difference.
Anyway, I never get a normal footer with date and/or page number.
Any hints?
BTW, this may not be the appropriate newsgroup(s), but I assume that whoever responds to
this knows the Documentation Tools manual by heart, so I'll ask anyway:
Apparently, some man page (e.g. XCreateGC.3X) contain index creation stuff. This causes
nroff/troff/ptroff to send some output to stderr. The following is from XCreateGC:
3:XGCValues::@DEF@
4:Pixel value::
4:Plane:mask:
6:Graphics context:path:
My questions are:
6. Can this be eliminated ?
7. Is this garbage (-:) useful for anything ?
RTFM responses (with page numbers :-) are frowned upon, but accepted...
-- Thanks in advance,
--
Amir J. Katz, System Manager
Internet: amir%pilat.UUCP@taux01.nsc.com OR amir@taux01.nsc.com
UUCP: {decwrl,uunet,...}!nsc!taux01!amir
Phone: +972 52-570713
Fax: +972 52-570719
Snail-mail: Amir J. Katz, Silvaco Israel Ltd.
19 Maskit St., Herzelia, Israel 46733tchrist@convex.COM (Tom Christiansen) (04/24/91)
> 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