1Pod::LaTeX(3pm) Perl Programmers Reference Guide Pod::LaTeX(3pm)
2
3
4
6 Pod::LaTeX - Convert Pod data to formatted Latex
7
9 use Pod::LaTeX;
10 my $parser = Pod::LaTeX->new ( );
11
12 $parser->parse_from_filehandle;
13
14 $parser->parse_from_file ('file.pod', 'file.tex');
15
17 "Pod::LaTeX" is a module to convert documentation in the Pod format
18 into Latex. The pod2latex command uses this module for translation.
19
20 "Pod::LaTeX" is a derived class from Pod::Select.
21
23 The following methods are provided in this module. Methods inherited
24 from "Pod::Select" are not described in the public interface.
25
26 Data Accessors
27
28 The following methods are provided for accessing instance data. These
29 methods should be used for accessing configuration parameters rather
30 than assuming the object is a hash.
31
32 Default values can be supplied by using these names as keys to a hash
33 of arguments when using the "new()" constructor.
34
35 AddPreamble
36 Logical to control whether a "latex" preamble is to be written. If
37 true, a valid "latex" preamble is written before the pod data is
38 written. This is similar to:
39
40 \documentclass{article}
41 \usepackage[T1]{fontenc}
42 \usepackage{textcomp}
43 \begin{document}
44
45 but will be more complicated if table of contents and indexing are
46 required. Can be used to set or retrieve the current value.
47
48 $add = $parser->AddPreamble();
49 $parser->AddPreamble(1);
50
51 If used in conjunction with "AddPostamble" a full latex document
52 will be written that could be immediately processed by "latex".
53
54 For some pod escapes it may be necessary to include the amsmath
55 package. This is not yet added to the preamble automaatically.
56
57 AddPostamble
58 Logical to control whether a standard "latex" ending is written to
59 the output file after the document has been processed. In its sim‐
60 plest form this is simply:
61
62 \end{document}
63
64 but can be more complicated if a index is required. Can be used to
65 set or retrieve the current value.
66
67 $add = $parser->AddPostamble();
68 $parser->AddPostamble(1);
69
70 If used in conjunction with "AddPreaamble" a full latex document
71 will be written that could be immediately processed by "latex".
72
73 Head1Level
74 The "latex" sectioning level that should be used to correspond to a
75 pod "=head1" directive. This can be used, for example, to turn a
76 "=head1" into a "latex" "subsection". This should hold a number
77 corresponding to the required position in an array containing the
78 following elements:
79
80 [0] chapter
81 [1] section
82 [2] subsection
83 [3] subsubsection
84 [4] paragraph
85 [5] subparagraph
86
87 Can be used to set or retrieve the current value:
88
89 $parser->Head1Level(2);
90 $sect = $parser->Head1Level;
91
92 Setting this number too high can result in sections that may not be
93 reproducible in the expected way. For example, setting this to 4
94 would imply that "=head3" do not have a corresponding "latex" sec‐
95 tion ("=head1" would correspond to a "paragraph").
96
97 A check is made to ensure that the supplied value is an integer in
98 the range 0 to 5.
99
100 Default is for a value of 1 (i.e. a "section").
101
102 Label
103 This is the label that is prefixed to all "latex" label and index
104 entries to make them unique. In general, pods have similarly titled
105 sections (NAME, DESCRIPTION etc) and a "latex" label will be multi‐
106 ply defined if more than one pod document is to be included in a
107 single "latex" file. To overcome this, this label is prefixed to a
108 label whenever a label is required (joined with an underscore) or
109 to an index entry (joined by an exclamation mark which is the nor‐
110 mal index separator). For example, "\label{text}" becomes
111 "\label{Label_text}".
112
113 Can be used to set or retrieve the current value:
114
115 $label = $parser->Label;
116 $parser->Label($label);
117
118 This label is only used if "UniqueLabels" is true. Its value is
119 set automatically from the "NAME" field if "ReplaceNAMEwithSection"
120 is true. If this is not the case it must be set manually before
121 starting the parse.
122
123 Default value is "undef".
124
125 LevelNoNum
126 Control the point at which "latex" section numbering is turned off.
127 For example, this can be used to make sure that "latex" sections
128 are numbered but subsections are not.
129
130 Can be used to set or retrieve the current value:
131
132 $lev = $parser->LevelNoNum;
133 $parser->LevelNoNum(2);
134
135 The argument must be an integer between 0 and 5 and is the same as
136 the number described in "Head1Level" method description. The number
137 has nothing to do with the pod heading number, only the "latex"
138 sectioning.
139
140 Default is 2. (i.e. "latex" subsections are written as "subsec‐
141 tion*" but sections are numbered).
142
143 MakeIndex
144 Controls whether "latex" commands for creating an index are to be
145 inserted into the preamble and postamble
146
147 $makeindex = $parser->MakeIndex;
148 $parser->MakeIndex(0);
149
150 Irrelevant if both "AddPreamble" and "AddPostamble" are false (or
151 equivalently, "UserPreamble" and "UserPostamble" are set).
152
153 Default is for an index to be created.
154
155 ReplaceNAMEwithSection
156 This controls whether the "NAME" section in the pod is to be trans‐
157 lated literally or converted to a slightly modified output where
158 the section name is the pod name rather than "NAME".
159
160 If true, the pod segment
161
162 =head1 NAME
163
164 pod::name - purpose
165
166 =head1 SYNOPSIS
167
168 is converted to the "latex"
169
170 \section{pod::name\label{pod_name}\index{pod::name}}
171
172 Purpose
173
174 \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
175 \index{pod::name!SYNOPSIS}}
176
177 (dependent on the value of "Head1Level" and "LevelNoNum"). Note
178 that subsequent "head1" directives translate to subsections rather
179 than sections and that the labels and index now include the pod
180 name (dependent on the value of "UniqueLabels").
181
182 The "Label" is set from the pod name regardless of any current
183 value of "Label".
184
185 $mod = $parser->ReplaceNAMEwithSection;
186 $parser->ReplaceNAMEwithSection(0);
187
188 Default is to translate the pod literally.
189
190 StartWithNewPage
191 If true, each pod translation will begin with a "latex"
192 "\clearpage".
193
194 $parser->StartWithNewPage(1);
195 $newpage = $parser->StartWithNewPage;
196
197 Default is false.
198
199 TableOfContents
200 If true, a table of contents will be created. Irrelevant if
201 "AddPreamble" is false or "UserPreamble" is set.
202
203 $toc = $parser->TableOfContents;
204 $parser->TableOfContents(1);
205
206 Default is false.
207
208 UniqueLabels
209 If true, the translator will attempt to make sure that each "latex"
210 label or index entry will be uniquely identified by prefixing the
211 contents of "Label". This allows multiple documents to be combined
212 without clashing common labels such as "DESCRIPTION" and "SYNOPSIS"
213
214 $parser->UniqueLabels(1);
215 $unq = $parser->UniqueLabels;
216
217 Default is true.
218
219 UserPreamble
220 User supplied "latex" preamble. Added before the pod translation
221 data.
222
223 If set, the contents will be prepended to the output file before
224 the translated data regardless of the value of "AddPreamble".
225 "MakeIndex" and "TableOfContents" will also be ignored.
226
227 UserPostamble
228 User supplied "latex" postamble. Added after the pod translation
229 data.
230
231 If set, the contents will be prepended to the output file after the
232 translated data regardless of the value of "AddPostamble".
233 "MakeIndex" will also be ignored.
234
236 Compatible with "latex2e" only. Can not be used with "latex" v2.09 or
237 earlier.
238
239 A subclass of "Pod::Select" so that specific pod sections can be con‐
240 verted to "latex" by using the "select" method.
241
242 Some HTML escapes are missing and many have not been tested.
243
245 Pod::Parser, Pod::Select, pod2latex
246
248 Tim Jenness <tjenness@cpan.org>
249
250 Bug fixes and improvements have been received from: Simon Cozens
251 <simon@cozens.net>, Mark A. Hershberger <mah@everybody.org>, Marcel
252 Grunauer <marcel@codewerk.com>, Hugh S Myers <hsmyers@sdragons.com>,
253 Peter J Acklam <jacklam@math.uio.no>, Sudhi Herle <sudhi@herle.net>,
254 Ariel Scolnicov <ariels@compugen.co.il>, Adriano Rodrigues Ferreira
255 <ferreira@triang.com.br> and R. de Vries <r.de.vries@dutchspace.nl>.
256
258 Copyright (C) 2000-2004 Tim Jenness. All Rights Reserved.
259
260 This program is free software; you can redistribute it and/or modify it
261 under the same terms as Perl itself.
262
263
264
265perl v5.8.8 2001-09-21 Pod::LaTeX(3pm)