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

[Randy W. S. <Ra...@Th...>]

On 10/15/2003 6:23 PM, Michael G Schwern wrote:
> On Wed, Oct 15, 2003 at 10:39:12AM -0500, Chris Dolan wrote:
> 
>>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...)
> 
> 
> A few things to note:
> 
> 5.8.1 finally included Config options for HTML installation directories.
> So look for $Config{install*html*dir} (installhtml1dir, installhtml3dir,
> installsitehtml1dir, etc...) and if they're set, Module::Build should
> install HTML docs by default.

IIRC, some of those have been around longer but where unused; I don't 
think anyone ever agreed on where html docs should be installed.

> I would avoid passing Pod::Html specific flags into Module::Build.  Have
> a plan ready to map them in case Pod::Html is replaced.  The names of
> the Pod::Html arguments are fairly generic, so its sort of moot.  Just keep 
> your upgrade path open in case one of the future POD->HTML modules on CPAN 
> matures.

ActiveState distributions have their own means of generating html from 
pod (the ActivePerl::DocTools module), if that module is present you 
probably should use it or atleast ask the user.

There is another issue here in that the list of actions is growing quite 
large, and M::B is (IMHO) turning into a large monolithic module. Would 
it be worth the effort to re-architect actions, so that they are 
plug-ins (M::B::ACTION::html, M::B::ACTION::dist). This would keep M::B 
from becoming monolithic and would allow others to develop plug-ins to 
expand functionality without requiring invasive code changes.

This is only half thought-out, so I'm not sure if it's practical. For 
example, I don't know how easy it would be to come up with an interface 
so that actions could get info from M::B without digging into the 
internals.

<thinking out loud>

Each module would contain one or more actions. M::B would search for 
plugin actions at startup, querying each module for a list of supported 
actions. Each action knows what parameters it accepts and can display 
its own help info. There could be a helper class for generating actions 
and linking them by dependencies, i.e.

my $action = new M::B::ACTION::Builder(
   name => 'My_lib',
   code => sub {},
   ...
);

my $top = new M::B::ACTION::Builtin( name => 'all' );
$top->add_dependency($action);

</thinking out loud>

Just a thought,
Randy.

-- 
A little learning is a dang'rous thing;
Drink deep, or taste not the Pierian spring;
There shallow draughts intoxicate the brain;
And drinking largely sobers us again.
                 - Alexander Pope