1Pod::Simple::HTMLBatch(U3s)er Contributed Perl DocumentatPioodn::Simple::HTMLBatch(3)
2
3
4

NAME

6       Pod::Simple::HTMLBatch - convert several Pod files to several HTML
7       files
8

SYNOPSIS

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

DESCRIPTION

13       This module is used for running batch-conversions of a lot of HTML
14       documents
15
16       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
20       The normal use of this class is like so:
21
22         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
28   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
34       However, the shortcut requires that you specify exactly two command-
35       line arguments, "indirs" and "outdir".
36
37       Example:
38
39         % 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
44       (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
49       Example:
50
51         % 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
57       Example:
58
59         % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go happydocs .
60             (to convert all pod from happydocs into the current directory)
61

MAIN METHODS

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
68       $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
73       $batchconv->batch_convert( undef    , ...);
74       $batchconv->batch_convert( q{@INC}, ...);
75           These two values for indirs specify that the normal Perl @INC
76
77       $batchconv->batch_convert( \@dirs , ...);
78           This specifies that the input directories are the items in the
79           arrayref "\@dirs".
80
81       $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
85           A common value you might want would be just "." for the current
86           directory:
87
88                $batchconv->batch_convert( "." , ...);
89
90       $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
98           (Exactly what separator character should be used, is gotten from
99           $Config::Config{'path_sep'}, via the Config module.)
100
101       $batchconv->batch_convert( ... , undef );
102           This specifies that you want the HTML output to go into the current
103           directory.
104
105           (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
110       $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
115       Note that you can also call "batch_convert" as a class method, like so:
116
117         Pod::Simple::HTMLBatch->batch_convert( ... );
118
119       That is just short for this:
120
121         Pod::Simple::HTMLBatch-> new-> batch_convert(...);
122
123       That is, it runs a conversion with default options, for whatever
124       inputdirs and output dir you specify.
125
126   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
132       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
138       $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
145       $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
150       $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
155       $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
159             <html>
160             <head><title>Perl Documentation</title></head>
161             <body class='contentspage'>
162             <h1>Perl Documentation</h1>
163
164       $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
168             <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
173       $batchconv->add_css( $url );
174           TODO
175
176       $batchconv->add_javascript( $url );
177           TODO
178
179       $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
184       $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
190       $batchconv->no_contents_links( true-or-false );
191           TODO
192
193       $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
200       $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

NOTES ON CUSTOMIZATION

208       TODO
209
210         call add_css($someurl) to add stylesheet as alternate
211         call add_css($someurl,1) to add as primary stylesheet
212
213         call add_javascript
214
215         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

SEE ALSO

225       Pod::Simple, Pod::Simple::HTMLBatch, perlpod, perlpodspec
226

SUPPORT

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
232       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
237       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
243       This library is free software; you can redistribute it and/or modify it
244       under the same terms as Perl itself.
245
246       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

AUTHOR

251       Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.  But don't
252       bother him, he's retired.
253
254       Pod::Simple is maintained by:
255
256       •   Allison Randal "allison@perl.org"
257
258       •   Hans Dieter Pearcey "hdp@cpan.org"
259
260       •   David E. Wheeler "dwheeler@cpan.org"
261
262
263
264perl v5.36.0                      2023-01-20         Pod::Simple::HTMLBatch(3)
Impressum