Pod::Simple::HTMLBatch

a b c d e f g h i j k l m n o p q r s t u v w x y z _
Pod::Simple::HTMLBatcUser Contributed Perl DocumentaPod::Simple::HTMLBatch(3)



NAME
       Pod::Simple::HTMLBatch - convert several Pod files to several HTML
       files

SYNOPSIS
	 perl -MPod::Simple::HTMLBatch -e ’Pod::Simple::HTMLBatch::go’ in out

DESCRIPTION
       This module is used for running batch-conversions of a lot of HTML
       documents

       This class is NOT a subclass of Pod::Simple::HTML (nor of bad old
       Pod::Html) -- although it uses Pod::Simple::HTML for doing the conver-
       sion of each document.

       The normal use of this class is like so:

	 use Pod::Simple::HTMLBatch;
	 my $batchconv = Pod::Simple::HTMLBatch->new;
	 $batchconv->some_option( some_value );
	 $batchconv->some_other_option( some_other_value );
	 $batchconv->batch_convert( \@search_dirs, $output_dir );

       FROM THE COMMAND LINE

       Note that this class also provides (but does not export) the function
       Pod::Simple::HTMLBatch::go.  This is basically just a shortcut for
       "Pod::Simple::HTMLBatch->batch_convert(@ARGV)".	It’s meant to be
       handy for calling from the command line.

       However, the shortcut requires that you specify exactly two command-
       line arguments, "indirs" and "outdir".

       Example:

	 % mkdir out_html
	 % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go @INC out_html
	     (to convert the pod from Perl’s @INC
	      files under the directory ../htmlversion)

       (Note that the command line there contains a literal atsign-I-N-C.
       This is handled as a special case by batch_convert, in order to save
       you having to enter the odd-looking "" as the first command-line
       parameter when you mean "just use whatever’s in @INC".)

       Example:

	 % mkdir ../seekrut
	 % chmod og-rx ../seekrut
	 % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go . ../htmlversion
	     (to convert the pod under the current dir into HTML
	      files under the directory ../htmlversion)

       Example:

	 % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go happydocs .
	     (to convert all pod from happydocs into the current directory)

MAIN METHODS
       $batchconv = Pod::Simple::HTMLBatch->new;
	   This TODO

       $batchconv->batch_convert( indirs, outdir );
	   this TODO

       $batchconv->batch_convert( undef	   , ...);
       $batchconv->batch_convert( q{@INC}, ...);
	   These two values for indirs specify that the normal Perl @INC

       $batchconv->batch_convert( \@dirs , ...);
	   This specifies that the input directories are the items in the
	   arrayref "\@dirs".

       $batchconv->batch_convert( "somedir" , ...);
	   This specifies that the director "somedir" is the input.  (This
	   can be an absolute or relative path, it doesn’t matter.)

	   A common value you might want would be just "." for the current
	   directory:

		$batchconv->batch_convert( "." , ...);

       $batchconv->batch_convert( ’somedir:someother:also’ , ...);
	   This specifies that you want the dirs "somedir", "somother", and
	   "also" scanned, just as if you’d passed the arrayref "[qw( somedir
	   someother also)]".  Note that a ":"-separator is normal under
	   Unix, but Under MSWin, you’ll need ’somedir;someother;also’
	   instead, since the pathsep on MSWin is ";" instead of ":".  (And
	   that is because ":" often comes up in paths, like "c:/perl/lib".)

	   (Exactly what separator character should be used, is gotten from
	   $Config::Config{’path_sep’}, via the Config module.)

       $batchconv->batch_convert( ... , undef );
	   This specifies that you want the HTML output to go into the cur-
	   rent directory.

	   (Note that a missing or undefined value means a different thing in
	   the first slot than in the second.  That’s so that "batch_con-
	   vert()" with no arguments (or undef arguments) means "go from
	   @INC, into the current directory.)

       $batchconv->batch_convert( ... , ’somedir’ );
	   This specifies that you want the HTML output to go into the direc-
	   tory ’somedir’.  (This can be an absolute or relative path, it
	   doesn’t matter.)

       Note that you can also call "batch_convert" as a class method, like
       so:

	 Pod::Simple::HTMLBatch->batch_convert( ... );

       That is just short for this:

	 Pod::Simple::HTMLBatch-> new-> batch_convert(...);

       That is, it runs a conversion with default options, for whatever
       inputdirs and output dir you specify.

       ACCESSOR METHODS

       The following are all accessor methods -- that is, they don’t do any-
       thing on their own, but just alter the contents of the conversion
       object, which comprises the options for this particular batch conver-
       sion.

       We show the "put" form of the accessors below (i.e., the syntax you
       use for setting the accessor to a specific value).  But you can also
       call each method with no parameters to get its current value.  For
       example, "$self->contents_file()" returns the current value of the
       contents_file attribute.

       $batchconv->verbose( nonnegative_integer );
	   This controls how verbose to be during batch conversion, as far as
	   notes to STDOUT (or whatever is "select"’d) about how the conver-
	   sion is going.  If 0, no progress information is printed.  If 1
	   (the default value), some progress information is printed.  Higher
	   values print more information.

       $batchconv->index( true-or-false );
	   This controls whether or not each HTML page is liable to have a
	   little table of contents at the top (which we call an "index" for
	   historical reasons).	 This is true by default.

       $batchconv->contents_file( filename );
	   If set, should be the name of a file (in the output directory) to
	   write the HTML index to.  The default value is "index.html".	 If
	   you set this to a false value, no contents file will be written.

       $batchconv->contents_page_start( HTML_string );
	   This specifies what string should be put at the beginning of the
	   contents page.  The default is a string more or less like this:

	     <html>
	     <head><title>Perl Documentation</title></head>
	     <body class=’contentspage’>
	     <h1>Perl Documentation</h1>

       $batchconv->contents_page_end( HTML_string );
	   This specifies what string should be put at the end of the con-
	   tents page.	The default is a string more or less like this:

	     <p class=’contentsfooty’>Generated by
	     Pod::Simple::HTMLBatch v3.01 under Perl v5.008
	     <br >At Fri May 14 22:26:42 2004 GMT,
	     which is Fri May 14 14:26:42 2004 local time.</p>

       $batchconv->add_css( $url );
	   TODO

       $batchconv->add_javascript( $url );
	   TODO

       $batchconv->css_flurry( true-or-false );
	   If true (the default value), we autogenerate some CSS files in the
	   output directory, and set our HTML files to use those.  TODO: con-
	   tinue

       $batchconv->javascript_flurry( true-or-false );
	   If true (the default value), we autogenerate a JavaScript in the
	   output directory, and set our HTML files to use it.	Currently,
	   the JavaScript is used only to get the browser to remember what
	   stylesheet it prefers.  TODO: continue

       $batchconv->no_contents_links( true-or-false );
	   TODO

       $batchconv->html_render_class( classname );
	   This sets what class is used for rendering the files.  The default
	   is "Pod::Simple::Search".  If you set it to something else, it
	   should probably be a subclass of Pod::Simple::Search, and you
	   should "require" or "use" that class so that’s it’s loaded before
	   Pod::Simple::HTMLBatch tries loading it.

NOTES ON CUSTOMIZATION
       TODO

	 call add_css($someurl) to add stylesheet as alternate
	 call add_css($someurl,1) to add as primary stylesheet

	 call add_javascript

	 subclass Pod::Simple::HTML and set $batchconv->html_render_class to
	   that classname
	 and maybe override
	   $page->batch_mode_page_object_init($self, $module, $infile, $outfile, $depth)
	 or maybe override
	   $batchconv->batch_mode_page_object_init($page, $module, $infile, $outfile, $depth)

ASK ME!
       If you want to do some kind of big pod-to-HTML version with some par-
       ticular kind of option that you don’t see how to achieve using this
       module, email me ("sburke@cpan.org") and I’ll probably have a good
       idea how to do it. For reasons of concision and energetic laziness,
       some methods and options in this module (and the dozen modules it
       depends on) are undocumented; but one of those undocumented bits might
       be just what you’re looking for.

SEE ALSO
       Pod::Simple, Pod::Simple::HTMLBatch, perlpod, perlpodspec

COPYRIGHT AND DISCLAIMERS
       Copyright (c) 2004 Sean M. Burke.  All rights reserved.

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

       This program is distributed in the hope that it will be useful, but
       without any warranty; without even the implied warranty of mer-
       chantability or fitness for a particular purpose.

AUTHOR
       Sean M. Burke "sburke@cpan.org"



perl v5.8.8			  2006-07-07	    Pod::Simple::HTMLBatch(3)