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

[<kev...@ub...>]

All

The following comments were collected from a previous thread:

SP> As an aside, I always thought it would be a bit more useful to=20
SP> generate HTML manpages on Win32 & friends, considering they don't =
have=20
SP> a 'man' tool by default.
=20
SP> For example, ACTION_docs could be split up into ACTION_manpages,=20
SP> ACTION_html_docs:
=20
SP> ./Build html_docs
SP> ./Build manpages
=20
SP> And there could be config parameters set for each (with sensible=20
SP> defaults for each OS) that ACTION_docs checked before trying to do=20
SP> anything.
=20
SP> What do people think: a useful idea, or feature creep?

YS-T> I'd think whether to install HTML would be a separate option, =
unrelated
YS-T> to man pages.
=20
SP> Yeah - that discussion really belongs in a separate thread.

So, here is the new thread :-)

I would love to see M::B support building HTML documentation.  I don't =
think
this is at all specific to platforms that don't have man.  I work on =
Unix, but
try to provide all documentation in both man and HTML form.  Currently, =
I
achieve this by using M::B to generate the man pages, then installhtml =
[1]
to generate HTML documentation.  However, there are two problems with =
this:

a) installhtml appears to be a bit of an obscure part of the Perl =
distribution.
For example, IIRC, it is not installed into the bin directory by =
default; you have to
copy it yourself.  It also does not support all the features of =
pod2html.
In particular, I want to use the --cachedir option (not documented in =
pod2html
but documented in the Pod::Html page).

b) It is not as elegant as if the functionality were integrated into =
M::B.

My favoured interface would be that ./Build generates man pages as it =
does now.
A separate action - ./Build htmldocs - would invoke pod2html (or maybe =
Pod::Html
directly, not sure) to generate the HTML docs.  There would need to be a
way to pass options through to pod2html.  Maybe something like the =
following:

./Build htmldocs -htmldir=3D/foo --htmlroot=3D/bar --cachedir=3Dname =
[etc]

1. http://search.cpan.org/dist/perl/installhtml

Cheers
Kevin

+ANYTHING+BELOW+WAS+ADDED+AFTER+I+HIT+SEND+

Visit our website at http://www.ubs.com

This message contains confidential information and is intended only 
for the individual named.  If you are not the named addressee you 
should not disseminate, distribute or copy this e-mail.  Please 
notify the sender immediately by e-mail if you have received this 
e-mail by mistake and delete this e-mail from your system.

E-mail transmission cannot be guaranteed to be secure or error-free 
as information could be intercepted, corrupted, lost, destroyed, 
arrive late or incomplete, or contain viruses.  The sender therefore 
does not accept liability for any errors or omissions in the contents 
of this message which arise as a result of e-mail transmission.  If 
verification is required please request a hard-copy version.  This 
message is provided for informational purposes and should not be 
construed as a solicitation or offer to buy or sell any securities or 
related financial instruments.