Pod::LaTeX(3pm)

💖 Pod::LaTeX 💖

okay bestie, gather round, because we're looking at the manual page for Pod::LaTeX(3pm) and honestly? it's giving "quiet little module that does a LOT." no cap.

---

🌸 NAME 🌸

Pod::LaTeX — it converts Pod data into formatted Latex. that's the whole job. she's a translator, and she eats. 💅

---

✨ SYNOPSIS ✨

use Pod::LaTeX;
my $parser = Pod::LaTeX->new ( );

$parser->parse_from_filehandle;

$parser->parse_from_file ('file.pod', 'file.tex');

look at her go 🫶

---

🦋 DESCRIPTION 🦋

Pod::LaTeX is a module that converts documentation written in the Pod format into Latex. the pod2latex command is the one out here using this module for translation. periodt.

also, real talk: Pod::LaTeX is a derived class from Pod::Select. she's got lineage. 👑

---

🌈 OBJECT METHODS 🌈

here's where it gets juicy. the methods below live in this module. methods she inherited from Pod::Select? not described in the public interface, so we're not spilling that tea here.

🎀 Data Accessors 🎀

these methods exist so you can access instance data. and bestie, please use them for poking at configuration parameters instead of just assuming the object is a hash. she's not a hash, she's a lady. 😭

you can hand over default values by using these names as keys to a hash of arguments when you call the new() constructor. love that for you.

AddPreamble

a logical flag controlling whether a latex preamble gets written. if it's true, a valid latex preamble is written before the pod data is written. it looks similar to this:

\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\begin{document}

but it'll be more complicated if you need a table of contents and indexing. can be used to set or retrieve the current value.

$add = $parser->AddPreamble();
$parser->AddPreamble(1);

if you use this together with AddPostamble, you get a full latex document written out that could be immediately processed by latex. iconic.

heads up: for some pod escapes it may be necessary to include the amsmath package. this is not yet added to the preamble automatically. so like, do it yourself, bestie. 💀

AddPostamble

logical flag controlling whether a standard latex ending gets written to the output file after the document has been processed. in its simplest form it's just:

\end{document}

but it can get more complicated if an index is required. can be used to set or retrieve the current value.

$add = $parser->AddPostamble();
$parser->AddPostamble(1);

if you use it together with AddPreaamble, a full latex document will be written that could be immediately processed by latex.

Head1Level

this is the latex sectioning level that should correspond to a pod =head1 directive. so like, you could use this to turn a =head1 into a latex subsection. it should hold a number corresponding to the required position in an array containing these 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 it to 4 would imply that =head3 do not have a corresponding latex section (=head1 would correspond to a paragraph). so like… be normal about it.

a check is made to make sure the value you supply is an integer in the range 0 to 5.

default is a value of 1 (i.e. a section).

Label

this is the label that gets 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 going to be included in a single latex file. to overcome that, 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}.

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 that's not the case, you have to set it manually before starting the parse. no skipping. 🙈

default value is undef.

LevelNoNum

controls the point at which latex section numbering gets turned off. for example, you could use this to make sure latex sections are numbered but subsections 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 it's the same as the number described in the Head1Level method description. the number has nothing to do with the pod heading number, only the latex sectioning. iykyk.

default is 2. (i.e. latex subsections are written as subsection* but sections are numbered).

MakeIndex

controls whether latex commands for creating an index get 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).

default is for an index to be created.

ReplaceNAMEwithSection

this controls whether the NAME section in the pod gets translated literally, or converted into 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

gets 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).

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 begins with a latex \clearpage.

$parser->StartWithNewPage(1);
$newpage = $parser->StartWithNewPage;

default is false.

TableOfContents

if true, a table of contents gets created. irrelevant if AddPreamble is false or UserPreamble is set.

$toc = $parser->TableOfContents;
$parser->TableOfContents(1);

default is false.

UniqueLabels

if true, the translator attempts to make sure each latex label or index entry is uniquely identified by prefixing the contents of Label. this allows multiple documents to be combined without clashing common labels such as DESCRIPTION and SYNOPSIS. slay.

$parser->UniqueLabels(1);
$unq = $parser->UniqueLabels;

default is true.

UserPreamble

user supplied latex preamble. added before the pod translation data.

if set, the contents get prepended to the output file before the translated data, regardless of the value of AddPreamble. MakeIndex and TableOfContents will also be ignored.

UserPostamble

user supplied latex postamble. added after the pod translation data.

if set, the contents get 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. cute.
• some HTML escapes are missing and many have not been tested. she's honest about it. 💜

---

👑 SEE ALSO 👑

Pod::Parser, Pod::Select, pod2latex, Pod::Simple.

---

🫶 AUTHORS 🫶

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>.

the whole group chat showed up to help. we love to see it. 🌈

---

💜 COPYRIGHT 💜

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.

---

and that's the whole page, bestie ✨ this was perl v5.30.0, dated 2020-05-17, and it's the Pod::LaTeX(3pm) manual. go write some beautiful Latex, you absolute icon 🎀💅🦋