This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to Pod::LaTeX 0.58
[perl5.git] / lib / Pod / LaTeX.pm
1 package Pod::LaTeX;
2
3 =head1 NAME
4
5 Pod::LaTeX - Convert Pod data to formatted Latex
6
7 =head1 SYNOPSIS
8
9   use Pod::LaTeX;
10   my $parser = Pod::LaTeX->new ( );
11
12   $parser->parse_from_filehandle;
13
14   $parser->parse_from_file ('file.pod', 'file.tex');
15
16 =head1 DESCRIPTION
17
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.
21
22 C<Pod::LaTeX> is a derived class from L<Pod::Select|Pod::Select>.
23
24 =cut
25
26
27 use strict;
28 require Pod::ParseUtils;
29 use base qw/ Pod::Select /;
30
31 # use Data::Dumper; # for debugging
32 use Carp;
33
34 use vars qw/ $VERSION %HTML_Escapes @LatexSections /;
35
36 $VERSION = '0.58';
37
38 # Definitions of =headN -> latex mapping
39 @LatexSections = (qw/
40                   chapter
41                   section
42                   subsection
43                   subsubsection
44                   paragraph
45                   subparagraph
46                   /);
47
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.
51
52 %HTML_Escapes = (
53      'sol'    => '\textfractionsolidus{}',  # xxx - or should it be just '/'
54      'verbar' => '|',
55
56      # The stuff below is based on the information available at
57      # http://www.w3.org/TR/html401/sgml/entities.html
58
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
157
158      # Latin Extended-B
159      'fnof'   => q|\textflorin{}|,   # latin small f with hook = function = florin
160
161      # Greek
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
186
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
215
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
224
225      # Letterlike Symbols
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
233
234      # Arrows
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
252
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
301
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'
313
314      # Geometric Shapes
315      'loz'      => q|$\lozenge$|,                # lozenge
316
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
322
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
356 );
357
358 =head1 OBJECT METHODS
359
360 The following methods are provided in this module. Methods inherited
361 from C<Pod::Select> are not described in the public interface.
362
363 =over 4
364
365 =begin __PRIVATE__
366
367 =item C<initialize>
368
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
372 the constructor. 
373
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.
377
378 This method should not be invoked by the user directly.
379
380 =end __PRIVATE__
381
382 =cut
383
384
385
386 #   - An array for nested lists
387
388 # Arguments have already been read by this point
389
390 sub initialize {
391   my $self = shift;
392
393   # print Dumper($self);
394
395   # Internals
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
400
401   # Options - only initialise if not already set
402
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)
422
423   $self->{UniqueLabels}     = 1          # Use label unique for each pod
424     unless exists $self->{UniqueLabels}; # either based on the filename
425                                          # or supplied
426
427   # Control the level of =head1. default is \section
428   # 
429   $self->{Head1Level}     = 1   # Offset in latex sections
430     unless exists $self->{Head1Level}; # 0 is chapter, 2 is subsection
431
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};
439
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
445
446   $self->{Label}            = undef # label to be used as prefix
447     unless exists $self->{Label};   # to all internal section names
448
449   # These allow the caller to add arbritrary latex code to
450   # start and end of document. AddPreamble and AddPostamble are ignored
451   # if these are set.
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};
457
458   # Run base initialize
459   $self->SUPER::initialize;
460
461 }
462
463 =back
464
465 =head2 Data Accessors
466
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.
470
471 Default values can be supplied by using these names as keys to a hash
472 of arguments when using the C<new()> constructor.
473
474 =over 4
475
476 =item B<AddPreamble>
477
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.
480 This is similar to:
481
482   \documentclass{article}
483   \usepackage[T1]{fontenc}
484   \usepackage{textcomp}
485   \begin{document}
486
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.
489
490   $add = $parser->AddPreamble();
491   $parser->AddPreamble(1);
492
493 If used in conjunction with C<AddPostamble> a full latex document will
494 be written that could be immediately processed by C<latex>.
495
496 For some pod escapes it may be necessary to include the amsmath
497 package. This is not yet added to the preamble automaatically.
498
499 =cut
500
501 sub AddPreamble {
502    my $self = shift;
503    if (@_) {
504      $self->{AddPreamble} = shift;
505    }
506    return $self->{AddPreamble};
507 }
508
509 =item B<AddPostamble>
510
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:
514
515   \end{document}
516
517 but can be more complicated if a index is required.
518 Can be used to set or retrieve the current value.
519
520   $add = $parser->AddPostamble();
521   $parser->AddPostamble(1);
522
523 If used in conjunction with C<AddPreaamble> a full latex document will
524 be written that could be immediately processed by C<latex>.
525
526 =cut
527
528 sub AddPostamble {
529    my $self = shift;
530    if (@_) {
531      $self->{AddPostamble} = shift;
532    }
533    return $self->{AddPostamble};
534 }
535
536 =item B<Head1Level>
537
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
542 following elements:
543
544  [0] chapter
545  [1] section
546  [2] subsection
547  [3] subsubsection
548  [4] paragraph
549  [5] subparagraph
550
551 Can be used to set or retrieve the current value:
552
553   $parser->Head1Level(2);
554   $sect = $parser->Head1Level;
555
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
559 a C<paragraph>).
560
561 A check is made to ensure that the supplied value is an integer in the
562 range 0 to 5.
563
564 Default is for a value of 1 (i.e. a C<section>).
565
566 =cut
567
568 sub Head1Level {
569    my $self = shift;
570    if (@_) {
571      my $arg = shift;
572      if ($arg =~ /^\d$/ && $arg <= $#LatexSections) {
573        $self->{Head1Level} = $arg;
574      } else {
575        carp "Head1Level supplied ($arg) must be integer in range 0 to ".$#LatexSections . "- Ignoring\n";
576      }
577    }
578    return $self->{Head1Level};
579 }
580
581 =item B<Label>
582
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}>.
591
592 Can be used to set or retrieve the current value:
593
594   $label = $parser->Label;
595   $parser->Label($label);
596
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.
601
602 Default value is C<undef>.
603
604 =cut
605
606 sub Label {
607    my $self = shift;
608    if (@_) {
609      $self->{Label} = shift;
610    }
611    return $self->{Label};
612 }
613
614 =item B<LevelNoNum>
615
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.
619
620 Can be used to set or retrieve the current value:
621
622   $lev = $parser->LevelNoNum;
623   $parser->LevelNoNum(2);
624
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.
628
629 Default is 2. (i.e. C<latex> subsections are written as C<subsection*>
630 but sections are numbered).
631
632 =cut
633
634 sub LevelNoNum {
635    my $self = shift;
636    if (@_) {
637      $self->{LevelNoNum} = shift;
638    }
639    return $self->{LevelNoNum};
640 }
641
642 =item B<MakeIndex>
643
644 Controls whether C<latex> commands for creating an index are to be inserted
645 into the preamble and postamble
646
647   $makeindex = $parser->MakeIndex;
648   $parser->MakeIndex(0);
649
650 Irrelevant if both C<AddPreamble> and C<AddPostamble> are false (or equivalently,
651 C<UserPreamble> and C<UserPostamble> are set).
652
653 Default is for an index to be created.
654
655 =cut
656
657 sub MakeIndex {
658    my $self = shift;
659    if (@_) {
660      $self->{MakeIndex} = shift;
661    }
662    return $self->{MakeIndex};
663 }
664
665 =item B<ReplaceNAMEwithSection>
666
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".
670
671 If true, the pod segment
672
673   =head1 NAME
674
675   pod::name - purpose
676
677   =head1 SYNOPSIS
678
679 is converted to the C<latex>
680
681   \section{pod::name\label{pod_name}\index{pod::name}}
682
683   Purpose
684
685   \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
686                \index{pod::name!SYNOPSIS}}
687
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>).
692
693 The C<Label> is set from the pod name regardless of any current value
694 of C<Label>.
695
696   $mod = $parser->ReplaceNAMEwithSection;
697   $parser->ReplaceNAMEwithSection(0);
698
699 Default is to translate the pod literally.
700
701 =cut
702
703 sub ReplaceNAMEwithSection {
704    my $self = shift;
705    if (@_) {
706      $self->{ReplaceNAMEwithSection} = shift;
707    }
708    return $self->{ReplaceNAMEwithSection};
709 }
710
711 =item B<StartWithNewPage>
712
713 If true, each pod translation will begin with a C<latex>
714 C<\clearpage>.
715
716   $parser->StartWithNewPage(1);
717   $newpage = $parser->StartWithNewPage;
718
719 Default is false.
720
721 =cut
722
723 sub StartWithNewPage {
724    my $self = shift;
725    if (@_) {
726      $self->{StartWithNewPage} = shift;
727    }
728    return $self->{StartWithNewPage};
729 }
730
731 =item B<TableOfContents>
732
733 If true, a table of contents will be created.
734 Irrelevant if C<AddPreamble> is false or C<UserPreamble>
735 is set.
736
737   $toc = $parser->TableOfContents;
738   $parser->TableOfContents(1);
739
740 Default is false.
741
742 =cut
743
744 sub TableOfContents {
745    my $self = shift;
746    if (@_) {
747      $self->{TableOfContents} = shift;
748    }
749    return $self->{TableOfContents};
750 }
751
752 =item B<UniqueLabels>
753
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>
759
760   $parser->UniqueLabels(1);
761   $unq = $parser->UniqueLabels;
762
763 Default is true.
764
765 =cut
766
767 sub UniqueLabels {
768    my $self = shift;
769    if (@_) {
770      $self->{UniqueLabels} = shift;
771    }
772    return $self->{UniqueLabels};
773 }
774
775 =item B<UserPreamble>
776
777 User supplied C<latex> preamble. Added before the pod translation
778 data. 
779
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.
783
784 =cut
785
786 sub UserPreamble {
787    my $self = shift;
788    if (@_) {
789      $self->{UserPreamble} = shift;
790    }
791    return $self->{UserPreamble};
792 }
793
794 =item B<UserPostamble>
795
796 User supplied C<latex> postamble. Added after the pod translation
797 data. 
798
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.
802
803 =cut
804
805 sub UserPostamble {
806    my $self = shift;
807    if (@_) {
808      $self->{UserPostamble} = shift;
809    }
810    return $self->{UserPostamble};
811 }
812
813 =begin __PRIVATE__
814
815 =item B<Lists>
816
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
822 lists are active.
823
824 Returns array of list information in list context
825 Returns array ref in scalar context
826
827 =cut
828
829
830
831 sub lists {
832   my $self = shift;
833   return @{ $self->{_Lists} } if wantarray();
834   return $self->{_Lists};
835 }
836
837 =end __PRIVATE__
838
839 =back
840
841 =begin __PRIVATE__
842
843 =head2 Subclassed methods
844
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.
848
849 =over 4
850
851 =cut
852
853 ######### END ACCESSORS ###################
854
855 # Opening pod
856
857 =item B<begin_pod>
858
859 Writes the C<latex> preamble if requested. Only writes something
860 if AddPreamble is true. Writes a standard header unless a UserPreamble
861 is defined.
862
863 =cut
864
865 sub begin_pod {
866   my $self = shift;
867
868   # Get the pod identification
869   # This should really come from the '=head1 NAME' paragraph
870
871   my $infile = $self->input_file;
872   my $class = ref($self);
873   my $date = gmtime(time);
874
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
880 __TEX_COMMENT__
881
882   # Write the preamble
883   # If the caller has supplied one then we just use that
884
885   my $preamble = '';
886
887   if ($self->AddPreamble) {
888
889     if (defined $self->UserPreamble) {
890
891       $preamble = $self->UserPreamble;
892
893       # Add the description of where this came from
894       $preamble .=  "\n$comment\n%%  Preamble supplied by user.\n\n";
895
896     } else {
897
898       # Write our own preamble
899
900       # Code to initialise index making
901       # Use an array so that we can prepend comment if required
902       my @makeidx = (
903                      '\usepackage{makeidx}',
904                      '\makeindex',
905                     );
906
907       unless ($self->MakeIndex) {
908         foreach (@makeidx) {
909           $_ = '%% ' . $_;
910         }
911       }
912       my $makeindex = join("\n",@makeidx) . "\n";
913
914       # Table of contents
915       my $tableofcontents = '\tableofcontents';
916
917       $tableofcontents = '%% ' . $tableofcontents
918         unless $self->TableOfContents;
919
920       # Roll our own
921       $preamble = << "__TEX_HEADER__";
922 \\documentclass{article}
923 \\usepackage[T1]{fontenc}
924 \\usepackage{textcomp}
925
926 $comment
927
928 $makeindex
929
930 \\begin{document}
931
932 $tableofcontents
933
934 __TEX_HEADER__
935
936     }
937   }
938
939   # Write the header (blank if none)
940   $self->_output($preamble);
941
942   # Start on new page if requested
943   $self->_output("\\clearpage\n") if $self->StartWithNewPage;
944
945 }
946
947
948 =item B<end_pod>
949
950 Write the closing C<latex> code. Only writes something if AddPostamble
951 is true. Writes a standard header unless a UserPostamble is defined.
952
953 =cut
954
955 sub end_pod {
956   my $self = shift;
957
958   # End string
959   my $end = '';
960
961   # Use the user version of the postamble if defined
962   if ($self->AddPostamble) {
963
964     if (defined $self->UserPostamble) {
965       $end = $self->UserPostamble;
966
967     } else {
968
969       # Check for index
970       my $makeindex = '\printindex';
971
972       $makeindex = '%% '. $makeindex  unless $self->MakeIndex;
973
974       $end = "$makeindex\n\n\\end{document}\n";
975     }
976   }
977
978   $self->_output($end);
979
980 }
981
982 =item B<command>
983
984 Process basic pod commands.
985
986 =cut
987
988 sub command {
989   my $self = shift;
990   my ($command, $paragraph, $line_num, $parobj) = @_;
991
992   # return if we dont care
993   return if $command eq 'pod';
994
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;
998
999   # Do the latex escapes
1000   $paragraph = $self->_replace_special_chars($paragraph);
1001
1002   # Interpolate pod sequences in paragraph
1003   $paragraph = $self->interpolate($paragraph, $line_num);
1004   $paragraph =~ s/\s+$//;
1005
1006   # Replace characters that can only be done after 
1007   # interpolation of interior sequences
1008   $paragraph = $self->_replace_special_chars_late($paragraph);
1009
1010   # Now run the command
1011   if ($command eq 'over') {
1012
1013     $self->begin_list($paragraph, $line_num);
1014
1015   } elsif ($command eq 'item') {
1016
1017     $self->add_item($paragraph, $line_num);
1018
1019   } elsif ($command eq 'back') {
1020
1021     $self->end_list($line_num);
1022
1023   } elsif ($command eq 'head1') {
1024
1025     # Store the name of the section
1026     $self->{_CURRENT_HEAD1} = $paragraph;
1027
1028     # Print it
1029     $self->head(1, $paragraph, $parobj);
1030
1031   } elsif ($command eq 'head2') {
1032
1033     $self->head(2, $paragraph, $parobj);
1034
1035   } elsif ($command eq 'head3') {
1036
1037     $self->head(3, $paragraph, $parobj);
1038
1039   } elsif ($command eq 'head4') {
1040
1041     $self->head(4, $paragraph, $parobj);
1042
1043   } elsif ($command eq 'head5') {
1044
1045     $self->head(5, $paragraph, $parobj);
1046
1047   } elsif ($command eq 'head6') {
1048
1049     $self->head(6, $paragraph, $parobj);
1050
1051   } elsif ($command eq 'begin') {
1052
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;
1057
1058     } else {
1059       # Suppress all subsequent paragraphs unless 
1060       # it is explcitly intended for latex
1061       $self->{_suppress_all_para} = 1;
1062     }
1063
1064   } elsif ($command eq 'for') {
1065
1066     # =for latex
1067     #   some latex
1068
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
1073
1074     # The first line contains the format and the rest is the
1075     # raw code.
1076     my ($format, $chunk) = split(/\n/, $rawpara, 2);
1077
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 );
1083
1084     }
1085
1086   } elsif ($command eq 'end') {
1087
1088     # Reset suppression
1089     $self->{_suppress_all_para} = 0;
1090     $self->{_dont_modify_any_para} = 0;
1091
1092   } elsif ($command eq 'pod') {
1093
1094     # Do nothing
1095
1096   } else {
1097     carp "Command $command not recognised at line $line_num\n";
1098   }
1099
1100 }
1101
1102 =item B<verbatim>
1103
1104 Verbatim text
1105
1106 =cut
1107
1108 sub verbatim {
1109   my $self = shift;
1110   my ($paragraph, $line_num, $parobj) = @_;
1111
1112   # Expand paragraph unless in =begin block
1113   if ($self->{_dont_modify_any_para}) {
1114     # Just print as is
1115     $self->_output($paragraph);
1116
1117   } else {
1118
1119     return if $paragraph =~ /^\s+$/;
1120
1121     # Clean trailing space
1122     $paragraph =~ s/\s+$//;
1123
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);
1128     foreach (@l) {
1129       1 while s/(^|\n)([^\t\n]*)(\t+)/
1130         $1. $2 . (" " x 
1131                   (8 * length($3)
1132                    - (length($2) % 8)))
1133           /sex;
1134     }
1135     $paragraph = join("\n",@l);
1136     # End of change.
1137
1138
1139
1140     $self->_output('\begin{verbatim}' . "\n$paragraph\n". '\end{verbatim}'."\n");
1141   }
1142 }
1143
1144 =item B<textblock>
1145
1146 Plain text paragraph.
1147
1148 =cut
1149
1150 sub textblock {
1151   my $self = shift;
1152   my ($paragraph, $line_num, $parobj) = @_;
1153
1154   # print Dumper($self);
1155
1156   # Expand paragraph unless in =begin block
1157   if ($self->{_dont_modify_any_para}) {
1158     # Just print as is
1159     $self->_output($paragraph);
1160
1161     return;
1162   }
1163
1164
1165   # Escape latex special characters
1166   $paragraph = $self->_replace_special_chars($paragraph);
1167
1168   # Interpolate interior sequences
1169   my $expansion = $self->interpolate($paragraph, $line_num);
1170   $expansion =~ s/\s+$//;
1171
1172   # Escape special characters that can not be done earlier
1173   $expansion = $self->_replace_special_chars_late($expansion);
1174
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
1179   # present.
1180   if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()) {
1181
1182     # Strip white space from start and end
1183     $paragraph =~ s/^\s+//;
1184     $paragraph =~ s/\s$//;
1185
1186     # Split the string into 2 parts
1187     my ($name, $purpose) = split(/\s+-\s+/, $expansion,2);
1188
1189     # Now prevent this from triggering until a new head1 NAME is set
1190     $self->{_CURRENT_HEAD1} = '_NAME';
1191
1192     # Might want to clear the Label() before doing this (CHECK)
1193
1194     # Print the heading
1195     $self->head(1, $name, $parobj);
1196
1197     # Set the labeling in case we want unique names later
1198     $self->Label( $self->_create_label( $name, 1 ) );
1199
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;
1205
1206     # Now write out the new latex paragraph
1207     $purpose = ucfirst($purpose);
1208     $self->_output("\n\n$purpose\n\n");
1209
1210   } else {
1211     # Just write the output
1212     $self->_output("\n\n$expansion\n\n");
1213   }
1214
1215 }
1216
1217 =item B<interior_sequence>
1218
1219 Interior sequence expansion
1220
1221 =cut
1222
1223 sub interior_sequence {
1224   my $self = shift;
1225
1226   my ($seq_command, $seq_argument, $pod_seq) = @_;
1227
1228   if ($seq_command eq 'B') {
1229     return "\\textbf{$seq_argument}";
1230
1231   } elsif ($seq_command eq 'I') {
1232     return "\\textit{$seq_argument}";
1233
1234   } elsif ($seq_command eq 'E') {
1235
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};
1242
1243     } else {
1244       my ($file, $line) = $pod_seq->file_line();
1245       warn "Escape sequence $seq_argument not recognised at line $line of file $file\n";
1246       return;
1247     }
1248
1249   } elsif ($seq_command eq 'Z') {
1250
1251     # Zero width space
1252     return '{}';
1253
1254   } elsif ($seq_command eq 'C') {
1255     return "\\texttt{$seq_argument}";
1256
1257   } elsif ($seq_command eq 'F') {
1258     return "\\emph{$seq_argument}";
1259
1260   } elsif ($seq_command eq 'S') {
1261     # non breakable spaces
1262     my $nbsp = '~';
1263
1264     $seq_argument =~ s/\s/$nbsp/g;
1265     return $seq_argument;
1266
1267   } elsif ($seq_command eq 'L') {
1268     my $link = new Pod::Hyperlink($seq_argument);
1269
1270     # undef on failure
1271     unless (defined $link) {
1272       carp $@;
1273       return;
1274     }
1275
1276     # Handle internal links differently
1277     my $type = $link->type;
1278     my $page = $link->page;
1279
1280     if ($type eq 'section' && $page eq '') {
1281       # Use internal latex reference 
1282       my $node = $link->node;
1283
1284       # Convert to a label
1285       $node = $self->_create_label($node);
1286
1287       return "\\S\\ref{$node}";
1288
1289     } else {
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();
1294
1295       return $self->interpolate($link->markup, $line);
1296     }
1297
1298
1299
1300   } elsif ($seq_command eq 'P') {
1301     # Special markup for Pod::Hyperlink
1302     # Replace :: with / - but not sure if I want to do this
1303     # any more.
1304     my $link = $seq_argument;
1305     $link =~ s|::|/|g;
1306
1307     my $ref = "\\emph{$seq_argument}";
1308     return $ref;
1309
1310   } elsif ($seq_command eq 'Q') {
1311     # Special markup for Pod::Hyperlink
1312     return "\\textsf{$seq_argument}";
1313
1314   } elsif ($seq_command eq 'X') {
1315     # Index entries
1316
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";
1322
1323   } else {
1324     carp "Unknown sequence $seq_command<$seq_argument>";
1325   }
1326
1327 }
1328
1329 =back
1330
1331 =head2 List Methods
1332
1333 Methods used to handle lists.
1334
1335 =over 4
1336
1337 =item B<begin_list>
1338
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 
1341 list stack.
1342
1343   $parser->begin_list($indent, $line_num);
1344
1345 =cut
1346
1347 sub begin_list {
1348   my $self = shift;
1349   my $indent = shift;
1350   my $line_num = shift;
1351
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,
1357                                        )         
1358        );
1359
1360 }
1361
1362 =item B<end_list>
1363
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.
1367
1368   $parser->end_list($line_num);
1369
1370 =cut
1371
1372 sub end_list {
1373   my $self = shift;
1374   my $line_num = shift;
1375
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";
1379     return;
1380   }
1381
1382   # What to write depends on list type
1383   my $type = $self->lists->[-1]->type;
1384
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);
1390   
1391   # Clear list
1392   pop(@{ $self->lists});
1393
1394 }
1395
1396 =item B<add_item>
1397
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.
1402
1403   $parser->add_item($paragraph, $line_num);
1404
1405 =cut
1406
1407 sub add_item {
1408   my $self = shift;
1409   my $paragraph = shift;
1410   my $line_num = shift;
1411
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");
1418     return;
1419   }
1420
1421   # If paragraphs printing is turned off via =begin/=end or whatver
1422   # simply return immediately
1423   return if $self->{_suppress_all_para};
1424
1425   # Check to see whether we are starting a new lists
1426   if (scalar($self->lists->[-1]->item) == 0) {
1427
1428     # Examine the paragraph to determine what type of list
1429     # we have
1430     $paragraph =~ s/\s+$//;
1431     $paragraph =~ s/^\s+//;
1432
1433     my $type;
1434     if (substr($paragraph, 0,1) eq '*') {
1435       $type = 'itemize';
1436     } elsif ($paragraph =~ /^\d/) {
1437       $type = 'enumerate';
1438     } else {
1439       $type = 'description';
1440     }
1441     $self->lists->[-1]->type($type);
1442
1443     $self->_output("\\begin{$type}\n");
1444
1445   }
1446
1447   my $type = $self->lists->[-1]->type;
1448
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.
1453     my $maxlen = 40;
1454     my ($hunk1, $hunk2) = $self->_split_delimited( $paragraph, $maxlen );
1455
1456     # Print the first hunk
1457     $self->_output("\n\\item[{$hunk1}] ");
1458
1459     # and the second hunk if it is defined
1460     if ($hunk2) {
1461       $self->_output("\\textbf{$hunk2}");
1462     } else {
1463       # Not there so make sure we have a new line
1464       $self->_output("\\mbox{}");
1465     }
1466
1467   } else {
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");
1473   }
1474
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);
1478
1479 }
1480
1481 =back
1482
1483 =head2 Methods for headings
1484
1485 =over 4
1486
1487 =item B<head>
1488
1489 Print a heading of the required level.
1490
1491   $parser->head($level, $paragraph, $parobj);
1492
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.
1496
1497 =cut
1498
1499 sub head {
1500   my $self = shift;
1501   my $num = shift;
1502   my $paragraph = shift;
1503   my $parobj = shift;
1504
1505   # If we are replace 'head1 NAME' with a section
1506   # we return immediately if we get it
1507   return 
1508     if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection());
1509
1510   # Create a label
1511   my $label = $self->_create_label($paragraph);
1512
1513   # Create an index entry
1514   my $index = $self->_create_index($paragraph);
1515
1516   # Work out position in the above array taking into account
1517   # that =head1 is equivalent to $self->Head1Level
1518
1519   my $level = $self->Head1Level() - 1 + $num;
1520
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;
1527   }
1528
1529   # Check to see whether section should be unnumbered
1530   my $star = ($level >= $self->LevelNoNum ? '*' : '');
1531
1532   # Section
1533   $self->_output("\\" .$LatexSections[$level] .$star ."{$paragraph\\label{".$label ."}\\index{".$index."}}\n");
1534
1535 }
1536
1537
1538 =back
1539
1540 =end __PRIVATE__
1541
1542 =begin __PRIVATE__
1543
1544 =head2 Internal methods
1545
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.
1548
1549 =over 4
1550
1551 =item B<_output>
1552
1553 Output text to the output filehandle. This method must be always be called
1554 to output parsed text.
1555
1556    $parser->_output($text);
1557
1558 Does not write anything if a =begin is active that should be
1559 ignored.
1560
1561 =cut
1562
1563 sub _output { 
1564   my $self = shift;
1565   my $text = shift;
1566
1567   print { $self->output_handle } $text
1568     unless $self->{_suppress_all_para};
1569
1570 }
1571
1572
1573 =item B<_replace_special_chars>
1574
1575 Subroutine to replace characters that are special in C<latex>
1576 with the escaped forms
1577
1578   $escaped = $parser->_replace_special_chars($paragraph);
1579
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
1585 sequences.
1586
1587 Special characters and the C<latex> equivalents are:
1588
1589   }     \}
1590   {     \{
1591   _     \_
1592   $     \$
1593   %     \%
1594   &     \&
1595   \     $\backslash$
1596   ^     \^{}
1597   ~     \~{}
1598   #     \#
1599
1600 =cut
1601
1602 sub _replace_special_chars {
1603   my $self = shift;
1604   my $paragraph = shift;
1605
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;
1611
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;
1615
1616   # Replace ^ characters with \^{} so that $^F works okay
1617   $paragraph =~ s/(\^)/\\$1\{\}/g;
1618
1619   # Replace tilde (~) with \texttt{\~{}}
1620   $paragraph =~ s/~/\\texttt\{\\~\{\}\}/g;
1621
1622   # Now add the dollars around each \backslash
1623   $paragraph =~ s/(\\backslash)/\$$1\$/g;
1624   return $paragraph;
1625 }
1626
1627 =item B<_replace_special_chars_late>
1628
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
1632 sequences.
1633
1634 Does the following transformation:
1635
1636   <   $<$
1637   >   $>$
1638   |   $|$
1639
1640
1641 =cut
1642
1643 sub _replace_special_chars_late {
1644   my $self = shift;
1645   my $paragraph = shift;
1646
1647   # < and >
1648   $paragraph =~ s/(<|>)/\$$1\$/g;
1649
1650   # Replace | with $|$
1651   $paragraph =~ s'\|'$|$'g;
1652
1653
1654   return $paragraph;
1655 }
1656
1657
1658 =item B<_create_label>
1659
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)
1662
1663  $label = $parser->_create_label($string)
1664
1665 If UniqueLabels is true returns a label prefixed by Label()
1666 This can be suppressed with an optional second argument.
1667
1668  $label = $parser->_create_label($string, $suppress);
1669
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.
1673
1674 =cut
1675
1676 sub _create_label {
1677   my $self = shift;
1678   my $paragraph = shift;
1679   my $suppress = (@_ ? 1 : 0 );
1680
1681   # Remove latex commands
1682   $paragraph = $self->_clean_latex_commands($paragraph);
1683
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;
1687
1688   # Multiple underscores will look unsightly so remove repeats
1689   # This will also have the advantage of tidying up the end and
1690   # start of string
1691   $paragraph =~ s/_+/_/g;
1692
1693   # If required need to make sure that the label is unique
1694   # since it is possible to have multiple pods in a single
1695   # document
1696   if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
1697     $paragraph = $self->Label() .'_'. $paragraph;
1698   }
1699
1700   return $paragraph;
1701 }
1702
1703
1704 =item B<_create_index>
1705
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.
1709
1710   $ind = $parser->_create_index($paragraph);
1711
1712 An exclamation mark is used by C<makeindex> to generate 
1713 sub-entries in an index.
1714
1715 =cut
1716
1717 sub _create_index {
1718   my $self = shift;
1719   my $paragraph = shift;
1720   my $suppress = (@_ ? 1 : 0 );
1721
1722   # Remove latex commands
1723   $paragraph = $self->_clean_latex_commands($paragraph);
1724
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
1727   # document
1728   if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
1729     $paragraph = $self->Label() .'!'. $paragraph;
1730   }
1731
1732   # Need to replace _ with space
1733   $paragraph =~ s/_/ /g;
1734
1735   return $paragraph;
1736
1737 }
1738
1739 =item B<_clean_latex_commands>
1740
1741 Removes latex commands from text. The latex command is assumed to be of the
1742 form C<\command{ text }>. "C<text>" is retained
1743
1744   $clean = $parser->_clean_latex_commands($text);
1745
1746 =cut
1747
1748 sub _clean_latex_commands {
1749   my $self = shift;
1750   my $paragraph = shift;
1751
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
1757   #  "a} and \text2{b"
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;
1762
1763   return $paragraph
1764 }
1765
1766 =item B<_split_delimited>
1767
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.
1771
1772 e.g. "this text is \textbf{very bold}" would not be split into
1773 "this text is \textbf{very" and " bold".
1774
1775   ($hunk1, $hunk2) = $self->_split_delimited( $para, $length);
1776
1777 The length indicates the maximum length of hunk1.
1778
1779 =cut
1780
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 {
1785   my $self = shift;
1786   my $input = shift;
1787   my $limit = shift;
1788
1789   # Return immediately if already small
1790   return ($input, '') if length($input) < $limit;
1791
1792   my @output;
1793   my $s = '';
1794   my $t = '';
1795   my $depth = 0;
1796   my $token;
1797
1798   $input =~ s/\n/ /gm;
1799   $input .= ' ';
1800   foreach ( split ( //, $input ) ) {
1801     $token .= $_;
1802     if (/\{/) {
1803       $depth++;
1804     } elsif ( /}/ ) {
1805       $depth--;
1806     } elsif ( / / and $depth == 0) {
1807       push @output, $token if ( $token and $token ne ' ' );
1808       $token = '';
1809     }
1810   }
1811
1812   foreach  (@output) {
1813     if (length($s) < $limit) {
1814       $s .= $_;
1815     } else {
1816       $t .= $_;
1817     }
1818   }
1819
1820   # Tidy up
1821   $s =~ s/\s+$//;
1822   $t =~ s/\s+$//;
1823   return ($s,$t);
1824 }
1825
1826 =back
1827
1828 =end __PRIVATE__
1829
1830 =head1 NOTES
1831
1832 Compatible with C<latex2e> only. Can not be used with C<latex> v2.09
1833 or earlier.
1834
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.
1837
1838 Some HTML escapes are missing and many have not been tested.
1839
1840 =head1 SEE ALSO
1841
1842 L<Pod::Parser>, L<Pod::Select>, L<pod2latex>
1843
1844 =head1 AUTHORS
1845
1846 Tim Jenness E<lt>tjenness@cpan.orgE<gt>
1847
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>.
1857
1858
1859 =head1 COPYRIGHT
1860
1861 Copyright (C) 2000-2004 Tim Jenness. All Rights Reserved.
1862
1863 This program is free software; you can redistribute it and/or modify
1864 it under the same terms as Perl itself.
1865
1866 =begin __PRIVATE__
1867
1868 =head1 REVISION
1869
1870 $Id: LaTeX.pm,v 1.19 2004/12/30 01:40:44 timj Exp $
1871
1872 =end __PRIVATE__
1873
1874 =cut
1875
1876 1;