Debian Codegraph @

upstream/debian-unstable/man3/Pod::Simple::HTMLBatch.3perl

raw
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