moving man pages from monolith to modular

[Kevin E Martin]

On Sun, May 22, 2005 at 11:10:48AM -0700, Alan Coopersmith wrote:
> 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
> 	[...]

This sounds like a good idea.

> 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.

The InstallManPageAliases macro looks fairly straightforward, but it
might be better to just include the files directly in CVS.

Another solution would be for us to simply link the shadow man pages to
the real ones instead of using the .so roff request.  This could be done
in the Makefile.am files.

> 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?

We've discussed this in the past, but IIRC we never reached a decision.
If we are going to create our own macros, etc., I think we should create
a new component in the util module that is installed and used by all
other packages.  The idea being that we should share as much as possible
and not create one-off solutions in every package.

>                                                   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?

I think it should reference the package version since each package will
have its own release schedule in the modular tree that is independent
from our global roll-up releases.  What do others think?

Kevin