Bug Tracker #53478 and HTML documentation

"Scott Renner" <[email protected]> Tue, 26 Jan 2010 20:27:09 -0500
Newsgroups gmane.comp.lang.perl.modules.module-build
Message-ID <003501ca9eef$d83a9250$88afb6f0$@net> 
Hello,

 

I recently encountered a problem with the tarballs generated by
Module::Build reported a bug a few weeks ago.  I got a mail the next
morning that it had recently been fixed.   Thanks!!!

 

I noticed bug #53478 "Diffs with Active State HTML generation and PPM
compatibility" because  I am working on a utility to fix broken links in the
HTML documentation that are caused by a variety of reasons (mostly due to
pod2html inability to figure out links correctly.)   Anyway,  I have become
very familiar with ActiveState HTML generation routines (and pod2html) and
have come up with fixes for Module::Build that will address all of the HTML
generation issues, including the generation of the Table of Contents on
ActivePerl installations.  

 

The fixes are pretty simple and I've attached Module::Build::Base.pm with my
the changes.  The changes are based on build 0.3603, with a new version of
0.36031. 

 

I've tested quite a bit (doing a variety builds, install, ppminstall, dist,
ppmdist, etc.) and everything works as it should, but I am limited to
Windows for testing.   I've tested on Perl 5.8 and 5.10 (both AS and
standard).  

 

With these updates, there is no need to make changes to EU:Install  to get
the html documentation working properly on any type of installation.  

 

Here is a summary of the changes..

 

In the section setting default properties. (line 929)

 

Deleted the property "html_css", it is no longer needed or used.

 

sub _is_ActivePerl (line 3034)

 

New method that returns true if running on an ActivePerl installation.  Is
set using the same eval (require ActivePerl::DocTools) that was used to set
the property "html_css".    This is not a property because its value needs
to be determined when the installation is run, not the value on the  system
that built the package.  

 

sub ACTION_manpages (line 3039)

 

I removed the check to see if there are any files to process, because this
is performed in both the 'manify' subs.  No point in doing the check twice.

 

sub ACTION_html (line 3133)

 

I also optimized this sub as well.   'htmlify_pods' checks if there are no
files to process, so there really isn't any point in doing the check here
too.

 

Sub htmlify_pods (line 3172)

                

I saw the comment that says "Links to other modules are not being generated"
and saw the problem.  The original code uses "$self->blib" as the "podroot"
and "podpath" only points to directories in "blib".   "podroot" must be the
absolute path to the directory where the installed pod files are stored, and
"podpath" can be relative directories off of podroot, plus an absolute path
to the "blib" directory.    With this code,  all links are generated
properly.  

 

If $self->_is_ActivePerl is true, we use ActivePerl::DocTools::Pod::pod2html
to generate the HTML documentation, otherwise we use Pod::Html:pod2html to
create it.  The ActivePerl version also uses Pod::Html::pod2html, but then
does some post processing on the HTML files to format them in the ActivePerl
style.

 

I also added code to do some cleanup on the html files after they are
generated by pod2html.    The generated HTML is NOT XHMTL, so the DOCTYPE is
wrong.  IE6+ will not display the page if it does not pass validation based
on the DOCTYPE.  Local pages also need this statement in the <HEAD> "<!--
saved from url=(0017)http://localhost/ -->" for IE6+ to load local html
pages (file://) if certain security settings on the user's PC are strict.
Lastly anchor references to html pages within the package point to the
"blib" directory.  These are fixed up so they point to where they will be
after they are installed.

 

sub ACTION_install (line 3357)

 

Added logic to check if '$self->is_ActivePerl' is true, and run
ActivePerl::DocTools::WriteTOC().  WriteTOC() is the ActivePerl routine that
updates the ActivePerl Table of Contents page and must be run AFTER the all
the html files have been installed.

 

sub ACTION_ppmdist (line 3515)

 

You don't need to generate HTML documentation when creating a PPM
distribution, because it is generated automatically by the ppm client at
install.   This is noted in the fact that "libdoc" and "bindoc" are set to
"undef".   I commented out the lines that generate the HTML.  

 

sub install_map (line 4830)

 

Added some logic so that man pages are not installed unless you are running
on a Unix like operating system.  

 

Feel free to use these changes and to contact me if you have any questions
or comments.  I'm glad to help in any way I can.

 

Scott Renner
Base.36031.pm (application/octet-stream, 149.4 KB) - not displayed