MIT X11R4 man pages glitches?

[Amir J. Katz Xpert]

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 at taux01.nsc.com OR amir at 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 46733