nick at ccl4
May 14, 2012, 3:26 AM
Post #2 of 5
(50 views)
Permalink
|
On Thu, May 10, 2012 at 10:21:35PM +0100, Steve Hay wrote:
> I have a few issues with the way HTML manpages are installed, at least
> on Windows.
>
> 1. The installhtml script is run like this from the win32/Makefile:
>
> $(PERLEXE) -I..\lib ..\installhtml --podroot=.. --htmldir=$(HTMLDIR) \
> --podpath=pod:lib:ext:utils --htmlroot="file://$(INST_HTML::=|)" \
> --recurse
>
> The inclusion of 'ext' in the podpath results in an 'ext' folder in
> the final <installdir>\html folder, alongside a 'lib' folder and more
> or less duplicating part of it, but in a different format, e.g. it
> gives you <installdir>\html\ext\Devel-Peek\Peek.html, but we already
> have <installdir>\html\lib\Devel\Peek.html. The latter, of course,
> mimcs the layout of folders/files in <installdir>\lib, so makes more
> sense. Also, the inclusion of 'ext' results in extensions that don't
> even get built/installed having their documentation installed, e.g. I
> have <installdir>\html\ext\VMS-Stdio\Stdio.html, but obviously don't
> have VMS::Stdio on Windows.
>
> I would therefore like to remove 'ext' from that list. (It already
> doesn't contain 'dist' or 'cpan', so I don't really understand why it
> contains 'ext' in the first place.) Any objections?
It's not clear. The rule to run installhtml springs fully-formed into
the Win32 Makefiles in commit 3e3baf6d63945cb6 (5.004_01, back in June 1997)
without any direct explanation. However, Makefile.SH at that point has:
# Not implemented yet.
#install.html: all installhtml
# ./perl installhtml
In turn, installhtml gives a clue:
=head1 EXAMPLE
The following command-line is an example of the one we use to convert
perl documentation:
./installhtml --podpath=lib:ext:pod:vms \
--podroot=/usr/src/perl \
--htmldir=/perl/nmanual \
--htmlroot=/perl/nmanual \
--splithead=pod/perlipc \
--splititem=pod/perlfunc \
--libpods=perlfunc:perlguts:perlvar:perlrun:perlop \
--recurse \
--verbose
nearly all of that dates back to commit 54310121b4429747, which added
installhtml in March 1997. I would have guessed that the inclusion of
ext there harks back to installman running around ext, but it doesn't.
Even this bit of pod/Makefile isn't any help:
HTMLROOT = / # Change this to fix cross-references in HTML
POD2HTML = pod2html \
--htmlroot=$(HTMLROOT) \
--podroot=.. --podpath=pod:lib:ext:vms \
--libpods=perlfunc:perlguts:perlvar:perlrun:perlop
as it dates from commit dc848c6f6758d4d9 in *April* 1997.
I'm guessing that it's just a mistake, based on the assumption that the
distribution ships Pod-containing files in these directories, and
forgetting that build process stages everything into lib/
> 2. The inclusion of 'utils' in the podpath doesn't seem to achieve
> anything. My <installdir>\html folder contains only 'ext', 'lib' and
> 'pod'. Does the pod2html conversion perhaps only look for *.pm and
> *.pod, so doesn't pick up on the files which are in utils?
Seems so. installhtml is documented as
=item B<--podroot> POD search path base directory
The base directory to search for all .pod and .pm files to be converted.
Default is current directory.
=item B<--podpath> POD search path
The list of directories to search for .pod and .pm files to be converted.
Default is 'podroot/.'.
=item B<--recurse> recurse on subdirectories
Whether or not to convert all .pm and .pod files found in subdirectories
too. Default is to not recurse.
and in turn, the code agrees, consistently only looking for .pm and .pod:
# find the directories to recurse on
@dirlist = map { if ($^O eq 'VMS') {/^(.*)\.dir$/i; "$dir/$1";} else {"$dir/$_";}}
grep(-d "$podroot/$dir/$_" && !/^\.{1,2}/, readdir(DIR)) if $recurse;
rewinddir(DIR);
# find all the .pod files within the directory
@podlist = map { /^(.*)\.pod$/; "$dir/$1" }
grep(! -d "$podroot/$dir/$_" && /\.pod$/, readdir(DIR));
rewinddir(DIR);
# find all the .pm files within the directory
@pmlist = map { /^(.*)\.pm$/; "$dir/$1" }
grep(! -d "$podroot/$dir/$_" && /\.pm$/, readdir(DIR));
[.Aaaarrrgh. It burns. Why the *multiple* uses of rewinddir? Why not replace
the 3 maps with one foreach loop. Over-clever code. Using map is not
achieving nirvana.]
> Do HTML manpages get installed on other OSes, and if so then (how) do
> they include the documentation of the 'utils' programs?
Answer to the first question is not by default, and "badly".
I think not.
> 3. Should the installhtml program itself be installed with perl?
> Having built and installed perl, the first thing I do next is install
> numerous distros from CPAN, which all go into my <installdir>\site\lib
> folder, so now I want an <installdir>\html\site\lib folder containing
> all their manpages, but there is no tool installed with perl to make
> that easy since pod2html only converts one file at a time.
I think don't think that it should. We don't install installman.
> For that reason I normally copy installhtml into the <installdir>\bin
> folder so that I can run (and re-run) it any time to get HTML manpages
> for all my installed CPAN distros. It would be nice if installhtml was
> installed by default, unless there is some other way of doing this
> which I'm missing?
I *think* that the correct place should be the toolchain. Specifically
ExtUtils::MakeMaker and Module::Build. This is how manpages get made.
Nicholas Clark
|
