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
14 documents
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
18 conversion 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
30 Pod::Simple::HTMLBatch::go. This is basically just a shortcut for
31 "Pod::Simple::HTMLBatch->batch_convert(@ARGV)". It's meant to be handy
32 for calling from the command line.
33 However, the shortcut requires that you specify exactly two command-
35 line arguments, "indirs" and "outdir".
36 Example:
38 % mkdir out_html
40 % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go @INC out_html
41 (to convert the pod from Perl's @INC
42 files under the directory ./out_html)
43 (Note that the command line there contains a literal atsign-I-N-C.
45 This is handled as a special case by batch_convert, in order to save
46 you having to enter the odd-looking "" as the first command-line
47 parameter when you mean "just use whatever's in @INC".)
48 Example:
50 % mkdir ../seekrut
52 % chmod og-rx ../seekrut
53 % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go . ../seekrut
54 (to convert the pod under the current dir into HTML
55 files under the directory ./seekrut)
56 Example:
58 % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go happydocs .
60 (to convert all pod from happydocs into the current directory)
61
63 $batchconv = Pod::Simple::HTMLBatch->new;
64 This creates a new batch converter. The method doesn't take
65 parameters. To change the converter's attributes, use the
66 "ACCESSOR METHODS"" in " below.
67 $batchconv->batch_convert( indirs, outdir );
69 This searches the directories given in indirs and writes HTML files
70 for each of these to a corresponding directory in outdir. The
71 directory outdir must exist.
72 $batchconv->batch_convert( undef , ...);
74 $batchconv->batch_convert( q{@INC}, ...);
75 These two values for indirs specify that the normal Perl @INC
76 $batchconv->batch_convert( \@dirs , ...);
78 This specifies that the input directories are the items in the
79 arrayref "\@dirs".
80 $batchconv->batch_convert( "somedir" , ...);
82 This specifies that the director "somedir" is the input. (This can
83 be an absolute or relative path, it doesn't matter.)
84 A common value you might want would be just "." for the current
86 directory:
87 $batchconv->batch_convert( "." , ...);
89 $batchconv->batch_convert( 'somedir:someother:also' , ...);
91 This specifies that you want the dirs "somedir", "someother", and
92 "also" scanned, just as if you'd passed the arrayref "[qw( somedir
93 someother also)]". Note that a ":"-separator is normal under Unix,
94 but Under MSWin, you'll need 'somedir;someother;also' instead,
95 since the pathsep on MSWin is ";" instead of ":". (And that is
96 because ":" often comes up in paths, like "c:/perl/lib".)
97 (Exactly what separator character should be used, is gotten from
99 $Config::Config{'path_sep'}, via the Config module.)
100 $batchconv->batch_convert( ... , undef );
102 This specifies that you want the HTML output to go into the current
103 directory.
104 (Note that a missing or undefined value means a different thing in
106 the first slot than in the second. That's so that batch_convert()
107 with no arguments (or undef arguments) means "go from @INC, into
108 the current directory.)
109 $batchconv->batch_convert( ... , 'somedir' );
111 This specifies that you want the HTML output to go into the
112 directory 'somedir'. (This can be an absolute or relative path, it
113 doesn't matter.)
114 Note that you can also call "batch_convert" as a class method, like so:
116 Pod::Simple::HTMLBatch->batch_convert( ... );
118 That is just short for this:
120 Pod::Simple::HTMLBatch-> new-> batch_convert(...);
122 That is, it runs a conversion with default options, for whatever
124 inputdirs and output dir you specify.
125 ACCESSOR METHODS
127 The following are all accessor methods -- that is, they don't do
128 anything on their own, but just alter the contents of the conversion
129 object, which comprises the options for this particular batch
130 conversion.
131 We show the "put" form of the accessors below (i.e., the syntax you use
133 for setting the accessor to a specific value). But you can also call
134 each method with no parameters to get its current value. For example,
135 "$self->contents_file()" returns the current value of the contents_file
136 attribute.
137 $batchconv->verbose( nonnegative_integer );
139 This controls how verbose to be during batch conversion, as far as
140 notes to STDOUT (or whatever is "select"'d) about how the
141 conversion is going. If 0, no progress information is printed. If
142 1 (the default value), some progress information is printed.
143 Higher values print more information.
144 $batchconv->index( true-or-false );
146 This controls whether or not each HTML page is liable to have a
147 little table of contents at the top (which we call an "index" for
148 historical reasons). This is true by default.
149 $batchconv->contents_file( filename );
151 If set, should be the name of a file (in the output directory) to
152 write the HTML index to. The default value is "index.html". If
153 you set this to a false value, no contents file will be written.
154 $batchconv->contents_page_start( HTML_string );
156 This specifies what string should be put at the beginning of the
157 contents page. The default is a string more or less like this:
158 <html>
160 <head><title>Perl Documentation</title></head>
161 <body class='contentspage'>
162 <h1>Perl Documentation</h1>
163 $batchconv->contents_page_end( HTML_string );
165 This specifies what string should be put at the end of the contents
166 page. The default is a string more or less like this:
167 <p class='contentsfooty'>Generated by
169 Pod::Simple::HTMLBatch v3.01 under Perl v5.008
170 <br >At Fri May 14 22:26:42 2004 GMT,
171 which is Fri May 14 14:26:42 2004 local time.</p>
172 $batchconv->add_css( $url );
174 TODO
175 $batchconv->add_javascript( $url );
177 TODO
178 $batchconv->css_flurry( true-or-false );
180 If true (the default value), we autogenerate some CSS files in the
181 output directory, and set our HTML files to use those. TODO:
182 continue
183 $batchconv->javascript_flurry( true-or-false );
185 If true (the default value), we autogenerate a JavaScript in the
186 output directory, and set our HTML files to use it. Currently, the
187 JavaScript is used only to get the browser to remember what
188 stylesheet it prefers. TODO: continue
189 $batchconv->no_contents_links( true-or-false );
191 TODO
192 $batchconv->html_render_class( classname );
194 This sets what class is used for rendering the files. The default
195 is "Pod::Simple::HTML". If you set it to something else, it should
196 probably be a subclass of Pod::Simple::HTML, and you should
197 "require" or "use" that class so that's it's loaded before
198 Pod::Simple::HTMLBatch tries loading it.
199 $batchconv->search_class( classname );
201 This sets what class is used for searching for the files. The
202 default is "Pod::Simple::Search". If you set it to something else,
203 it should probably be a subclass of Pod::Simple::Search, and you
204 should "require" or "use" that class so that's it's loaded before
205 Pod::Simple::HTMLBatch tries loading it.
206
208 TODO
209 call add_css($someurl) to add stylesheet as alternate
211 call add_css($someurl,1) to add as primary stylesheet
212 call add_javascript
214 subclass Pod::Simple::HTML and set $batchconv->html_render_class to
216 that classname
217 and maybe override
218 $page->batch_mode_page_object_init($self, $module, $infile, $outfile, $depth)
219 or maybe override
220 $batchconv->batch_mode_page_object_init($page, $module, $infile, $outfile, $depth)
221 subclass Pod::Simple::Search and set $batchconv->search_class to
222 that classname
223
225 Pod::Simple, Pod::Simple::HTMLBatch, perlpod, perlpodspec
226
228 Questions or discussion about POD and Pod::Simple should be sent to the
229 pod-people@perl.org mail list. Send an empty email to
230 pod-people-subscribe@perl.org to subscribe.
231 This module is managed in an open GitHub repository,
233 <https://github.com/perl-pod/pod-simple/>. Feel free to fork and
234 contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and
235 send patches!
236 Patches against Pod::Simple are welcome. Please send bug reports to
238 <bug-pod-simple@rt.cpan.org>.
239
241 Copyright (c) 2002 Sean M. Burke.
242 This library is free software; you can redistribute it and/or modify it
244 under the same terms as Perl itself.
245 This program is distributed in the hope that it will be useful, but
247 without any warranty; without even the implied warranty of
248 merchantability or fitness for a particular purpose.
249
251 Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. But don't
252 bother him, he's retired.
253 Pod::Simple is maintained by:
255 • Allison Randal "allison@perl.org"
257 • Hans Dieter Pearcey "hdp@cpan.org"
259 • David E. Wheeler "dwheeler@cpan.org"
261perl v5.36.0 2023-01-20 Pod::Simple::HTMLBatch(3)