[Module::Build] PROPOSAL: M::B should install HTML documentation
Status: Beta
Brought to you by:
kwilliams
|
From: <kev...@ub...> - 2003-10-15 11:13:48
|
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. |