Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine
 
PerlMonks  

Update HTML Doc

by Rudif (Hermit)
on Apr 16, 2001 at 16:09 UTC ( [id://72809]=sourcecode: print w/replies, xml ) Need Help??
Category: HTML Utility
Author/Contact Info rudif@bluemail.ch
Description: ActiveState Perl installer creates a html tree and a TOC file for access to the perl documentation from a browser.
The PPM updates this tree and the TOC when installing packages.

However, in several circumstances you may wish to use this script here, to convert pod found in module files to html and/or to update the TOC:
  1. you added html files found on the web
  2. you installed a module from CPAN whose files contain pod
  3. you installed your own scripts or modules containing pod
Update: the ryddler's 'quick and dirty utility' that I started from was originally posted right here at PM. Thanks to $code or die for making the connection.

#! perl -w

use strict; 

use ActivePerl::DocTools; 
use Config;
use File::Copy; 
use File::Find; 
use File::Path; 
use File::stat;
use Getopt::Long;
use Pod::Find; 
use Pod::Html; 
use Pod::Usage;


my %opts = (query=>0, verbose=>0, force=>0, help=>0, man=>0, listro=>0
+,);
my $ok = GetOptions(\%opts, keys %opts);
                       
pod2usage(0) unless $ok;
pod2usage(0) if $opts{help};
pod2usage(-exitstatus => 0, -verbose => 2) if $opts{man};


$|++;


my $stylesheet = 'Active.css';

my $podroot  = "$Config{installprefix}"; # usually C:/perl on Win32
my $htmlroot = "$Config{installhtmldir}"; # usually C:/perl/html on Wi
+n32

$podroot =~ s#\\#/#g;
$htmlroot =~ s#\\#/#g;


if ($opts{listro}) {
    listReadonlyHtmls();
    exit;
}


my $logfile = "$Config{installhtmldir}/htmllog.txt"; 
open LOGFILE, ">>$logfile" || die "couldn't open LOGFILE $logfile\n"; 
print LOGFILE scalar localtime(), "\n"; 

findAndConvertPods(); 
print LOGFILE "-" x 60, "\n"; 
close LOGFILE; 
printf STDERR "Updated logfile $logfile\n";

ActivePerl::DocTools::WriteTOC(); 



sub findAndConvertPods {
    print STDERR "Finding files containing pod in $podroot\n" if $opts
+{verbose};
    my %pods = Pod::Find::pod_find({ -verbose => $opts{verbose},  }, "
+$podroot"); 
    my $pods = keys %pods;
    printf STDERR "Found $pods files\n";

    # convert pods unless query
    #
    my $converted = 0;
    foreach(sort keys %pods) { 
        print STDERR "    $_ podfile\n" if $opts{verbose};
        convertPod2html($_) && ++$converted; 
    } 
    printf STDERR "$converted files %sconverted to html.\n", $opts{que
+ry} ? 'should be ' : '';
} 


sub convertPod2html { 
    my $podfile = shift; 
    $podfile =~ s#\\#/#g; 
    if ($podfile =~ m!$podroot/(.*)/(\w+)\.p(od|l|m)$!i) { 
        my $path = $1; 
        my $name = $2; 
        my $outfile = "$htmlroot/$path/$name.html";
        my $action = '';
        if (! -e $outfile) { 
            $action = 'created';
        }
        elsif (stat($podfile)->mtime > stat($outfile)->mtime || $opts{
+force}) {
            $action = 'updated';
        }
        if ($action) {
            if ($opts{query}) {
                $action = "should be $action";
            }
            else {
                (my $stylesheetpath = "$path") =~ s#\w+(/?)#..$1#g;
                mkpath("$htmlroot/$path"); 
                pod2html(    "--infile=$podfile", 
                            "--outfile=$outfile", 
                            "--header", 
                            "--podroot=$podroot", 
                            "--podpath=site/lib:lib", 
                            "--htmlroot=$htmlroot",
                            "--css=$stylesheetpath/$stylesheet", 
                ); 
            }
            print LOGFILE "-- $outfile $action\n";
            print STDERR"-- $outfile $action\n" if $opts{verbose};
            return 1;
        }
    } 
    return 0;
} 
  

sub listReadonlyHtmls {
    my $html = 0;
    my $htmlro = 0;
    find( sub { 
                ++$html if /\.html?$/; 
                ++$htmlro unless -w; 
#                printf "$File::Find::name %d\n", -s;
                print STDERR "$File::Find::name RO\n" unless -w;
    }, $htmlroot);
    print STDERR "Found $html html files ($htmlro read-only).\n";
}

__END__
  


=head1 NAME

UpdateHtmlDoc.pl 

=head1 SYNOPSIS

UpdateHtmlDoc  [options]
  
 Updates html doc files and TOC in the ActiveState Perl directory tree
+.

 Options:
    -force          forces update of all html files
    -help           prints brief help message and exits
    -listro         lists read-only html files and exits
    -man            prints full documentation and exits
    -query          only lists html files that need to be created or u
+pdated
    -verbose        prints detail of operations

=head1 DESCRIPTION

Finds pod content in .pod, .pm and .pl files in Perl tree
directories lib, site\lib and bin.

Creates or updates the corresponding html files in corresponding subdi
+rectories of
perl\html directory.

Updates the TOC file.

=head1 MOTIVATION

ActiveState Perl installer creates a html tree and a TOC file for acce
+ss 
to the perl documentation from a browser.
The PPM updates this tree and the TOC when installing packages.

However, in several circumstances you may wish to use this script,
to convert pod found in module files to html and/or to update the TOC:

=over 4

=item *

you added html files found on the web

=item *

you installed a module from CPAN whose files contain pod

=item *

you installed your own scripts or modules containing pod

=back


=head1 PATCH

The module Toc.pm from ActiveState (perl/site/lib/ActivePerl/DocTools/
+Toc.pm)
indexes only files under lib and site/lib. 

To include files from perl\bin directory, you need to patch Toc.pm 

 my @checkdirs = qw(bin lib site/lib); ### RF added bin 

 $TOCdir =~ s#.*bin/(.*)$#$1#;  ### RF added bin 
 $TOCdir =~ s#.*?lib/(.*)$#$1#; 
 $TOCdir =~ s#/#::#g; 
  

=head1 LIMITATIONS

This script was tested only on Win2k with Perl 5.6.0 (build 623). 
Please let me know if you find any problems. 

=head1 SEE ALSO

perl(1).

=head1 AUTHOR

Rudi Farkas rudif@bluemail.ch  15 Apr 2001

Based on ideas and code from 'a quick and dirty utility' 
script posted to perl-win32-users@listserv.ActiveState.com by
ryddler@cu-online.com on 13 Mar 2001.

=cut
Replies are listed 'Best First'.
Re: Update HTML Doc
by $code or die (Deacon) on Apr 18, 2001 at 08:55 UTC
    Looks good. I've used the script here by ryddler. I modified it so it uses the ActiveState CSS. I will test your script properly tomorrow when I get in to work.

    The only thing that ryddler's script didn't do that would have been neat, would be to update the HTML docs if you installed a newer version of the module. But it looks like your script will do this.

    $ perldoc perldoc
(crazyinsomniac) Re: Update HTML Doc
by crazyinsomniac (Prior) on Nov 05, 2001 at 13:23 UTC
    Great job.

    There is a bug, I haven't been able to track it down (I haven't really tried), but I'd like you to fix it.

    This is immediately noticable on my Tk::* pod, where as if I'm on Tk::callbacks for example, there will be links at the bottom like:

    SEE ALSO

    Tk::bind Tk::after Tk::options Tk::fileevent

    or more precisely

    <H1><A NAME="see also">SEE ALSO</A></H1> <P><A HREF="/site/lib/Tk/bind.html">Tk::bind</A> <A HREF="/site/lib/Tk/after.html">Tk::after</A> <A HREF="/site/lib/Tk/options.html">Tk::options</A> <A HREF="/site/lib/Tk/fileevent.html">Tk::fileevent</A></P> <P>
    This doesn't sit well with me (I click, I don't go anywhere), and it might just be an issue wiht Tk (or with POD::Html, i don't know), but I'd like to see you try and figure it out (please) ;D

     
    ___crazyinsomniac_______________________________________
    Disclaimer: Don't blame. It came from inside the void

    perl -e "$q=$_;map({chr unpack qq;H*;,$_}split(q;;,q*H*));print;$q/$q;"

Re: Update HTML Doc
by PodMaster (Abbot) on Jul 21, 2002 at 08:31 UTC
    I accidentally stumbled upon ActivePerl::DocTools::Tree::HTML, so now all I do is, and I get no problems with cross/linking like crazyinsomniac does
    perl -MActivePerl::DocTools -e ActivePerl::DocTools::UpdateHTML() perl -MActivePerl::DocTools -e ActivePerl::DocTools::WriteTOC()
    Since all my html docs were messed up, I had to do a
    perl -MFile::Path -MConfig -e" rmtree(qq[$Config{installhtmldir}\\bin] +) " perl -MFile::Path -MConfig -e" rmtree(qq[$Config{installhtmldir}\\site +\\lib]) "
    before running the above code

    update: John M. Dlugosz , it is a part of ActivePerl::DocTools. The ActivePerl guys commented out the pod a long time ago, so when you say perldoc ActivePerl::DocTools nothing shows up. Anyway, I use Pod::Master now.

    ____________________________________________________
    ** The Third rule of perl club is a statement of fact: pod is sexy.

      There is nothing there reported by Google. Perhaps they took it down?
Re: Update HTML Doc
by John M. Dlugosz (Monsignor) on Jan 12, 2003 at 06:17 UTC
    Thanks for having such a neat ready-to-run solution to wrap the underlying primitives.

    Question, though: why the quotes around the hash keys?

    my $podroot = "$Config{installprefix}"; my $htmlroot = "$Config{installhtmldir}";
    We all know that perlfaq4 admonishes against this. But I know that there is a difference, that you are forcing string context on the object. So, are those values class objects rather than ordinary scalars, or what?

    —John

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: sourcecode [id://72809]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others taking refuge in the Monastery: (4)
As of 2024-03-29 13:25 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found