CSJewell has asked for the wisdom of the Perl Monks concerning the following question:

System: WinXPsp2, ActiveState perl 817, PPM::Make 0.79, Module::Build 0.2805

I've got my PPM's creating right, except for one thing: The HTML documentation is "a little screwy".

Specifically, instead of nice names like DBI - Database independent interface for Perl at the top, I get stuff like 

C:\DOCUME~1\Curtis\LOCALS~1\Temp\Perl-Critic-3908-1156377001\blib/lib/
+Perl/Critic/Policy/BuiltinFunctions/ProhibitLvalueSubstr.pm"

[download]
at the top (withour quotes) when I generate a PPM.

ppm_install/make_ppm from PPM::Make and the "Build ppm" part of Module::Build both do this.

I can't find Pod::Master, (finding that would be useful, too, if only to update it - it looks nice, and I'd like a way to refresh my HTML documentation, as trying the crossed-out code does NOT do it - I had to reinstall ActiveState after I tried that!), I've read HowTo build and distribute a PPMed module for Win32. What options/scripts do I need to set/fix to fix this?

(OK, I checked. It's only when the module author doesn't put both a name and an abstract on the same line in the NAME section, or has no NAME section at all. Perl::Critic and Net::OpenID::JanRain::Consumer are bad at that - talk to the maintainers?)

Replies are listed 'Best First'.
Re: Question about creating PPM's...
by randyk (Parson) on Aug 25, 2006 at 15:50 UTC

    I believe that the problem arises on ActivePerl's side, as both PPM::Make and Module::Build appear to use the module name as the title in these cases, instead of the path to the local file. You can see this by doing 

       perl Makefile.PL
   nmake

    [download]
    and noticing the nmake step generates already the html files. Amongst other things, this will insert ActivePerl-specific stuff like links to JavaScript scripts used in the local ActivePerl html docs, but will also have the problem with the path to the local file being used as the title. If you then run PPM::Make's make_ppm on this, the script will see a blib/html directory present, and will not regenerate the html docs.

    If you want to not use the html docs generated by ActivePerl, using PPM::Make, you can do 

       perl Makefile.PL
   nmake
   deltree blib\html
   make_ppm

    [download]
    which will generate the html files using PPM::Make and leads to, for example, a title of Perl::Critic::Policy::BuiltinFunctions::ProhibitLvalueSubstr, rather than the path to the local file that results using ActivePerl's html generation. If you're using Module-Build, this problem can be avoided by using 
      perl Build.PL
  perl Build

    [download]
    directly, instead of some Makefile.PL compatibility mode, as this will use Module::Build directly to generate the html docs. However, not using ActivePerl's generated docs will lose the JavaScript functionality that ActivePerl provides.

    Unfortunately, after all this, even if you fix these problems before you make up the ppm package, if you're installing this on a recent ActivePerl, the ppm utility won't install the docs present under blib/html, but instead will generate the html docs directly from the module files. This results in these cases in the path to the local file being used in the title.

    It's probably worth filing a bug report with ActiveState about this.

[reply]
[d/l]
[select]

      They DO use the module name IF the module has a NAME section that has the format "Module::Name - Abstract" (which most do, but not all). Otherwise, it puts the path there.

      Maybe AS's routines should be more aggressive about trying to find a name?

[reply]

        That's true - the problem only arises in the circumstances you found in your original post.

        I think the place to start looking into this is the _translate sub of ActivePerl::DocTools::Tree::HTML. The title (and subsequent heading in the body) is coming from what Pod::Html generates. I guess possible fixes are
        • patch Pod::Html
        • pass pod2html a title option which handles these problem cases better (that's what Module-Build and PPM-Make do)
        • after generating the html, edit it to replace the title (_translate already is doing such editing for other things)

        Update: I filed a bug report (together with a patch) regarding this issue.

[reply]
Re: Question about creating PPM's...
by Anonymous Monk on Aug 25, 2006 at 12:51 UTC
[reply]

Back to Seekers of Perl Wisdom