local-lib5/man/man3/Pod::Simple::HTMLBatch.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Pod::Simple::HTMLBatch 3"
 132 .TH Pod::Simple::HTMLBatch 3 "2009-10-26" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Pod::Simple::HTMLBatch \- convert several Pod files to several HTML files
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  perl \-MPod::Simple::HTMLBatch \-e 'Pod::Simple::HTMLBatch::go' in out
 139 .Ve
 140 .SH "DESCRIPTION"
 141 .IX Header "DESCRIPTION"
 142 This module is used for running batch-conversions of a lot of \s-1HTML\s0
 143 documents
 144 .PP
 145 This class is \s-1NOT\s0 a subclass of Pod::Simple::HTML
 146 (nor of bad old Pod::Html) \*(-- although it uses
 147 Pod::Simple::HTML for doing the conversion of each document.
 148 .PP
 149 The normal use of this class is like so:
 150 .PP
 151 .Vb 5
 152 \&  use Pod::Simple::HTMLBatch;
 153 \&  my $batchconv = Pod::Simple::HTMLBatch\->new;
 154 \&  $batchconv\->some_option( some_value );
 155 \&  $batchconv\->some_other_option( some_other_value );
 156 \&  $batchconv\->batch_convert( \e@search_dirs, $output_dir );
 157 .Ve
 158 .Sh "\s-1FROM\s0 \s-1THE\s0 \s-1COMMAND\s0 \s-1LINE\s0"
 159 .IX Subsection "FROM THE COMMAND LINE"
 160 Note that this class also provides
 161 (but does not export) the function Pod::Simple::HTMLBatch::go.
 162 This is basically just a shortcut for \f(CW\*(C`Pod::Simple::HTMLBatch\->batch_convert(@ARGV)\*(C'\fR.
 163 It's meant to be handy for calling from the command line.
 164 .PP
 165 However, the shortcut requires that you specify exactly two command-line
 166 arguments, \f(CW\*(C`indirs\*(C'\fR and \f(CW\*(C`outdir\*(C'\fR.
 167 .PP
 168 Example:
 169 .PP
 170 .Vb 4
 171 \&  % mkdir out_html
 172 \&  % perl \-MPod::Simple::HTMLBatch \-e Pod::Simple::HTMLBatch::go @INC out_html
 173 \&      (to convert the pod from Perl's @INC
 174 \&       files under the directory ../htmlversion)
 175 .Ve
 176 .PP
 177 (Note that the command line there contains a literal atsign\-I\-N\-C.  This
 178 is handled as a special case by batch_convert, in order to save you having
 179 to enter the odd-looking "\*(L" as the first command-line parameter when you
 180 mean \*(R"just use whatever's in \f(CW@INC\fR".)
 181 .PP
 182 Example:
 183 .PP
 184 .Vb 5
 185 \&  % mkdir ../seekrut
 186 \&  % chmod og\-rx ../seekrut
 187 \&  % perl \-MPod::Simple::HTMLBatch \-e Pod::Simple::HTMLBatch::go . ../htmlversion
 188 \&      (to convert the pod under the current dir into HTML
 189 \&       files under the directory ../htmlversion)
 190 .Ve
 191 .PP
 192 Example:
 193 .PP
 194 .Vb 2
 195 \&  % perl \-MPod::Simple::HTMLBatch \-e Pod::Simple::HTMLBatch::go happydocs .
 196 \&      (to convert all pod from happydocs into the current directory)
 197 .Ve
 198 .SH "MAIN METHODS"
 199 .IX Header "MAIN METHODS"
 200 .IP "$batchconv = Pod::Simple::HTMLBatch\->new;" 4
 201 .IX Item "$batchconv = Pod::Simple::HTMLBatch->new;"
 202 This \s-1TODO\s0
 203 .IP "$batchconv\->batch_convert( \fIindirs\fR, \fIoutdir\fR );" 4
 204 .IX Item "$batchconv->batch_convert( indirs, outdir );"
 205 this \s-1TODO\s0
 206 .IP "$batchconv\->batch_convert( undef    , ...);" 4
 207 .IX Item "$batchconv->batch_convert( undef    , ...);"
 208 .PD 0
 209 .IP "$batchconv\->batch_convert( q{@INC}, ...);" 4
 210 .IX Item "$batchconv->batch_convert( q{@INC}, ...);"
 211 .PD
 212 These two values for \fIindirs\fR specify that the normal Perl \f(CW@INC\fR
 213 .IP "$batchconv\->batch_convert( \e@dirs , ...);" 4
 214 .IX Item "$batchconv->batch_convert( @dirs , ...);"
 215 This specifies that the input directories are the items in
 216 the arrayref \f(CW\*(C`\e@dirs\*(C'\fR.
 217 .ie n .IP "$batchconv\->batch_convert( ""somedir"" , ...);" 4
 218 .el .IP "$batchconv\->batch_convert( ``somedir'' , ...);" 4
 219 .IX Item "$batchconv->batch_convert( somedir , ...);"
 220 This specifies that the director \*(L"somedir\*(R" is the input.
 221 (This can be an absolute or relative path, it doesn't matter.)
 222 .Sp
 223 A common value you might want would be just \*(L".\*(R" for the current
 224 directory:
 225 .Sp
 226 .Vb 1
 227 \&     $batchconv\->batch_convert( "." , ...);
 228 .Ve
 229 .IP "$batchconv\->batch_convert( 'somedir:someother:also' , ...);" 4
 230 .IX Item "$batchconv->batch_convert( 'somedir:someother:also' , ...);"
 231 This specifies that you want the dirs \*(L"somedir\*(R", \*(L"somother\*(R", and \*(L"also\*(R"
 232 scanned, just as if you'd passed the arrayref
 233 \&\f(CW\*(C`[qw( somedir someother also)]\*(C'\fR.  Note that a \*(L":\*(R"\-separator is normal
 234 under Unix, but Under MSWin, you'll need \f(CW'somedir;someother;also'\fR
 235 instead, since the pathsep on MSWin is \*(L";\*(R" instead of \*(L":\*(R".  (And
 236 \&\fIthat\fR is because \*(L":\*(R" often comes up in paths, like
 237 \&\f(CW"c:/perl/lib"\fR.)
 238 .Sp
 239 (Exactly what separator character should be used, is gotten from
 240 \&\f(CW$Config::Config{'path_sep'}\fR, via the Config module.)
 241 .IP "$batchconv\->batch_convert( ... , undef );" 4
 242 .IX Item "$batchconv->batch_convert( ... , undef );"
 243 This specifies that you want the \s-1HTML\s0 output to go into the current
 244 directory.
 245 .Sp
 246 (Note that a missing or undefined value means a different thing in
 247 the first slot than in the second.  That's so that \f(CW\*(C`batch_convert()\*(C'\fR
 248 with no arguments (or undef arguments) means "go from \f(CW@INC\fR, into
 249 the current directory.)
 250 .IP "$batchconv\->batch_convert( ... , 'somedir' );" 4
 251 .IX Item "$batchconv->batch_convert( ... , 'somedir' );"
 252 This specifies that you want the \s-1HTML\s0 output to go into the
 253 directory 'somedir'.
 254 (This can be an absolute or relative path, it doesn't matter.)
 255 .PP
 256 Note that you can also call \f(CW\*(C`batch_convert\*(C'\fR as a class method,
 257 like so:
 258 .PP
 259 .Vb 1
 260 \&  Pod::Simple::HTMLBatch\->batch_convert( ... );
 261 .Ve
 262 .PP
 263 That is just short for this:
 264 .PP
 265 .Vb 1
 266 \&  Pod::Simple::HTMLBatch\-> new\-> batch_convert(...);
 267 .Ve
 268 .PP
 269 That is, it runs a conversion with default options, for
 270 whatever inputdirs and output dir you specify.
 271 .Sh "\s-1ACCESSOR\s0 \s-1METHODS\s0"
 272 .IX Subsection "ACCESSOR METHODS"
 273 The following are all accessor methods \*(-- that is, they don't do anything
 274 on their own, but just alter the contents of the conversion object,
 275 which comprises the options for this particular batch conversion.
 276 .PP
 277 We show the \*(L"put\*(R" form of the accessors below (i.e., the syntax you use
 278 for setting the accessor to a specific value).  But you can also
 279 call each method with no parameters to get its current value.  For
 280 example, \f(CW\*(C`$self\->contents_file()\*(C'\fR returns the current value of
 281 the contents_file attribute.
 282 .IP "$batchconv\->verbose( \fInonnegative_integer\fR );" 4
 283 .IX Item "$batchconv->verbose( nonnegative_integer );"
 284 This controls how verbose to be during batch conversion, as far as
 285 notes to \s-1STDOUT\s0 (or whatever is \f(CW\*(C`select\*(C'\fR'd) about how the conversion
 286 is going.  If 0, no progress information is printed.
 287 If 1 (the default value), some progress information is printed.
 288 Higher values print more information.
 289 .IP "$batchconv\->index( \fItrue-or-false\fR );" 4
 290 .IX Item "$batchconv->index( true-or-false );"
 291 This controls whether or not each \s-1HTML\s0 page is liable to have a little
 292 table of contents at the top (which we call an \*(L"index\*(R" for historical
 293 reasons).  This is true by default.
 294 .IP "$batchconv\->contents_file( \fIfilename\fR );" 4
 295 .IX Item "$batchconv->contents_file( filename );"
 296 If set, should be the name of a file (in the output directory)
 297 to write the \s-1HTML\s0 index to.  The default value is \*(L"index.html\*(R".
 298 If you set this to a false value, no contents file will be written.
 299 .IP "$batchconv\->contents_page_start( \fIHTML_string\fR );" 4
 300 .IX Item "$batchconv->contents_page_start( HTML_string );"
 301 This specifies what string should be put at the beginning of
 302 the contents page.
 303 The default is a string more or less like this:
 304 .Sp
 305 .Vb 4
 306 \&  <html>
 307 \&  <head><title>Perl Documentation</title></head>
 308 \&  <body class='contentspage'>
 309 \&  <h1>Perl Documentation</h1>
 310 .Ve
 311 .IP "$batchconv\->contents_page_end( \fIHTML_string\fR );" 4
 312 .IX Item "$batchconv->contents_page_end( HTML_string );"
 313 This specifies what string should be put at the end of the contents page.
 314 The default is a string more or less like this:
 315 .Sp
 316 .Vb 4
 317 \&  <p class='contentsfooty'>Generated by
 318 \&  Pod::Simple::HTMLBatch v3.01 under Perl v5.008
 319 \&  <br >At Fri May 14 22:26:42 2004 GMT,
 320 \&  which is Fri May 14 14:26:42 2004 local time.</p>
 321 .Ve
 322 .ie n .IP "$batchconv\->add_css( $url );" 4
 323 .el .IP "$batchconv\->add_css( \f(CW$url\fR );" 4
 324 .IX Item "$batchconv->add_css( $url );"
 325 \&\s-1TODO\s0
 326 .ie n .IP "$batchconv\->add_javascript( $url );" 4
 327 .el .IP "$batchconv\->add_javascript( \f(CW$url\fR );" 4
 328 .IX Item "$batchconv->add_javascript( $url );"
 329 \&\s-1TODO\s0
 330 .IP "$batchconv\->css_flurry( \fItrue-or-false\fR );" 4
 331 .IX Item "$batchconv->css_flurry( true-or-false );"
 332 If true (the default value), we autogenerate some \s-1CSS\s0 files in the
 333 output directory, and set our \s-1HTML\s0 files to use those.
 334 \&\s-1TODO:\s0 continue
 335 .IP "$batchconv\->javascript_flurry( \fItrue-or-false\fR );" 4
 336 .IX Item "$batchconv->javascript_flurry( true-or-false );"
 337 If true (the default value), we autogenerate a JavaScript in the
 338 output directory, and set our \s-1HTML\s0 files to use it.  Currently,
 339 the JavaScript is used only to get the browser to remember what
 340 stylesheet it prefers.
 341 \&\s-1TODO:\s0 continue
 342 .IP "$batchconv\->no_contents_links( \fItrue-or-false\fR );" 4
 343 .IX Item "$batchconv->no_contents_links( true-or-false );"
 344 \&\s-1TODO\s0
 345 .IP "$batchconv\->html_render_class( \fIclassname\fR );" 4
 346 .IX Item "$batchconv->html_render_class( classname );"
 347 This sets what class is used for rendering the files.
 348 The default is \*(L"Pod::Simple::HTML\*(R".  If you set it to something else,
 349 it should probably be a subclass of Pod::Simple::HTML, and you should
 350 \&\f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR that class so that's it's loaded before
 351 Pod::Simple::HTMLBatch tries loading it.
 352 .IP "$batchconv\->search_class( \fIclassname\fR );" 4
 353 .IX Item "$batchconv->search_class( classname );"
 354 This sets what class is used for searching for the files.
 355 The default is \*(L"Pod::Simple::Search\*(R".  If you set it to something else,
 356 it should probably be a subclass of Pod::Simple::Search, and you should
 357 \&\f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR that class so that's it's loaded before
 358 Pod::Simple::HTMLBatch tries loading it.
 359 .SH "NOTES ON CUSTOMIZATION"
 360 .IX Header "NOTES ON CUSTOMIZATION"
 361 \&\s-1TODO\s0
 362 .PP
 363 .Vb 2
 364 \&  call add_css($someurl) to add stylesheet as alternate
 365 \&  call add_css($someurl,1) to add as primary stylesheet
 366 .Ve
 367 .PP
 368 .Vb 1
 369 \&  call add_javascript
 370 .Ve
 371 .PP
 372 .Vb 8
 373 \&  subclass Pod::Simple::HTML and set $batchconv\->html_render_class to
 374 \&    that classname
 375 \&  and maybe override
 376 \&    $page\->batch_mode_page_object_init($self, $module, $infile, $outfile, $depth)
 377 \&  or maybe override
 378 \&    $batchconv\->batch_mode_page_object_init($page, $module, $infile, $outfile, $depth)
 379 \&  subclass Pod::Simple::Search and set $batchconv\->search_class to
 380 \&    that classname
 381 .Ve
 382 .SH "ASK ME!"
 383 .IX Header "ASK ME!"
 384 If you want to do some kind of big pod-to-HTML version with some
 385 particular kind of option that you don't see how to achieve using this
 386 module, email me (\f(CW\*(C`sburke@cpan.org\*(C'\fR) and I'll probably have a good idea
 387 how to do it. For reasons of concision and energetic laziness, some
 388 methods and options in this module (and the dozen modules it depends on)
 389 are undocumented; but one of those undocumented bits might be just what
 390 you're looking for.
 391 .SH "SEE ALSO"
 392 .IX Header "SEE ALSO"
 393 Pod::Simple, Pod::Simple::HTMLBatch, perlpod, perlpodspec
 394 .SH "COPYRIGHT AND DISCLAIMERS"
 395 .IX Header "COPYRIGHT AND DISCLAIMERS"
 396 Copyright (c) 2004 Sean M. Burke.  All rights reserved.
 397 .PP
 398 This library is free software; you can redistribute it and/or modify it
 399 under the same terms as Perl itself.
 400 .PP
 401 This program is distributed in the hope that it will be useful, but
 402 without any warranty; without even the implied warranty of
 403 merchantability or fitness for a particular purpose.
 404 .SH "AUTHOR"
 405 .IX Header "AUTHOR"
 406 Sean M. Burke \f(CW\*(C`sburke@cpan.org\*(C'\fR