Debian Codegraph @

upstream/mageia-cauldron/man3pm/Pod::Simple::HTMLBatch.3pm

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