moving man pages from monolith to modular

[Alan Coopersmith]

I've been playing a bit with the man page bits in the conversion
and hit across a few issues in trying to make automake do everything
Imake currently does.

1) InstallManPageLong:  Long long ago, in the dark days before BSD rewrote
     the filesystem, Unix was limited to 14 character filenames.   This
     persisted in the SysV line up to SysVR3.   X has traditionally supported
     those poor souls stuck on these backwards OS'es by keeping file names
     shorter than 14 characters, which is why the libX11 source & man page
     files are so awkwardly named.   For most OS'es (in the current Imake
     configs, everything that isn't (SystemV & not SVR4), which is pretty
     much everything in widespread use today), Imake provides a macro
     InstallManPageLong that maps the short name to the long name.
     Replicating this in automake seems very messy, and since we've already
     broken the 14-character filename length limit elsewhere in the tree
     without complaint, seems unnecessary.   Therefore, I'd like to suggest
     we use the modularization as our chance to rename the man pages to their
     full names and will change symlink.sh entries to do this:
	action      BlkPScrn.man    BlackPixelOfScreen.man
	action      Dis3C.man       DisplayOfCCC.man
	[...]

2) InstallManPageAliases: Many of the man pages document multiple functions,
    so the Imakefiles include rules to generate "shadow" man pages like:
     InstallManPageAliases(DisplayOfCCC,$(MANDIR),VisualOfCCC
       ScreenNumberOfCCC ScreenWhitePointOfCCC ClientWhitePointOfCCC)
    (these man pages consist of simply a .so macro listing the name of the
     real man page to show).   For these I'm not sure if it's best to just
     check the shadow pages into CVS or if it's worth trying to replicate
     the Imake macros in automake syntax.

3) CppManTarget:  Most of the man pages are run through cpp now, to do
    things like substitute in the current Xorg version number, set the man
    page  sections to the correct ones for the current systems, set
    ProjectRoot to match the installation target, allow substituting the
    server name with Xorg or XFree86 as necessary, and so on.   I've been
    able to create rules to do most of this, but copying them into every
    single module seems cumbersome and difficult to update.   Are we going
    to have some sort of common repository for autoconf macros and automake
    include files shared across all the modules?   Also, what should we use
    for the __xorgversion__  value in the man pages?  Will it become the
    name & version of the module it's shipping in instead?

-- 
	-Alan Coopersmith-           alan.coopersmith at sun.com
	 Sun Microsystems, Inc. - X Window System Engineering