Pod::LaTeX(3) Perl Programmers Reference Guide Pod::LaTeX(3)NAMEPod::LaTeX - Convert Pod data to formatted Latex
SYNOPSIS
use Pod::LaTeX;
my $parser = Pod::LaTeX->new ( );
$parser->parse_from_filehandle;
$parser->parse_from_file ('file.pod', 'file.tex');
DESCRIPTION
"Pod::LaTeX" is a module to convert documentation in the
Pod format into Latex. The pod2latex command uses this
module for translation.
"Pod::LaTeX" is a derived class from Pod::Select.
OBJECT METHODS
The following methods are provided in this module. Methods
inherited from "Pod::Select" are not described in the pub
lic interface.
Data Accessors
The following methods are provided for accessing instance
data. These methods should be used for accessing configu
ration 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()" con
structor.
AddPreamble
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:
\documentclass{article}
\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 immedi
ately processed by "latex".
AddPostamble
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 immedi
ately processed by "latex".
Head1Level
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:
[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").
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").
Label
This is the label that is prefixed to all "latex"
label and index entries to make them unique. In gen
eral, 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 nor
mal index separator). For example, "\label{text}"
becomes "\label{Label_text}".
Can be used to set or retrieve the current value:
$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.
Default value is "undef".
LevelNoNum
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 subsec
tions are not.
Can be used to set or retrieve the current value:
$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.
Default is 2. (i.e. "latex" subsections are written as
"subsection*" but sections are numbered).
MakeIndex
Controls whether "latex" commands for creating an
index are to be inserted into the preamble and postam
ble
$makeindex = $parser->MakeIndex;
$parser->MakeIndex(0);
Irrelevant if both "AddPreamble" and "AddPostamble"
are false (or equivalently, "UserPreamble" and "User
Postamble" are set).
Default is for an index to be created.
ReplaceNAMEwithSection
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 "Level
NoNum"). Note that subsequent "head1" directives
translate to subsections rather than sections and that
the labels and index now include the pod name (depen
dent on the value of "UniqueLabels").
The "Label" is set from the pod name regardless of any
current value of "Label".
$mod = $parser->ReplaceNAMEwithSection;
$parser->ReplaceNAMEwithSection(0);
Default is to translate the pod literally.
StartWithNewPage
If true, each pod translation will begin with a
"latex" "\clearpage".
$parser->StartWithNewPage(1);
$newpage = $parser->StartWithNewPage;
Default is false.
TableOfContents
If true, a table of contents will be created. Irrele
vant if "AddPreamble" is false or "UserPreamble" is
set.
$toc = $parser->TableOfContents;
$parser->TableOfContents(1);
Default is false.
UniqueLabels
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 "SYN
OPSIS"
$parser->UniqueLabels(1);
$unq = $parser->UniqueLabels;
Default is true.
UserPreamble
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 "TableOfCon
tents" will also be ignored.
UserPostamble
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.
NOTES
Compatible with "latex2e" only. Can not be used with
"latex" v2.09 or earlier.
A subclass of "Pod::Select" so that specific pod sections
can be converted to "latex" by using the "select" method.
Some HTML escapes are missing and many have not been
tested.
SEE ALSO
the Pod::Parser manpage, the Pod::Select manpage, the
pod2latex manpage
AUTHORS
Tim Jenness <t.jenness@jach.hawaii.edu>
COPYRIGHT
Copyright (C) 2000 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.
2001-02-22 perl v5.6.1 Pod::LaTeX(3)
