[EXPERIMENT] the "installhtml" make target

[p5pRT]

Migrated from rt.perl.org#116487 (status was 'open')

Searchable as RT116487$

[p5pRT]

From @rjbs

There is an C<install.html> target in the Makefile. It's marked as
"experimental". It would be good to get this tested, make it work
reliably, and remove the "experimental" tag. This would include

1. Checking that cross linking between various parts of the
documentation works. In particular that links work between the modules
(files with POD in F<lib/>) and the core documentation (files in
F<pod/>)

2. Improving the code that split C<perlfunc> into chunks, preferably
with general case code added to L<Pod​::Functions> that could be used
elsewhere.

Challenges here are correctly identifying the groups of functions that
go together, and making the right named external cross-links point to
the right page. Currently this works reasonably well in the general
case, and correctly parses two or more C<=items> giving the different
parameter lists for the same function, such used by C<substr>. However
it fails completely where I<different> functions are listed as a
sequence of C<=items> but share the same description. All the functions
from C<getpwnam> to C<endprotoent> have individual stub pages, with only
the page for C<endservent> holding the description common to all.
Likewise C<q>, C<qq> and C<qw> have stub pages, instead of sharing the
body of C<qx>.

Note also the current code isn't ideal with the two forms of C<select>,
mushing them both into one F<select.html> with the two descriptions run
together. Fixing this may well be a special case.

[p5pRT]

From @Leont

On Mon, Jan 21, 2013 at 5​:26 PM, Ricardo SIGNES
<perlbug-followup@​perl.org> wrote​:

There is an C<install.html> target in the Makefile. It's marked as
"experimental". It would be good to get this tested, make it work
reliably, and remove the "experimental" tag. This would include

1. Checking that cross linking between various parts of the
documentation works. In particular that links work between the modules
(files with POD in F<lib/>) and the core documentation (files in
F<pod/>)

I think it'd be a bit silly if we don't at the same time improve
toolchain support for HTML. Currently MakeMaker doesn't support it at
all out of the box (I think ActivePerl patches it to add html
support). Module​::Build has some support for it, but AFAIK it has
issues (probably the same that led to it being removed from
MakeMaker).

Leon

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[p5pRT]

From @jandubois

On Mon, Jan 21, 2013 at 9​:13 AM, Leon Timmermans <fawaka@​gmail.com> wrote​:

I think it'd be a bit silly if we don't at the same time improve
toolchain support for HTML. Currently MakeMaker doesn't support it at
all out of the box (I think ActivePerl patches it to add html
support). Module​::Build has some support for it, but AFAIK it has
issues (probably the same that led to it being removed from
MakeMaker).

You are probably thinking of this one​:

  https://rt.cpan.org/Public/Bug/Display.html?id=45600

Cheers,
-Jan

[p5pRT]

From @jkeenan

At the Perl hackathon we held at Duck-Duck-Go last summer, Rik Signes
suggested I take a look at refactoring and testing of Pod​::Html, which
he described as a mess -- which, not coincidentally, is the name of the
other [META] ticket we have open for this library (RT #112014).

I spent several weeks giving this module the Phalanx treatment (see​:
https://github.com/jkeenan/Pod-Html).  Several of the RT items linked to
in this ticket were tickets I opened. But at a certain point my efforts
lagged and I turned my attention elsewhere. For one thing, I can't
recall having personally used Pod​::Html or the pod2html utility any time
in the past ten years. For another, other than possibly being used in
installations of Perl on Windows, I couldn't find any evidence that it
was used in the Perl core. The INSTALL file says​:

#####
Currently, the standard perl installation does not do anything with
HTML documentation, but that may change in the future.
#####

So, eventually I began to pose these questions to myself -- and now to you​:

* Why is Pod​::Html still part of the Perl 5 core distribution?

* Why is Pod​::Html still maintained in blead, i.e., why is it still the
responsibility of the Perl 5 Porters?

* Wouldn't Pod​::Html be better off if it were maintained on CPAN?

* If it were maintained on CPAN, would we even need to "dual-life" it,
i.e., would there be a compelling need to even include it in the core
distribution?

* Are there packagers who depend on Pod​::Html, pod2html, or the
installhtml 'make' target? Does that dependency require P5P to be the
place where the library is maintained?

Open for discussion. But if you think this functionality still deserves
to be in core and maintained by P5P, please indicate what efforts you
are willing to make to get Pod​::Html, etc., into good shape.

Thank you very much.
Jim Keenan

[p5pRT]

From @Leont

On Tue, Jan 22, 2013 at 1​:21 AM, James E Keenan via RT
<perlbug-followup@​perl.org> wrote​:

For one thing, I can't
recall having personally used Pod​::Html or the pod2html utility any time
in the past ten years. For another, other than possibly being used in
installations of Perl on Windows, I couldn't find any evidence that it
was used in the Perl core. The INSTALL file says​:

Module​::Build uses it if the perl was configured to have a location to
install html files to. By default it doesn't though.

* Why is Pod​::Html still maintained in blead, i.e., why is it still the
responsibility of the Perl 5 Porters?

Because no one has taken it over.

* Wouldn't Pod​::Html be better off if it were maintained on CPAN?

Probably.

* If it were maintained on CPAN, would we even need to "dual-life" it,
i.e., would there be a compelling need to even include it in the core
distribution?

HTML > manpages. We're living in the 21st century, and our hypertext
support is still mediocre. IMHO the solution is to improve it, not to
give it up.

Leon

[p5pRT]

From @jkeenan

On 1/21/13 7​:41 PM, Leon Timmermans wrote​:

On Tue, Jan 22, 2013 at 1​:21 AM, James E Keenan via RT

* If it were maintained on CPAN, would we even need to "dual-life" it,
i.e., would there be a compelling need to even include it in the core
distribution?

HTML> manpages. We're living in the 21st century, and our hypertext
support is still mediocre. IMHO the solution is to improve it, not to
give it up.

Leon

Can you elaborate on that? I wouldn't think that HTML would be used as
an input for manpages. Can you describe what our hypertext support is,
and what it should be?

Thank you very much.
Jim Keenan

[p5pRT]

From @rjbs

* James E Keenan <jkeen@​verizon.net> [2013-01-21T21​:55​:19]

On 1/21/13 7​:41 PM, Leon Timmermans wrote​:

We're living in the 21st century, and our hypertext
support is still mediocre. IMHO the solution is to improve it, not to
give it up.

Can you elaborate on that? I wouldn't think that HTML would be used
as an input for manpages. Can you describe what our hypertext
support is, and what it should be?

Just this week (or maybe last) we had someone write in because our
documentation, displayed as text, didn't convey which part of the text was a
cross-reference.

A while back, we were really hesitant to break apart some very large documents
that might be better organized as many smaller documents because it would stink
when browser primarily as man pages, and because "perldoc" has no facility to
follow links.

We are in an awkward position where our documentation is very bounded by the
constraints, not (only) of Pod, but also of man. What if HTML documentation
was more easily available? What if perldoc could be configured to open the
installed HTML page in your browser, if you wished?

I'm not saying we must keep installhtml, or must get rid of it, or anything
else. It's just sometimes frustrating to feel limited by the lowest level
viewer.

All that said​: if nobody is going to do any work to maintain, support, or
improve our HTML documentation building, it's hard to see much of a future for
it beyond "still limping along."

--
rjbs

[p5pRT]

From @nwc10

Note that everyone is conflating HTML install targets, pod2html and Pod​::HTML

It's possible to toss Pod​::HTML completely but keep the other two functional
using Pod​::Simple​::XHTML

On Tue, Jan 22, 2013 at 01​:41​:23AM +0100, Leon Timmermans wrote​:

On Tue, Jan 22, 2013 at 1​:21 AM, James E Keenan via RT

* Wouldn't Pod​::Html be better off if it were maintained on CPAN?

Probably.

Would it be better if it died?

On Mon, Jan 21, 2013 at 10​:40​:03PM -0500, Ricardo Signes wrote​:

All that said​: if nobody is going to do any work to maintain, support, or
improve our HTML documentation building, it's hard to see much of a future for
it beyond "still limping along."

So would be the best plan of attack be to redo HTML documentation building
using Pod​::Simple​::XHTML?

[Obviously this needs /volunteer+/ to work on it, but as it's not a task
needing any C, XS or OS specific knowledge, *everyone* on this list is
qualified. Hence anyone reading this message - I'm including you :-)]

Nicholas Clark

[p5pRT]

From @rjbs

* Nicholas Clark <nick@​ccl4.org> [2013-01-22T08​:06​:34]

Note that everyone is conflating HTML install targets, pod2html and Pod​::HTML

It's possible to toss Pod​::HTML completely but keep the other two functional
using Pod​::Simple​::XHTML

It's true, but to what extent would a "convert all the documents in these
trees using Pod​::Simple​::XHTML" be simpler to do than to work from the existing
version of that, which is Pod​::Html? (I don't know the answer.)

On Mon, Jan 21, 2013 at 10​:40​:03PM -0500, Ricardo Signes wrote​:

All that said​: if nobody is going to do any work to maintain, support, or
improve our HTML documentation building, it's hard to see much of a future
for it beyond "still limping along."

So would be the best plan of attack be to redo HTML documentation building
using Pod​::Simple​::XHTML?

Pod​::Simple​::XHTML converts /one/ document.

Pod​::Simple​::HTMLBatch converts /many/. It uses (but does not subclass)
Pod​::Simple​:HTML, not :​:XHTML. This may be better than Pod​::Html (which uses
Pod​::Simple​::XHTML, but I'm not sure we can say without some research and
points of comparison.

[Obviously this needs /volunteer+/ to work on it, but as it's not a task
needing any C, XS or OS specific knowledge, *everyone* on this list is
qualified. Hence anyone reading this message - I'm including you :-)]

Hey, buddy, you leave me out of this. ;)

--
rjbs

[p5pRT]

From @cpansprout

On Tue Jan 22 05​:07​:20 2013, nicholas wrote​:

So would be the best plan of attack be to redo HTML documentation
building
using Pod​::Simple​::XHTML?

[Obviously this needs /volunteer+/ to work on it, but as it's not a
task
needing any C, XS or OS specific knowledge, *everyone* on this list is
qualified. Hence anyone reading this message - I'm including you :-)]

Not so. Not everyone is familiar with XHTML syntax. :-)

--

Father Chrysostomos