Pod::Simple::HTMLBatch (3pm)

  perl -MPod::Simple::HTMLBatch -e 'Pod::Simple::HTMLBatch::go' in out

This module is used for running batch-conversions of a lot of \s-1HTML\s0 documents

This class is \s-1NOT\s0 a subclass of Pod::Simple::HTML (nor of bad old Pod::Html) \*(-- although it uses Pod::Simple::HTML for doing the conversion 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 );

\s-1FROM\s0 \s-1THE\s0 \s-1COMMAND\s0 \s-1LINE\s0

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

However, the shortcut requires that you specify exactly two command-line arguments, \*(C`indirs\*(C' and \*(C`outdir\*(C'.

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 ./out_html)

(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 "\*(L" as the first command-line parameter when you mean \*(R"just use whatever's in @INC".)

Example:

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

Example:

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

This \s-1TODO\s0 this \s-1TODO\s0 These two values for indirs specify that the normal Perl @INC This specifies that the input directories are the items in the arrayref \*(C`\@dirs\*(C'. This specifies that the director \*(L"somedir\*(R" is the input. (This can be an absolute or relative path, it doesn't matter.) A common value you might want would be just \*(L".\*(R" for the current directory: $batchconv->batch_convert( "." , ...); This specifies that you want the dirs \*(L"somedir\*(R", \*(L"someother\*(R", and \*(L"also\*(R" scanned, just as if you'd passed the arrayref \*(C`[qw( somedir someother also)]\*(C'. Note that a \*(L":\*(R"-separator is normal under Unix, but Under MSWin, you'll need 'somedir;someother;also' instead, since the pathsep on MSWin is \*(L";\*(R" instead of \*(L":\*(R". (And that is because \*(L":\*(R" 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.) This specifies that you want the \s-1HTML\s0 output to go into the current directory. (Note that a missing or undefined value means a different thing in the first slot than in the second. That's so that \*(C`batch_convert()\*(C' with no arguments (or undef arguments) means "go from @INC, into the current directory.) This specifies that you want the \s-1HTML\s0 output to go into the directory 'somedir'. (This can be an absolute or relative path, it doesn't matter.)

Note that you can also call \*(C`batch_convert\*(C' 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.

\s-1ACCESSOR\s0 \s-1METHODS\s0

The following are all accessor methods \*(-- that is, they don't do anything on their own, but just alter the contents of the conversion object, which comprises the options for this particular batch conversion.

We show the \*(L"put\*(R" 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, \*(C`$self->contents_file()\*(C' returns the current value of the contents_file attribute. This controls how verbose to be during batch conversion, as far as notes to \s-1STDOUT\s0 (or whatever is \*(C`select\*(C''d) about how the conversion is going. If 0, no progress information is printed. If 1 (the default value), some progress information is printed. Higher values print more information. This controls whether or not each \s-1HTML\s0 page is liable to have a little table of contents at the top (which we call an \*(L"index\*(R" for historical reasons). This is true by default. If set, should be the name of a file (in the output directory) to write the \s-1HTML\s0 index to. The default value is \*(L"index.html\*(R". If you set this to a false value, no contents file will be written. 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> This specifies what string should be put at the end of the contents 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> \s-1TODO\s0 \s-1TODO\s0 If true (the default value), we autogenerate some \s-1CSS\s0 files in the output directory, and set our \s-1HTML\s0 files to use those. \s-1TODO:\s0 continue If true (the default value), we autogenerate a JavaScript in the output directory, and set our \s-1HTML\s0 files to use it. Currently, the JavaScript is used only to get the browser to remember what stylesheet it prefers. \s-1TODO:\s0 continue \s-1TODO\s0 This sets what class is used for rendering the files. The default is \*(L"Pod::Simple::HTML\*(R". If you set it to something else, it should probably be a subclass of Pod::Simple::HTML, and you should \*(C`require\*(C' or \*(C`use\*(C' that class so that's it's loaded before Pod::Simple::HTMLBatch tries loading it. This sets what class is used for searching for the files. The default is \*(L"Pod::Simple::Search\*(R". If you set it to something else, it should probably be a subclass of Pod::Simple::Search, and you should \*(C`require\*(C' or \*(C`use\*(C' that class so that's it's loaded before Pod::Simple::HTMLBatch tries loading it.

\s-1TODO\s0

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) subclass Pod::Simple::Search and set $batchconv->search_class to that classname

If you want to do some kind of big pod-to-HTML version with some particular kind of option that you don't see how to achieve using this module, email me (\*(C`[email protected]\*(C') 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.

Pod::Simple, Pod::Simple::HTMLBatch, perlpod, perlpodspec

Questions or discussion about \s-1POD\s0 and Pod::Simple should be sent to the [email protected] mail list. Send an empty email to [email protected] to subscribe.

This module is managed in an open GitHub repository, https://github.com/theory/pod-simple/ <https://github.com/theory/pod-simple/>. Feel free to fork and contribute, or to clone git://github.com/theory/pod-simple.git <git://github.com/theory/pod-simple.git> and send patches!

Patches against Pod::Simple are welcome. Please send bug reports to <[email protected]>.

Copyright (c) 2002 Sean M. Burke.

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 merchantability or fitness for a particular purpose.

Pod::Simple was created by Sean M. Burke <[email protected]>. But don't bother him, he's retired.

Pod::Simple is maintained by:

• Allison Randal \*(C`[email protected]\*(C'

• Hans Dieter Pearcey \*(C`[email protected]\*(C'

• David E. Wheeler \*(C`[email protected]\*(C'