NAME
pod2html - convert Perl POD documentation to HTML
SYNOPSIS
pod2html [ -converter module ] [ -suffix suffix ] [ -filesuffix suffix ] [ -dir path ] [ -libpods pod1,pod2,... ] [ -(no)localtoc ] [ -(no)navigation ] [ -(no)toc ] [ -tocname filename ] [ -toctitle title ] [ -(no)idx ] [ -idxopt options ] [ -idxname filename ] [ -idxtitle title ] [ -(no)ps ] [ -psdir path ] [ -psfont font ] [ -papersize format ] [ -(no)inc ] [ -(no)script ] [ -(no)warnings ] [ -(no)verbose ] [ -(no)banner ] [ -stylesheet link ] [ dir1 , dir2 , ... ] [ pod1 , pod2 , ... ]
DESCRIPTION
mpod2html converts Perl POD documentation to HTML. This was originally meant as a replacement for the existing core pod2html
, but has turned out to be a heavy-weight, fancy HTML converter that needs quite a lot of additional modules. There are a lot of other Pod to HTML converters out there that may suit you needs better.
See "SEE ALSO" below for sources of more details.
An important note: mpod2html will cross-link only those documents that are processed in one conversion session. The benefit is that you will get only working hyperlinks, no "dead ends". The downside is that you cannot simply convert one additional Pod and everything will be nicely crosslinked. Future versions of this module (or a complete rewrite) may support a caching mechanism for the hyperlink destination, such that additional Pods converted to HTML will have working hyperlinks to the existing, already converted Pods; but updating all existing HTML files for links to the newly converted Pod is rather cumbersome.
OPTIONS
- -converter module
-
The converter class to use, defaults to
Marek::Pod::HTML
. This hook allows for simple customization, see also "Customizing" in Marek::Pod::HTML. - -suffix string
-
Use this string for links to other converted Pod documents. The default is
.html
and also sets the filename suffix unless -filesuffix has been specified. The dot must be included! - -filesuffix string
-
Use this string as a suffix for the output HTML files. This does not change the suffix used in the hyperlinks to different documents. This feature is meant to be used if some (Makefile based) postprocessing of the generated files has to be performed, but without having to adapt the links.
- -dir path
-
Write the generated HTML files (can be a directory hierarchy) to this path. The default is the current working directory.
- -libpods name1,name2,...
-
This option activates a highly magical feature: The
=item
nodes of the specified Pod documents (given by Pod name, e.g.Pod::Parser
) serve as destinations for highlighted text in all converted Pod documents. Typical usage: When converting your Perl installation's documentation, you may want to saypod2html -libpods perlfunc,perlvar,perlrun -script -inc
then you will get a hyperlink to perlvar in the text
I<$|>
. - -localtoc | -nolocaltoc
-
This is by default true, so that at the top of the page a local table of contents with all the
=head
n lines is generated. -
When using the default customization, this flag enables or disables the navigation in the header of each Pod document (next/previous doc, table of contents, index).
- -toc | -notoc
-
If true, a table of contents is built from the processed Pod documents.
- -tocname name
-
Use name as the filename of the table of contents. Default is podtoc. The general file suffix is added to this name.
- -toctitle string
-
The string that is used as the heading of the table of contents. Default is `Table of Contents'.
- -idx | -noidx
-
If true, an index is built from all processed Pod documents.
- -idxopt options
-
Options for index building. Default is "item,x", which means that item strings as well as text marked up with
X<...>
generate entries in the index. - -idxname name
-
Use name as the filename of the index. Default is podindex. The general file suffix is added to this name.
- -idxtitle string
-
The string that is used as the heading of the table of contents. Default is `Index'.
- -ps | -nops
-
In addition to HTML, generate also Postscript output. The suffix is .ps. Default is no.
- -psdir
-
The root directory where to write Postscript files. Defaults to the same as -dir.
- -psfont fontname
-
Generate Postscript files using the font fontname. Default is `Helvetica'.
- -papersize size
-
Generate Postscript files using the paper size size. Default is `A4'.
- -inc | -noinc
-
In addition to the files specified on the command line, use Pod::Find to traverse
@INC
for all Pod documents. For a decent Perl installation this will collect a huge number of files. - -script | -noscript
-
Similar to -inc, this looks in the Perl installation executables directory for scripts containing Pod to be converted. Using this, you will e.g. catch
perldoc
. - -warnings | -nowarnings
-
When processing the first pass, print warnings. See Pod::Checker for more information on warnings. Note: This can produce a lot of output if the Pod source does not correspond to strict guidelines.
- -verbose | -noverbose
-
Print more status information along the conversion process.
-
Generate a banner at the bottom of all converted files (or not). Default is true.
- -stylesheet link
-
The (optional) link to a style sheet, which is included in the resulting HTML as
<LINK TYPE="text/css" REL="stylesheet" HREF=$link>
ARGUMENTS
- none
-
If no arguments are specified (and neither -inc nor -script), then mpod2html acts as a filter, reading STDIN and writing to STDOUT.
- dir1 , dir2 , ...
-
Directories specified on the command line will be processed recursively. This means especially that if there is e.g. Pod/Checker.pm in the specified directory, it will be recognized as
Pod::Checker
(rather thanChecker
). - pod1 , pod2 , ...
-
A list of files. Note that if you specify Mail/Alias.pm, then this is not recognized as
Mail::Alias
, with the consequence that links in other documents pointing toMail::Alias
will not be resolved.
AUTHOR
Marek Rouchal <marekr@cpan.org>
SEE ALSO
Marek::Pod::HTML, HTML::Element, Pod::Parser, Pod::Checker, HTML::Entities