Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Perl: porters

installhtml questions

 

 

Perl porters RSS feed   Index | Next | Previous | View Threaded


steve.m.hay at googlemail

May 10, 2012, 2:21 PM

Post #1 of 5 (110 views)
Permalink
installhtml questions

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?


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?


nick at ccl4

May 14, 2012, 3:26 AM

Post #2 of 5 (107 views)
Permalink
Re: installhtml questions [In reply to]

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


fawaka at gmail

May 14, 2012, 4:53 AM

Post #3 of 5 (106 views)
Permalink
Re: installhtml questions [In reply to]

On Thu, May 10, 2012 at 11:21 PM, Steve Hay <steve.m.hay [at] googlemail> wrote:
> 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?

Module::Build already contains code for that, but it's only enabled if
your perl is configured to know where it should put them (the
install{,site,vendor}[13]htmldir configuration keys). In practice I
think Activestate is the only perl that defines them. AFAIK html
support in ExtUtils::MakeMaker has been removed at least twice because
of some serious issues, but I'm pretty sure those could be fixed if
someone put the tuits into it. I think Activestate ships a patched
version of EU::MM with htmlification enabled.

Leon


pagaltzis at gmx

May 14, 2012, 8:25 PM

Post #4 of 5 (102 views)
Permalink
Re: installhtml questions [In reply to]

* Nicholas Clark <nick [at] ccl4> [2012-05-14 12:30]:
> # 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.]

That is not even the worst part. What’s really terrible is how much
duplication of logic there is. The same string concatenation is pasted
in four different places, and the readdir&grep in three, with minor
variations.

I tried to make this as plain and clear as possible and ended up with
this:

while(readdir DIR) {
my $is_dir = -d "$podroot/$dir/$_";
next if $is_dir and not $recurse;
my $target = (
$is_dir ? \@dirlist :
s/\.pod$// ? \@podlist :
s/\.pm$// ? \@pmlist :
undef
);
push @$target, "$dir/$_" if $target;
}

if ($^O eq 'VMS') { s/\.dir$//i for @dirlist }

Shall I send the patch series?

It does not fix the “doesn’t look for any other kind of file” issue but
offers a much better starting point to anyone who wants to.

I debated whether to return `undef` as the default case and guard the
`push`, or just `next` off the bottom of the table and leave the `push`
unconditional. I used `next` at first but then switched to `undef` since
I figure that this way it will be easier to add collection logic in the
future that does not fit neatly into the table, should the need arise.

Regards,
--
Aristotle Pagaltzis // <http://plasmasturm.org/>


nick at ccl4

May 15, 2012, 12:40 AM

Post #5 of 5 (103 views)
Permalink
Re: installhtml questions [In reply to]

On Tue, May 15, 2012 at 05:25:11AM +0200, Aristotle Pagaltzis wrote:

> I tried to make this as plain and clear as possible and ended up with
> this:
>
> while(readdir DIR) {
> my $is_dir = -d "$podroot/$dir/$_";
> next if $is_dir and not $recurse;
> my $target = (
> $is_dir ? \@dirlist :
> s/\.pod$// ? \@podlist :
> s/\.pm$// ? \@pmlist :
> undef
> );
> push @$target, "$dir/$_" if $target;
> }
>
> if ($^O eq 'VMS') { s/\.dir$//i for @dirlist }

> Shall I send the patch series?
>
> It does not fix the "doesn't look for any other kind of file" issue but
> offers a much better starting point to anyone who wants to.

Yes please, for exactly that reason - no-one else needs to have their
eyes burnt by it.

> I debated whether to return `undef` as the default case and guard the
> `push`, or just `next` off the bottom of the table and leave the `push`
> unconditional. I used `next` at first but then switched to `undef` since
> I figure that this way it will be easier to add collection logic in the
> future that does not fit neatly into the table, should the need arise.

Yes, I don't know either. I think, stick with what you've got.
It might turn out that the location of the "other files" comes from
utils.lst rather than extending the scanning list, but no-one knows that
yet. [.But I'm sure that the waterfall planning advocates insist that we
should :-)]

Nicholas Clark

Perl porters RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.