Skip Menu |

CC: rjbs [...] cpan.org
Subject: [META] make installhtml a non-experimental target
Date: Mon, 21 Jan 2013 11:25:52 -0500 (EST)
To: perlbug [...] perl.org
From: rjbs [...] cpan.org
Download (untitled) / with headers
text/plain 1.4k
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.
CC: bugs-bitbucket [...] rt.perl.org
Subject: Re: [perl #116487] [META] make installhtml a non-experimental target
Date: Mon, 21 Jan 2013 18:13:10 +0100
To: perl5-porters [...] perl.org
From: Leon Timmermans <fawaka [...] gmail.com>
Download (untitled) / with headers
text/plain 845b
On Mon, Jan 21, 2013 at 5:26 PM, Ricardo SIGNES <perlbug-followup@perl.org> wrote: Show quoted text
> 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
CC: perl5-porters [...] perl.org, bugs-bitbucket [...] rt.perl.org
Subject: Re: [perl #116487] [META] make installhtml a non-experimental target
Date: Mon, 21 Jan 2013 10:39:54 -0800
To: Leon Timmermans <fawaka [...] gmail.com>
From: Jan Dubois <jand [...] activestate.com>
Download (untitled) / with headers
text/plain 535b
On Mon, Jan 21, 2013 at 9:13 AM, Leon Timmermans <fawaka@gmail.com> wrote: Show quoted text
> 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
RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 1.8k
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
CC: perl5-porters [...] perl.org
Subject: Re: [perl #116487] [META] make installhtml a non-experimental target
Date: Tue, 22 Jan 2013 01:41:23 +0100
To: perlbug-followup [...] perl.org
From: Leon Timmermans <fawaka [...] gmail.com>
On Tue, Jan 22, 2013 at 1:21 AM, James E Keenan via RT <perlbug-followup@perl.org> wrote: Show quoted text
> 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. Show quoted text
> * 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. Show quoted text
> * Wouldn't Pod::Html be better off if it were maintained on CPAN?
Probably. Show quoted text
> * 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
Subject: Re: [perl #116487] [META] make installhtml a non-experimental target
Date: Mon, 21 Jan 2013 21:55:19 -0500
To: perl5-porters [...] perl.org
From: James E Keenan <jkeen [...] verizon.net>
Download (untitled) / with headers
text/plain 639b
On 1/21/13 7:41 PM, Leon Timmermans wrote: Show quoted text
> On Tue, Jan 22, 2013 at 1:21 AM, James E Keenan via RT
Show quoted text
>
>> * 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
CC: perl5-porters [...] perl.org
Subject: Re: [perl #116487] [META] make installhtml a non-experimental target
Date: Mon, 21 Jan 2013 22:40:03 -0500
To: James E Keenan <jkeen [...] verizon.net>
From: Ricardo Signes <perl.p5p [...] rjbs.manxome.org>
Download (untitled) / with headers
text/plain 1.4k
* James E Keenan <jkeen@verizon.net> [2013-01-21T21:55:19] Show quoted text
> 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
Download signature.asc
application/pgp-signature 490b

Message body not shown because it is not plain text.

Subject: Re: [perl #116487] [META] make installhtml a non-experimental target
Date: Tue, 22 Jan 2013 13:06:34 +0000
To: perl5-porters [...] perl.org
From: Nicholas Clark <nick [...] ccl4.org>
Download (untitled) / with headers
text/plain 1015b
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: Show quoted text
> On Tue, Jan 22, 2013 at 1:21 AM, James E Keenan via RT
Show quoted text
> > * 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: Show quoted text
> 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
Subject: Re: [perl #116487] [META] make installhtml a non-experimental target
Date: Tue, 22 Jan 2013 10:33:19 -0500
To: perl5-porters [...] perl.org
From: Ricardo Signes <perl.p5p [...] rjbs.manxome.org>
Download (untitled) / with headers
text/plain 1.3k
* Nicholas Clark <nick@ccl4.org> [2013-01-22T08:06:34] Show quoted text
> 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.) Show quoted text
> 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. Show quoted text
> [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
Download signature.asc
application/pgp-signature 490b

Message body not shown because it is not plain text.

RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 461b
On Tue Jan 22 05:07:20 2013, nicholas wrote: Show quoted text
> 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


This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

For issues related to this RT instance (aka "perlbug"), please contact perlbug-admin at perl.org