The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Pod-HtmlEasy-1.0107
River stage one • 1 direct dependent • 1 total dependent
/ pod2indexed_html

NAME

pod2indexed_html - Convert POD files to HTML and create an index page

VERSION

This documentation refers to pod2indexed_html version 0.6.7

SYNOPSIS

pod2indexed_html [--dump] [--help] [--outfile file] [--scratch] [--verbose] [POD file ...]

In much the same way as pod2html, pod2indexed_html converts POD (.pm, .pl or .pod) files to HTML. However, pod2indexed_html also indexes them. That is, a page of links is created to allow the individual pages to be accessed easily. The state of the HTML with respect to the POD is tracked, and re-conversion is avoided if unnecessary.

If path(s) are specified on the command line, indexing is skipped, and conversion takes place directly. /foo/bar/test.pm => ./test.pm.html

The POD file may be specified as "-", in which case input is taken from STDIN.

REQUIRED ARGUMENTS

There are none. However, consult the "Static configuration" section at the beginning of the script to make sure that you like the choices.

OPTIONS

--dump - Dump .html_track, .index_track and .nopod_track, then exit.

This also provides a list of all links having the same tag.

--help - Print this and exit.
--outfile - File name to use when converting from STDIN. Defaults to STDIN.html.
--scratch - Rebuild the persistent files, which re-creates all HTML.
--verbose - Babble.

READ ME

See DESCRIPTION.

DESCRIPTION

pod2indexed_html locates all the Perl modules in your distribution that have documentation in POD format, converts it to HTML and makes an index page. Links are rendered so as to refer to the appropriate pages.

The principal advantage of pod2indexed_html is that it uses a persistent database of module creation times so that once its been run for the first time, subsequent executions are relatively quick, depending of course on what has been changed. pod2indexed_html notices both new modules and updates. This indexing is performed for all converted files; in particular, those specified on the command line.

The generated HTML index is flat, organized to look like a module hierarchy. For example, /some/path/DBI/Const/GetInfo/ANSI.pm goes to /another/path/DBI/Cons/GetInfo/ANSI.html, and is indexed under Const::GetInfo::Ansi.

HTML display is controlled by a style sheet, .doc.css in the document root directory, or, if you're converting documents on the command line, embedded in the generated HTML file.

ENVIRONMENT

$ENV{HOME} is used in debug mode.

DEPENDENCIES

This script requires the following modules: Carp, Config, English, File::Basename, File::Find, File::Path, File::Slurp, File::Spec, File::Spec::Unix, GDBM_File, Getopt::Long, HTML::EasyTags, IO::File, IO::Handle, MIME::Base64, Pod::HtmlEasy, Readonly, Regexp::Common, Storable

It also requires Perl 5.8.0, but should run under earlier version with only minor modifications. Required modules willing, of course.

CONFIGURATION AND ENVIRONMENT

The persistent user environment, configured in the script.

@addpods

Defaults to /usr/local/doc/POD. This is a list of paths to search for POD files, in addition to @INC.

$CPAN

Defaults to "search.cpan.org". This is the URL to be used to search for modules that are mentioned in a POD, but have not been installed locally.

$sourcedir

Defaults to the shortest path in @INC. Usually, that's /usr/lib/perl5 If there are multiple roots, we attempt to accomodate that.

$targetdir

Defaults to /usr/local/doc/HTML/Perl

$user

Email address for the creator of the index page. Defaults to "root@localhost".

$title

Defaults to "Perl Documentation"

DIAGNOSTICS

--verbose

This will produce all sorts of (allegedly) helpful info.

Tag references more than one POD.

Sometimes, one index entry will map to more than one HTML file. For example, both /usr/local/doc/HTML/Perl/vendor_perl/5.8.8/IPC/Run/Timer.html and /usr/local/doc/HTML/Perl/site_perl/5.8.8/IPC/Run/Timer.html would be pointed to by IPC::Run::Timer. Obviously, this is not going to work very well. The situation is resolved by choosing the most recently modified POD file. To see what's going on, run with -dump and look for the section titled "Multiple index references" at the end.

Unable to open file - error

Failure to open (or create) the database files.

Tag match failure for some/path

Failure of the regular expression matching that strips @INC paths.

Can't combine --dump and --scratch.

Don't combine --dumpb and --scratch, as this will delete the database before dumping it.

HTML conversion has missed a particular link type. Supported types are: URL, manpage, URI.

FILES

Assuming the you are using the default target directory.

/usr/local/doc/HTML/Perl/.html_track

Tracks the HTML file by the corresponding POD (.pm or .pod) file.

 /usr/local/doc/HTML/Perl/.html_track
  /usr/lib/perl5/5.8.8/AnyDBM_File.pm =>
    /usr/local/doc/HTML/Perl/5.8.8/AnyDBM_File.html
    Sun Jun  4 16:45:28 2006
  /usr/lib/perl5/5.8.8/Attribute/Handlers.pm =>
    /usr/local/doc/HTML/Perl/5.8.8/Attribute/Handlers.html
    Sun Jun  4 16:45:28 2006
  /usr/lib/perl5/5.8.8/AutoLoader.pm =>
    /usr/local/doc/HTML/Perl/5.8.8/AutoLoader.html
    Sun Jun  4 16:45:28 2006
...
/usr/local/doc/HTML/Perl/.index_track

Tracks the HTML index entry by the file tag and HTML file.

 /usr/local/doc/HTML/Perl/.index_track
  APR =>
    /usr/local/doc/HTML/Perl/vendor_perl/5.8.8/i386-linux-thread-multi/APR.html
    Sat Feb 11 23:29:50 2006
  APR::Base64 =>
    /usr/local/doc/HTML/Perl/vendor_perl/5.8.8/i386-linux-thread-multi/APR/Base64.html
    Sat Feb 11 23:29:57 2006
  APR::Brigade =>
    /usr/local/doc/HTML/Perl/vendor_perl/5.8.8/i386-linux-thread-multi/APR/Brigade.html
    Sat Feb 11 23:29:34 2006
...

There are some entries that point to multiple HTML files (found at the end out the output), for example:

  Archive::Extract =>
    /usr/local/doc/HTML/Perl/vendor_perl/5.8.8/Archive/Extract.html
    Thu Jan 19 04:53:02 2006
    /usr/local/doc/HTML/Perl/site_perl/5.8.8/Archive/Extract.html
    Thu Jan 19 04:53:02 2006
...
/usr/local/doc/HTML/Perl/.nopod_track

Tracks those .pm files that were not found to have POD.

 /usr/local/doc/HTML/Perl/.nopod_track
  /usr/lib/perl5/5.8.8/CGI/eg/make_links.pl =>
    Sun Jun  4 16:45:28 2006
  /usr/lib/perl5/5.8.8/CPAN/Config.pm =>
    Mon Jun 19 17:02:39 2006
...
/usr/local/doc/HTML/Perl/.doc.css

The style sheet that's generated to go with the HTML. The source for this file is found in the script, at the end of the file.

/usr/local/doc/HTML/Perl/.up.png

The "back to the top" arrow glyph. The source for this file is found in the script.

INCOMPATIBILITIES

None known.

BUGS AND LIMITATIONS

None known.

EXIT STATUS

0 on success, 1 on failure.

AUTHOR

Geoffrey Leach <geoff@hughes.net>

LICENSE AND COPYRIGHT

Copyright 2006 - 2010 by Geoffrey Leach

This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SCRIPT CATEGORIES

CPAN/Administrative