5 Pod::LaTeX - Convert Pod data to formatted Latex
10 my $parser = Pod::LaTeX->new ( );
12 $parser->parse_from_filehandle;
14 $parser->parse_from_file ('file.pod', 'file.tex');
18 C<Pod::LaTeX> is a module to convert documentation in the Pod format
19 into Latex. The L<B<pod2latex>|pod2latex> X<pod2latex> command uses
20 this module for translation.
22 C<Pod::LaTeX> is a derived class from L<Pod::Select|Pod::Select>.
28 require Pod::ParseUtils;
29 use base qw/ Pod::Select /;
31 # use Data::Dumper; # for debugging
34 use vars qw/ $VERSION %HTML_Escapes @LatexSections /;
38 # Definitions of =headN -> latex mapping
48 # Standard escape sequences converted to Latex.
49 # The Unicode name of each character is given in the comments.
50 # Complete LaTeX set added by Peter Acklam.
53 'sol' => '\textfractionsolidus{}', # xxx - or should it be just '/'
56 # The stuff below is based on the information available at
57 # http://www.w3.org/TR/html401/sgml/entities.html
59 # All characters in the range 0xA0-0xFF of the ISO 8859-1 character set.
60 # Several of these characters require the `textcomp' LaTeX package.
61 'nbsp' => q|~|, # 0xA0 - no-break space = non-breaking space
62 'iexcl' => q|\textexclamdown{}|, # 0xA1 - inverted exclamation mark
63 'cent' => q|\textcent{}|, # 0xA2 - cent sign
64 'pound' => q|\textsterling{}|, # 0xA3 - pound sign
65 'curren' => q|\textcurrency{}|, # 0xA4 - currency sign
66 'yen' => q|\textyen{}|, # 0xA5 - yen sign = yuan sign
67 'brvbar' => q|\textbrokenbar{}|, # 0xA6 - broken bar = broken vertical bar
68 'sect' => q|\textsection{}|, # 0xA7 - section sign
69 'uml' => q|\textasciidieresis{}|, # 0xA8 - diaeresis = spacing diaeresis
70 'copy' => q|\textcopyright{}|, # 0xA9 - copyright sign
71 'ordf' => q|\textordfeminine{}|, # 0xAA - feminine ordinal indicator
72 'laquo' => q|\guillemotleft{}|, # 0xAB - left-pointing double angle quotation mark = left pointing guillemet
73 'not' => q|\textlnot{}|, # 0xAC - not sign
74 'shy' => q|\-|, # 0xAD - soft hyphen = discretionary hyphen
75 'reg' => q|\textregistered{}|, # 0xAE - registered sign = registered trade mark sign
76 'macr' => q|\textasciimacron{}|, # 0xAF - macron = spacing macron = overline = APL overbar
77 'deg' => q|\textdegree{}|, # 0xB0 - degree sign
78 'plusmn' => q|\textpm{}|, # 0xB1 - plus-minus sign = plus-or-minus sign
79 'sup2' => q|\texttwosuperior{}|, # 0xB2 - superscript two = superscript digit two = squared
80 'sup3' => q|\textthreesuperior{}|, # 0xB3 - superscript three = superscript digit three = cubed
81 'acute' => q|\textasciiacute{}|, # 0xB4 - acute accent = spacing acute
82 'micro' => q|\textmu{}|, # 0xB5 - micro sign
83 'para' => q|\textparagraph{}|, # 0xB6 - pilcrow sign = paragraph sign
84 'middot' => q|\textperiodcentered{}|, # 0xB7 - middle dot = Georgian comma = Greek middle dot
85 'cedil' => q|\c{}|, # 0xB8 - cedilla = spacing cedilla
86 'sup1' => q|\textonesuperior{}|, # 0xB9 - superscript one = superscript digit one
87 'ordm' => q|\textordmasculine{}|, # 0xBA - masculine ordinal indicator
88 'raquo' => q|\guillemotright{}|, # 0xBB - right-pointing double angle quotation mark = right pointing guillemet
89 'frac14' => q|\textonequarter{}|, # 0xBC - vulgar fraction one quarter = fraction one quarter
90 'frac12' => q|\textonehalf{}|, # 0xBD - vulgar fraction one half = fraction one half
91 'frac34' => q|\textthreequarters{}|, # 0xBE - vulgar fraction three quarters = fraction three quarters
92 'iquest' => q|\textquestiondown{}|, # 0xBF - inverted question mark = turned question mark
93 'Agrave' => q|\`A|, # 0xC0 - latin capital letter A with grave = latin capital letter A grave
94 'Aacute' => q|\'A|, # 0xC1 - latin capital letter A with acute
95 'Acirc' => q|\^A|, # 0xC2 - latin capital letter A with circumflex
96 'Atilde' => q|\~A|, # 0xC3 - latin capital letter A with tilde
97 'Auml' => q|\"A|, # 0xC4 - latin capital letter A with diaeresis
98 'Aring' => q|\AA{}|, # 0xC5 - latin capital letter A with ring above = latin capital letter A ring
99 'AElig' => q|\AE{}|, # 0xC6 - latin capital letter AE = latin capital ligature AE
100 'Ccedil' => q|\c{C}|, # 0xC7 - latin capital letter C with cedilla
101 'Egrave' => q|\`E|, # 0xC8 - latin capital letter E with grave
102 'Eacute' => q|\'E|, # 0xC9 - latin capital letter E with acute
103 'Ecirc' => q|\^E|, # 0xCA - latin capital letter E with circumflex
104 'Euml' => q|\"E|, # 0xCB - latin capital letter E with diaeresis
105 'Igrave' => q|\`I|, # 0xCC - latin capital letter I with grave
106 'Iacute' => q|\'I|, # 0xCD - latin capital letter I with acute
107 'Icirc' => q|\^I|, # 0xCE - latin capital letter I with circumflex
108 'Iuml' => q|\"I|, # 0xCF - latin capital letter I with diaeresis
109 'ETH' => q|\DH{}|, # 0xD0 - latin capital letter ETH
110 'Ntilde' => q|\~N|, # 0xD1 - latin capital letter N with tilde
111 'Ograve' => q|\`O|, # 0xD2 - latin capital letter O with grave
112 'Oacute' => q|\'O|, # 0xD3 - latin capital letter O with acute
113 'Ocirc' => q|\^O|, # 0xD4 - latin capital letter O with circumflex
114 'Otilde' => q|\~O|, # 0xD5 - latin capital letter O with tilde
115 'Ouml' => q|\"O|, # 0xD6 - latin capital letter O with diaeresis
116 'times' => q|\texttimes{}|, # 0xD7 - multiplication sign
117 'Oslash' => q|\O{}|, # 0xD8 - latin capital letter O with stroke = latin capital letter O slash
118 'Ugrave' => q|\`U|, # 0xD9 - latin capital letter U with grave
119 'Uacute' => q|\'U|, # 0xDA - latin capital letter U with acute
120 'Ucirc' => q|\^U|, # 0xDB - latin capital letter U with circumflex
121 'Uuml' => q|\"U|, # 0xDC - latin capital letter U with diaeresis
122 'Yacute' => q|\'Y|, # 0xDD - latin capital letter Y with acute
123 'THORN' => q|\TH{}|, # 0xDE - latin capital letter THORN
124 'szlig' => q|\ss{}|, # 0xDF - latin small letter sharp s = ess-zed
125 'agrave' => q|\`a|, # 0xE0 - latin small letter a with grave = latin small letter a grave
126 'aacute' => q|\'a|, # 0xE1 - latin small letter a with acute
127 'acirc' => q|\^a|, # 0xE2 - latin small letter a with circumflex
128 'atilde' => q|\~a|, # 0xE3 - latin small letter a with tilde
129 'auml' => q|\"a|, # 0xE4 - latin small letter a with diaeresis
130 'aring' => q|\aa{}|, # 0xE5 - latin small letter a with ring above = latin small letter a ring
131 'aelig' => q|\ae{}|, # 0xE6 - latin small letter ae = latin small ligature ae
132 'ccedil' => q|\c{c}|, # 0xE7 - latin small letter c with cedilla
133 'egrave' => q|\`e|, # 0xE8 - latin small letter e with grave
134 'eacute' => q|\'e|, # 0xE9 - latin small letter e with acute
135 'ecirc' => q|\^e|, # 0xEA - latin small letter e with circumflex
136 'euml' => q|\"e|, # 0xEB - latin small letter e with diaeresis
137 'igrave' => q|\`i|, # 0xEC - latin small letter i with grave
138 'iacute' => q|\'i|, # 0xED - latin small letter i with acute
139 'icirc' => q|\^i|, # 0xEE - latin small letter i with circumflex
140 'iuml' => q|\"i|, # 0xEF - latin small letter i with diaeresis
141 'eth' => q|\dh{}|, # 0xF0 - latin small letter eth
142 'ntilde' => q|\~n|, # 0xF1 - latin small letter n with tilde
143 'ograve' => q|\`o|, # 0xF2 - latin small letter o with grave
144 'oacute' => q|\'o|, # 0xF3 - latin small letter o with acute
145 'ocirc' => q|\^o|, # 0xF4 - latin small letter o with circumflex
146 'otilde' => q|\~o|, # 0xF5 - latin small letter o with tilde
147 'ouml' => q|\"o|, # 0xF6 - latin small letter o with diaeresis
148 'divide' => q|\textdiv{}|, # 0xF7 - division sign
149 'oslash' => q|\o{}|, # 0xF8 - latin small letter o with stroke, = latin small letter o slash
150 'ugrave' => q|\`u|, # 0xF9 - latin small letter u with grave
151 'uacute' => q|\'u|, # 0xFA - latin small letter u with acute
152 'ucirc' => q|\^u|, # 0xFB - latin small letter u with circumflex
153 'uuml' => q|\"u|, # 0xFC - latin small letter u with diaeresis
154 'yacute' => q|\'y|, # 0xFD - latin small letter y with acute
155 'thorn' => q|\th{}|, # 0xFE - latin small letter thorn
156 'yuml' => q|\"y|, # 0xFF - latin small letter y with diaeresis
159 'fnof' => q|\textflorin{}|, # latin small f with hook = function = florin
162 'Alpha' => q|$\mathrm{A}$|, # greek capital letter alpha
163 'Beta' => q|$\mathrm{B}$|, # greek capital letter beta
164 'Gamma' => q|$\Gamma$|, # greek capital letter gamma
165 'Delta' => q|$\Delta$|, # greek capital letter delta
166 'Epsilon' => q|$\mathrm{E}$|, # greek capital letter epsilon
167 'Zeta' => q|$\mathrm{Z}$|, # greek capital letter zeta
168 'Eta' => q|$\mathrm{H}$|, # greek capital letter eta
169 'Theta' => q|$\Theta$|, # greek capital letter theta
170 'Iota' => q|$\mathrm{I}$|, # greek capital letter iota
171 'Kappa' => q|$\mathrm{K}$|, # greek capital letter kappa
172 'Lambda' => q|$\Lambda$|, # greek capital letter lambda
173 'Mu' => q|$\mathrm{M}$|, # greek capital letter mu
174 'Nu' => q|$\mathrm{N}$|, # greek capital letter nu
175 'Xi' => q|$\Xi$|, # greek capital letter xi
176 'Omicron' => q|$\mathrm{O}$|, # greek capital letter omicron
177 'Pi' => q|$\Pi$|, # greek capital letter pi
178 'Rho' => q|$\mathrm{R}$|, # greek capital letter rho
179 'Sigma' => q|$\Sigma$|, # greek capital letter sigma
180 'Tau' => q|$\mathrm{T}$|, # greek capital letter tau
181 'Upsilon' => q|$\Upsilon$|, # greek capital letter upsilon
182 'Phi' => q|$\Phi$|, # greek capital letter phi
183 'Chi' => q|$\mathrm{X}$|, # greek capital letter chi
184 'Psi' => q|$\Psi$|, # greek capital letter psi
185 'Omega' => q|$\Omega$|, # greek capital letter omega
187 'alpha' => q|$\alpha$|, # greek small letter alpha
188 'beta' => q|$\beta$|, # greek small letter beta
189 'gamma' => q|$\gamma$|, # greek small letter gamma
190 'delta' => q|$\delta$|, # greek small letter delta
191 'epsilon' => q|$\epsilon$|, # greek small letter epsilon
192 'zeta' => q|$\zeta$|, # greek small letter zeta
193 'eta' => q|$\eta$|, # greek small letter eta
194 'theta' => q|$\theta$|, # greek small letter theta
195 'iota' => q|$\iota$|, # greek small letter iota
196 'kappa' => q|$\kappa$|, # greek small letter kappa
197 'lambda' => q|$\lambda$|, # greek small letter lambda
198 'mu' => q|$\mu$|, # greek small letter mu
199 'nu' => q|$\nu$|, # greek small letter nu
200 'xi' => q|$\xi$|, # greek small letter xi
201 'omicron' => q|$o$|, # greek small letter omicron
202 'pi' => q|$\pi$|, # greek small letter pi
203 'rho' => q|$\rho$|, # greek small letter rho
204 # 'sigmaf' => q||, # greek small letter final sigma
205 'sigma' => q|$\sigma$|, # greek small letter sigma
206 'tau' => q|$\tau$|, # greek small letter tau
207 'upsilon' => q|$\upsilon$|, # greek small letter upsilon
208 'phi' => q|$\phi$|, # greek small letter phi
209 'chi' => q|$\chi$|, # greek small letter chi
210 'psi' => q|$\psi$|, # greek small letter psi
211 'omega' => q|$\omega$|, # greek small letter omega
212 # 'thetasym' => q||, # greek small letter theta symbol
213 # 'upsih' => q||, # greek upsilon with hook symbol
214 # 'piv' => q||, # greek pi symbol
216 # General Punctuation
217 'bull' => q|\textbullet{}|, # bullet = black small circle
218 # bullet is NOT the same as bullet operator
219 'hellip' => q|\textellipsis{}|, # horizontal ellipsis = three dot leader
220 'prime' => q|\textquotesingle{}|, # prime = minutes = feet
221 'Prime' => q|\textquotedbl{}|, # double prime = seconds = inches
222 'oline' => q|\textasciimacron{}|, # overline = spacing overscore
223 'frasl' => q|\textfractionsolidus{}|, # fraction slash
226 'weierp' => q|$\wp$|, # script capital P = power set = Weierstrass p
227 'image' => q|$\Re$|, # blackletter capital I = imaginary part
228 'real' => q|$\Im$|, # blackletter capital R = real part symbol
229 'trade' => q|\texttrademark{}|, # trade mark sign
230 # 'alefsym' => q||, # alef symbol = first transfinite cardinal
231 # alef symbol is NOT the same as hebrew letter alef, although the same
232 # glyph could be used to depict both characters
235 'larr' => q|\textleftarrow{}|, # leftwards arrow
236 'uarr' => q|\textuparrow{}|, # upwards arrow
237 'rarr' => q|\textrightarrow{}|, # rightwards arrow
238 'darr' => q|\textdownarrow{}|, # downwards arrow
239 'harr' => q|$\leftrightarrow$|, # left right arrow
240 # 'crarr' => q||, # downwards arrow with corner leftwards = carriage return
241 'lArr' => q|$\Leftarrow$|, # leftwards double arrow
242 # ISO 10646 does not say that lArr is the same as the 'is implied by'
243 # arrow but also does not have any other character for that function. So
244 # lArr can be used for 'is implied by' as ISOtech suggests
245 'uArr' => q|$\Uparrow$|, # upwards double arrow
246 'rArr' => q|$\Rightarrow$|, # rightwards double arrow
247 # ISO 10646 does not say this is the 'implies' character but does not
248 # have another character with this function so ? rArr can be used for
249 # 'implies' as ISOtech suggests
250 'dArr' => q|$\Downarrow$|, # downwards double arrow
251 'hArr' => q|$\Leftrightarrow$|, # left right double arrow
253 # Mathematical Operators.
254 # Some of these require the `amssymb' package.
255 'forall' => q|$\forall$|, # for all
256 'part' => q|$\partial$|, # partial differential
257 'exist' => q|$\exists$|, # there exists
258 'empty' => q|$\emptyset$|, # empty set = null set = diameter
259 'nabla' => q|$\nabla$|, # nabla = backward difference
260 'isin' => q|$\in$|, # element of
261 'notin' => q|$\notin$|, # not an element of
262 'ni' => q|$\ni$|, # contains as member
263 'prod' => q|$\prod$|, # n-ary product = product sign
264 # prod is NOT the same character as 'greek capital letter pi' though the
265 # same glyph might be used for both
266 'sum' => q|$\sum$|, # n-ary sumation
267 # sum is NOT the same character as 'greek capital letter sigma' though
268 # the same glyph might be used for both
269 'minus' => q|$-$|, # minus sign
270 'lowast' => q|$\ast$|, # asterisk operator
271 'radic' => q|$\surd$|, # square root = radical sign
272 'prop' => q|$\propto$|, # proportional to
273 'infin' => q|$\infty$|, # infinity
274 'ang' => q|$\angle$|, # angle
275 'and' => q|$\wedge$|, # logical and = wedge
276 'or' => q|$\vee$|, # logical or = vee
277 'cap' => q|$\cap$|, # intersection = cap
278 'cup' => q|$\cup$|, # union = cup
279 'int' => q|$\int$|, # integral
280 'there4' => q|$\therefore$|, # therefore
281 'sim' => q|$\sim$|, # tilde operator = varies with = similar to
282 # tilde operator is NOT the same character as the tilde
283 'cong' => q|$\cong$|, # approximately equal to
284 'asymp' => q|$\asymp$|, # almost equal to = asymptotic to
285 'ne' => q|$\neq$|, # not equal to
286 'equiv' => q|$\equiv$|, # identical to
287 'le' => q|$\leq$|, # less-than or equal to
288 'ge' => q|$\geq$|, # greater-than or equal to
289 'sub' => q|$\subset$|, # subset of
290 'sup' => q|$\supset$|, # superset of
291 # note that nsup, 'not a superset of' is not covered by the Symbol font
292 # encoding and is not included.
293 'nsub' => q|$\not\subset$|, # not a subset of
294 'sube' => q|$\subseteq$|, # subset of or equal to
295 'supe' => q|$\supseteq$|, # superset of or equal to
296 'oplus' => q|$\oplus$|, # circled plus = direct sum
297 'otimes' => q|$\otimes$|, # circled times = vector product
298 'perp' => q|$\perp$|, # up tack = orthogonal to = perpendicular
299 'sdot' => q|$\cdot$|, # dot operator
300 # dot operator is NOT the same character as middle dot
302 # Miscellaneous Technical
303 'lceil' => q|$\lceil$|, # left ceiling = apl upstile
304 'rceil' => q|$\rceil$|, # right ceiling
305 'lfloor' => q|$\lfloor$|, # left floor = apl downstile
306 'rfloor' => q|$\rfloor$|, # right floor
307 'lang' => q|$\langle$|, # left-pointing angle bracket = bra
308 # lang is NOT the same character as 'less than' or 'single left-pointing
309 # angle quotation mark'
310 'rang' => q|$\rangle$|, # right-pointing angle bracket = ket
311 # rang is NOT the same character as 'greater than' or 'single
312 # right-pointing angle quotation mark'
315 'loz' => q|$\lozenge$|, # lozenge
317 # Miscellaneous Symbols
318 'spades' => q|$\spadesuit$|, # black spade suit
319 'clubs' => q|$\clubsuit$|, # black club suit = shamrock
320 'hearts' => q|$\heartsuit$|, # black heart suit = valentine
321 'diams' => q|$\diamondsuit$|, # black diamond suit
323 # C0 Controls and Basic Latin
324 'quot' => q|"|, # quotation mark = APL quote ["]
325 'amp' => q|\&|, # ampersand
326 'lt' => q|<|, # less-than sign
327 'gt' => q|>|, # greater-than sign
328 'OElig' => q|\OE{}|, # latin capital ligature OE
329 'oelig' => q|\oe{}|, # latin small ligature oe
330 'Scaron' => q|\v{S}|, # latin capital letter S with caron
331 'scaron' => q|\v{s}|, # latin small letter s with caron
332 'Yuml' => q|\"Y|, # latin capital letter Y with diaeresis
333 'circ' => q|\textasciicircum{}|, # modifier letter circumflex accent
334 'tilde' => q|\textasciitilde{}|, # small tilde
335 'ensp' => q|\phantom{n}|, # en space
336 'emsp' => q|\hspace{1em}|, # em space
337 'thinsp' => q|\,|, # thin space
338 'zwnj' => q|{}|, # zero width non-joiner
339 # 'zwj' => q||, # zero width joiner
340 # 'lrm' => q||, # left-to-right mark
341 # 'rlm' => q||, # right-to-left mark
342 'ndash' => q|--|, # en dash
343 'mdash' => q|---|, # em dash
344 'lsquo' => q|\textquoteleft{}|, # left single quotation mark
345 'rsquo' => q|\textquoteright{}|, # right single quotation mark
346 'sbquo' => q|\quotesinglbase{}|, # single low-9 quotation mark
347 'ldquo' => q|\textquotedblleft{}|, # left double quotation mark
348 'rdquo' => q|\textquotedblright{}|, # right double quotation mark
349 'bdquo' => q|\quotedblbase{}|, # double low-9 quotation mark
350 'dagger' => q|\textdagger{}|, # dagger
351 'Dagger' => q|\textdaggerdbl{}|, # double dagger
352 'permil' => q|\textperthousand{}|, # per mille sign
353 'lsaquo' => q|\guilsinglleft{}|, # single left-pointing angle quotation mark
354 'rsaquo' => q|\guilsinglright{}|, # single right-pointing angle quotation mark
355 'euro' => q|\texteuro{}|, # euro sign
358 =head1 OBJECT METHODS
360 The following methods are provided in this module. Methods inherited
361 from C<Pod::Select> are not described in the public interface.
369 Initialise the object. This method is subclassed from C<Pod::Parser>.
370 The base class method is invoked. This method defines the default
371 behaviour of the object unless overridden by supplying arguments to
374 Internal settings are defaulted as well as the public instance data.
375 Internal hash values are accessed directly (rather than through
376 a method) and start with an underscore.
378 This method should not be invoked by the user directly.
386 # - An array for nested lists
388 # Arguments have already been read by this point
393 # print Dumper($self);
396 $self->{_Lists} = []; # For nested lists
397 $self->{_suppress_all_para} = 0; # For =begin blocks
398 $self->{_dont_modify_any_para}=0; # For =begin blocks
399 $self->{_CURRENT_HEAD1} = ''; # Name of current HEAD1 section
401 # Options - only initialise if not already set
403 # Cause the '=head1 NAME' field to be treated specially
404 # The contents of the NAME paragraph will be converted
405 # to a section title. All subsequent =head1 will be converted
406 # to =head2 and down. Will not affect =head1's prior to NAME
407 # Assumes: 'Module - purpose' format
408 # Also creates a purpose field
409 # The name is used for Labeling of the subsequent subsections
410 $self->{ReplaceNAMEwithSection} = 0
411 unless exists $self->{ReplaceNAMEwithSection};
412 $self->{AddPreamble} = 1 # make full latex document
413 unless exists $self->{AddPreamble};
414 $self->{StartWithNewPage} = 0 # Start new page for pod section
415 unless exists $self->{StartWithNewPage};
416 $self->{TableOfContents} = 0 # Add table of contents
417 unless exists $self->{TableOfContents}; # only relevent if AddPreamble=1
418 $self->{AddPostamble} = 1 # Add closing latex code at end
419 unless exists $self->{AddPostamble}; # effectively end{document} and index
420 $self->{MakeIndex} = 1 # Add index (only relevant AddPostamble
421 unless exists $self->{MakeIndex}; # and AddPreamble)
423 $self->{UniqueLabels} = 1 # Use label unique for each pod
424 unless exists $self->{UniqueLabels}; # either based on the filename
427 # Control the level of =head1. default is \section
429 $self->{Head1Level} = 1 # Offset in latex sections
430 unless exists $self->{Head1Level}; # 0 is chapter, 2 is subsection
432 # Control at which level numbering of sections is turned off
433 # ie subsection becomes subsection*
434 # The numbering is relative to the latex sectioning commands
435 # and is independent of Pod heading level
436 # default is to number \section but not \subsection
437 $self->{LevelNoNum} = 2
438 unless exists $self->{LevelNoNum};
440 # Label to be used as prefix to all internal section names
441 # If not defined will attempt to derive it from the filename
442 # This can not happen when running parse_from_filehandle though
443 # hence the ability to set the label externally
444 # The label could then be Pod::Parser_DESCRIPTION or somesuch
446 $self->{Label} = undef # label to be used as prefix
447 unless exists $self->{Label}; # to all internal section names
449 # These allow the caller to add arbritrary latex code to
450 # start and end of document. AddPreamble and AddPostamble are ignored
452 # Also MakeIndex and TableOfContents are also ignored.
453 $self->{UserPreamble} = undef # User supplied start (AddPreamble =1)
454 unless exists $self->{Label};
455 $self->{UserPostamble} = undef # Use supplied end (AddPostamble=1)
456 unless exists $self->{Label};
458 # Run base initialize
459 $self->SUPER::initialize;
465 =head2 Data Accessors
467 The following methods are provided for accessing instance data. These
468 methods should be used for accessing configuration parameters rather
469 than assuming the object is a hash.
471 Default values can be supplied by using these names as keys to a hash
472 of arguments when using the C<new()> constructor.
478 Logical to control whether a C<latex> preamble is to be written.
479 If true, a valid C<latex> preamble is written before the pod data is written.
482 \documentclass{article}
483 \usepackage[T1]{fontenc}
484 \usepackage{textcomp}
487 but will be more complicated if table of contents and indexing are required.
488 Can be used to set or retrieve the current value.
490 $add = $parser->AddPreamble();
491 $parser->AddPreamble(1);
493 If used in conjunction with C<AddPostamble> a full latex document will
494 be written that could be immediately processed by C<latex>.
496 For some pod escapes it may be necessary to include the amsmath
497 package. This is not yet added to the preamble automatically.
504 $self->{AddPreamble} = shift;
506 return $self->{AddPreamble};
509 =item B<AddPostamble>
511 Logical to control whether a standard C<latex> ending is written to the output
512 file after the document has been processed.
513 In its simplest form this is simply:
517 but can be more complicated if a index is required.
518 Can be used to set or retrieve the current value.
520 $add = $parser->AddPostamble();
521 $parser->AddPostamble(1);
523 If used in conjunction with C<AddPreaamble> a full latex document will
524 be written that could be immediately processed by C<latex>.
531 $self->{AddPostamble} = shift;
533 return $self->{AddPostamble};
538 The C<latex> sectioning level that should be used to correspond to
539 a pod C<=head1> directive. This can be used, for example, to turn
540 a C<=head1> into a C<latex> C<subsection>. This should hold a number
541 corresponding to the required position in an array containing the
551 Can be used to set or retrieve the current value:
553 $parser->Head1Level(2);
554 $sect = $parser->Head1Level;
556 Setting this number too high can result in sections that may not be reproducible
557 in the expected way. For example, setting this to 4 would imply that C<=head3>
558 do not have a corresponding C<latex> section (C<=head1> would correspond to
561 A check is made to ensure that the supplied value is an integer in the
564 Default is for a value of 1 (i.e. a C<section>).
572 if ($arg =~ /^\d$/ && $arg <= $#LatexSections) {
573 $self->{Head1Level} = $arg;
575 carp "Head1Level supplied ($arg) must be integer in range 0 to ".$#LatexSections . "- Ignoring\n";
578 return $self->{Head1Level};
583 This is the label that is prefixed to all C<latex> label and index
584 entries to make them unique. In general, pods have similarly titled
585 sections (NAME, DESCRIPTION etc) and a C<latex> label will be multiply
586 defined if more than one pod document is to be included in a single
587 C<latex> file. To overcome this, this label is prefixed to a label
588 whenever a label is required (joined with an underscore) or to an
589 index entry (joined by an exclamation mark which is the normal index
590 separator). For example, C<\label{text}> becomes C<\label{Label_text}>.
592 Can be used to set or retrieve the current value:
594 $label = $parser->Label;
595 $parser->Label($label);
597 This label is only used if C<UniqueLabels> is true.
598 Its value is set automatically from the C<NAME> field
599 if C<ReplaceNAMEwithSection> is true. If this is not the case
600 it must be set manually before starting the parse.
602 Default value is C<undef>.
609 $self->{Label} = shift;
611 return $self->{Label};
616 Control the point at which C<latex> section numbering is turned off.
617 For example, this can be used to make sure that C<latex> sections
618 are numbered but subsections are not.
620 Can be used to set or retrieve the current value:
622 $lev = $parser->LevelNoNum;
623 $parser->LevelNoNum(2);
625 The argument must be an integer between 0 and 5 and is the same as the
626 number described in C<Head1Level> method description. The number has
627 nothing to do with the pod heading number, only the C<latex> sectioning.
629 Default is 2. (i.e. C<latex> subsections are written as C<subsection*>
630 but sections are numbered).
637 $self->{LevelNoNum} = shift;
639 return $self->{LevelNoNum};
644 Controls whether C<latex> commands for creating an index are to be inserted
645 into the preamble and postamble
647 $makeindex = $parser->MakeIndex;
648 $parser->MakeIndex(0);
650 Irrelevant if both C<AddPreamble> and C<AddPostamble> are false (or equivalently,
651 C<UserPreamble> and C<UserPostamble> are set).
653 Default is for an index to be created.
660 $self->{MakeIndex} = shift;
662 return $self->{MakeIndex};
665 =item B<ReplaceNAMEwithSection>
667 This controls whether the C<NAME> section in the pod is to be translated
668 literally or converted to a slightly modified output where the section
669 name is the pod name rather than "NAME".
671 If true, the pod segment
679 is converted to the C<latex>
681 \section{pod::name\label{pod_name}\index{pod::name}}
685 \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
686 \index{pod::name!SYNOPSIS}}
688 (dependent on the value of C<Head1Level> and C<LevelNoNum>). Note that
689 subsequent C<head1> directives translate to subsections rather than
690 sections and that the labels and index now include the pod name (dependent
691 on the value of C<UniqueLabels>).
693 The C<Label> is set from the pod name regardless of any current value
696 $mod = $parser->ReplaceNAMEwithSection;
697 $parser->ReplaceNAMEwithSection(0);
699 Default is to translate the pod literally.
703 sub ReplaceNAMEwithSection {
706 $self->{ReplaceNAMEwithSection} = shift;
708 return $self->{ReplaceNAMEwithSection};
711 =item B<StartWithNewPage>
713 If true, each pod translation will begin with a C<latex>
716 $parser->StartWithNewPage(1);
717 $newpage = $parser->StartWithNewPage;
723 sub StartWithNewPage {
726 $self->{StartWithNewPage} = shift;
728 return $self->{StartWithNewPage};
731 =item B<TableOfContents>
733 If true, a table of contents will be created.
734 Irrelevant if C<AddPreamble> is false or C<UserPreamble>
737 $toc = $parser->TableOfContents;
738 $parser->TableOfContents(1);
744 sub TableOfContents {
747 $self->{TableOfContents} = shift;
749 return $self->{TableOfContents};
752 =item B<UniqueLabels>
754 If true, the translator will attempt to make sure that
755 each C<latex> label or index entry will be uniquely identified
756 by prefixing the contents of C<Label>. This allows
757 multiple documents to be combined without clashing
758 common labels such as C<DESCRIPTION> and C<SYNOPSIS>
760 $parser->UniqueLabels(1);
761 $unq = $parser->UniqueLabels;
770 $self->{UniqueLabels} = shift;
772 return $self->{UniqueLabels};
775 =item B<UserPreamble>
777 User supplied C<latex> preamble. Added before the pod translation
780 If set, the contents will be prepended to the output file before the translated
781 data regardless of the value of C<AddPreamble>.
782 C<MakeIndex> and C<TableOfContents> will also be ignored.
789 $self->{UserPreamble} = shift;
791 return $self->{UserPreamble};
794 =item B<UserPostamble>
796 User supplied C<latex> postamble. Added after the pod translation
799 If set, the contents will be prepended to the output file after the translated
800 data regardless of the value of C<AddPostamble>.
801 C<MakeIndex> will also be ignored.
808 $self->{UserPostamble} = shift;
810 return $self->{UserPostamble};
817 Contains details of the currently active lists.
818 The array contains C<Pod::List> objects. A new C<Pod::List>
819 object is created each time a list is encountered and it is
820 pushed onto this stack. When the list context ends, it
821 is popped from the stack. The array will be empty if no
824 Returns array of list information in list context
825 Returns array ref in scalar context
833 return @{ $self->{_Lists} } if wantarray();
834 return $self->{_Lists};
843 =head2 Subclassed methods
845 The following methods override methods provided in the C<Pod::Select>
846 base class. See C<Pod::Parser> and C<Pod::Select> for more information
847 on what these methods require.
853 ######### END ACCESSORS ###################
859 Writes the C<latex> preamble if requested. Only writes something
860 if AddPreamble is true. Writes a standard header unless a UserPreamble
868 # Get the pod identification
869 # This should really come from the '=head1 NAME' paragraph
871 my $infile = $self->input_file;
872 my $class = ref($self);
873 my $date = gmtime(time);
875 # Comment message to say where this came from
876 my $comment = << "__TEX_COMMENT__";
877 %% Latex generated from POD in document $infile
878 %% Using the perl module $class
879 %% Converted on $date
883 # If the caller has supplied one then we just use that
887 if ($self->AddPreamble) {
889 if (defined $self->UserPreamble) {
891 $preamble = $self->UserPreamble;
893 # Add the description of where this came from
894 $preamble .= "\n$comment\n%% Preamble supplied by user.\n\n";
898 # Write our own preamble
900 # Code to initialise index making
901 # Use an array so that we can prepend comment if required
903 '\usepackage{makeidx}',
907 unless ($self->MakeIndex) {
912 my $makeindex = join("\n",@makeidx) . "\n";
915 my $tableofcontents = '\tableofcontents';
917 $tableofcontents = '%% ' . $tableofcontents
918 unless $self->TableOfContents;
921 $preamble = << "__TEX_HEADER__";
922 \\documentclass{article}
923 \\usepackage[T1]{fontenc}
924 \\usepackage{textcomp}
939 # Write the header (blank if none)
940 $self->_output($preamble);
942 # Start on new page if requested
943 $self->_output("\\clearpage\n") if $self->StartWithNewPage;
950 Write the closing C<latex> code. Only writes something if AddPostamble
951 is true. Writes a standard header unless a UserPostamble is defined.
961 # Use the user version of the postamble if defined
962 if ($self->AddPostamble) {
964 if (defined $self->UserPostamble) {
965 $end = $self->UserPostamble;
970 my $makeindex = '\printindex';
972 $makeindex = '%% '. $makeindex unless $self->MakeIndex;
974 $end = "$makeindex\n\n\\end{document}\n";
978 $self->_output($end);
984 Process basic pod commands.
990 my ($command, $paragraph, $line_num, $parobj) = @_;
992 # return if we dont care
993 return if $command eq 'pod';
995 # Store a copy of the raw text in case we are in a =for
996 # block and need to preserve the existing latex
997 my $rawpara = $paragraph;
999 # Do the latex escapes
1000 $paragraph = $self->_replace_special_chars($paragraph);
1002 # Interpolate pod sequences in paragraph
1003 $paragraph = $self->interpolate($paragraph, $line_num);
1004 $paragraph =~ s/\s+$//;
1006 # Replace characters that can only be done after
1007 # interpolation of interior sequences
1008 $paragraph = $self->_replace_special_chars_late($paragraph);
1010 # Now run the command
1011 if ($command eq 'over') {
1013 $self->begin_list($paragraph, $line_num);
1015 } elsif ($command eq 'item') {
1017 $self->add_item($paragraph, $line_num);
1019 } elsif ($command eq 'back') {
1021 $self->end_list($line_num);
1023 } elsif ($command eq 'head1') {
1025 # Store the name of the section
1026 $self->{_CURRENT_HEAD1} = $paragraph;
1029 $self->head(1, $paragraph, $parobj);
1031 } elsif ($command eq 'head2') {
1033 $self->head(2, $paragraph, $parobj);
1035 } elsif ($command eq 'head3') {
1037 $self->head(3, $paragraph, $parobj);
1039 } elsif ($command eq 'head4') {
1041 $self->head(4, $paragraph, $parobj);
1043 } elsif ($command eq 'head5') {
1045 $self->head(5, $paragraph, $parobj);
1047 } elsif ($command eq 'head6') {
1049 $self->head(6, $paragraph, $parobj);
1051 } elsif ($command eq 'begin') {
1053 # pass through if latex
1054 if ($paragraph =~ /^latex/i) {
1055 # Make sure that subsequent paragraphs are not modfied before printing
1056 $self->{_dont_modify_any_para} = 1;
1059 # Suppress all subsequent paragraphs unless
1060 # it is explcitly intended for latex
1061 $self->{_suppress_all_para} = 1;
1064 } elsif ($command eq 'for') {
1069 # With =for we will get the text for the full paragraph
1070 # as well as the format name.
1071 # We do not get an additional paragraph later on. The next
1072 # paragraph is not governed by the =for
1074 # The first line contains the format and the rest is the
1076 my ($format, $chunk) = split(/\n/, $rawpara, 2);
1078 # If we have got some latex code print it out immediately
1079 # unmodified. Else do nothing.
1080 if ($format =~ /^latex/i) {
1081 # Make sure that next paragraph is not modfied before printing
1082 $self->_output( $chunk );
1086 } elsif ($command eq 'end') {
1089 $self->{_suppress_all_para} = 0;
1090 $self->{_dont_modify_any_para} = 0;
1092 } elsif ($command eq 'pod') {
1097 carp "Command $command not recognised at line $line_num\n";
1110 my ($paragraph, $line_num, $parobj) = @_;
1112 # Expand paragraph unless in =begin block
1113 if ($self->{_dont_modify_any_para}) {
1115 $self->_output($paragraph);
1119 return if $paragraph =~ /^\s+$/;
1121 # Clean trailing space
1122 $paragraph =~ s/\s+$//;
1124 # Clean tabs. Routine taken from Tabs.pm
1125 # by David Muir Sharnoff muir@idiom.com,
1126 # slightly modified by hsmyers@sdragons.com 10/22/01
1127 my @l = split("\n",$paragraph);
1129 1 while s/(^|\n)([^\t\n]*)(\t+)/
1132 - (length($2) % 8)))
1135 $paragraph = join("\n",@l);
1140 $self->_output('\begin{verbatim}' . "\n$paragraph\n". '\end{verbatim}'."\n");
1146 Plain text paragraph.
1152 my ($paragraph, $line_num, $parobj) = @_;
1154 # print Dumper($self);
1156 # Expand paragraph unless in =begin block
1157 if ($self->{_dont_modify_any_para}) {
1159 $self->_output($paragraph);
1165 # Escape latex special characters
1166 $paragraph = $self->_replace_special_chars($paragraph);
1168 # Interpolate interior sequences
1169 my $expansion = $self->interpolate($paragraph, $line_num);
1170 $expansion =~ s/\s+$//;
1172 # Escape special characters that can not be done earlier
1173 $expansion = $self->_replace_special_chars_late($expansion);
1175 # If we are replacing 'head1 NAME' with a section
1176 # we need to look in the paragraph and rewrite things
1177 # Need to make sure this is called only on the first paragraph
1178 # following 'head1 NAME' and not on subsequent paragraphs that may be
1180 if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()) {
1182 # Strip white space from start and end
1183 $paragraph =~ s/^\s+//;
1184 $paragraph =~ s/\s$//;
1186 # Split the string into 2 parts
1187 my ($name, $purpose) = split(/\s+-\s+/, $expansion,2);
1189 # Now prevent this from triggering until a new head1 NAME is set
1190 $self->{_CURRENT_HEAD1} = '_NAME';
1192 # Might want to clear the Label() before doing this (CHECK)
1195 $self->head(1, $name, $parobj);
1197 # Set the labeling in case we want unique names later
1198 $self->Label( $self->_create_label( $name, 1 ) );
1200 # Raise the Head1Level by one so that subsequent =head1 appear
1201 # as subsections of the main name section unless we are already
1202 # at maximum [Head1Level() could check this itself - CHECK]
1203 $self->Head1Level( $self->Head1Level() + 1)
1204 unless $self->Head1Level == $#LatexSections;
1206 # Now write out the new latex paragraph
1207 $purpose = ucfirst($purpose);
1208 $self->_output("\n\n$purpose\n\n");
1211 # Just write the output
1212 $self->_output("\n\n$expansion\n\n");
1217 =item B<interior_sequence>
1219 Interior sequence expansion
1223 sub interior_sequence {
1226 my ($seq_command, $seq_argument, $pod_seq) = @_;
1228 if ($seq_command eq 'B') {
1229 return "\\textbf{$seq_argument}";
1231 } elsif ($seq_command eq 'I') {
1232 return "\\textit{$seq_argument}";
1234 } elsif ($seq_command eq 'E') {
1236 # If it is simply a number
1237 if ($seq_argument =~ /^\d+$/) {
1238 return chr($seq_argument);
1239 # Look up escape in hash table
1240 } elsif (exists $HTML_Escapes{$seq_argument}) {
1241 return $HTML_Escapes{$seq_argument};
1244 my ($file, $line) = $pod_seq->file_line();
1245 warn "Escape sequence $seq_argument not recognised at line $line of file $file\n";
1249 } elsif ($seq_command eq 'Z') {
1254 } elsif ($seq_command eq 'C') {
1255 return "\\texttt{$seq_argument}";
1257 } elsif ($seq_command eq 'F') {
1258 return "\\emph{$seq_argument}";
1260 } elsif ($seq_command eq 'S') {
1261 # non breakable spaces
1264 $seq_argument =~ s/\s/$nbsp/g;
1265 return $seq_argument;
1267 } elsif ($seq_command eq 'L') {
1268 my $link = new Pod::Hyperlink($seq_argument);
1271 unless (defined $link) {
1276 # Handle internal links differently
1277 my $type = $link->type;
1278 my $page = $link->page;
1280 if ($type eq 'section' && $page eq '') {
1281 # Use internal latex reference
1282 my $node = $link->node;
1284 # Convert to a label
1285 $node = $self->_create_label($node);
1287 return "\\S\\ref{$node}";
1290 # Use default markup for external references
1291 # (although Starlink would use \xlabel)
1292 my $markup = $link->markup;
1293 my ($file, $line) = $pod_seq->file_line();
1295 return $self->interpolate($link->markup, $line);
1300 } elsif ($seq_command eq 'P') {
1301 # Special markup for Pod::Hyperlink
1302 # Replace :: with / - but not sure if I want to do this
1304 my $link = $seq_argument;
1307 my $ref = "\\emph{$seq_argument}";
1310 } elsif ($seq_command eq 'Q') {
1311 # Special markup for Pod::Hyperlink
1312 return "\\textsf{$seq_argument}";
1314 } elsif ($seq_command eq 'X') {
1317 # use \index command
1318 # I will let '!' go through for now
1319 # not sure how sub categories are handled in X<>
1320 my $index = $self->_create_index($seq_argument);
1321 return "\\index{$index}\n";
1324 carp "Unknown sequence $seq_command<$seq_argument>";
1333 Methods used to handle lists.
1339 Called when a new list is found (via the C<over> directive).
1340 Creates a new C<Pod::List> object and stores it on the
1343 $parser->begin_list($indent, $line_num);
1350 my $line_num = shift;
1352 # Indicate that a list should be started for the next item
1353 # need to do this to work out the type of list
1354 push ( @{$self->lists}, new Pod::List(-indent => $indent,
1355 -start => $line_num,
1356 -file => $self->input_file,
1364 Called when the end of a list is found (the C<back> directive).
1365 Pops the C<Pod::List> object off the stack of lists and writes
1366 the C<latex> code required to close a list.
1368 $parser->end_list($line_num);
1374 my $line_num = shift;
1376 unless (defined $self->lists->[-1]) {
1377 my $file = $self->input_file;
1378 warn "No list is active at line $line_num (file=$file). Missing =over?\n";
1382 # What to write depends on list type
1383 my $type = $self->lists->[-1]->type;
1385 # Dont write anything if the list type is not set
1386 # iomplying that a list was created but no entries were
1387 # placed in it (eg because of a =begin/=end combination)
1388 $self->_output("\\end{$type}\n")
1389 if (defined $type && length($type) > 0);
1392 pop(@{ $self->lists});
1398 Add items to the list. The first time an item is encountered
1399 (determined from the state of the current C<Pod::List> object)
1400 the type of list is determined (ordered, unnumbered or description)
1401 and the relevant latex code issued.
1403 $parser->add_item($paragraph, $line_num);
1409 my $paragraph = shift;
1410 my $line_num = shift;
1412 unless (defined $self->lists->[-1]) {
1413 my $file = $self->input_file;
1414 warn "List has already ended by line $line_num of file $file. Missing =over?\n";
1415 # Replace special chars
1416 # $paragraph = $self->_replace_special_chars($paragraph);
1417 $self->_output("$paragraph\n\n");
1421 # If paragraphs printing is turned off via =begin/=end or whatver
1422 # simply return immediately
1423 return if $self->{_suppress_all_para};
1425 # Check to see whether we are starting a new lists
1426 if (scalar($self->lists->[-1]->item) == 0) {
1428 # Examine the paragraph to determine what type of list
1430 $paragraph =~ s/\s+$//;
1431 $paragraph =~ s/^\s+//;
1434 if (substr($paragraph, 0,1) eq '*') {
1436 } elsif ($paragraph =~ /^\d/) {
1437 $type = 'enumerate';
1439 $type = 'description';
1441 $self->lists->[-1]->type($type);
1443 $self->_output("\\begin{$type}\n");
1447 my $type = $self->lists->[-1]->type;
1449 if ($type eq 'description') {
1450 # Handle long items - long items do not wrap
1451 # If the string is longer than 40 characters we split
1452 # it into a real item header and some bold text.
1454 my ($hunk1, $hunk2) = $self->_split_delimited( $paragraph, $maxlen );
1456 # Print the first hunk
1457 $self->_output("\n\\item[{$hunk1}] ");
1459 # and the second hunk if it is defined
1461 $self->_output("\\textbf{$hunk2}");
1463 # Not there so make sure we have a new line
1464 $self->_output("\\mbox{}");
1468 # If the item was '* Something' or '\d+ something' we still need to write
1469 # out the something. Also allow 1) and 1.
1470 my $extra_info = $paragraph;
1471 $extra_info =~ s/^(\*|\d+[\.\)]?)\s*//;
1472 $self->_output("\n\\item $extra_info");
1475 # Store the item name in the object. Required so that
1476 # we can tell if the list is new or not
1477 $self->lists->[-1]->item($paragraph);
1483 =head2 Methods for headings
1489 Print a heading of the required level.
1491 $parser->head($level, $paragraph, $parobj);
1493 The first argument is the pod heading level. The second argument
1494 is the contents of the heading. The 3rd argument is a Pod::Paragraph
1495 object so that the line number can be extracted.
1502 my $paragraph = shift;
1505 # If we are replace 'head1 NAME' with a section
1506 # we return immediately if we get it
1508 if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection());
1511 my $label = $self->_create_label($paragraph);
1513 # Create an index entry
1514 my $index = $self->_create_index($paragraph);
1516 # Work out position in the above array taking into account
1517 # that =head1 is equivalent to $self->Head1Level
1519 my $level = $self->Head1Level() - 1 + $num;
1521 # Warn if heading to large
1522 if ($num > $#LatexSections) {
1523 my $line = $parobj->file_line;
1524 my $file = $self->input_file;
1525 warn "Heading level too large ($level) for LaTeX at line $line of file $file\n";
1526 $level = $#LatexSections;
1529 # Check to see whether section should be unnumbered
1530 my $star = ($level >= $self->LevelNoNum ? '*' : '');
1533 $self->_output("\\" .$LatexSections[$level] .$star ."{$paragraph\\label{".$label ."}\\index{".$index."}}\n");
1544 =head2 Internal methods
1546 Internal routines are described in this section. They do not form part of the
1547 public interface. All private methods start with an underscore.
1553 Output text to the output filehandle. This method must be always be called
1554 to output parsed text.
1556 $parser->_output($text);
1558 Does not write anything if a =begin is active that should be
1567 print { $self->output_handle } $text
1568 unless $self->{_suppress_all_para};
1573 =item B<_replace_special_chars>
1575 Subroutine to replace characters that are special in C<latex>
1576 with the escaped forms
1578 $escaped = $parser->_replace_special_chars($paragraph);
1580 Need to call this routine before interior_sequences are munged but not
1581 if verbatim. It must be called before interpolation of interior
1582 sequences so that curly brackets and special latex characters inserted
1583 during interpolation are not themselves escaped. This means that < and
1584 > can not be modified here since the text still contains interior
1587 Special characters and the C<latex> equivalents are:
1602 sub _replace_special_chars {
1604 my $paragraph = shift;
1606 # Replace a \ with $\backslash$
1607 # This is made more complicated because the dollars will be escaped
1608 # by the subsequent replacement. Easiest to add \backslash
1609 # now and then add the dollars
1610 $paragraph =~ s/\\/\\backslash/g;
1612 # Must be done after escape of \ since this command adds latex escapes
1613 # Replace characters that can be escaped
1614 $paragraph =~ s/([\$\#&%_{}])/\\$1/g;
1616 # Replace ^ characters with \^{} so that $^F works okay
1617 $paragraph =~ s/(\^)/\\$1\{\}/g;
1619 # Replace tilde (~) with \texttt{\~{}}
1620 $paragraph =~ s/~/\\texttt\{\\~\{\}\}/g;
1622 # Now add the dollars around each \backslash
1623 $paragraph =~ s/(\\backslash)/\$$1\$/g;
1627 =item B<_replace_special_chars_late>
1629 Replace special characters that can not be replaced before interior
1630 sequence interpolation. See C<_replace_special_chars> for a routine
1631 to replace special characters prior to interpolation of interior
1634 Does the following transformation:
1643 sub _replace_special_chars_late {
1645 my $paragraph = shift;
1648 $paragraph =~ s/(<|>)/\$$1\$/g;
1650 # Replace | with $|$
1651 $paragraph =~ s'\|'$|$'g;
1658 =item B<_create_label>
1660 Return a string that can be used as an internal reference
1661 in a C<latex> document (i.e. accepted by the C<\label> command)
1663 $label = $parser->_create_label($string)
1665 If UniqueLabels is true returns a label prefixed by Label()
1666 This can be suppressed with an optional second argument.
1668 $label = $parser->_create_label($string, $suppress);
1670 If a second argument is supplied (of any value including undef)
1671 the Label() is never prefixed. This means that this routine can
1672 be called to create a Label() without prefixing a previous setting.
1678 my $paragraph = shift;
1679 my $suppress = (@_ ? 1 : 0 );
1681 # Remove latex commands
1682 $paragraph = $self->_clean_latex_commands($paragraph);
1684 # Remove non alphanumerics from the label and replace with underscores
1685 # want to protect '-' though so use negated character classes
1686 $paragraph =~ s/[^-:\w]/_/g;
1688 # Multiple underscores will look unsightly so remove repeats
1689 # This will also have the advantage of tidying up the end and
1691 $paragraph =~ s/_+/_/g;
1693 # If required need to make sure that the label is unique
1694 # since it is possible to have multiple pods in a single
1696 if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
1697 $paragraph = $self->Label() .'_'. $paragraph;
1704 =item B<_create_index>
1706 Similar to C<_create_label> except an index entry is created.
1707 If C<UniqueLabels> is true, the index entry is prefixed by
1708 the current C<Label> and an exclamation mark.
1710 $ind = $parser->_create_index($paragraph);
1712 An exclamation mark is used by C<makeindex> to generate
1713 sub-entries in an index.
1719 my $paragraph = shift;
1720 my $suppress = (@_ ? 1 : 0 );
1722 # Remove latex commands
1723 $paragraph = $self->_clean_latex_commands($paragraph);
1725 # If required need to make sure that the index entry is unique
1726 # since it is possible to have multiple pods in a single
1728 if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
1729 $paragraph = $self->Label() .'!'. $paragraph;
1732 # Need to replace _ with space
1733 $paragraph =~ s/_/ /g;
1739 =item B<_clean_latex_commands>
1741 Removes latex commands from text. The latex command is assumed to be of the
1742 form C<\command{ text }>. "C<text>" is retained
1744 $clean = $parser->_clean_latex_commands($text);
1748 sub _clean_latex_commands {
1750 my $paragraph = shift;
1752 # Remove latex commands of the form \text{ }
1753 # and replace with the contents of the { }
1754 # need to make this non-greedy so that it can handle
1755 # "\text{a} and \text2{b}"
1756 # without converting it to
1758 # This match will still get into trouble if \} is present
1759 # This is not vital since the subsequent replacement of non-alphanumeric
1760 # characters will tidy it up anyway
1761 $paragraph =~ s/\\\w+{(.*?)}/$1/g;
1766 =item B<_split_delimited>
1768 Split the supplied string into two parts at approximately the
1769 specified word boundary. Special care is made to make sure that it
1770 does not split in the middle of some curly brackets.
1772 e.g. "this text is \textbf{very bold}" would not be split into
1773 "this text is \textbf{very" and " bold".
1775 ($hunk1, $hunk2) = $self->_split_delimited( $para, $length);
1777 The length indicates the maximum length of hunk1.
1781 # initially Supplied by hsmyers@sdragons.com
1782 # 10/25/01, utility to split \hbox
1783 # busting lines. Reformatted by TimJ to match module style.
1784 sub _split_delimited {
1789 # Return immediately if already small
1790 return ($input, '') if length($input) < $limit;
1798 $input =~ s/\n/ /gm;
1800 foreach ( split ( //, $input ) ) {
1806 } elsif ( / / and $depth == 0) {
1807 push @output, $token if ( $token and $token ne ' ' );
1813 if (length($s) < $limit) {
1832 Compatible with C<latex2e> only. Can not be used with C<latex> v2.09
1835 A subclass of C<Pod::Select> so that specific pod sections can be
1836 converted to C<latex> by using the C<select> method.
1838 Some HTML escapes are missing and many have not been tested.
1842 L<Pod::Parser>, L<Pod::Select>, L<pod2latex>
1846 Tim Jenness E<lt>tjenness@cpan.orgE<gt>
1848 Bug fixes and improvements have been received from: Simon Cozens
1849 E<lt>simon@cozens.netE<gt>, Mark A. Hershberger
1850 E<lt>mah@everybody.orgE<gt>, Marcel Grunauer
1851 E<lt>marcel@codewerk.comE<gt>, Hugh S Myers
1852 E<lt>hsmyers@sdragons.comE<gt>, Peter J Acklam
1853 E<lt>jacklam@math.uio.noE<gt>, Sudhi Herle E<lt>sudhi@herle.netE<gt>,
1854 Ariel Scolnicov E<lt>ariels@compugen.co.ilE<gt>,
1855 Adriano Rodrigues Ferreira E<lt>ferreira@triang.com.brE<gt> and
1856 R. de Vries E<lt>r.de.vries@dutchspace.nlE<gt>.
1861 Copyright (C) 2000-2004 Tim Jenness. All Rights Reserved.
1863 This program is free software; you can redistribute it and/or modify
1864 it under the same terms as Perl itself.
1870 $Id: LaTeX.pm,v 1.19 2004/12/30 01:40:44 timj Exp $