Front page | perl.perl5.porters |
Postings from May 2012
From: Steve Hay
May 10, 2012 14:21
Message ID: CADED=K74U3KG_juGJo2x4E7oyjK=LZYVuM8xMKiyACOQS7C9vA@mail.gmail.com
I have a few issues with the way HTML manpages are installed, at least
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::=|)" \
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?
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?
Do HTML manpages get installed on other OSes, and if so then (how) do
they include the documentation of the 'utils' programs?
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.
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?
by Steve Hay