Re: [Module::Build] PROPOSAL: M::B should install HTML documentation

[Chris D. <ch...@cl...>]

On Wednesday, October 15, 2003, at 06:12  AM, <kev...@ub...> 
wrote:
> I would love to see M::B support building HTML documentation.


I have built a module to do exactly that.  It is not yet published to 
CPAN, but here's the documentation.  The main work left to do is to 
tweak some of the defaults and to get a Pod::Html regression bug fixed 
(doesn't handle nested =item tags right, grr...)

Chris



NAME
     Module::Build::Html - HTML documentation for packages

DESCRIPTION
     This package adds automatic generation of HTML documentation to
     Module::Build.

SYNOPSIS
     Use almost exactly like Module::Build. That is, for end users:

        cd My-Package
        perl Build.PL installhtml=/my/dir/for/html
        Build
        Build test
        Build install

     See the configuration section below for details on how to use the
     optional arguments to "perl Build.PL".

     For developers, create a file called Build.PL that looks something 
like:

         use Module::Build;
         my $builder = "Module::Build";
         eval 'use Module::Build::Html; $builder .= "::Html"; ';
         $builder -> new(
                         module_name => 'My::Package',
                         license => 'gpl',
                         requires => {
                            ...
                         },
         )->create_build_script;

CONFIGURATION
     We've added a few custom configuration parameters that you can use.
     Typically, these are useful to the end user, not the developer. As 
such,
     use them like this:

       perl Build.pl key=value

     instead of putting them into the Build.PL directly.

     css=URL
         Defaults to <http://www.clotho.com/css/perldoc.css>. Decent
         alternatives include <http://search.cpan.org/s/style.css> and
         <http://perldoc.com/css/perldoc.css>. You should feel to 
download
         and edit one of these for your own purposes. "file://" URLs work
         just great for local CSS files.

     installhtml=DIR
         Defaults to "undef", which means that HTML files are created, 
but
         not installed by default. Decent alternatives include, for 
example,
         "/usr/share/perlhtml" and "$HOME/Documents/perl".

     htmlext=EXTENSION
         Defaults to "html". Decent alternatives include, for example,
         "shtml", "HTM" and "php".

OVERRIDDEN METHODS
     _construct KEY => VALUE, KEY => VALUE, ...
         This method is called internally by new(). We apply our custom
         configuration value here (unless the user has already overridden
         them in "perl Build.PL").

     _set_install_paths
         Add the "installhtml" directory to the list of installation
         directories, if needed.

     ACTION_docs
         Add HTML output to the documentation creation step.

NEW METHODS
     htmlify_all_pods
         This closely parallels the manify_bin_pods() and 
manify_lib_pods()
         methods from Module::Build::Base. All files which might contain 
POD
         are examined and HTML versions of the POD are output to the
         "blib/htmldoc" directory. Pod::Html is loaded to perform the
         conversion.

AUTHOR
     Clotho Advanced Media Inc., *cp...@cl...*

--
Chris Dolan, Software Developer, Clotho Advanced Media Inc.
ch...@cl..., 294-7900, 211 S Paterson, Madison WI 53703