| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Pod::Simple::HTMLBatch 3perl" |
| 58 |
.TH Pod::Simple::HTMLBatch 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Pod::Simple::HTMLBatch \- convert several Pod files to several HTML files |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& perl \-MPod::Simple::HTMLBatch \-e \*(AqPod::Simple::HTMLBatch::go\*(Aq in out |
| 69 |
.Ve |
| 70 |
.SH DESCRIPTION |
| 71 |
.IX Header "DESCRIPTION" |
| 72 |
This module is used for running batch-conversions of a lot of HTML |
| 73 |
documents |
| 74 |
.PP |
| 75 |
This class is NOT a subclass of Pod::Simple::HTML |
| 76 |
(nor of bad old Pod::Html) \-\- although it uses |
| 77 |
Pod::Simple::HTML for doing the conversion of each document. |
| 78 |
.PP |
| 79 |
The normal use of this class is like so: |
| 80 |
.PP |
| 81 |
.Vb 5 |
| 82 |
\& use Pod::Simple::HTMLBatch; |
| 83 |
\& my $batchconv = Pod::Simple::HTMLBatch\->new; |
| 84 |
\& $batchconv\->some_option( some_value ); |
| 85 |
\& $batchconv\->some_other_option( some_other_value ); |
| 86 |
\& $batchconv\->batch_convert( \e@search_dirs, $output_dir ); |
| 87 |
.Ve |
| 88 |
.SS "FROM THE COMMAND LINE" |
| 89 |
.IX Subsection "FROM THE COMMAND LINE" |
| 90 |
Note that this class also provides |
| 91 |
(but does not export) the function Pod::Simple::HTMLBatch::go. |
| 92 |
This is basically just a shortcut for \f(CW\*(C`Pod::Simple::HTMLBatch\->batch_convert(@ARGV)\*(C'\fR. |
| 93 |
It's meant to be handy for calling from the command line. |
| 94 |
.PP |
| 95 |
However, the shortcut requires that you specify exactly two command-line |
| 96 |
arguments, \f(CW\*(C`indirs\*(C'\fR and \f(CW\*(C`outdir\*(C'\fR. |
| 97 |
.PP |
| 98 |
Example: |
| 99 |
.PP |
| 100 |
.Vb 4 |
| 101 |
\& % mkdir out_html |
| 102 |
\& % perl \-MPod::Simple::HTMLBatch \-e Pod::Simple::HTMLBatch::go @INC out_html |
| 103 |
\& (to convert the pod from Perl\*(Aqs @INC |
| 104 |
\& files under the directory ./out_html) |
| 105 |
.Ve |
| 106 |
.PP |
| 107 |
(Note that the command line there contains a literal atsign-I-N-C. This |
| 108 |
is handled as a special case by batch_convert, in order to save you having |
| 109 |
to enter the odd-looking "" as the first command-line parameter when you |
| 110 |
mean "just use whatever's in \f(CW@INC\fR".) |
| 111 |
.PP |
| 112 |
Example: |
| 113 |
.PP |
| 114 |
.Vb 5 |
| 115 |
\& % mkdir ../seekrut |
| 116 |
\& % chmod og\-rx ../seekrut |
| 117 |
\& % perl \-MPod::Simple::HTMLBatch \-e Pod::Simple::HTMLBatch::go . ../seekrut |
| 118 |
\& (to convert the pod under the current dir into HTML |
| 119 |
\& files under the directory ./seekrut) |
| 120 |
.Ve |
| 121 |
.PP |
| 122 |
Example: |
| 123 |
.PP |
| 124 |
.Vb 2 |
| 125 |
\& % perl \-MPod::Simple::HTMLBatch \-e Pod::Simple::HTMLBatch::go happydocs . |
| 126 |
\& (to convert all pod from happydocs into the current directory) |
| 127 |
.Ve |
| 128 |
.SH "MAIN METHODS" |
| 129 |
.IX Header "MAIN METHODS" |
| 130 |
.ie n .IP "$batchconv = Pod::Simple::HTMLBatch\->new;" 4 |
| 131 |
.el .IP "\f(CW$batchconv\fR = Pod::Simple::HTMLBatch\->new;" 4 |
| 132 |
.IX Item "$batchconv = Pod::Simple::HTMLBatch->new;" |
| 133 |
This creates a new batch converter. The method doesn't take parameters. |
| 134 |
To change the converter's attributes, use the "ACCESSOR METHODS"" in " |
| 135 |
below. |
| 136 |
.ie n .IP "$batchconv\->batch_convert( \fIindirs\fR, \fIoutdir\fR );" 4 |
| 137 |
.el .IP "\f(CW$batchconv\fR\->batch_convert( \fIindirs\fR, \fIoutdir\fR );" 4 |
| 138 |
.IX Item "$batchconv->batch_convert( indirs, outdir );" |
| 139 |
This searches the directories given in \fIindirs\fR and writes |
| 140 |
HTML files for each of these to a corresponding directory |
| 141 |
in \fIoutdir\fR. The directory \fIoutdir\fR must exist. |
| 142 |
.ie n .IP "$batchconv\->batch_convert( undef , ...);" 4 |
| 143 |
.el .IP "\f(CW$batchconv\fR\->batch_convert( undef , ...);" 4 |
| 144 |
.IX Item "$batchconv->batch_convert( undef , ...);" |
| 145 |
.PD 0 |
| 146 |
.ie n .IP "$batchconv\->batch_convert( q{@INC}, ...);" 4 |
| 147 |
.el .IP "\f(CW$batchconv\fR\->batch_convert( q{@INC}, ...);" 4 |
| 148 |
.IX Item "$batchconv->batch_convert( q{@INC}, ...);" |
| 149 |
.PD |
| 150 |
These two values for \fIindirs\fR specify that the normal Perl \f(CW@INC\fR |
| 151 |
.ie n .IP "$batchconv\->batch_convert( \e@dirs , ...);" 4 |
| 152 |
.el .IP "\f(CW$batchconv\fR\->batch_convert( \e@dirs , ...);" 4 |
| 153 |
.IX Item "$batchconv->batch_convert( @dirs , ...);" |
| 154 |
This specifies that the input directories are the items in |
| 155 |
the arrayref \f(CW\*(C`\e@dirs\*(C'\fR. |
| 156 |
.ie n .IP "$batchconv\->batch_convert( ""somedir"" , ...);" 4 |
| 157 |
.el .IP "\f(CW$batchconv\fR\->batch_convert( ""somedir"" , ...);" 4 |
| 158 |
.IX Item "$batchconv->batch_convert( ""somedir"" , ...);" |
| 159 |
This specifies that the director "somedir" is the input. |
| 160 |
(This can be an absolute or relative path, it doesn't matter.) |
| 161 |
.Sp |
| 162 |
A common value you might want would be just "." for the current |
| 163 |
directory: |
| 164 |
.Sp |
| 165 |
.Vb 1 |
| 166 |
\& $batchconv\->batch_convert( "." , ...); |
| 167 |
.Ve |
| 168 |
.ie n .IP "$batchconv\->batch_convert( 'somedir:someother:also' , ...);" 4 |
| 169 |
.el .IP "\f(CW$batchconv\fR\->batch_convert( 'somedir:someother:also' , ...);" 4 |
| 170 |
.IX Item "$batchconv->batch_convert( 'somedir:someother:also' , ...);" |
| 171 |
This specifies that you want the dirs "somedir", "someother", and "also" |
| 172 |
scanned, just as if you'd passed the arrayref |
| 173 |
\&\f(CW\*(C`[qw( somedir someother also)]\*(C'\fR. Note that a ":"\-separator is normal |
| 174 |
under Unix, but Under MSWin, you'll need \f(CW\*(Aqsomedir;someother;also\*(Aq\fR |
| 175 |
instead, since the pathsep on MSWin is ";" instead of ":". (And |
| 176 |
\&\fIthat\fR is because ":" often comes up in paths, like |
| 177 |
\&\f(CW"c:/perl/lib"\fR.) |
| 178 |
.Sp |
| 179 |
(Exactly what separator character should be used, is gotten from |
| 180 |
\&\f(CW$Config::Config{\*(Aqpath_sep\*(Aq}\fR, via the Config module.) |
| 181 |
.ie n .IP "$batchconv\->batch_convert( ... , undef );" 4 |
| 182 |
.el .IP "\f(CW$batchconv\fR\->batch_convert( ... , undef );" 4 |
| 183 |
.IX Item "$batchconv->batch_convert( ... , undef );" |
| 184 |
This specifies that you want the HTML output to go into the current |
| 185 |
directory. |
| 186 |
.Sp |
| 187 |
(Note that a missing or undefined value means a different thing in |
| 188 |
the first slot than in the second. That's so that \f(CWbatch_convert()\fR |
| 189 |
with no arguments (or undef arguments) means "go from \f(CW@INC\fR, into |
| 190 |
the current directory.) |
| 191 |
.ie n .IP "$batchconv\->batch_convert( ... , 'somedir' );" 4 |
| 192 |
.el .IP "\f(CW$batchconv\fR\->batch_convert( ... , 'somedir' );" 4 |
| 193 |
.IX Item "$batchconv->batch_convert( ... , 'somedir' );" |
| 194 |
This specifies that you want the HTML output to go into the |
| 195 |
directory 'somedir'. |
| 196 |
(This can be an absolute or relative path, it doesn't matter.) |
| 197 |
.PP |
| 198 |
Note that you can also call \f(CW\*(C`batch_convert\*(C'\fR as a class method, |
| 199 |
like so: |
| 200 |
.PP |
| 201 |
.Vb 1 |
| 202 |
\& Pod::Simple::HTMLBatch\->batch_convert( ... ); |
| 203 |
.Ve |
| 204 |
.PP |
| 205 |
That is just short for this: |
| 206 |
.PP |
| 207 |
.Vb 1 |
| 208 |
\& Pod::Simple::HTMLBatch\-> new\-> batch_convert(...); |
| 209 |
.Ve |
| 210 |
.PP |
| 211 |
That is, it runs a conversion with default options, for |
| 212 |
whatever inputdirs and output dir you specify. |
| 213 |
.SS "ACCESSOR METHODS" |
| 214 |
.IX Subsection "ACCESSOR METHODS" |
| 215 |
The following are all accessor methods \-\- that is, they don't do anything |
| 216 |
on their own, but just alter the contents of the conversion object, |
| 217 |
which comprises the options for this particular batch conversion. |
| 218 |
.PP |
| 219 |
We show the "put" form of the accessors below (i.e., the syntax you use |
| 220 |
for setting the accessor to a specific value). But you can also |
| 221 |
call each method with no parameters to get its current value. For |
| 222 |
example, \f(CW\*(C`$self\->contents_file()\*(C'\fR returns the current value of |
| 223 |
the contents_file attribute. |
| 224 |
.ie n .IP "$batchconv\->verbose( \fInonnegative_integer\fR );" 4 |
| 225 |
.el .IP "\f(CW$batchconv\fR\->verbose( \fInonnegative_integer\fR );" 4 |
| 226 |
.IX Item "$batchconv->verbose( nonnegative_integer );" |
| 227 |
This controls how verbose to be during batch conversion, as far as |
| 228 |
notes to STDOUT (or whatever is \f(CW\*(C`select\*(C'\fR'd) about how the conversion |
| 229 |
is going. If 0, no progress information is printed. |
| 230 |
If 1 (the default value), some progress information is printed. |
| 231 |
Higher values print more information. |
| 232 |
.ie n .IP "$batchconv\->index( \fItrue-or-false\fR );" 4 |
| 233 |
.el .IP "\f(CW$batchconv\fR\->index( \fItrue-or-false\fR );" 4 |
| 234 |
.IX Item "$batchconv->index( true-or-false );" |
| 235 |
This controls whether or not each HTML page is liable to have a little |
| 236 |
table of contents at the top (which we call an "index" for historical |
| 237 |
reasons). This is true by default. |
| 238 |
.ie n .IP "$batchconv\->contents_file( \fIfilename\fR );" 4 |
| 239 |
.el .IP "\f(CW$batchconv\fR\->contents_file( \fIfilename\fR );" 4 |
| 240 |
.IX Item "$batchconv->contents_file( filename );" |
| 241 |
If set, should be the name of a file (in the output directory) |
| 242 |
to write the HTML index to. The default value is "index.html". |
| 243 |
If you set this to a false value, no contents file will be written. |
| 244 |
.ie n .IP "$batchconv\->contents_page_start( \fIHTML_string\fR );" 4 |
| 245 |
.el .IP "\f(CW$batchconv\fR\->contents_page_start( \fIHTML_string\fR );" 4 |
| 246 |
.IX Item "$batchconv->contents_page_start( HTML_string );" |
| 247 |
This specifies what string should be put at the beginning of |
| 248 |
the contents page. |
| 249 |
The default is a string more or less like this: |
| 250 |
.Sp |
| 251 |
.Vb 4 |
| 252 |
\& <html> |
| 253 |
\& <head><title>Perl Documentation</title></head> |
| 254 |
\& <body class=\*(Aqcontentspage\*(Aq> |
| 255 |
\& <h1>Perl Documentation</h1> |
| 256 |
.Ve |
| 257 |
.ie n .IP "$batchconv\->contents_page_end( \fIHTML_string\fR );" 4 |
| 258 |
.el .IP "\f(CW$batchconv\fR\->contents_page_end( \fIHTML_string\fR );" 4 |
| 259 |
.IX Item "$batchconv->contents_page_end( HTML_string );" |
| 260 |
This specifies what string should be put at the end of the contents page. |
| 261 |
The default is a string more or less like this: |
| 262 |
.Sp |
| 263 |
.Vb 4 |
| 264 |
\& <p class=\*(Aqcontentsfooty\*(Aq>Generated by |
| 265 |
\& Pod::Simple::HTMLBatch v3.01 under Perl v5.008 |
| 266 |
\& <br >At Fri May 14 22:26:42 2004 GMT, |
| 267 |
\& which is Fri May 14 14:26:42 2004 local time.</p> |
| 268 |
.Ve |
| 269 |
.ie n .IP "$batchconv\->add_css( $url );" 4 |
| 270 |
.el .IP "\f(CW$batchconv\fR\->add_css( \f(CW$url\fR );" 4 |
| 271 |
.IX Item "$batchconv->add_css( $url );" |
| 272 |
TODO |
| 273 |
.ie n .IP "$batchconv\->add_javascript( $url );" 4 |
| 274 |
.el .IP "\f(CW$batchconv\fR\->add_javascript( \f(CW$url\fR );" 4 |
| 275 |
.IX Item "$batchconv->add_javascript( $url );" |
| 276 |
TODO |
| 277 |
.ie n .IP "$batchconv\->css_flurry( \fItrue-or-false\fR );" 4 |
| 278 |
.el .IP "\f(CW$batchconv\fR\->css_flurry( \fItrue-or-false\fR );" 4 |
| 279 |
.IX Item "$batchconv->css_flurry( true-or-false );" |
| 280 |
If true (the default value), we autogenerate some CSS files in the |
| 281 |
output directory, and set our HTML files to use those. |
| 282 |
TODO: continue |
| 283 |
.ie n .IP "$batchconv\->javascript_flurry( \fItrue-or-false\fR );" 4 |
| 284 |
.el .IP "\f(CW$batchconv\fR\->javascript_flurry( \fItrue-or-false\fR );" 4 |
| 285 |
.IX Item "$batchconv->javascript_flurry( true-or-false );" |
| 286 |
If true (the default value), we autogenerate a JavaScript in the |
| 287 |
output directory, and set our HTML files to use it. Currently, |
| 288 |
the JavaScript is used only to get the browser to remember what |
| 289 |
stylesheet it prefers. |
| 290 |
TODO: continue |
| 291 |
.ie n .IP "$batchconv\->no_contents_links( \fItrue-or-false\fR );" 4 |
| 292 |
.el .IP "\f(CW$batchconv\fR\->no_contents_links( \fItrue-or-false\fR );" 4 |
| 293 |
.IX Item "$batchconv->no_contents_links( true-or-false );" |
| 294 |
TODO |
| 295 |
.ie n .IP "$batchconv\->html_render_class( \fIclassname\fR );" 4 |
| 296 |
.el .IP "\f(CW$batchconv\fR\->html_render_class( \fIclassname\fR );" 4 |
| 297 |
.IX Item "$batchconv->html_render_class( classname );" |
| 298 |
This sets what class is used for rendering the files. |
| 299 |
The default is "Pod::Simple::HTML". If you set it to something else, |
| 300 |
it should probably be a subclass of Pod::Simple::HTML, and you should |
| 301 |
\&\f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR that class so that's it's loaded before |
| 302 |
Pod::Simple::HTMLBatch tries loading it. |
| 303 |
.ie n .IP "$batchconv\->search_class( \fIclassname\fR );" 4 |
| 304 |
.el .IP "\f(CW$batchconv\fR\->search_class( \fIclassname\fR );" 4 |
| 305 |
.IX Item "$batchconv->search_class( classname );" |
| 306 |
This sets what class is used for searching for the files. |
| 307 |
The default is "Pod::Simple::Search". If you set it to something else, |
| 308 |
it should probably be a subclass of Pod::Simple::Search, and you should |
| 309 |
\&\f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR that class so that's it's loaded before |
| 310 |
Pod::Simple::HTMLBatch tries loading it. |
| 311 |
.SH "NOTES ON CUSTOMIZATION" |
| 312 |
.IX Header "NOTES ON CUSTOMIZATION" |
| 313 |
TODO |
| 314 |
.PP |
| 315 |
.Vb 2 |
| 316 |
\& call add_css($someurl) to add stylesheet as alternate |
| 317 |
\& call add_css($someurl,1) to add as primary stylesheet |
| 318 |
\& |
| 319 |
\& call add_javascript |
| 320 |
\& |
| 321 |
\& subclass Pod::Simple::HTML and set $batchconv\->html_render_class to |
| 322 |
\& that classname |
| 323 |
\& and maybe override |
| 324 |
\& $page\->batch_mode_page_object_init($self, $module, $infile, $outfile, $depth) |
| 325 |
\& or maybe override |
| 326 |
\& $batchconv\->batch_mode_page_object_init($page, $module, $infile, $outfile, $depth) |
| 327 |
\& subclass Pod::Simple::Search and set $batchconv\->search_class to |
| 328 |
\& that classname |
| 329 |
.Ve |
| 330 |
.SH "SEE ALSO" |
| 331 |
.IX Header "SEE ALSO" |
| 332 |
Pod::Simple, Pod::Simple::HTMLBatch, perlpod, perlpodspec |
| 333 |
.SH SUPPORT |
| 334 |
.IX Header "SUPPORT" |
| 335 |
Questions or discussion about POD and Pod::Simple should be sent to the |
| 336 |
pod\[email protected] mail list. Send an empty email to |
| 337 |
pod\-people\[email protected] to subscribe. |
| 338 |
.PP |
| 339 |
This module is managed in an open GitHub repository, |
| 340 |
<https://github.com/perl\-pod/pod\-simple/>. Feel free to fork and contribute, or |
| 341 |
to clone <https://github.com/perl\-pod/pod\-simple.git> and send patches! |
| 342 |
.PP |
| 343 |
Patches against Pod::Simple are welcome. Please send bug reports to |
| 344 |
<bug\-pod\[email protected]>. |
| 345 |
.SH "COPYRIGHT AND DISCLAIMERS" |
| 346 |
.IX Header "COPYRIGHT AND DISCLAIMERS" |
| 347 |
Copyright (c) 2002 Sean M. Burke. |
| 348 |
.PP |
| 349 |
This library is free software; you can redistribute it and/or modify it |
| 350 |
under the same terms as Perl itself. |
| 351 |
.PP |
| 352 |
This program is distributed in the hope that it will be useful, but |
| 353 |
without any warranty; without even the implied warranty of |
| 354 |
merchantability or fitness for a particular purpose. |
| 355 |
.SH AUTHOR |
| 356 |
.IX Header "AUTHOR" |
| 357 |
Pod::Simple was created by Sean M. Burke <[email protected]>. |
| 358 |
But don't bother him, he's retired. |
| 359 |
.PP |
| 360 |
Pod::Simple is maintained by: |
| 361 |
.IP \(bu 4 |
| 362 |
Allison Randal \f(CW\*(C`[email protected]\*(C'\fR |
| 363 |
.IP \(bu 4 |
| 364 |
Hans Dieter Pearcey \f(CW\*(C`[email protected]\*(C'\fR |
| 365 |
.IP \(bu 4 |
| 366 |
David E. Wheeler \f(CW\*(C`[email protected]\*(C'\fR |