Pod::LaTeX - Convert Pod data to formatted Latex
use Pod::LaTeX; my $parser = Pod::LaTeX->new ( ); $parser->parse_from_filehandle; $parser->parse_from_file ('file.pod', 'file.tex');
Pod::LaTeX is a module to convert documentation in the Pod format into Latex. The pod2latex command uses this module for translation.
Pod::LaTeX
Pod::LaTeX is a derived class from Pod::Select.
The following methods are provided in this module. Methods inherited from Pod::Select are not described in the public interface.
Pod::Select
The following methods are provided for accessing instance data. These methods should be used for accessing configuration parameters rather than assuming the object is a hash.
Default values can be supplied by using these names as keys to a hash of arguments when using the new() constructor.
new()
Logical to control whether a latex preamble is to be written. If true, a valid latex preamble is written before the pod data is written. This is similar to:
latex
\documentclass{article} \usepackage[T1]{fontenc} \usepackage{textcomp} \begin{document}
but will be more complicated if table of contents and indexing are required. Can be used to set or retrieve the current value.
$add = $parser->AddPreamble(); $parser->AddPreamble(1);
If used in conjunction with AddPostamble a full latex document will be written that could be immediately processed by latex.
AddPostamble
For some pod escapes it may be necessary to include the amsmath package. This is not yet added to the preamble automatically.
Logical to control whether a standard latex ending is written to the output file after the document has been processed. In its simplest form this is simply:
\end{document}
but can be more complicated if a index is required. Can be used to set or retrieve the current value.
$add = $parser->AddPostamble(); $parser->AddPostamble(1);
If used in conjunction with AddPreaamble a full latex document will be written that could be immediately processed by latex.
AddPreaamble
The latex sectioning level that should be used to correspond to a pod =head1 directive. This can be used, for example, to turn a =head1 into a latex subsection. This should hold a number corresponding to the required position in an array containing the following elements:
=head1
subsection
[0] chapter [1] section [2] subsection [3] subsubsection [4] paragraph [5] subparagraph
Can be used to set or retrieve the current value:
$parser->Head1Level(2); $sect = $parser->Head1Level;
Setting this number too high can result in sections that may not be reproducible in the expected way. For example, setting this to 4 would imply that =head3 do not have a corresponding latex section (=head1 would correspond to a paragraph).
=head3
paragraph
A check is made to ensure that the supplied value is an integer in the range 0 to 5.
Default is for a value of 1 (i.e. a section).
section
This is the label that is prefixed to all latex label and index entries to make them unique. In general, pods have similarly titled sections (NAME, DESCRIPTION etc) and a latex label will be multiply defined if more than one pod document is to be included in a single latex file. To overcome this, this label is prefixed to a label whenever a label is required (joined with an underscore) or to an index entry (joined by an exclamation mark which is the normal index separator). For example, \label{text} becomes \label{Label_text}.
\label{text}
\label{Label_text}
$label = $parser->Label; $parser->Label($label);
This label is only used if UniqueLabels is true. Its value is set automatically from the NAME field if ReplaceNAMEwithSection is true. If this is not the case it must be set manually before starting the parse.
UniqueLabels
NAME
ReplaceNAMEwithSection
Default value is undef.
undef
Control the point at which latex section numbering is turned off. For example, this can be used to make sure that latex sections are numbered but subsections are not.
$lev = $parser->LevelNoNum; $parser->LevelNoNum(2);
The argument must be an integer between 0 and 5 and is the same as the number described in Head1Level method description. The number has nothing to do with the pod heading number, only the latex sectioning.
Head1Level
Default is 2. (i.e. latex subsections are written as subsection* but sections are numbered).
subsection*
Controls whether latex commands for creating an index are to be inserted into the preamble and postamble
$makeindex = $parser->MakeIndex; $parser->MakeIndex(0);
Irrelevant if both AddPreamble and AddPostamble are false (or equivalently, UserPreamble and UserPostamble are set).
AddPreamble
UserPreamble
UserPostamble
Default is for an index to be created.
This controls whether the NAME section in the pod is to be translated literally or converted to a slightly modified output where the section name is the pod name rather than "NAME".
If true, the pod segment
=head1 NAME pod::name - purpose =head1 SYNOPSIS
is converted to the latex
\section{pod::name\label{pod_name}\index{pod::name}} Purpose \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}% \index{pod::name!SYNOPSIS}}
(dependent on the value of Head1Level and LevelNoNum). Note that subsequent head1 directives translate to subsections rather than sections and that the labels and index now include the pod name (dependent on the value of UniqueLabels).
LevelNoNum
head1
The Label is set from the pod name regardless of any current value of Label.
Label
$mod = $parser->ReplaceNAMEwithSection; $parser->ReplaceNAMEwithSection(0);
Default is to translate the pod literally.
If true, each pod translation will begin with a latex \clearpage.
\clearpage
$parser->StartWithNewPage(1); $newpage = $parser->StartWithNewPage;
Default is false.
If true, a table of contents will be created. Irrelevant if AddPreamble is false or UserPreamble is set.
$toc = $parser->TableOfContents; $parser->TableOfContents(1);
If true, the translator will attempt to make sure that each latex label or index entry will be uniquely identified by prefixing the contents of Label. This allows multiple documents to be combined without clashing common labels such as DESCRIPTION and SYNOPSIS
DESCRIPTION
SYNOPSIS
$parser->UniqueLabels(1); $unq = $parser->UniqueLabels;
Default is true.
User supplied latex preamble. Added before the pod translation data.
If set, the contents will be prepended to the output file before the translated data regardless of the value of AddPreamble. MakeIndex and TableOfContents will also be ignored.
MakeIndex
TableOfContents
User supplied latex postamble. Added after the pod translation data.
If set, the contents will be prepended to the output file after the translated data regardless of the value of AddPostamble. MakeIndex will also be ignored.
Compatible with latex2e only. Can not be used with latex v2.09 or earlier.
latex2e
A subclass of Pod::Select so that specific pod sections can be converted to latex by using the select method.
select
Some HTML escapes are missing and many have not been tested.
Pod::Parser, Pod::Select, pod2latex, Pod::Simple.
Tim Jenness <tjenness@cpan.org>
Bug fixes and improvements have been received from: Simon Cozens <simon@cozens.net>, Mark A. Hershberger <mah@everybody.org>, Marcel Grunauer <marcel@codewerk.com>, Hugh S Myers <hsmyers@sdragons.com>, Peter J Acklam <jacklam@math.uio.no>, Sudhi Herle <sudhi@herle.net>, Ariel Scolnicov <ariels@compugen.co.il>, Adriano Rodrigues Ferreira <ferreira@triang.com.br>, R. de Vries <r.de.vries@dutchspace.nl> and Dave Mitchell <davem@iabyn.com>.
Copyright (C) 2011 Tim Jenness. Copyright (C) 2000-2004 Tim Jenness. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Pod::LaTeX, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::LaTeX
CPAN shell
perl -MCPAN -e shell install Pod::LaTeX
For more information on module installation, please visit the detailed CPAN module installation guide.