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 [email protected],
|
---|
1126 | # slightly modified by [email protected] 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 [email protected]
|
---|
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>[email protected]<gt>
|
---|
1847 |
|
---|
1848 | Bug fixes and improvements have been received from: Simon Cozens
|
---|
1849 | E<lt>[email protected]<gt>, Mark A. Hershberger
|
---|
1850 | E<lt>[email protected]<gt>, Marcel Grunauer
|
---|
1851 | E<lt>[email protected]<gt>, Hugh S Myers
|
---|
1852 | E<lt>[email protected]<gt>, Peter J Acklam
|
---|
1853 | E<lt>[email protected]<gt>, Sudhi Herle E<lt>[email protected]<gt>,
|
---|
1854 | Ariel Scolnicov E<lt>[email protected]<gt>,
|
---|
1855 | Adriano Rodrigues Ferreira E<lt>[email protected]<gt> and
|
---|
1856 | R. de Vries E<lt>[email protected]<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;
|
---|