Thread: [Module::Build] any pod2html action?
Status: Beta
Brought to you by:
kwilliams
Menu
▾
▴
module-build-general
|
From: Uri G. <ur...@st...> - 2004-01-15 06:39:10
|
i was looking for an action that would do pod2html on all the pm files and i can't seem to find one. would this be a good thing to have? if none exists i will probably write my own and post it here. uri -- Uri Guttman ------ ur...@st... -------- http://www.stemsystems.com --Perl Consulting, Stem Development, Systems Architecture, Design and Coding- Search or Offer Perl Jobs ---------------------------- http://jobs.perl.org |
|
From: Randy K. <ra...@th...> - 2004-01-15 17:22:13
|
On Thu, 15 Jan 2004, Uri Guttman wrote:
> i was looking for an action that would do pod2html on all
> the pm files and i can't seem to find one. would this be a
> good thing to have? if none exists i will probably write
> my own and post it here.
Coincidentally, this was just being discussed - here's a
diff that adds an 'html' target that runs pod2html on the
pods under blib/, and puts the results also under blib/
(which will be included in the 'ppm_dist' archive). There's
also an 'htmlinstall' target that would install the html
files locally to $Config{installhtmldir}, if that exists.
I tried to make it not assume too much about the
ActiveState html directory structure, but some things
may need tweaking to function outside of an ActiveState
distribution.
Note that a couple of new requirements - Pod::Find and
Pod::Html - are added.
In case you were wondering, the gymnastics concerning file
paths within the html action (using File::Spec->Unix and the
like) are mainly due to getting a '/' to be used as the
directory separator in a url when building things on
non-Unix (Win32 in particular).
==============================================================
Index: lib/Module/Build/Base.pm
===================================================================
RCS file: /cvsroot/module-build/Module-Build/lib/Module/Build/Base.pm,v
retrieving revision 1.240
diff -u -r1.240 Base.pm
--- lib/Module/Build/Base.pm 15 Jan 2004 04:18:46 -0000 1.240
+++ lib/Module/Build/Base.pm 15 Jan 2004 16:57:55 -0000
@@ -1360,6 +1360,73 @@
return '';
}
+sub ACTION_html {
+ require Pod::Find;
+ require Pod::Html;
+ my $self = shift;
+ $self->depends_on('build');
+ my $cwd = $self->cwd;
+ $cwd =~ s!^\w:!!;
+ $cwd =~ s!(\\|:)!/!g;
+ my $html_base = $Config{installhtmldir} ?
+ File::Basename::basename($Config{installhtmldir}) : 'html';
+ my $blib = File::Spec::Unix->catdir($cwd, 'blib');
+ my $html = File::Spec::Unix->catdir($blib, $html_base);
+ my $script = File::Spec::Unix->catdir($blib, 'script');
+ unless (-d $html) {
+ File::Path::mkpath($html, 1, 0755) or die "Couldn't mkdir $html: $!";
+ }
+ my %pods = Pod::Find::pod_find({-verbose => 1}, $blib);
+ if (-d $script) {
+ File::Find::finddepth( sub
+ {$pods{$File::Find::name} =
+ "script::" . basename($File::Find::name)
+ if (-f $_ and not /\.bat$/ and $self->contains_pod($_));
+ }, $script);
+ }
+
+ my $backlink = '__top';
+ my $css = ($^O =~ /Win32/) ? 'Active.css' : '';
+ foreach my $pod (keys %pods){
+ my @dirs = split /::/, $pods{$pod};
+ my $isbin = shift @dirs eq 'script';
+ my $infile = File::Spec::Unix->abs2rel($pod);
+ my $outfile = (pop @dirs) . '.html';
+
+ my @rootdirs = $isbin? ('bin') : ('site', 'lib');
+ my $path2root = "../" x (@rootdirs+@dirs);
+ $path2root =~ s!/$!!;
+
+ my $fulldir = File::Spec::Unix->catfile($html, @rootdirs, @dirs);
+ unless (-d $fulldir){
+ File::Path::mkpath($fulldir, 1, 0755)
+ or die "Couldn't mkdir $fulldir: $!";
+ }
+ $outfile = File::Spec::Unix->catfile($fulldir, $outfile);
+
+ my $htmlroot = File::Spec::Unix->catdir($path2root, 'site', 'lib');
+ my $podpath = join ":" => map { File::Spec::Unix->catdir($blib, $_) }
+ ($isbin ? qw(bin lib) : qw(lib));
+ (my $package = $pods{$pod}) =~ s!^(lib|script)::!!;
+ my $abstract = $self->dist_abstract($infile);
+ my $title = $abstract ? "$package - $abstract" : $package;
+ my @opts = (
+ '--header',
+ '--flush',
+ "--backlink=$backlink",
+ "--title=$title",
+ "--podpath=$podpath",
+ "--infile=$infile",
+ "--outfile=$outfile",
+ "--podroot=$blib",
+ "--htmlroot=$htmlroot",
+ );
+ push @opts, "--css=$path2root/$css" if $css;
+ print "pod2html @opts\n";
+ Pod::Html::pod2html(@opts);# or warn "pod2html @opts failed: $!";
+ }
+}
+
# Adapted from ExtUtils::MM_Unix
sub man1page_name {
my $self = shift;
@@ -1452,6 +1519,33 @@
my %onlyargs = map {exists($self->{args}{$_}) ? ($_ => $self->{args}{$_}) : ()}
qw(version versionlib);
only::install::install(%onlyargs);
+}
+
+sub ACTION_htmlinstall {
+ return unless my $destdir = $Config{installhtmldir};
+ my $self = shift;
+ $self->depends_on('html');
+ my $cwd = $self->cwd;
+ my $blib = File::Spec->catdir($cwd, 'blib');
+ my $html_base = File::Spec->catdir($blib,
+ File::Basename::basename($destdir));
+ my @files;
+ File::Find::finddepth(sub
+ {push @files, $File::Find::name
+ if $File::Find::name =~ /\.html$/
+ }, $html_base);
+ foreach my $file (@files) {
+ (my $relative_to = $file) =~ s!\Q$html_base!!;
+ $relative_to =~ s!^/!!;
+ my $to = File::Spec->catfile($destdir, $relative_to);
+ my $base_dir = File::Basename::dirname($to);
+ unless (-d $base_dir) {
+ File::Path::mkpath($base_dir, 1, 0755)
+ or die "Cannot mkpath $base_dir: $!";
+ }
+ File::Copy::copy($file, $to)
+ or warn "Cannot copy '$file' to '$to': $!";
+ }
}
sub ACTION_clean {
================================================================
--
best regards,
randy kobes
|
|
From: Uri G. <ur...@st...> - 2004-01-15 18:14:18
|
gack! i am glad i didn't attempt to write that. which version of build
will that appear in? i may write my own because i use the files from the
MANIFEST to find stuff but will i need to do all that stuff? i have
that nice grep_manifest method i use for other stuff as well. i assume
knowing the possible podded files will simplify much of the logic.
i do have some minor code comments:
>>>>> "RK" == Randy Kobes <ra...@th...> writes:
RK> + my $backlink = '__top';
RK> + my $css = ($^O =~ /Win32/) ? 'Active.css' : '';
RK> + foreach my $pod (keys %pods){
RK> + my @dirs = split /::/, $pods{$pod};
RK> + my $isbin = shift @dirs eq 'script';
i keep perl executables in a bin/ dir. shouldn't that be supported? also
what about other dirs such as utils/ (which has scripts only for using in
this tarball but may have pod as well)
and why a destructibve shift instead of an index? (i know shift is
slightly faster but index is probably clearer).
my $isbin = $dirs[0] eq 'script';
RK> + my $infile = File::Spec::Unix->abs2rel($pod);
RK> + my $outfile = (pop @dirs) . '.html';
same here:
my $outfile = "$dirs[-1].html";
thanx,
uri
--
Uri Guttman ------ ur...@st... -------- http://www.stemsystems.com
--Perl Consulting, Stem Development, Systems Architecture, Design and Coding-
Search or Offer Perl Jobs ---------------------------- http://jobs.perl.org
|
|
From: Randy K. <ra...@th...> - 2004-01-15 18:41:13
|
On Thu, 15 Jan 2004, Uri Guttman wrote:
>
> gack! i am glad i didn't attempt to write that. which
> version of build will that appear in? i may write my own
> because i use the files from the MANIFEST to find stuff
> but will i need to do all that stuff? i have that nice
> grep_manifest method i use for other stuff as well. i
> assume knowing the possible podded files will simplify
> much of the logic.
Originally I had also used MANIFEST to get a list of pod
files, but then an extra layer of logic had to be added to
figure out where to put the html files under the blib/ tree
(eg, Foo::Bar -> blib/html/site/lib/Foo/Bar.html, no matter
if Bar.pm is in the package's top-level directory, or under
lib/Foo/, or even somewhere else). The 'build' target
already figures the directory structure out, so I just used
that.
> i do have some minor code comments:
>
> >>>>> "RK" == Randy Kobes <ra...@th...> writes:
>
> RK> + my $backlink = '__top';
> RK> + my $css = ($^O =~ /Win32/) ? 'Active.css' : '';
> RK> + foreach my $pod (keys %pods){
> RK> + my @dirs = split /::/, $pods{$pod};
> RK> + my $isbin = shift @dirs eq 'script';
>
> i keep perl executables in a bin/ dir. shouldn't that be supported? also
> what about other dirs such as utils/ (which has scripts only for using in
> this tarball but may have pod as well)
That's a good point - those could be added.
> and why a destructibve shift instead of an index? (i know shift is
> slightly faster but index is probably clearer).
>
> my $isbin = $dirs[0] eq 'script';
>
> RK> + my $infile = File::Spec::Unix->abs2rel($pod);
> RK> + my $outfile = (pop @dirs) . '.html';
>
> same here:
>
> my $outfile = "$dirs[-1].html";
That would be clearer - thanks.
--
best regards,
randy
|
|
From: Uri G. <ur...@st...> - 2004-01-15 18:50:37
|
>>>>> "RK" == Randy Kobes <ra...@th...> writes:
>> my $outfile = "$dirs[-1].html";
RK> That would be clearer - thanks.
as a style point, i try to avoid plain . as much as possible. i like ""
strings and will try to use them if possible. you can get most scalar
values into a string without much trouble. the most annoying things is
when you have sub or method calls and you want to interpolate them. i
won't use the ugly @{[]} or ${\} tricks so it would have to be temp vars
or using ..
this doesn't mean i don't use .= . i use that all the time.
uri
--
Uri Guttman ------ ur...@st... -------- http://www.stemsystems.com
--Perl Consulting, Stem Development, Systems Architecture, Design and Coding-
Search or Offer Perl Jobs ---------------------------- http://jobs.perl.org
|
|
From: Ken W. <ke...@ma...> - 2004-01-15 23:56:24
|
On Thursday, January 15, 2004, at 12:39 PM, Randy Kobes wrote:
> On Thu, 15 Jan 2004, Uri Guttman wrote:
>
>>
>> gack! i am glad i didn't attempt to write that. which
>> version of build will that appear in? i may write my own
>> because i use the files from the MANIFEST to find stuff
>> but will i need to do all that stuff? i have that nice
>> grep_manifest method i use for other stuff as well. i
>> assume knowing the possible podded files will simplify
>> much of the logic.
>
> Originally I had also used MANIFEST to get a list of pod
> files, but then an extra layer of logic had to be added to
> figure out where to put the html files under the blib/ tree
> (eg, Foo::Bar -> blib/html/site/lib/Foo/Bar.html, no matter
> if Bar.pm is in the package's top-level directory, or under
> lib/Foo/, or even somewhere else). The 'build' target
> already figures the directory structure out, so I just used
> that.
Also, the package might be structured so that some POD files are
actually generated during the build process, so the blib/ directory is
really the only reliable place to build docs from. That's where the
manpages are built from, for instance.
>>
>> RK> + my $backlink = '__top';
>> RK> + my $css = ($^O =~ /Win32/) ? 'Active.css' : '';
>> RK> + foreach my $pod (keys %pods){
>> RK> + my @dirs = split /::/, $pods{$pod};
>> RK> + my $isbin = shift @dirs eq 'script';
>>
>> i keep perl executables in a bin/ dir. shouldn't that be supported?
>> also
>> what about other dirs such as utils/ (which has scripts only for
>> using in
>> this tarball but may have pod as well)
>
> That's a good point - those could be added.
Regardless of whether you keep your executables in bin/ or script/,
they'll end up in blib/script/ after the 'build' action.
-Ken
|
Thanks for helping keep SourceForge clean.
X