use Perl

The scenario, in brief:

One has a removable media device (say, like a USB (thumb|key)drive); and one wants to carry a bunch of Perl modules around on it, mounting it to a workstation as needed, and including the path to the modules in @INC (via the $PERL5LIB mechanism). This could involve use on a UNIX workstation or an MS Windows one, for example; it does not matter.

Installing modules to this (USB?) removable (thumb|key)drive in the normal manner involves setting a PREFIX= and possibly LIB= parameters for ExtUtils::MakeMaker -based module build-infrastructure supported modules, or the parallel means for a Module::Build -based one. Then you just go do the make ; make test ; make install or Module::Build analog as you would for any module installation. I guess for some readers this is going to sound like an exotic thing to envision, but for the author this is not. I've been doing things like this with the manual installation of modules for years. I understand all the mechanisms and gotchas involved, and IMHO the support for this in Perl is very good and the results I get are very satisfying.

The Problem:

When the build host is UNIX (i.e. GNU/Linux) the make process will create man pages for all detected *.pm *.pl and *.pod files. This is "normal" for the architecture / os type and I like and want the manpages to be installed to the file hierarchy on the removable media drive. However, the filenames of man files produced from the POD in modules are like Module::Kewl::Excelsior.pm3 on a UNIX system. Note the double-colons (::).

The filesystem of a USB (thumb|key)drive is (nearly ?) invariably FAT32 as shipped by the manufacturer (and for my purposes, for maximum portability, needs to be kept that way). A FAT-ish filesystem, having originated from MS DOS, does not accept colons : as part of filenames. They are (obviously) barred from the set of ascii characters allowed because of the special semantic meaning they have on an MS DOS-ish / Windows-ish system. The result is that the manpages cannot be written to the removable FAT/FAT32 media at make install time, possibly generating error messages or possibly just failing silently (the error message will be the ubiquitous and vastly informative MS Windows error No such file or directory).

I like manpages (or the moral equivalent like info pages). Manpages are goodness to me. They give me a feeling of reassurance that I have the proper up to date documentation (assuming the module dist maintainer is keeping the documentation in sync with the changes ;-) for the code I am using. Bare-bones Debian and Debian-based systems don't ship with a perldoc command (one is available as a separate Debian package), so that's an instance where having manpages built is substantially important to having the POD accessible to me as the user. This is about personal preference anyway.

Possible solutions:

On Cygwin (http://www.cygwin.com/), which is UNIX but lives within the special needs of the MS Win filesystem semantics WRT special characters and filenames (AUX, PRN, NUL, etc), the manpages are usable and are built. The EU::MM_Cygwin (http://cpan.uwinnipeg.ca/htdocs/ExtUtils-MakeMaker/ExtUtils/MM_Cygwin.pm.html) module overrides the default EU::MM method which generates make recipes to build manpages from module or script files; it provides a . (dot) in place of the :: (double-colon) in creating the filenames for the man pages that will be copied into place when everything installed.

A solution like the one used by Cygwin(perl) is great and is what I think I want, but it requires one to make some change to the files included in the module distribution; either some hand-editing or some addition of files or both. Can anyone think of a way to achieve this manipulation of EU::MM (or M::B) operations that doesn't require that kind of a tedious manual operation for each module to be built/installed to the removable media drive? Or does anyone have a suggestion for a new method or parameter or functionality for EU::MM or M::B that would allow for changing the manpage filename namespace delimiter to be compatible with FAT filename semantics?

I can envision for example a $PERL_MM_USE_MANFILE_SEP=. environ var that if present would trigger the desired overidding.

If you are a Perlmonks reader, then yes, you've seen this topic posted there as node id 585526 : "manpages file naming - a filesystem difference dilemma" in the SoPW section of the Monastery.