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 automaatically.
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.
866 # Get the pod identification
867 # This should really come from the '=head1 NAME' paragraph
869 my $infile = $self->input_file;
870 my $class = ref($self);
871 my $date = gmtime(time);
873 # Comment message to say where this came from
874 my $comment = << "__TEX_COMMENT__";
875 %% Latex generated from POD in document $infile
876 %% Using the perl module $class
877 %% Converted on $date
881 # If the caller has supplied one then we just use that
884 if (defined $self->UserPreamble) {
886 $preamble = $self->UserPreamble;
888 # Add the description of where this came from
889 $preamble .= "\n$comment";
892 } elsif ($self->AddPreamble) {
893 # Write our own preamble
895 # Code to initialise index making
896 # Use an array so that we can prepend comment if required
898 '\usepackage{makeidx}',
902 unless ($self->MakeIndex) {
907 my $makeindex = join("\n",@makeidx) . "\n";
911 my $tableofcontents = '\tableofcontents';
913 $tableofcontents = '%% ' . $tableofcontents
914 unless $self->TableOfContents;
917 $preamble = << "__TEX_HEADER__";
918 \\documentclass{article}
919 \\usepackage[T1]{fontenc}
920 \\usepackage{textcomp}
934 # Write the header (blank if none)
935 $self->_output($preamble);
937 # Start on new page if requested
938 $self->_output("\\clearpage\n") if $self->StartWithNewPage;
945 Write the closing C<latex> code.
955 # Use the user version of the postamble if deinfed
956 if (defined $self->UserPostamble) {
957 $end = $self->UserPostamble;
959 $self->_output($end);
961 } elsif ($self->AddPostamble) {
964 my $makeindex = '\printindex';
966 $makeindex = '%% '. $makeindex unless $self->MakeIndex;
968 $end = "$makeindex\n\n\\end{document}\n";
972 $self->_output($end);
978 Process basic pod commands.
984 my ($command, $paragraph, $line_num, $parobj) = @_;
986 # return if we dont care
987 return if $command eq 'pod';
989 # Store a copy of the raw text in case we are in a =for
990 # block and need to preserve the existing latex
991 my $rawpara = $paragraph;
993 # Do the latex escapes
994 $paragraph = $self->_replace_special_chars($paragraph);
996 # Interpolate pod sequences in paragraph
997 $paragraph = $self->interpolate($paragraph, $line_num);
998 $paragraph =~ s/\s+$//;
1000 # Replace characters that can only be done after
1001 # interpolation of interior sequences
1002 $paragraph = $self->_replace_special_chars_late($paragraph);
1004 # Now run the command
1005 if ($command eq 'over') {
1007 $self->begin_list($paragraph, $line_num);
1009 } elsif ($command eq 'item') {
1011 $self->add_item($paragraph, $line_num);
1013 } elsif ($command eq 'back') {
1015 $self->end_list($line_num);
1017 } elsif ($command eq 'head1') {
1019 # Store the name of the section
1020 $self->{_CURRENT_HEAD1} = $paragraph;
1023 $self->head(1, $paragraph, $parobj);
1025 } elsif ($command eq 'head2') {
1027 $self->head(2, $paragraph, $parobj);
1029 } elsif ($command eq 'head3') {
1031 $self->head(3, $paragraph, $parobj);
1033 } elsif ($command eq 'head4') {
1035 $self->head(4, $paragraph, $parobj);
1037 } elsif ($command eq 'head5') {
1039 $self->head(5, $paragraph, $parobj);
1041 } elsif ($command eq 'head6') {
1043 $self->head(6, $paragraph, $parobj);
1045 } elsif ($command eq 'begin') {
1047 # pass through if latex
1048 if ($paragraph =~ /^latex/i) {
1049 # Make sure that subsequent paragraphs are not modfied before printing
1050 $self->{_dont_modify_any_para} = 1;
1053 # Suppress all subsequent paragraphs unless
1054 # it is explcitly intended for latex
1055 $self->{_suppress_all_para} = 1;
1058 } elsif ($command eq 'for') {
1063 # With =for we will get the text for the full paragraph
1064 # as well as the format name.
1065 # We do not get an additional paragraph later on. The next
1066 # paragraph is not governed by the =for
1068 # The first line contains the format and the rest is the
1070 my ($format, $chunk) = split(/\n/, $rawpara, 2);
1072 # If we have got some latex code print it out immediately
1073 # unmodified. Else do nothing.
1074 if ($format =~ /^latex/i) {
1075 # Make sure that next paragraph is not modfied before printing
1076 $self->_output( $chunk );
1080 } elsif ($command eq 'end') {
1083 $self->{_suppress_all_para} = 0;
1084 $self->{_dont_modify_any_para} = 0;
1086 } elsif ($command eq 'pod') {
1091 carp "Command $command not recognised at line $line_num\n";
1104 my ($paragraph, $line_num, $parobj) = @_;
1106 # Expand paragraph unless in =begin block
1107 if ($self->{_dont_modify_any_para}) {
1109 $self->_output($paragraph);
1113 return if $paragraph =~ /^\s+$/;
1115 # Clean trailing space
1116 $paragraph =~ s/\s+$//;
1118 # Clean tabs. Routine taken from Tabs.pm
1119 # by David Muir Sharnoff muir@idiom.com,
1120 # slightly modified by hsmyers@sdragons.com 10/22/01
1121 my @l = split("\n",$paragraph);
1123 1 while s/(^|\n)([^\t\n]*)(\t+)/
1126 - (length($2) % 8)))
1129 $paragraph = join("\n",@l);
1134 $self->_output('\begin{verbatim}' . "\n$paragraph\n". '\end{verbatim}'."\n");
1140 Plain text paragraph.
1146 my ($paragraph, $line_num, $parobj) = @_;
1148 # print Dumper($self);
1150 # Expand paragraph unless in =begin block
1151 if ($self->{_dont_modify_any_para}) {
1153 $self->_output($paragraph);
1159 # Escape latex special characters
1160 $paragraph = $self->_replace_special_chars($paragraph);
1162 # Interpolate interior sequences
1163 my $expansion = $self->interpolate($paragraph, $line_num);
1164 $expansion =~ s/\s+$//;
1166 # Escape special characters that can not be done earlier
1167 $expansion = $self->_replace_special_chars_late($expansion);
1169 # If we are replacing 'head1 NAME' with a section
1170 # we need to look in the paragraph and rewrite things
1171 # Need to make sure this is called only on the first paragraph
1172 # following 'head1 NAME' and not on subsequent paragraphs that may be
1174 if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()) {
1176 # Strip white space from start and end
1177 $paragraph =~ s/^\s+//;
1178 $paragraph =~ s/\s$//;
1180 # Split the string into 2 parts
1181 my ($name, $purpose) = split(/\s+-\s+/, $expansion,2);
1183 # Now prevent this from triggering until a new head1 NAME is set
1184 $self->{_CURRENT_HEAD1} = '_NAME';
1186 # Might want to clear the Label() before doing this (CHECK)
1189 $self->head(1, $name, $parobj);
1191 # Set the labeling in case we want unique names later
1192 $self->Label( $self->_create_label( $name, 1 ) );
1194 # Raise the Head1Level by one so that subsequent =head1 appear
1195 # as subsections of the main name section unless we are already
1196 # at maximum [Head1Level() could check this itself - CHECK]
1197 $self->Head1Level( $self->Head1Level() + 1)
1198 unless $self->Head1Level == $#LatexSections;
1200 # Now write out the new latex paragraph
1201 $purpose = ucfirst($purpose);
1202 $self->_output("\n\n$purpose\n\n");
1205 # Just write the output
1206 $self->_output("\n\n$expansion\n\n");
1211 =item B<interior_sequence>
1213 Interior sequence expansion
1217 sub interior_sequence {
1220 my ($seq_command, $seq_argument, $pod_seq) = @_;
1222 if ($seq_command eq 'B') {
1223 return "\\textbf{$seq_argument}";
1225 } elsif ($seq_command eq 'I') {
1226 return "\\textit{$seq_argument}";
1228 } elsif ($seq_command eq 'E') {
1230 # If it is simply a number
1231 if ($seq_argument =~ /^\d+$/) {
1232 return chr($seq_argument);
1233 # Look up escape in hash table
1234 } elsif (exists $HTML_Escapes{$seq_argument}) {
1235 return $HTML_Escapes{$seq_argument};
1238 my ($file, $line) = $pod_seq->file_line();
1239 warn "Escape sequence $seq_argument not recognised at line $line of file $file\n";
1243 } elsif ($seq_command eq 'Z') {
1248 } elsif ($seq_command eq 'C') {
1249 return "\\texttt{$seq_argument}";
1251 } elsif ($seq_command eq 'F') {
1252 return "\\emph{$seq_argument}";
1254 } elsif ($seq_command eq 'S') {
1255 # non breakable spaces
1258 $seq_argument =~ s/\s/$nbsp/g;
1259 return $seq_argument;
1261 } elsif ($seq_command eq 'L') {
1262 my $link = new Pod::Hyperlink($seq_argument);
1265 unless (defined $link) {
1270 # Handle internal links differently
1271 my $type = $link->type;
1272 my $page = $link->page;
1274 if ($type eq 'section' && $page eq '') {
1275 # Use internal latex reference
1276 my $node = $link->node;
1278 # Convert to a label
1279 $node = $self->_create_label($node);
1281 return "\\S\\ref{$node}";
1284 # Use default markup for external references
1285 # (although Starlink would use \xlabel)
1286 my $markup = $link->markup;
1287 my ($file, $line) = $pod_seq->file_line();
1289 return $self->interpolate($link->markup, $line);
1294 } elsif ($seq_command eq 'P') {
1295 # Special markup for Pod::Hyperlink
1296 # Replace :: with / - but not sure if I want to do this
1298 my $link = $seq_argument;
1301 my $ref = "\\emph{$seq_argument}";
1304 } elsif ($seq_command eq 'Q') {
1305 # Special markup for Pod::Hyperlink
1306 return "\\textsf{$seq_argument}";
1308 } elsif ($seq_command eq 'X') {
1311 # use \index command
1312 # I will let '!' go through for now
1313 # not sure how sub categories are handled in X<>
1314 my $index = $self->_create_index($seq_argument);
1315 return "\\index{$index}\n";
1318 carp "Unknown sequence $seq_command<$seq_argument>";
1327 Methods used to handle lists.
1333 Called when a new list is found (via the C<over> directive).
1334 Creates a new C<Pod::List> object and stores it on the
1337 $parser->begin_list($indent, $line_num);
1344 my $line_num = shift;
1346 # Indicate that a list should be started for the next item
1347 # need to do this to work out the type of list
1348 push ( @{$self->lists}, new Pod::List(-indent => $indent,
1349 -start => $line_num,
1350 -file => $self->input_file,
1358 Called when the end of a list is found (the C<back> directive).
1359 Pops the C<Pod::List> object off the stack of lists and writes
1360 the C<latex> code required to close a list.
1362 $parser->end_list($line_num);
1368 my $line_num = shift;
1370 unless (defined $self->lists->[-1]) {
1371 my $file = $self->input_file;
1372 warn "No list is active at line $line_num (file=$file). Missing =over?\n";
1376 # What to write depends on list type
1377 my $type = $self->lists->[-1]->type;
1379 # Dont write anything if the list type is not set
1380 # iomplying that a list was created but no entries were
1381 # placed in it (eg because of a =begin/=end combination)
1382 $self->_output("\\end{$type}\n")
1383 if (defined $type && length($type) > 0);
1386 pop(@{ $self->lists});
1392 Add items to the list. The first time an item is encountered
1393 (determined from the state of the current C<Pod::List> object)
1394 the type of list is determined (ordered, unnumbered or description)
1395 and the relevant latex code issued.
1397 $parser->add_item($paragraph, $line_num);
1403 my $paragraph = shift;
1404 my $line_num = shift;
1406 unless (defined $self->lists->[-1]) {
1407 my $file = $self->input_file;
1408 warn "List has already ended by line $line_num of file $file. Missing =over?\n";
1409 # Replace special chars
1410 # $paragraph = $self->_replace_special_chars($paragraph);
1411 $self->_output("$paragraph\n\n");
1415 # If paragraphs printing is turned off via =begin/=end or whatver
1416 # simply return immediately
1417 return if $self->{_suppress_all_para};
1419 # Check to see whether we are starting a new lists
1420 if (scalar($self->lists->[-1]->item) == 0) {
1422 # Examine the paragraph to determine what type of list
1424 $paragraph =~ s/\s+$//;
1425 $paragraph =~ s/^\s+//;
1428 if (substr($paragraph, 0,1) eq '*') {
1430 } elsif ($paragraph =~ /^\d/) {
1431 $type = 'enumerate';
1433 $type = 'description';
1435 $self->lists->[-1]->type($type);
1437 $self->_output("\\begin{$type}\n");
1441 my $type = $self->lists->[-1]->type;
1443 if ($type eq 'description') {
1444 # Handle long items - long items do not wrap
1445 # If the string is longer than 40 characters we split
1446 # it into a real item header and some bold text.
1448 my ($hunk1, $hunk2) = $self->_split_delimited( $paragraph, $maxlen );
1450 # Print the first hunk
1451 $self->_output("\n\\item[$hunk1] ");
1453 # and the second hunk if it is defined
1455 $self->_output("\\textbf{$hunk2}");
1457 # Not there so make sure we have a new line
1458 $self->_output("\\mbox{}");
1462 # If the item was '* Something' or '\d+ something' we still need to write
1463 # out the something. Also allow 1) and 1.
1464 my $extra_info = $paragraph;
1465 $extra_info =~ s/^(\*|\d+[\.\)]?)\s*//;
1466 $self->_output("\n\\item $extra_info");
1469 # Store the item name in the object. Required so that
1470 # we can tell if the list is new or not
1471 $self->lists->[-1]->item($paragraph);
1477 =head2 Methods for headings
1483 Print a heading of the required level.
1485 $parser->head($level, $paragraph, $parobj);
1487 The first argument is the pod heading level. The second argument
1488 is the contents of the heading. The 3rd argument is a Pod::Paragraph
1489 object so that the line number can be extracted.
1496 my $paragraph = shift;
1499 # If we are replace 'head1 NAME' with a section
1500 # we return immediately if we get it
1502 if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection());
1505 my $label = $self->_create_label($paragraph);
1507 # Create an index entry
1508 my $index = $self->_create_index($paragraph);
1510 # Work out position in the above array taking into account
1511 # that =head1 is equivalent to $self->Head1Level
1513 my $level = $self->Head1Level() - 1 + $num;
1515 # Warn if heading to large
1516 if ($num > $#LatexSections) {
1517 my $line = $parobj->file_line;
1518 my $file = $self->input_file;
1519 warn "Heading level too large ($level) for LaTeX at line $line of file $file\n";
1520 $level = $#LatexSections;
1523 # Check to see whether section should be unnumbered
1524 my $star = ($level >= $self->LevelNoNum ? '*' : '');
1527 $self->_output("\\" .$LatexSections[$level] .$star ."{$paragraph\\label{".$label ."}\\index{".$index."}}\n");
1538 =head2 Internal methods
1540 Internal routines are described in this section. They do not form part of the
1541 public interface. All private methods start with an underscore.
1547 Output text to the output filehandle. This method must be always be called
1548 to output parsed text.
1550 $parser->_output($text);
1552 Does not write anything if a =begin is active that should be
1561 print { $self->output_handle } $text
1562 unless $self->{_suppress_all_para};
1567 =item B<_replace_special_chars>
1569 Subroutine to replace characters that are special in C<latex>
1570 with the escaped forms
1572 $escaped = $parser->_replace_special_chars($paragraph);
1574 Need to call this routine before interior_sequences are munged but not
1575 if verbatim. It must be called before interpolation of interior
1576 sequences so that curly brackets and special latex characters inserted
1577 during interpolation are not themselves escaped. This means that < and
1578 > can not be modified here since the text still contains interior
1581 Special characters and the C<latex> equivalents are:
1596 sub _replace_special_chars {
1598 my $paragraph = shift;
1600 # Replace a \ with $\backslash$
1601 # This is made more complicated because the dollars will be escaped
1602 # by the subsequent replacement. Easiest to add \backslash
1603 # now and then add the dollars
1604 $paragraph =~ s/\\/\\backslash/g;
1606 # Must be done after escape of \ since this command adds latex escapes
1607 # Replace characters that can be escaped
1608 $paragraph =~ s/([\$\#&%_{}])/\\$1/g;
1610 # Replace ^ characters with \^{} so that $^F works okay
1611 $paragraph =~ s/(\^)/\\$1\{\}/g;
1613 # Replace tilde (~) with \texttt{\~{}}
1614 $paragraph =~ s/~/\\texttt\{\\~\{\}\}/g;
1616 # Now add the dollars around each \backslash
1617 $paragraph =~ s/(\\backslash)/\$$1\$/g;
1621 =item B<_replace_special_chars_late>
1623 Replace special characters that can not be replaced before interior
1624 sequence interpolation. See C<_replace_special_chars> for a routine
1625 to replace special characters prior to interpolation of interior
1628 Does the following transformation:
1637 sub _replace_special_chars_late {
1639 my $paragraph = shift;
1642 $paragraph =~ s/(<|>)/\$$1\$/g;
1644 # Replace | with $|$
1645 $paragraph =~ s'\|'$|$'g;
1652 =item B<_create_label>
1654 Return a string that can be used as an internal reference
1655 in a C<latex> document (i.e. accepted by the C<\label> command)
1657 $label = $parser->_create_label($string)
1659 If UniqueLabels is true returns a label prefixed by Label()
1660 This can be suppressed with an optional second argument.
1662 $label = $parser->_create_label($string, $suppress);
1664 If a second argument is supplied (of any value including undef)
1665 the Label() is never prefixed. This means that this routine can
1666 be called to create a Label() without prefixing a previous setting.
1672 my $paragraph = shift;
1673 my $suppress = (@_ ? 1 : 0 );
1675 # Remove latex commands
1676 $paragraph = $self->_clean_latex_commands($paragraph);
1678 # Remove non alphanumerics from the label and replace with underscores
1679 # want to protect '-' though so use negated character classes
1680 $paragraph =~ s/[^-:\w]/_/g;
1682 # Multiple underscores will look unsightly so remove repeats
1683 # This will also have the advantage of tidying up the end and
1685 $paragraph =~ s/_+/_/g;
1687 # If required need to make sure that the label is unique
1688 # since it is possible to have multiple pods in a single
1690 if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
1691 $paragraph = $self->Label() .'_'. $paragraph;
1698 =item B<_create_index>
1700 Similar to C<_create_label> except an index entry is created.
1701 If C<UniqueLabels> is true, the index entry is prefixed by
1702 the current C<Label> and an exclamation mark.
1704 $ind = $parser->_create_index($paragraph);
1706 An exclamation mark is used by C<makeindex> to generate
1707 sub-entries in an index.
1713 my $paragraph = shift;
1714 my $suppress = (@_ ? 1 : 0 );
1716 # Remove latex commands
1717 $paragraph = $self->_clean_latex_commands($paragraph);
1719 # If required need to make sure that the index entry is unique
1720 # since it is possible to have multiple pods in a single
1722 if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
1723 $paragraph = $self->Label() .'!'. $paragraph;
1726 # Need to replace _ with space
1727 $paragraph =~ s/_/ /g;
1733 =item B<_clean_latex_commands>
1735 Removes latex commands from text. The latex command is assumed to be of the
1736 form C<\command{ text }>. "C<text>" is retained
1738 $clean = $parser->_clean_latex_commands($text);
1742 sub _clean_latex_commands {
1744 my $paragraph = shift;
1746 # Remove latex commands of the form \text{ }
1747 # and replace with the contents of the { }
1748 # need to make this non-greedy so that it can handle
1749 # "\text{a} and \text2{b}"
1750 # without converting it to
1752 # This match will still get into trouble if \} is present
1753 # This is not vital since the subsequent replacement of non-alphanumeric
1754 # characters will tidy it up anyway
1755 $paragraph =~ s/\\\w+{(.*?)}/$1/g;
1760 =item B<_split_delimited>
1762 Split the supplied string into two parts at approximately the
1763 specified word boundary. Special care is made to make sure that it
1764 does not split in the middle of some curly brackets.
1766 e.g. "this text is \textbf{very bold}" would not be split into
1767 "this text is \textbf{very" and " bold".
1769 ($hunk1, $hunk2) = $self->_split_delimited( $para, $length);
1771 The length indicates the maximum length of hunk1.
1775 # initially Supplied by hsmyers@sdragons.com
1776 # 10/25/01, utility to split \hbox
1777 # busting lines. Reformatted by TimJ to match module style.
1778 sub _split_delimited {
1783 # Return immediately if already small
1784 return ($input, '') if length($input) < $limit;
1792 $input =~ s/\n/ /gm;
1794 foreach ( split ( //, $input ) ) {
1800 } elsif ( / / and $depth == 0) {
1801 push @output, $token if ( $token and $token ne ' ' );
1807 if (length($s) < $limit) {
1826 Compatible with C<latex2e> only. Can not be used with C<latex> v2.09
1829 A subclass of C<Pod::Select> so that specific pod sections can be
1830 converted to C<latex> by using the C<select> method.
1832 Some HTML escapes are missing and many have not been tested.
1836 L<Pod::Parser>, L<Pod::Select>, L<pod2latex>
1840 Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt>
1842 Bug fixes and improvements have been received from: Simon Cozens
1843 E<lt>simon@cozens.netE<gt>, Mark A. Hershberger
1844 E<lt>mah@everybody.orgE<gt>, Marcel Grunauer
1845 E<lt>marcel@codewerk.comE<gt>, Hugh S Myers
1846 E<lt>hsmyers@sdragons.comE<gt>, Peter J Acklam
1847 E<lt>jacklam@math.uio.noE<gt>, Sudhi Herle E<lt>sudhi@herle.netE<gt>
1848 and Ariel Scolnicov E<lt>ariels@compugen.co.ilE<gt>.
1853 Copyright (C) 2000-2003 Tim Jenness. All Rights Reserved.
1855 This program is free software; you can redistribute it and/or modify
1856 it under the same terms as Perl itself.
1862 $Id: LaTeX.pm,v 1.17 2003/04/05 21:25:49 timj Exp $