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

Make and index html doc files

by Rudif (Hermit)
on Mar 03, 2001 at 23:11 UTC ( [id://62038]=sourcecode: print w/replies, xml ) Need Help??
Category: HTML Utility
Author/Contact Info rudif@bluemail.ch, rudif@lecroy.com
Description: Script pods2htmlextracts the pod documentation from a multitude of pod, pm and pl files in a source directory tree into the corresponding html files. It will create/update a html directory tree, populate it with html files, and optionally create an index file and a 2-frame browser frameset with the index in the l.h. frame and the current html file in the r.h. frame.

My script is an extension of script of same name which is distributed with the module Pod-Tree-1.06 by Steven McDougall.

I added the option and code that generates the 2-frame frameset similar to that used in ActiveState Perl doc.
I also fixed a few minor problems, documented in my script.

To install, drop the script below into a directory that is in your path and name it pods2html.pl. Next, install the prerequisite modules from CPAN: Pod-Tree and HTML-Stream.
To create or update a html doc tree from pods in your perl work directory, invoke
pods2html <workdir> <htmldir> --frames
To view the html doc index, point your browser to file <htmldir>/default.html.

Rudif
#!/usr/local/bin/perl

use strict;
use File::Find;
use File::Path;
use Getopt::Long;
use HTML::Stream;
use IO::File;
use Pod::Tree::HTML;

my %Options = (bgcolor => '#fffff8',
           text    => '#000000',
           hr      => 1,
           toc     => 1 );

my $ok = GetOptions(\%Options, "base:s", 
                       "index:s", 
                       "frames", 
                       "bgcolor:s", 
                       "text:s",
                       "toc!", 
                       "hr:i");
$ok or die "Bad command line options\n";

my %Index;
my($PodDir, $HTMLDir) = @ARGV;
$HTMLDir or die "pods2html PodDir HTMLDir\n";

if ($Options{frames}) {
    unless ($Options{index}) {
        $Options{index} = 'User Doc Index';
    }
}

# fix up the Win32 paths
$PodDir  =~ s( \\ )(/)gx;
$HTMLDir =~ s( \\ )(/)gx;


$PodDir  =~ s( /$ )()x;
$HTMLDir =~ s( /$ )()x;

umask 0022;
find({ wanted   => \&Translate,
       no_chdir => 1          }, $PodDir);
Index() if $Options{index};
Default_Frames() if $Options{frames}; 


sub Translate
{
    return if -d and $_ eq $HTMLDir; 
    -f and &Translate_POD;
}


sub Translate_Dir
{
    print "$File::Find::name\n";
    my $dir = $File::Find::name;
    $dir =~ s/^$PodDir/$HTMLDir/o;
    -d $dir or mkdir $dir, 0755 or die "Can't mkdir $dir: $!\n";
}


sub Translate_POD
{
    m( \.(pm|pod|pl)$ )x or return;
    my $source = $File::Find::name;
    print "$source\n";

    my $dest = $source;
    $dest =~ s/^$PodDir/$HTMLDir/;
    $dest =~ s( \.\w+$ )(.html)x;

    my $destdir = $File::Find::dir;
    $destdir =~ s/^$PodDir/$HTMLDir/;
    mkpath $destdir unless -d $destdir;

    my $pod = $source;
    $pod =~ s(^$PodDir/)();
    $pod =~ s( \.\w+$ )()x;
    {
        my $html = new Pod::Tree::HTML $source, $dest;
        $html->set_options(%Options);
        $html->translate;
    }
    # index $dest unless it has no content 
    # (a kludge based on size of a contentless file on Win32) 
    # (translate ought not a create contentless file)
    $Index{$pod} = 1 unless -s $dest <= 105; 
#    printf "$dest %d\n", -s $dest;
}


sub Index
{
    my $index = "$HTMLDir/index.html";
    my $fh = new IO::File ">$index";
    defined $fh or die "Can't open $index: $!\n";

    my $stream = new HTML::Stream $fh;

    my $title    = $Options{index};
    my $bgcolor  = $Options{bgcolor};
    my $text      = $Options{text};

    $stream-> HTML->HEAD;
    $stream-> TITLE->text($title)->_TITLE;
    $stream-> BASE(TARGET=>'UserHtmlDoc')->_BASE if $Options{frames}; 
+# Rudif-5
    $stream->_HEAD
       -> BODY(BGCOLOR => $bgcolor, TEXT => $text);
    $stream->H1->t($title)->_H1;

    Emit_Entries($stream);

    $stream->_BODY->_HTML;
}


sub Emit_Entries
{
    my $stream = shift;

    $stream->UL;

    for my $entry (sort keys %Index)
    {
    $stream->LI
           ->A(HREF => "$entry.html")
           ->t($entry)
           ->_A
           ->_LI;
    }

    $stream->_UL;
}


sub Default_Frames
{
    my $default = "$HTMLDir/default.html";
    my $fh = new IO::File ">$default";
    defined $fh or die "Can't open $default: $!\n";

    my $stream = new HTML::Stream $fh;

    my $title    = $Options{index};
    my $bgcolor  = $Options{bgcolor};
    my $text      = $Options{text};

    $stream->set_tag('FRAMESET', Newlines=>15); 
    $stream->set_tag('FRAME', Newlines=>8); 
    $stream->set_tag('NOFRAMES', Newlines=>9); 

    $stream-> HTML->HEAD;
    $stream-> TITLE->text($title)->_TITLE;
    $stream->_HEAD;

    $stream->FRAMESET(COLS=> '250,*'); 
    $stream->FRAME(NAME=>'TOC', SRC=>'index.html', TARGET=>'UserHtmlDo
+c');
    $stream->FRAME(NAME=>'UserHtmlDoc', SRC=>''); # without SRC=>'', N
+etscape 4.75 opens a new window
    $stream->NOFRAMES
            ->H1->text('Sorry!')->_H1
            ->H3->text('This page must be viewed by a browser that is 
+capable of viewing frames.')->_H3
            ->_NOFRAMES;
    $stream->_FRAMESET;

    $stream->_HTML;
}



__END__

=head1 NAME

pods2html - translate a tree of PODs to HTML

=head1 SYNOPSIS

C<pods2html> 
[C<--base> I<url>]
[C<--index> I<title>]
[C<--frames>]
[C<-->[C<no>]C<toc>] [C<--hr> I<level>] 
[C<--bgcolor> I<#rrggbb>] [C<--text> I<#rrggbb>]
I<PODdir> I<HTMLdir>

=head1 DESCRIPTION

C<pod2html> finds all the F<.pod>, F<.pl> and F<.pm> files in the 
directory tree rooted at I<PODdir>.
It translates each POD to HTML,
and writes it to a parallel directory tree rooted at I<HTMLdir>

It makes the HTML files world-readable.

=head1 OPTIONS

=over 4

=item C<--base> I<url>

Translate C<LE<lt>E<gt>> sequences into HTML
links relative to I<url>.

=item C<--index> I<title>

Writes an index of all the HTML files to I<HTMLDir>F</index.html>.
I<title> is used as the title of the index page.

=item C<--frames>

Writes the I<HTMLDir>F</default.html>. This file sets up 2 frames 
in the browser, containing the index and the currently viewed file.
This option implies --index and provides a default title.

=item C<-->[C<no>]C<toc>

Includes or omits the table of contents.
Default is to include the TOC.

=item C<--hr> I<level>

Controls the profusion of horizontal lines in the output, as follows:

    level   horizontal lines
    0         none
    1         between TOC and body
    2         after each =head1
    3         after each =head1 and =head2

Default is level 1.

=item C<--bgcolor> I<#rrggbb>

Set the background color to I<#rrggbb>.
Default is off-white.

=item C<--text> I<#rrggbb>

Set the text color to I<#rrggbb>.
Default is black.

=back

=head1 REQUIRES

L<C<Pod::Tree::HTML>>

=head1 SEE ALSO

L<C<pod2html>>, L<C<Pod::Tree::HTML>>

=head1 AUTHOR

Steven McDougall, <swmcd@world.std.com>

=head1 COPYRIGHT

Copyright 1999 by Steven McDougall.  This program is free software;
you can redistribute it and/or modify it under the same terms as Perl.

=head1 EXTENSIONS

Extended by Rudi Farkas, <rudif@bluemail.ch> <rudif@lecroy.com>, 3 Mar
+ 2001.

=over 4

=item 1

Accepts Win32 style directory paths containing '\'

=item 2

I<HTMLDir> can be a subdirectory of I<PodDir> 

=item 3

Does not create empty subdirectories in the html tree 

=item 4

Can create I<HTMLDir> also if it is not an immediate subdirectory of a
+n existing directory.

=item 5

New option --frames creates a 2-frame browser window.

=item 6

Also heeds the pl extension, in addition to pm and pod, when looking f
+or pod content.

=item 7

Does not index a html file empty of content.
TODO: $html->translate should refrain from creating a html file and re
+turn 0 
if the source file contains no pod.  


=back

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others drinking their drinks and smoking their pipes about the Monastery: (7)
As of 2024-03-28 08:00 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found