1Pod::Simple::HTMLBatch(U3s)er Contributed Perl DocumentatPioodn::Simple::HTMLBatch(3)
2
6 Pod::Simple::HTMLBatch - convert several Pod files to several HTML
7 files
8
10 perl -MPod::Simple::HTMLBatch -e 'Pod::Simple::HTMLBatch::go' in out
11
13 This module is used for running batch-conversions of a lot of HTML doc‐
14 uments
15 This class is NOT a subclass of Pod::Simple::HTML (nor of bad old
17 Pod::Html) -- although it uses Pod::Simple::HTML for doing the conver‐
18 sion of each document.
19 The normal use of this class is like so:
21 use Pod::Simple::HTMLBatch;
23 my $batchconv = Pod::Simple::HTMLBatch->new;
24 $batchconv->some_option( some_value );
25 $batchconv->some_other_option( some_other_value );
26 $batchconv->batch_convert( \@search_dirs, $output_dir );
27 FROM THE COMMAND LINE
29 Note that this class also provides (but does not export) the function
31 Pod::Simple::HTMLBatch::go. This is basically just a shortcut for
32 "Pod::Simple::HTMLBatch->batch_convert(@ARGV)". It's meant to be handy
33 for calling from the command line.
34 However, the shortcut requires that you specify exactly two command-
36 line arguments, "indirs" and "outdir".
37 Example:
39 % mkdir out_html
41 % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go @INC out_html
42 (to convert the pod from Perl's @INC
43 files under the directory ../htmlversion)
44 (Note that the command line there contains a literal atsign-I-N-C.
46 This is handled as a special case by batch_convert, in order to save
47 you having to enter the odd-looking "" as the first command-line param‐
48 eter when you mean "just use whatever's in @INC".)
49 Example:
51 % mkdir ../seekrut
53 % chmod og-rx ../seekrut
54 % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go . ../htmlversion
55 (to convert the pod under the current dir into HTML
56 files under the directory ../htmlversion)
57 Example:
59 % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go happydocs .
61 (to convert all pod from happydocs into the current directory)
62
64 $batchconv = Pod::Simple::HTMLBatch->new;
65 This TODO
66 $batchconv->batch_convert( indirs, outdir );
68 this TODO
69 $batchconv->batch_convert( undef , ...);
71 $batchconv->batch_convert( q{@INC}, ...);
72 These two values for indirs specify that the normal Perl @INC
73 $batchconv->batch_convert( \@dirs , ...);
75 This specifies that the input directories are the items in the
76 arrayref "\@dirs".
77 $batchconv->batch_convert( "somedir" , ...);
79 This specifies that the director "somedir" is the input. (This can
80 be an absolute or relative path, it doesn't matter.)
81 A common value you might want would be just "." for the current
83 directory:
84 $batchconv->batch_convert( "." , ...);
86 $batchconv->batch_convert( 'somedir:someother:also' , ...);
88 This specifies that you want the dirs "somedir", "somother", and
89 "also" scanned, just as if you'd passed the arrayref "[qw( somedir
90 someother also)]". Note that a ":"-separator is normal under Unix,
91 but Under MSWin, you'll need 'somedir;someother;also' instead,
92 since the pathsep on MSWin is ";" instead of ":". (And that is
93 because ":" often comes up in paths, like "c:/perl/lib".)
94 (Exactly what separator character should be used, is gotten from
96 $Config::Config{'path_sep'}, via the Config module.)
97 $batchconv->batch_convert( ... , undef );
99 This specifies that you want the HTML output to go into the current
100 directory.
101 (Note that a missing or undefined value means a different thing in
103 the first slot than in the second. That's so that "batch_con‐
104 vert()" with no arguments (or undef arguments) means "go from @INC,
105 into the current directory.)
106 $batchconv->batch_convert( ... , 'somedir' );
108 This specifies that you want the HTML output to go into the direc‐
109 tory 'somedir'. (This can be an absolute or relative path, it
110 doesn't matter.)
111 Note that you can also call "batch_convert" as a class method, like so:
113 Pod::Simple::HTMLBatch->batch_convert( ... );
115 That is just short for this:
117 Pod::Simple::HTMLBatch-> new-> batch_convert(...);
119 That is, it runs a conversion with default options, for whatever input‐
121 dirs and output dir you specify.
122 ACCESSOR METHODS
124 The following are all accessor methods -- that is, they don't do any‐
126 thing on their own, but just alter the contents of the conversion
127 object, which comprises the options for this particular batch conver‐
128 sion.
129 We show the "put" form of the accessors below (i.e., the syntax you use
131 for setting the accessor to a specific value). But you can also call
132 each method with no parameters to get its current value. For example,
133 "$self->contents_file()" returns the current value of the contents_file
134 attribute.
135 $batchconv->verbose( nonnegative_integer );
137 This controls how verbose to be during batch conversion, as far as
138 notes to STDOUT (or whatever is "select"'d) about how the conver‐
139 sion is going. If 0, no progress information is printed. If 1
140 (the default value), some progress information is printed. Higher
141 values print more information.
142 $batchconv->index( true-or-false );
144 This controls whether or not each HTML page is liable to have a
145 little table of contents at the top (which we call an "index" for
146 historical reasons). This is true by default.
147 $batchconv->contents_file( filename );
149 If set, should be the name of a file (in the output directory) to
150 write the HTML index to. The default value is "index.html". If
151 you set this to a false value, no contents file will be written.
152 $batchconv->contents_page_start( HTML_string );
154 This specifies what string should be put at the beginning of the
155 contents page. The default is a string more or less like this:
156 <html>
158 <head><title>Perl Documentation</title></head>
159 <body class='contentspage'>
160 <h1>Perl Documentation</h1>
161 $batchconv->contents_page_end( HTML_string );
163 This specifies what string should be put at the end of the contents
164 page. The default is a string more or less like this:
165 <p class='contentsfooty'>Generated by
167 Pod::Simple::HTMLBatch v3.01 under Perl v5.008
168 <br >At Fri May 14 22:26:42 2004 GMT,
169 which is Fri May 14 14:26:42 2004 local time.</p>
170 $batchconv->add_css( $url );
172 TODO
173 $batchconv->add_javascript( $url );
175 TODO
176 $batchconv->css_flurry( true-or-false );
178 If true (the default value), we autogenerate some CSS files in the
179 output directory, and set our HTML files to use those. TODO: con‐
180 tinue
181 $batchconv->javascript_flurry( true-or-false );
183 If true (the default value), we autogenerate a JavaScript in the
184 output directory, and set our HTML files to use it. Currently, the
185 JavaScript is used only to get the browser to remember what
186 stylesheet it prefers. TODO: continue
187 $batchconv->no_contents_links( true-or-false );
189 TODO
190 $batchconv->html_render_class( classname );
192 This sets what class is used for rendering the files. The default
193 is "Pod::Simple::Search". If you set it to something else, it
194 should probably be a subclass of Pod::Simple::Search, and you
195 should "require" or "use" that class so that's it's loaded before
196 Pod::Simple::HTMLBatch tries loading it.
197
199 TODO
200 call add_css($someurl) to add stylesheet as alternate
202 call add_css($someurl,1) to add as primary stylesheet
203 call add_javascript
205 subclass Pod::Simple::HTML and set $batchconv->html_render_class to
207 that classname
208 and maybe override
209 $page->batch_mode_page_object_init($self, $module, $infile, $outfile, $depth)
210 or maybe override
211 $batchconv->batch_mode_page_object_init($page, $module, $infile, $outfile, $depth)
212
214 If you want to do some kind of big pod-to-HTML version with some par‐
215 ticular kind of option that you don't see how to achieve using this
216 module, email me ("sburke@cpan.org") and I'll probably have a good idea
217 how to do it. For reasons of concision and energetic laziness, some
218 methods and options in this module (and the dozen modules it depends
219 on) are undocumented; but one of those undocumented bits might be just
220 what you're looking for.
221
223 Pod::Simple, Pod::Simple::HTMLBatch, perlpod, perlpodspec
224
226 Copyright (c) 2004 Sean M. Burke. All rights reserved.
227 This library is free software; you can redistribute it and/or modify it
229 under the same terms as Perl itself.
230 This program is distributed in the hope that it will be useful, but
232 without any warranty; without even the implied warranty of mer‐
233 chantability or fitness for a particular purpose.
234
236 Sean M. Burke "sburke@cpan.org"
237perl v5.8.8 2003-11-02 Pod::Simple::HTMLBatch(3)