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 TODO
65 $batchconv->batch_convert( indirs, outdir );
67 this TODO
68 $batchconv->batch_convert( undef , ...);
70 $batchconv->batch_convert( q{@INC}, ...);
71 These two values for indirs specify that the normal Perl @INC
72 $batchconv->batch_convert( \@dirs , ...);
74 This specifies that the input directories are the items in the
75 arrayref "\@dirs".
76 $batchconv->batch_convert( "somedir" , ...);
78 This specifies that the director "somedir" is the input. (This can
79 be an absolute or relative path, it doesn't matter.)
80 A common value you might want would be just "." for the current
82 directory:
83 $batchconv->batch_convert( "." , ...);
85 $batchconv->batch_convert( 'somedir:someother:also' , ...);
87 This specifies that you want the dirs "somedir", "someother", and
88 "also" scanned, just as if you'd passed the arrayref "[qw( somedir
89 someother also)]". Note that a ":"-separator is normal under Unix,
90 but Under MSWin, you'll need 'somedir;someother;also' instead,
91 since the pathsep on MSWin is ";" instead of ":". (And that is
92 because ":" often comes up in paths, like "c:/perl/lib".)
93 (Exactly what separator character should be used, is gotten from
95 $Config::Config{'path_sep'}, via the Config module.)
96 $batchconv->batch_convert( ... , undef );
98 This specifies that you want the HTML output to go into the current
99 directory.
100 (Note that a missing or undefined value means a different thing in
102 the first slot than in the second. That's so that
103 "batch_convert()" with no arguments (or undef arguments) means "go
104 from @INC, into the current directory.)
105 $batchconv->batch_convert( ... , 'somedir' );
107 This specifies that you want the HTML output to go into the
108 directory 'somedir'. (This can be an absolute or relative path, it
109 doesn't matter.)
110 Note that you can also call "batch_convert" as a class method, like so:
112 Pod::Simple::HTMLBatch->batch_convert( ... );
114 That is just short for this:
116 Pod::Simple::HTMLBatch-> new-> batch_convert(...);
118 That is, it runs a conversion with default options, for whatever
120 inputdirs and output dir you specify.
121 ACCESSOR METHODS
123 The following are all accessor methods -- that is, they don't do
124 anything on their own, but just alter the contents of the conversion
125 object, which comprises the options for this particular batch
126 conversion.
127 We show the "put" form of the accessors below (i.e., the syntax you use
129 for setting the accessor to a specific value). But you can also call
130 each method with no parameters to get its current value. For example,
131 "$self->contents_file()" returns the current value of the contents_file
132 attribute.
133 $batchconv->verbose( nonnegative_integer );
135 This controls how verbose to be during batch conversion, as far as
136 notes to STDOUT (or whatever is "select"'d) about how the
137 conversion is going. If 0, no progress information is printed. If
138 1 (the default value), some progress information is printed.
139 Higher values print more information.
140 $batchconv->index( true-or-false );
142 This controls whether or not each HTML page is liable to have a
143 little table of contents at the top (which we call an "index" for
144 historical reasons). This is true by default.
145 $batchconv->contents_file( filename );
147 If set, should be the name of a file (in the output directory) to
148 write the HTML index to. The default value is "index.html". If
149 you set this to a false value, no contents file will be written.
150 $batchconv->contents_page_start( HTML_string );
152 This specifies what string should be put at the beginning of the
153 contents page. The default is a string more or less like this:
154 <html>
156 <head><title>Perl Documentation</title></head>
157 <body class='contentspage'>
158 <h1>Perl Documentation</h1>
159 $batchconv->contents_page_end( HTML_string );
161 This specifies what string should be put at the end of the contents
162 page. The default is a string more or less like this:
163 <p class='contentsfooty'>Generated by
165 Pod::Simple::HTMLBatch v3.01 under Perl v5.008
166 <br >At Fri May 14 22:26:42 2004 GMT,
167 which is Fri May 14 14:26:42 2004 local time.</p>
168 $batchconv->add_css( $url );
170 TODO
171 $batchconv->add_javascript( $url );
173 TODO
174 $batchconv->css_flurry( true-or-false );
176 If true (the default value), we autogenerate some CSS files in the
177 output directory, and set our HTML files to use those. TODO:
178 continue
179 $batchconv->javascript_flurry( true-or-false );
181 If true (the default value), we autogenerate a JavaScript in the
182 output directory, and set our HTML files to use it. Currently, the
183 JavaScript is used only to get the browser to remember what
184 stylesheet it prefers. TODO: continue
185 $batchconv->no_contents_links( true-or-false );
187 TODO
188 $batchconv->html_render_class( classname );
190 This sets what class is used for rendering the files. The default
191 is "Pod::Simple::HTML". If you set it to something else, it should
192 probably be a subclass of Pod::Simple::HTML, and you should
193 "require" or "use" that class so that's it's loaded before
194 Pod::Simple::HTMLBatch tries loading it.
195 $batchconv->search_class( classname );
197 This sets what class is used for searching for the files. The
198 default is "Pod::Simple::Search". If you set it to something else,
199 it should probably be a subclass of Pod::Simple::Search, and you
200 should "require" or "use" that class so that's it's loaded before
201 Pod::Simple::HTMLBatch tries loading it.
202
204 TODO
205 call add_css($someurl) to add stylesheet as alternate
207 call add_css($someurl,1) to add as primary stylesheet
208 call add_javascript
210 subclass Pod::Simple::HTML and set $batchconv->html_render_class to
212 that classname
213 and maybe override
214 $page->batch_mode_page_object_init($self, $module, $infile, $outfile, $depth)
215 or maybe override
216 $batchconv->batch_mode_page_object_init($page, $module, $infile, $outfile, $depth)
217 subclass Pod::Simple::Search and set $batchconv->search_class to
218 that classname
219
221 If you want to do some kind of big pod-to-HTML version with some
222 particular kind of option that you don't see how to achieve using this
223 module, email me ("sburke@cpan.org") and I'll probably have a good idea
224 how to do it. For reasons of concision and energetic laziness, some
225 methods and options in this module (and the dozen modules it depends
226 on) are undocumented; but one of those undocumented bits might be just
227 what you're looking for.
228
230 Pod::Simple, Pod::Simple::HTMLBatch, perlpod, perlpodspec
231
233 Questions or discussion about POD and Pod::Simple should be sent to the
234 pod-people@perl.org mail list. Send an empty email to
235 pod-people-subscribe@perl.org to subscribe.
236 This module is managed in an open GitHub repository,
238 <https://github.com/theory/pod-simple/>. Feel free to fork and
239 contribute, or to clone <git://github.com/theory/pod-simple.git> and
240 send patches!
241 Patches against Pod::Simple are welcome. Please send bug reports to
243 <bug-pod-simple@rt.cpan.org>.
244
246 Copyright (c) 2002 Sean M. Burke.
247 This library is free software; you can redistribute it and/or modify it
249 under the same terms as Perl itself.
250 This program is distributed in the hope that it will be useful, but
252 without any warranty; without even the implied warranty of
253 merchantability or fitness for a particular purpose.
254
256 Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. But don't
257 bother him, he's retired.
258 Pod::Simple is maintained by:
260 · Allison Randal "allison@perl.org"
262 · Hans Dieter Pearcey "hdp@cpan.org"
264 · David E. Wheeler "dwheeler@cpan.org"
266perl v5.16.3 2013-05-03 Pod::Simple::HTMLBatch(3)