Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl: the Markov chain saw

Make and index html doc files

by Rudif (Hermit)
on Mar 03, 2001 at 23:11 UTC ( #62038=sourcecode: print w/replies, xml ) Need Help??
Category: HTML Utility
Author/Contact Info,
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 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.


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", 
$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;
    # 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
       -> BODY(BGCOLOR => $bgcolor, TEXT => $text);



sub Emit_Entries
    my $stream = shift;


    for my $entry (sort keys %Index)
           ->A(HREF => "$entry.html")


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->FRAMESET(COLS=> '250,*'); 
    $stream->FRAME(NAME=>'TOC', SRC=>'index.html', TARGET=>'UserHtmlDo
    $stream->FRAME(NAME=>'UserHtmlDoc', SRC=>''); # without SRC=>'', N
+etscape 4.75 opens a new window
            ->H3->text('This page must be viewed by a browser that is 
+capable of viewing frames.')->_H3



=head1 NAME

pods2html - translate a tree of PODs to HTML


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


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.




=head1 SEE ALSO

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

=head1 AUTHOR

Steven McDougall, <>


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


Extended by Rudi Farkas, <> <>, 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.  

Log In?

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

How do I use this? | Other CB clients
Other Users?
Others musing on the Monastery: (6)
As of 2020-09-19 09:27 GMT
Find Nodes?
    Voting Booth?
    If at first I donít succeed, I Ö

    Results (114 votes). Check out past polls.