manpages file naming - a filesystem difference dilemmaby Intrepid (Deacon)
|on Nov 22, 2006 at 14:25 UTC||Need Help??|
Intrepid has asked for the
wisdom of the Perl Monks concerning the following question:
The scenario, in brief:
One has a removable media device 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 happen on a UNIX workstation or a MS Windows one, 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.
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. Manpages are good 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 (this is old news ...), 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. I'll downvote replies that consist of "So use perldoc instead" and / or "So don't install / live without the manpages" (go ahead, downvote this node for mentioning downvoting (or because Intrepid authored it); you know you want to; why try to change now?).
On Cygwin, 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 ExtUtils::MM_Cygwin module overrides the 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.
--Words can be slippery, so consider who speaks as well as what is said; know as much as you can about the total context of the speaker's participation in a forum over time, before deciding that you fully comprehend the intention behind those words; if in doubt, ask for clarification before you 'flame'.