Pod::Simple::HTMLBatch(3pm)

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 TODO
65
66       $batchconv->batch_convert( indirs, outdir );
67           this TODO
68
69       $batchconv->batch_convert( undef    , ...);
70       $batchconv->batch_convert( q{@INC}, ...);
71           These two values for indirs specify that the normal Perl @INC
72
73       $batchconv->batch_convert( \@dirs , ...);
74           This specifies that the input directories are the items in the
75           arrayref "\@dirs".
76
77       $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
81           A common value you might want would be just "." for the current
82           directory:
83
84                $batchconv->batch_convert( "." , ...);
85
86       $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
94           (Exactly what separator character should be used, is gotten from
95           $Config::Config{'path_sep'}, via the Config module.)
96
97       $batchconv->batch_convert( ... , undef );
98           This specifies that you want the HTML output to go into the current
99           directory.
100
101           (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
106       $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
111       Note that you can also call "batch_convert" as a class method, like so:
112
113         Pod::Simple::HTMLBatch->batch_convert( ... );
114
115       That is just short for this:
116
117         Pod::Simple::HTMLBatch-> new-> batch_convert(...);
118
119       That is, it runs a conversion with default options, for whatever
120       inputdirs and output dir you specify.
121
122   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
128       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
134       $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
141       $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
146       $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
151       $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
155             <html>
156             <head><title>Perl Documentation</title></head>
157             <body class='contentspage'>
158             <h1>Perl Documentation</h1>
159
160       $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
164             <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
169       $batchconv->add_css( $url );
170           TODO
171
172       $batchconv->add_javascript( $url );
173           TODO
174
175       $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
180       $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
186       $batchconv->no_contents_links( true-or-false );
187           TODO
188
189       $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
196       $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

NOTES ON CUSTOMIZATION

204       TODO
205
206         call add_css($someurl) to add stylesheet as alternate
207         call add_css($someurl,1) to add as primary stylesheet
208
209         call add_javascript
210
211         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

SUPPORT

224       Questions or discussion about POD and Pod::Simple should be sent to the
225       pod-people@perl.org mail list. Send an empty email to
226       pod-people-subscribe@perl.org to subscribe.
227
228       This module is managed in an open GitHub repository,
229       <https://github.com/perl-pod/pod-simple/>. Feel free to fork and
230       contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and
231       send patches!
232
233       Patches against Pod::Simple are welcome. Please send bug reports to
234       <bug-pod-simple@rt.cpan.org>.
235

COPYRIGHT AND DISCLAIMERS

237       Copyright (c) 2002 Sean M. Burke.
238
239       This library is free software; you can redistribute it and/or modify it
240       under the same terms as Perl itself.
241
242       This program is distributed in the hope that it will be useful, but
243       without any warranty; without even the implied warranty of
244       merchantability or fitness for a particular purpose.
245

AUTHOR

247       Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.  But don't
248       bother him, he's retired.
249
250       Pod::Simple is maintained by:
251
252       ·   Allison Randal "allison@perl.org"
253
254       ·   Hans Dieter Pearcey "hdp@cpan.org"
255
256       ·   David E. Wheeler "dwheeler@cpan.org"
257
258
259
260perl v5.26.3                      2016-11-29         Pod::Simple::HTMLBatch(3)