path: root/upstream/debian-bookworm/man3/Pod::Simple::HTMLBatch.3perl

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Pod::Simple::HTMLBatch 3perl"
.TH Pod::Simple::HTMLBatch 3perl "2023-11-25" "perl v5.36.0" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Pod::Simple::HTMLBatch \- convert several Pod files to several HTML files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  perl \-MPod::Simple::HTMLBatch \-e \*(AqPod::Simple::HTMLBatch::go\*(Aq in out
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is used for running batch-conversions of a lot of \s-1HTML\s0
documents
.PP
This class is \s-1NOT\s0 a subclass of Pod::Simple::HTML
(nor of bad old Pod::Html) \*(-- although it uses
Pod::Simple::HTML for doing the conversion of each document.
.PP
The normal use of this class is like so:
.PP
.Vb 5
\&  use Pod::Simple::HTMLBatch;
\&  my $batchconv = Pod::Simple::HTMLBatch\->new;
\&  $batchconv\->some_option( some_value );
\&  $batchconv\->some_other_option( some_other_value );
\&  $batchconv\->batch_convert( \e@search_dirs, $output_dir );
.Ve
.SS "\s-1FROM THE COMMAND LINE\s0"
.IX Subsection "FROM THE COMMAND LINE"
Note that this class also provides
(but does not export) the function Pod::Simple::HTMLBatch::go.
This is basically just a shortcut for \f(CW\*(C`Pod::Simple::HTMLBatch\->batch_convert(@ARGV)\*(C'\fR.
It's meant to be handy for calling from the command line.
.PP
However, the shortcut requires that you specify exactly two command-line
arguments, \f(CW\*(C`indirs\*(C'\fR and \f(CW\*(C`outdir\*(C'\fR.
.PP
Example:
.PP
.Vb 4
\&  % mkdir out_html
\&  % perl \-MPod::Simple::HTMLBatch \-e Pod::Simple::HTMLBatch::go @INC out_html
\&      (to convert the pod from Perl\*(Aqs @INC
\&       files under the directory ./out_html)
.Ve
.PP
(Note that the command line there contains a literal atsign-I-N-C.  This
is handled as a special case by batch_convert, in order to save you having
to enter the odd-looking "\*(L" as the first command-line parameter when you
mean \*(R"just use whatever's in \f(CW@INC\fR".)
.PP
Example:
.PP
.Vb 5
\&  % mkdir ../seekrut
\&  % chmod og\-rx ../seekrut
\&  % perl \-MPod::Simple::HTMLBatch \-e Pod::Simple::HTMLBatch::go . ../seekrut
\&      (to convert the pod under the current dir into HTML
\&       files under the directory ./seekrut)
.Ve
.PP
Example:
.PP
.Vb 2
\&  % perl \-MPod::Simple::HTMLBatch \-e Pod::Simple::HTMLBatch::go happydocs .
\&      (to convert all pod from happydocs into the current directory)
.Ve
.SH "MAIN METHODS"
.IX Header "MAIN METHODS"
.ie n .IP "$batchconv = Pod::Simple::HTMLBatch\->new;" 4
.el .IP "\f(CW$batchconv\fR = Pod::Simple::HTMLBatch\->new;" 4
.IX Item "$batchconv = Pod::Simple::HTMLBatch->new;"
This creates a new batch converter.  The method doesn't take parameters.
To change the converter's attributes, use the \*(L"\s-1ACCESSOR METHODS\*(R"\*(L"\s0 in \*(R"
below.
.ie n .IP "$batchconv\->batch_convert( \fIindirs\fR, \fIoutdir\fR );" 4
.el .IP "\f(CW$batchconv\fR\->batch_convert( \fIindirs\fR, \fIoutdir\fR );" 4
.IX Item "$batchconv->batch_convert( indirs, outdir );"
This searches the directories given in \fIindirs\fR and writes
\&\s-1HTML\s0 files for each of these to a corresponding directory
in \fIoutdir\fR.  The directory \fIoutdir\fR must exist.
.ie n .IP "$batchconv\->batch_convert( undef    , ...);" 4
.el .IP "\f(CW$batchconv\fR\->batch_convert( undef    , ...);" 4
.IX Item "$batchconv->batch_convert( undef , ...);"
.PD 0
.ie n .IP "$batchconv\->batch_convert( q{@INC}, ...);" 4
.el .IP "\f(CW$batchconv\fR\->batch_convert( q{@INC}, ...);" 4
.IX Item "$batchconv->batch_convert( q{@INC}, ...);"
.PD
These two values for \fIindirs\fR specify that the normal Perl \f(CW@INC\fR
.ie n .IP "$batchconv\->batch_convert( \e@dirs , ...);" 4
.el .IP "\f(CW$batchconv\fR\->batch_convert( \e@dirs , ...);" 4
.IX Item "$batchconv->batch_convert( @dirs , ...);"
This specifies that the input directories are the items in
the arrayref \f(CW\*(C`\e@dirs\*(C'\fR.
.ie n .IP "$batchconv\->batch_convert( ""somedir"" , ...);" 4
.el .IP "\f(CW$batchconv\fR\->batch_convert( ``somedir'' , ...);" 4
.IX Item "$batchconv->batch_convert( somedir , ...);"
This specifies that the director \*(L"somedir\*(R" is the input.
(This can be an absolute or relative path, it doesn't matter.)
.Sp
A common value you might want would be just \*(L".\*(R" for the current
directory:
.Sp
.Vb 1
\&     $batchconv\->batch_convert( "." , ...);
.Ve
.ie n .IP "$batchconv\->batch_convert( 'somedir:someother:also' , ...);" 4
.el .IP "\f(CW$batchconv\fR\->batch_convert( 'somedir:someother:also' , ...);" 4
.IX Item "$batchconv->batch_convert( 'somedir:someother:also' , ...);"
This specifies that you want the dirs \*(L"somedir\*(R", \*(L"someother\*(R", and \*(L"also\*(R"
scanned, just as if you'd passed the arrayref
\&\f(CW\*(C`[qw( somedir someother also)]\*(C'\fR.  Note that a \*(L":\*(R"\-separator is normal
under Unix, but Under MSWin, you'll need \f(CW\*(Aqsomedir;someother;also\*(Aq\fR
instead, since the pathsep on MSWin is \*(L";\*(R" instead of \*(L":\*(R".  (And
\&\fIthat\fR is because \*(L":\*(R" often comes up in paths, like
\&\f(CW"c:/perl/lib"\fR.)
.Sp
(Exactly what separator character should be used, is gotten from
\&\f(CW$Config::Config{\*(Aqpath_sep\*(Aq}\fR, via the Config module.)
.ie n .IP "$batchconv\->batch_convert( ... , undef );" 4
.el .IP "\f(CW$batchconv\fR\->batch_convert( ... , undef );" 4
.IX Item "$batchconv->batch_convert( ... , undef );"
This specifies that you want the \s-1HTML\s0 output to go into the current
directory.
.Sp
(Note that a missing or undefined value means a different thing in
the first slot than in the second.  That's so that \f(CW\*(C`batch_convert()\*(C'\fR
with no arguments (or undef arguments) means "go from \f(CW@INC\fR, into
the current directory.)
.ie n .IP "$batchconv\->batch_convert( ... , 'somedir' );" 4
.el .IP "\f(CW$batchconv\fR\->batch_convert( ... , 'somedir' );" 4
.IX Item "$batchconv->batch_convert( ... , 'somedir' );"
This specifies that you want the \s-1HTML\s0 output to go into the
directory 'somedir'.
(This can be an absolute or relative path, it doesn't matter.)
.PP
Note that you can also call \f(CW\*(C`batch_convert\*(C'\fR as a class method,
like so:
.PP
.Vb 1
\&  Pod::Simple::HTMLBatch\->batch_convert( ... );
.Ve
.PP
That is just short for this:
.PP
.Vb 1
\&  Pod::Simple::HTMLBatch\-> new\-> batch_convert(...);
.Ve
.PP
That is, it runs a conversion with default options, for
whatever inputdirs and output dir you specify.
.SS "\s-1ACCESSOR METHODS\s0"
.IX Subsection "ACCESSOR METHODS"
The following are all accessor methods \*(-- that is, they don't do anything
on their own, but just alter the contents of the conversion object,
which comprises the options for this particular batch conversion.
.PP
We show the \*(L"put\*(R" form of the accessors below (i.e., the syntax you use
for setting the accessor to a specific value).  But you can also
call each method with no parameters to get its current value.  For
example, \f(CW\*(C`$self\->contents_file()\*(C'\fR returns the current value of
the contents_file attribute.
.ie n .IP "$batchconv\->verbose( \fInonnegative_integer\fR );" 4
.el .IP "\f(CW$batchconv\fR\->verbose( \fInonnegative_integer\fR );" 4
.IX Item "$batchconv->verbose( nonnegative_integer );"
This controls how verbose to be during batch conversion, as far as
notes to \s-1STDOUT\s0 (or whatever is \f(CW\*(C`select\*(C'\fR'd) about how the conversion
is going.  If 0, no progress information is printed.
If 1 (the default value), some progress information is printed.
Higher values print more information.
.ie n .IP "$batchconv\->index( \fItrue-or-false\fR );" 4
.el .IP "\f(CW$batchconv\fR\->index( \fItrue-or-false\fR );" 4
.IX Item "$batchconv->index( true-or-false );"
This controls whether or not each \s-1HTML\s0 page is liable to have a little
table of contents at the top (which we call an \*(L"index\*(R" for historical
reasons).  This is true by default.
.ie n .IP "$batchconv\->contents_file( \fIfilename\fR );" 4
.el .IP "\f(CW$batchconv\fR\->contents_file( \fIfilename\fR );" 4
.IX Item "$batchconv->contents_file( filename );"
If set, should be the name of a file (in the output directory)
to write the \s-1HTML\s0 index to.  The default value is \*(L"index.html\*(R".
If you set this to a false value, no contents file will be written.
.ie n .IP "$batchconv\->contents_page_start( \fIHTML_string\fR );" 4
.el .IP "\f(CW$batchconv\fR\->contents_page_start( \fIHTML_string\fR );" 4
.IX Item "$batchconv->contents_page_start( HTML_string );"
This specifies what string should be put at the beginning of
the contents page.
The default is a string more or less like this:
.Sp
.Vb 4
\&  <html>
\&  <head><title>Perl Documentation</title></head>
\&  <body class=\*(Aqcontentspage\*(Aq>
\&  <h1>Perl Documentation</h1>
.Ve
.ie n .IP "$batchconv\->contents_page_end( \fIHTML_string\fR );" 4
.el .IP "\f(CW$batchconv\fR\->contents_page_end( \fIHTML_string\fR );" 4
.IX Item "$batchconv->contents_page_end( HTML_string );"
This specifies what string should be put at the end of the contents page.
The default is a string more or less like this:
.Sp
.Vb 4
\&  <p class=\*(Aqcontentsfooty\*(Aq>Generated by
\&  Pod::Simple::HTMLBatch v3.01 under Perl v5.008
\&  <br >At Fri May 14 22:26:42 2004 GMT,
\&  which is Fri May 14 14:26:42 2004 local time.</p>
.Ve
.ie n .IP "$batchconv\->add_css( $url );" 4
.el .IP "\f(CW$batchconv\fR\->add_css( \f(CW$url\fR );" 4
.IX Item "$batchconv->add_css( $url );"
\&\s-1TODO\s0
.ie n .IP "$batchconv\->add_javascript( $url );" 4
.el .IP "\f(CW$batchconv\fR\->add_javascript( \f(CW$url\fR );" 4
.IX Item "$batchconv->add_javascript( $url );"
\&\s-1TODO\s0
.ie n .IP "$batchconv\->css_flurry( \fItrue-or-false\fR );" 4
.el .IP "\f(CW$batchconv\fR\->css_flurry( \fItrue-or-false\fR );" 4
.IX Item "$batchconv->css_flurry( true-or-false );"
If true (the default value), we autogenerate some \s-1CSS\s0 files in the
output directory, and set our \s-1HTML\s0 files to use those.
\&\s-1TODO:\s0 continue
.ie n .IP "$batchconv\->javascript_flurry( \fItrue-or-false\fR );" 4
.el .IP "\f(CW$batchconv\fR\->javascript_flurry( \fItrue-or-false\fR );" 4
.IX Item "$batchconv->javascript_flurry( true-or-false );"
If true (the default value), we autogenerate a JavaScript in the
output directory, and set our \s-1HTML\s0 files to use it.  Currently,
the JavaScript is used only to get the browser to remember what
stylesheet it prefers.
\&\s-1TODO:\s0 continue
.ie n .IP "$batchconv\->no_contents_links( \fItrue-or-false\fR );" 4
.el .IP "\f(CW$batchconv\fR\->no_contents_links( \fItrue-or-false\fR );" 4
.IX Item "$batchconv->no_contents_links( true-or-false );"
\&\s-1TODO\s0
.ie n .IP "$batchconv\->html_render_class( \fIclassname\fR );" 4
.el .IP "\f(CW$batchconv\fR\->html_render_class( \fIclassname\fR );" 4
.IX Item "$batchconv->html_render_class( classname );"
This sets what class is used for rendering the files.
The default is \*(L"Pod::Simple::HTML\*(R".  If you set it to something else,
it should probably be a subclass of Pod::Simple::HTML, and you should
\&\f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR that class so that's it's loaded before
Pod::Simple::HTMLBatch tries loading it.
.ie n .IP "$batchconv\->search_class( \fIclassname\fR );" 4
.el .IP "\f(CW$batchconv\fR\->search_class( \fIclassname\fR );" 4
.IX Item "$batchconv->search_class( classname );"
This sets what class is used for searching for the files.
The default is \*(L"Pod::Simple::Search\*(R".  If you set it to something else,
it should probably be a subclass of Pod::Simple::Search, and you should
\&\f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR that class so that's it's loaded before
Pod::Simple::HTMLBatch tries loading it.
.SH "NOTES ON CUSTOMIZATION"
.IX Header "NOTES ON CUSTOMIZATION"
\&\s-1TODO\s0
.PP
.Vb 2
\&  call add_css($someurl) to add stylesheet as alternate
\&  call add_css($someurl,1) to add as primary stylesheet
\&
\&  call add_javascript
\&
\&  subclass Pod::Simple::HTML and set $batchconv\->html_render_class to
\&    that classname
\&  and maybe override
\&    $page\->batch_mode_page_object_init($self, $module, $infile, $outfile, $depth)
\&  or maybe override
\&    $batchconv\->batch_mode_page_object_init($page, $module, $infile, $outfile, $depth)
\&  subclass Pod::Simple::Search and set $batchconv\->search_class to
\&    that classname
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Pod::Simple, Pod::Simple::HTMLBatch, perlpod, perlpodspec
.SH "SUPPORT"
.IX Header "SUPPORT"
Questions or discussion about \s-1POD\s0 and Pod::Simple should be sent to the
pod\-people@perl.org mail list. Send an empty email to
pod\-people\-subscribe@perl.org to subscribe.
.PP
This module is managed in an open GitHub repository,
<https://github.com/perl\-pod/pod\-simple/>. Feel free to fork and contribute, or
to clone <git://github.com/perl\-pod/pod\-simple.git> and send patches!
.PP
Patches against Pod::Simple are welcome. Please send bug reports to
<bug\-pod\-simple@rt.cpan.org>.
.SH "COPYRIGHT AND DISCLAIMERS"
.IX Header "COPYRIGHT AND DISCLAIMERS"
Copyright (c) 2002 Sean M. Burke.
.PP
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.PP
This program is distributed in the hope that it will be useful, but
without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.
.SH "AUTHOR"
.IX Header "AUTHOR"
Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
But don't bother him, he's retired.
.PP
Pod::Simple is maintained by:
.IP "\(bu" 4
Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR
.IP "\(bu" 4
Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR
.IP "\(bu" 4
David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR