LaTeX.pm revision 3517:79d66aa80b8b
1package Pod::LaTeX; 2 3=head1 NAME 4 5Pod::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 18C<Pod::LaTeX> is a module to convert documentation in the Pod format 19into Latex. The L<B<pod2latex>|pod2latex> X<pod2latex> command uses 20this module for translation. 21 22C<Pod::LaTeX> is a derived class from L<Pod::Select|Pod::Select>. 23 24=cut 25 26 27use strict; 28require Pod::ParseUtils; 29use base qw/ Pod::Select /; 30 31# use Data::Dumper; # for debugging 32use Carp; 33 34use vars qw/ $VERSION %HTML_Escapes @LatexSections /; 35 36$VERSION = '0.55'; 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 360The following methods are provided in this module. Methods inherited 361from C<Pod::Select> are not described in the public interface. 362 363=over 4 364 365=begin __PRIVATE__ 366 367=item C<initialize> 368 369Initialise the object. This method is subclassed from C<Pod::Parser>. 370The base class method is invoked. This method defines the default 371behaviour of the object unless overridden by supplying arguments to 372the constructor. 373 374Internal settings are defaulted as well as the public instance data. 375Internal hash values are accessed directly (rather than through 376a method) and start with an underscore. 377 378This 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 390sub 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 relevant 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 467The following methods are provided for accessing instance data. These 468methods should be used for accessing configuration parameters rather 469than assuming the object is a hash. 470 471Default values can be supplied by using these names as keys to a hash 472of arguments when using the C<new()> constructor. 473 474=over 4 475 476=item B<AddPreamble> 477 478Logical to control whether a C<latex> preamble is to be written. 479If true, a valid C<latex> preamble is written before the pod data is written. 480This is similar to: 481 482 \documentclass{article} 483 \usepackage[T1]{fontenc} 484 \usepackage{textcomp} 485 \begin{document} 486 487but will be more complicated if table of contents and indexing are required. 488Can be used to set or retrieve the current value. 489 490 $add = $parser->AddPreamble(); 491 $parser->AddPreamble(1); 492 493If used in conjunction with C<AddPostamble> a full latex document will 494be written that could be immediately processed by C<latex>. 495 496For some pod escapes it may be necessary to include the amsmath 497package. This is not yet added to the preamble automaatically. 498 499=cut 500 501sub AddPreamble { 502 my $self = shift; 503 if (@_) { 504 $self->{AddPreamble} = shift; 505 } 506 return $self->{AddPreamble}; 507} 508 509=item B<AddPostamble> 510 511Logical to control whether a standard C<latex> ending is written to the output 512file after the document has been processed. 513In its simplest form this is simply: 514 515 \end{document} 516 517but can be more complicated if a index is required. 518Can be used to set or retrieve the current value. 519 520 $add = $parser->AddPostamble(); 521 $parser->AddPostamble(1); 522 523If used in conjunction with C<AddPreaamble> a full latex document will 524be written that could be immediately processed by C<latex>. 525 526=cut 527 528sub AddPostamble { 529 my $self = shift; 530 if (@_) { 531 $self->{AddPostamble} = shift; 532 } 533 return $self->{AddPostamble}; 534} 535 536=item B<Head1Level> 537 538The C<latex> sectioning level that should be used to correspond to 539a pod C<=head1> directive. This can be used, for example, to turn 540a C<=head1> into a C<latex> C<subsection>. This should hold a number 541corresponding to the required position in an array containing the 542following elements: 543 544 [0] chapter 545 [1] section 546 [2] subsection 547 [3] subsubsection 548 [4] paragraph 549 [5] subparagraph 550 551Can be used to set or retrieve the current value: 552 553 $parser->Head1Level(2); 554 $sect = $parser->Head1Level; 555 556Setting this number too high can result in sections that may not be reproducible 557in the expected way. For example, setting this to 4 would imply that C<=head3> 558do not have a corresponding C<latex> section (C<=head1> would correspond to 559a C<paragraph>). 560 561A check is made to ensure that the supplied value is an integer in the 562range 0 to 5. 563 564Default is for a value of 1 (i.e. a C<section>). 565 566=cut 567 568sub 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 583This is the label that is prefixed to all C<latex> label and index 584entries to make them unique. In general, pods have similarly titled 585sections (NAME, DESCRIPTION etc) and a C<latex> label will be multiply 586defined if more than one pod document is to be included in a single 587C<latex> file. To overcome this, this label is prefixed to a label 588whenever a label is required (joined with an underscore) or to an 589index entry (joined by an exclamation mark which is the normal index 590separator). For example, C<\label{text}> becomes C<\label{Label_text}>. 591 592Can be used to set or retrieve the current value: 593 594 $label = $parser->Label; 595 $parser->Label($label); 596 597This label is only used if C<UniqueLabels> is true. 598Its value is set automatically from the C<NAME> field 599if C<ReplaceNAMEwithSection> is true. If this is not the case 600it must be set manually before starting the parse. 601 602Default value is C<undef>. 603 604=cut 605 606sub Label { 607 my $self = shift; 608 if (@_) { 609 $self->{Label} = shift; 610 } 611 return $self->{Label}; 612} 613 614=item B<LevelNoNum> 615 616Control the point at which C<latex> section numbering is turned off. 617For example, this can be used to make sure that C<latex> sections 618are numbered but subsections are not. 619 620Can be used to set or retrieve the current value: 621 622 $lev = $parser->LevelNoNum; 623 $parser->LevelNoNum(2); 624 625The argument must be an integer between 0 and 5 and is the same as the 626number described in C<Head1Level> method description. The number has 627nothing to do with the pod heading number, only the C<latex> sectioning. 628 629Default is 2. (i.e. C<latex> subsections are written as C<subsection*> 630but sections are numbered). 631 632=cut 633 634sub LevelNoNum { 635 my $self = shift; 636 if (@_) { 637 $self->{LevelNoNum} = shift; 638 } 639 return $self->{LevelNoNum}; 640} 641 642=item B<MakeIndex> 643 644Controls whether C<latex> commands for creating an index are to be inserted 645into the preamble and postamble 646 647 $makeindex = $parser->MakeIndex; 648 $parser->MakeIndex(0); 649 650Irrelevant if both C<AddPreamble> and C<AddPostamble> are false (or equivalently, 651C<UserPreamble> and C<UserPostamble> are set). 652 653Default is for an index to be created. 654 655=cut 656 657sub MakeIndex { 658 my $self = shift; 659 if (@_) { 660 $self->{MakeIndex} = shift; 661 } 662 return $self->{MakeIndex}; 663} 664 665=item B<ReplaceNAMEwithSection> 666 667This controls whether the C<NAME> section in the pod is to be translated 668literally or converted to a slightly modified output where the section 669name is the pod name rather than "NAME". 670 671If true, the pod segment 672 673 =head1 NAME 674 675 pod::name - purpose 676 677 =head1 SYNOPSIS 678 679is 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 689subsequent C<head1> directives translate to subsections rather than 690sections and that the labels and index now include the pod name (dependent 691on the value of C<UniqueLabels>). 692 693The C<Label> is set from the pod name regardless of any current value 694of C<Label>. 695 696 $mod = $parser->ReplaceNAMEwithSection; 697 $parser->ReplaceNAMEwithSection(0); 698 699Default is to translate the pod literally. 700 701=cut 702 703sub ReplaceNAMEwithSection { 704 my $self = shift; 705 if (@_) { 706 $self->{ReplaceNAMEwithSection} = shift; 707 } 708 return $self->{ReplaceNAMEwithSection}; 709} 710 711=item B<StartWithNewPage> 712 713If true, each pod translation will begin with a C<latex> 714C<\clearpage>. 715 716 $parser->StartWithNewPage(1); 717 $newpage = $parser->StartWithNewPage; 718 719Default is false. 720 721=cut 722 723sub StartWithNewPage { 724 my $self = shift; 725 if (@_) { 726 $self->{StartWithNewPage} = shift; 727 } 728 return $self->{StartWithNewPage}; 729} 730 731=item B<TableOfContents> 732 733If true, a table of contents will be created. 734Irrelevant if C<AddPreamble> is false or C<UserPreamble> 735is set. 736 737 $toc = $parser->TableOfContents; 738 $parser->TableOfContents(1); 739 740Default is false. 741 742=cut 743 744sub TableOfContents { 745 my $self = shift; 746 if (@_) { 747 $self->{TableOfContents} = shift; 748 } 749 return $self->{TableOfContents}; 750} 751 752=item B<UniqueLabels> 753 754If true, the translator will attempt to make sure that 755each C<latex> label or index entry will be uniquely identified 756by prefixing the contents of C<Label>. This allows 757multiple documents to be combined without clashing 758common labels such as C<DESCRIPTION> and C<SYNOPSIS> 759 760 $parser->UniqueLabels(1); 761 $unq = $parser->UniqueLabels; 762 763Default is true. 764 765=cut 766 767sub UniqueLabels { 768 my $self = shift; 769 if (@_) { 770 $self->{UniqueLabels} = shift; 771 } 772 return $self->{UniqueLabels}; 773} 774 775=item B<UserPreamble> 776 777User supplied C<latex> preamble. Added before the pod translation 778data. 779 780If set, the contents will be prepended to the output file before the translated 781data regardless of the value of C<AddPreamble>. 782C<MakeIndex> and C<TableOfContents> will also be ignored. 783 784=cut 785 786sub UserPreamble { 787 my $self = shift; 788 if (@_) { 789 $self->{UserPreamble} = shift; 790 } 791 return $self->{UserPreamble}; 792} 793 794=item B<UserPostamble> 795 796User supplied C<latex> postamble. Added after the pod translation 797data. 798 799If set, the contents will be prepended to the output file after the translated 800data regardless of the value of C<AddPostamble>. 801C<MakeIndex> will also be ignored. 802 803=cut 804 805sub 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 817Contains details of the currently active lists. 818 The array contains C<Pod::List> objects. A new C<Pod::List> 819object is created each time a list is encountered and it is 820pushed onto this stack. When the list context ends, it 821is popped from the stack. The array will be empty if no 822lists are active. 823 824Returns array of list information in list context 825Returns array ref in scalar context 826 827=cut 828 829 830 831sub 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 845The following methods override methods provided in the C<Pod::Select> 846base class. See C<Pod::Parser> and C<Pod::Select> for more information 847on 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 859Writes the C<latex> preamble if requested. 860 861=cut 862 863sub begin_pod { 864 my $self = shift; 865 866 # Get the pod identification 867 # This should really come from the '=head1 NAME' paragraph 868 869 my $infile = $self->input_file; 870 my $class = ref($self); 871 my $date = gmtime(time); 872 873 # Comment message to say where this came from 874 my $comment = << "__TEX_COMMENT__"; 875%% Latex generated from POD in document $infile 876%% Using the perl module $class 877%% Converted on $date 878__TEX_COMMENT__ 879 880 # Write the preamble 881 # If the caller has supplied one then we just use that 882 883 my $preamble = ''; 884 if (defined $self->UserPreamble) { 885 886 $preamble = $self->UserPreamble; 887 888 # Add the description of where this came from 889 $preamble .= "\n$comment"; 890 891 892 } elsif ($self->AddPreamble) { 893 # Write our own preamble 894 895 # Code to initialise index making 896 # Use an array so that we can prepend comment if required 897 my @makeidx = ( 898 '\usepackage{makeidx}', 899 '\makeindex', 900 ); 901 902 unless ($self->MakeIndex) { 903 foreach (@makeidx) { 904 $_ = '%% ' . $_; 905 } 906 } 907 my $makeindex = join("\n",@makeidx) . "\n"; 908 909 910 # Table of contents 911 my $tableofcontents = '\tableofcontents'; 912 913 $tableofcontents = '%% ' . $tableofcontents 914 unless $self->TableOfContents; 915 916 # Roll our own 917 $preamble = << "__TEX_HEADER__"; 918\\documentclass{article} 919\\usepackage[T1]{fontenc} 920\\usepackage{textcomp} 921 922$comment 923 924$makeindex 925 926\\begin{document} 927 928$tableofcontents 929 930__TEX_HEADER__ 931 932 } 933 934 # Write the header (blank if none) 935 $self->_output($preamble); 936 937 # Start on new page if requested 938 $self->_output("\\clearpage\n") if $self->StartWithNewPage; 939 940} 941 942 943=item B<end_pod> 944 945Write the closing C<latex> code. 946 947=cut 948 949sub end_pod { 950 my $self = shift; 951 952 # End string 953 my $end = ''; 954 955 # Use the user version of the postamble if deinfed 956 if (defined $self->UserPostamble) { 957 $end = $self->UserPostamble; 958 959 $self->_output($end); 960 961 } elsif ($self->AddPostamble) { 962 963 # Check for index 964 my $makeindex = '\printindex'; 965 966 $makeindex = '%% '. $makeindex unless $self->MakeIndex; 967 968 $end = "$makeindex\n\n\\end{document}\n"; 969 } 970 971 972 $self->_output($end); 973 974} 975 976=item B<command> 977 978Process basic pod commands. 979 980=cut 981 982sub command { 983 my $self = shift; 984 my ($command, $paragraph, $line_num, $parobj) = @_; 985 986 # return if we dont care 987 return if $command eq 'pod'; 988 989 # Store a copy of the raw text in case we are in a =for 990 # block and need to preserve the existing latex 991 my $rawpara = $paragraph; 992 993 # Do the latex escapes 994 $paragraph = $self->_replace_special_chars($paragraph); 995 996 # Interpolate pod sequences in paragraph 997 $paragraph = $self->interpolate($paragraph, $line_num); 998 $paragraph =~ s/\s+$//; 999 1000 # Replace characters that can only be done after 1001 # interpolation of interior sequences 1002 $paragraph = $self->_replace_special_chars_late($paragraph); 1003 1004 # Now run the command 1005 if ($command eq 'over') { 1006 1007 $self->begin_list($paragraph, $line_num); 1008 1009 } elsif ($command eq 'item') { 1010 1011 $self->add_item($paragraph, $line_num); 1012 1013 } elsif ($command eq 'back') { 1014 1015 $self->end_list($line_num); 1016 1017 } elsif ($command eq 'head1') { 1018 1019 # Store the name of the section 1020 $self->{_CURRENT_HEAD1} = $paragraph; 1021 1022 # Print it 1023 $self->head(1, $paragraph, $parobj); 1024 1025 } elsif ($command eq 'head2') { 1026 1027 $self->head(2, $paragraph, $parobj); 1028 1029 } elsif ($command eq 'head3') { 1030 1031 $self->head(3, $paragraph, $parobj); 1032 1033 } elsif ($command eq 'head4') { 1034 1035 $self->head(4, $paragraph, $parobj); 1036 1037 } elsif ($command eq 'head5') { 1038 1039 $self->head(5, $paragraph, $parobj); 1040 1041 } elsif ($command eq 'head6') { 1042 1043 $self->head(6, $paragraph, $parobj); 1044 1045 } elsif ($command eq 'begin') { 1046 1047 # pass through if latex 1048 if ($paragraph =~ /^latex/i) { 1049 # Make sure that subsequent paragraphs are not modfied before printing 1050 $self->{_dont_modify_any_para} = 1; 1051 1052 } else { 1053 # Suppress all subsequent paragraphs unless 1054 # it is explcitly intended for latex 1055 $self->{_suppress_all_para} = 1; 1056 } 1057 1058 } elsif ($command eq 'for') { 1059 1060 # =for latex 1061 # some latex 1062 1063 # With =for we will get the text for the full paragraph 1064 # as well as the format name. 1065 # We do not get an additional paragraph later on. The next 1066 # paragraph is not governed by the =for 1067 1068 # The first line contains the format and the rest is the 1069 # raw code. 1070 my ($format, $chunk) = split(/\n/, $rawpara, 2); 1071 1072 # If we have got some latex code print it out immediately 1073 # unmodified. Else do nothing. 1074 if ($format =~ /^latex/i) { 1075 # Make sure that next paragraph is not modfied before printing 1076 $self->_output( $chunk ); 1077 1078 } 1079 1080 } elsif ($command eq 'end') { 1081 1082 # Reset suppression 1083 $self->{_suppress_all_para} = 0; 1084 $self->{_dont_modify_any_para} = 0; 1085 1086 } elsif ($command eq 'pod') { 1087 1088 # Do nothing 1089 1090 } else { 1091 carp "Command $command not recognised at line $line_num\n"; 1092 } 1093 1094} 1095 1096=item B<verbatim> 1097 1098Verbatim text 1099 1100=cut 1101 1102sub verbatim { 1103 my $self = shift; 1104 my ($paragraph, $line_num, $parobj) = @_; 1105 1106 # Expand paragraph unless in =begin block 1107 if ($self->{_dont_modify_any_para}) { 1108 # Just print as is 1109 $self->_output($paragraph); 1110 1111 } else { 1112 1113 return if $paragraph =~ /^\s+$/; 1114 1115 # Clean trailing space 1116 $paragraph =~ s/\s+$//; 1117 1118 # Clean tabs. Routine taken from Tabs.pm 1119 # by David Muir Sharnoff muir@idiom.com, 1120 # slightly modified by hsmyers@sdragons.com 10/22/01 1121 my @l = split("\n",$paragraph); 1122 foreach (@l) { 1123 1 while s/(^|\n)([^\t\n]*)(\t+)/ 1124 $1. $2 . (" " x 1125 (8 * length($3) 1126 - (length($2) % 8))) 1127 /sex; 1128 } 1129 $paragraph = join("\n",@l); 1130 # End of change. 1131 1132 1133 1134 $self->_output('\begin{verbatim}' . "\n$paragraph\n". '\end{verbatim}'."\n"); 1135 } 1136} 1137 1138=item B<textblock> 1139 1140Plain text paragraph. 1141 1142=cut 1143 1144sub textblock { 1145 my $self = shift; 1146 my ($paragraph, $line_num, $parobj) = @_; 1147 1148 # print Dumper($self); 1149 1150 # Expand paragraph unless in =begin block 1151 if ($self->{_dont_modify_any_para}) { 1152 # Just print as is 1153 $self->_output($paragraph); 1154 1155 return; 1156 } 1157 1158 1159 # Escape latex special characters 1160 $paragraph = $self->_replace_special_chars($paragraph); 1161 1162 # Interpolate interior sequences 1163 my $expansion = $self->interpolate($paragraph, $line_num); 1164 $expansion =~ s/\s+$//; 1165 1166 # Escape special characters that can not be done earlier 1167 $expansion = $self->_replace_special_chars_late($expansion); 1168 1169 # If we are replacing 'head1 NAME' with a section 1170 # we need to look in the paragraph and rewrite things 1171 # Need to make sure this is called only on the first paragraph 1172 # following 'head1 NAME' and not on subsequent paragraphs that may be 1173 # present. 1174 if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()) { 1175 1176 # Strip white space from start and end 1177 $paragraph =~ s/^\s+//; 1178 $paragraph =~ s/\s$//; 1179 1180 # Split the string into 2 parts 1181 my ($name, $purpose) = split(/\s+-\s+/, $expansion,2); 1182 1183 # Now prevent this from triggering until a new head1 NAME is set 1184 $self->{_CURRENT_HEAD1} = '_NAME'; 1185 1186 # Might want to clear the Label() before doing this (CHECK) 1187 1188 # Print the heading 1189 $self->head(1, $name, $parobj); 1190 1191 # Set the labeling in case we want unique names later 1192 $self->Label( $self->_create_label( $name, 1 ) ); 1193 1194 # Raise the Head1Level by one so that subsequent =head1 appear 1195 # as subsections of the main name section unless we are already 1196 # at maximum [Head1Level() could check this itself - CHECK] 1197 $self->Head1Level( $self->Head1Level() + 1) 1198 unless $self->Head1Level == $#LatexSections; 1199 1200 # Now write out the new latex paragraph 1201 $purpose = ucfirst($purpose); 1202 $self->_output("\n\n$purpose\n\n"); 1203 1204 } else { 1205 # Just write the output 1206 $self->_output("\n\n$expansion\n\n"); 1207 } 1208 1209} 1210 1211=item B<interior_sequence> 1212 1213Interior sequence expansion 1214 1215=cut 1216 1217sub interior_sequence { 1218 my $self = shift; 1219 1220 my ($seq_command, $seq_argument, $pod_seq) = @_; 1221 1222 if ($seq_command eq 'B') { 1223 return "\\textbf{$seq_argument}"; 1224 1225 } elsif ($seq_command eq 'I') { 1226 return "\\textit{$seq_argument}"; 1227 1228 } elsif ($seq_command eq 'E') { 1229 1230 # If it is simply a number 1231 if ($seq_argument =~ /^\d+$/) { 1232 return chr($seq_argument); 1233 # Look up escape in hash table 1234 } elsif (exists $HTML_Escapes{$seq_argument}) { 1235 return $HTML_Escapes{$seq_argument}; 1236 1237 } else { 1238 my ($file, $line) = $pod_seq->file_line(); 1239 warn "Escape sequence $seq_argument not recognised at line $line of file $file\n"; 1240 return; 1241 } 1242 1243 } elsif ($seq_command eq 'Z') { 1244 1245 # Zero width space 1246 return '{}'; 1247 1248 } elsif ($seq_command eq 'C') { 1249 return "\\texttt{$seq_argument}"; 1250 1251 } elsif ($seq_command eq 'F') { 1252 return "\\emph{$seq_argument}"; 1253 1254 } elsif ($seq_command eq 'S') { 1255 # non breakable spaces 1256 my $nbsp = '~'; 1257 1258 $seq_argument =~ s/\s/$nbsp/g; 1259 return $seq_argument; 1260 1261 } elsif ($seq_command eq 'L') { 1262 my $link = new Pod::Hyperlink($seq_argument); 1263 1264 # undef on failure 1265 unless (defined $link) { 1266 carp $@; 1267 return; 1268 } 1269 1270 # Handle internal links differently 1271 my $type = $link->type; 1272 my $page = $link->page; 1273 1274 if ($type eq 'section' && $page eq '') { 1275 # Use internal latex reference 1276 my $node = $link->node; 1277 1278 # Convert to a label 1279 $node = $self->_create_label($node); 1280 1281 return "\\S\\ref{$node}"; 1282 1283 } else { 1284 # Use default markup for external references 1285 # (although Starlink would use \xlabel) 1286 my $markup = $link->markup; 1287 my ($file, $line) = $pod_seq->file_line(); 1288 1289 return $self->interpolate($link->markup, $line); 1290 } 1291 1292 1293 1294 } elsif ($seq_command eq 'P') { 1295 # Special markup for Pod::Hyperlink 1296 # Replace :: with / - but not sure if I want to do this 1297 # any more. 1298 my $link = $seq_argument; 1299 $link =~ s|::|/|g; 1300 1301 my $ref = "\\emph{$seq_argument}"; 1302 return $ref; 1303 1304 } elsif ($seq_command eq 'Q') { 1305 # Special markup for Pod::Hyperlink 1306 return "\\textsf{$seq_argument}"; 1307 1308 } elsif ($seq_command eq 'X') { 1309 # Index entries 1310 1311 # use \index command 1312 # I will let '!' go through for now 1313 # not sure how sub categories are handled in X<> 1314 my $index = $self->_create_index($seq_argument); 1315 return "\\index{$index}\n"; 1316 1317 } else { 1318 carp "Unknown sequence $seq_command<$seq_argument>"; 1319 } 1320 1321} 1322 1323=back 1324 1325=head2 List Methods 1326 1327Methods used to handle lists. 1328 1329=over 4 1330 1331=item B<begin_list> 1332 1333Called when a new list is found (via the C<over> directive). 1334Creates a new C<Pod::List> object and stores it on the 1335list stack. 1336 1337 $parser->begin_list($indent, $line_num); 1338 1339=cut 1340 1341sub begin_list { 1342 my $self = shift; 1343 my $indent = shift; 1344 my $line_num = shift; 1345 1346 # Indicate that a list should be started for the next item 1347 # need to do this to work out the type of list 1348 push ( @{$self->lists}, new Pod::List(-indent => $indent, 1349 -start => $line_num, 1350 -file => $self->input_file, 1351 ) 1352 ); 1353 1354} 1355 1356=item B<end_list> 1357 1358Called when the end of a list is found (the C<back> directive). 1359Pops the C<Pod::List> object off the stack of lists and writes 1360the C<latex> code required to close a list. 1361 1362 $parser->end_list($line_num); 1363 1364=cut 1365 1366sub end_list { 1367 my $self = shift; 1368 my $line_num = shift; 1369 1370 unless (defined $self->lists->[-1]) { 1371 my $file = $self->input_file; 1372 warn "No list is active at line $line_num (file=$file). Missing =over?\n"; 1373 return; 1374 } 1375 1376 # What to write depends on list type 1377 my $type = $self->lists->[-1]->type; 1378 1379 # Dont write anything if the list type is not set 1380 # iomplying that a list was created but no entries were 1381 # placed in it (eg because of a =begin/=end combination) 1382 $self->_output("\\end{$type}\n") 1383 if (defined $type && length($type) > 0); 1384 1385 # Clear list 1386 pop(@{ $self->lists}); 1387 1388} 1389 1390=item B<add_item> 1391 1392Add items to the list. The first time an item is encountered 1393(determined from the state of the current C<Pod::List> object) 1394the type of list is determined (ordered, unnumbered or description) 1395and the relevant latex code issued. 1396 1397 $parser->add_item($paragraph, $line_num); 1398 1399=cut 1400 1401sub add_item { 1402 my $self = shift; 1403 my $paragraph = shift; 1404 my $line_num = shift; 1405 1406 unless (defined $self->lists->[-1]) { 1407 my $file = $self->input_file; 1408 warn "List has already ended by line $line_num of file $file. Missing =over?\n"; 1409 # Replace special chars 1410# $paragraph = $self->_replace_special_chars($paragraph); 1411 $self->_output("$paragraph\n\n"); 1412 return; 1413 } 1414 1415 # If paragraphs printing is turned off via =begin/=end or whatver 1416 # simply return immediately 1417 return if $self->{_suppress_all_para}; 1418 1419 # Check to see whether we are starting a new lists 1420 if (scalar($self->lists->[-1]->item) == 0) { 1421 1422 # Examine the paragraph to determine what type of list 1423 # we have 1424 $paragraph =~ s/\s+$//; 1425 $paragraph =~ s/^\s+//; 1426 1427 my $type; 1428 if (substr($paragraph, 0,1) eq '*') { 1429 $type = 'itemize'; 1430 } elsif ($paragraph =~ /^\d/) { 1431 $type = 'enumerate'; 1432 } else { 1433 $type = 'description'; 1434 } 1435 $self->lists->[-1]->type($type); 1436 1437 $self->_output("\\begin{$type}\n"); 1438 1439 } 1440 1441 my $type = $self->lists->[-1]->type; 1442 1443 if ($type eq 'description') { 1444 # Handle long items - long items do not wrap 1445 # If the string is longer than 40 characters we split 1446 # it into a real item header and some bold text. 1447 my $maxlen = 40; 1448 my ($hunk1, $hunk2) = $self->_split_delimited( $paragraph, $maxlen ); 1449 1450 # Print the first hunk 1451 $self->_output("\n\\item[$hunk1] "); 1452 1453 # and the second hunk if it is defined 1454 if ($hunk2) { 1455 $self->_output("\\textbf{$hunk2}"); 1456 } else { 1457 # Not there so make sure we have a new line 1458 $self->_output("\\mbox{}"); 1459 } 1460 1461 } else { 1462 # If the item was '* Something' or '\d+ something' we still need to write 1463 # out the something. Also allow 1) and 1. 1464 my $extra_info = $paragraph; 1465 $extra_info =~ s/^(\*|\d+[\.\)]?)\s*//; 1466 $self->_output("\n\\item $extra_info"); 1467 } 1468 1469 # Store the item name in the object. Required so that 1470 # we can tell if the list is new or not 1471 $self->lists->[-1]->item($paragraph); 1472 1473} 1474 1475=back 1476 1477=head2 Methods for headings 1478 1479=over 4 1480 1481=item B<head> 1482 1483Print a heading of the required level. 1484 1485 $parser->head($level, $paragraph, $parobj); 1486 1487The first argument is the pod heading level. The second argument 1488is the contents of the heading. The 3rd argument is a Pod::Paragraph 1489object so that the line number can be extracted. 1490 1491=cut 1492 1493sub head { 1494 my $self = shift; 1495 my $num = shift; 1496 my $paragraph = shift; 1497 my $parobj = shift; 1498 1499 # If we are replace 'head1 NAME' with a section 1500 # we return immediately if we get it 1501 return 1502 if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()); 1503 1504 # Create a label 1505 my $label = $self->_create_label($paragraph); 1506 1507 # Create an index entry 1508 my $index = $self->_create_index($paragraph); 1509 1510 # Work out position in the above array taking into account 1511 # that =head1 is equivalent to $self->Head1Level 1512 1513 my $level = $self->Head1Level() - 1 + $num; 1514 1515 # Warn if heading to large 1516 if ($num > $#LatexSections) { 1517 my $line = $parobj->file_line; 1518 my $file = $self->input_file; 1519 warn "Heading level too large ($level) for LaTeX at line $line of file $file\n"; 1520 $level = $#LatexSections; 1521 } 1522 1523 # Check to see whether section should be unnumbered 1524 my $star = ($level >= $self->LevelNoNum ? '*' : ''); 1525 1526 # Section 1527 $self->_output("\\" .$LatexSections[$level] .$star ."{$paragraph\\label{".$label ."}\\index{".$index."}}\n"); 1528 1529} 1530 1531 1532=back 1533 1534=end __PRIVATE__ 1535 1536=begin __PRIVATE__ 1537 1538=head2 Internal methods 1539 1540Internal routines are described in this section. They do not form part of the 1541public interface. All private methods start with an underscore. 1542 1543=over 4 1544 1545=item B<_output> 1546 1547Output text to the output filehandle. This method must be always be called 1548to output parsed text. 1549 1550 $parser->_output($text); 1551 1552Does not write anything if a =begin is active that should be 1553ignored. 1554 1555=cut 1556 1557sub _output { 1558 my $self = shift; 1559 my $text = shift; 1560 1561 print { $self->output_handle } $text 1562 unless $self->{_suppress_all_para}; 1563 1564} 1565 1566 1567=item B<_replace_special_chars> 1568 1569Subroutine to replace characters that are special in C<latex> 1570with the escaped forms 1571 1572 $escaped = $parser->_replace_special_chars($paragraph); 1573 1574Need to call this routine before interior_sequences are munged but not 1575if verbatim. It must be called before interpolation of interior 1576sequences so that curly brackets and special latex characters inserted 1577during interpolation are not themselves escaped. This means that < and 1578> can not be modified here since the text still contains interior 1579sequences. 1580 1581Special characters and the C<latex> equivalents are: 1582 1583 } \} 1584 { \{ 1585 _ \_ 1586 $ \$ 1587 % \% 1588 & \& 1589 \ $\backslash$ 1590 ^ \^{} 1591 ~ \~{} 1592 # \# 1593 1594=cut 1595 1596sub _replace_special_chars { 1597 my $self = shift; 1598 my $paragraph = shift; 1599 1600 # Replace a \ with $\backslash$ 1601 # This is made more complicated because the dollars will be escaped 1602 # by the subsequent replacement. Easiest to add \backslash 1603 # now and then add the dollars 1604 $paragraph =~ s/\\/\\backslash/g; 1605 1606 # Must be done after escape of \ since this command adds latex escapes 1607 # Replace characters that can be escaped 1608 $paragraph =~ s/([\$\#&%_{}])/\\$1/g; 1609 1610 # Replace ^ characters with \^{} so that $^F works okay 1611 $paragraph =~ s/(\^)/\\$1\{\}/g; 1612 1613 # Replace tilde (~) with \texttt{\~{}} 1614 $paragraph =~ s/~/\\texttt\{\\~\{\}\}/g; 1615 1616 # Now add the dollars around each \backslash 1617 $paragraph =~ s/(\\backslash)/\$$1\$/g; 1618 return $paragraph; 1619} 1620 1621=item B<_replace_special_chars_late> 1622 1623Replace special characters that can not be replaced before interior 1624sequence interpolation. See C<_replace_special_chars> for a routine 1625to replace special characters prior to interpolation of interior 1626sequences. 1627 1628Does the following transformation: 1629 1630 < $<$ 1631 > $>$ 1632 | $|$ 1633 1634 1635=cut 1636 1637sub _replace_special_chars_late { 1638 my $self = shift; 1639 my $paragraph = shift; 1640 1641 # < and > 1642 $paragraph =~ s/(<|>)/\$$1\$/g; 1643 1644 # Replace | with $|$ 1645 $paragraph =~ s'\|'$|$'g; 1646 1647 1648 return $paragraph; 1649} 1650 1651 1652=item B<_create_label> 1653 1654Return a string that can be used as an internal reference 1655in a C<latex> document (i.e. accepted by the C<\label> command) 1656 1657 $label = $parser->_create_label($string) 1658 1659If UniqueLabels is true returns a label prefixed by Label() 1660This can be suppressed with an optional second argument. 1661 1662 $label = $parser->_create_label($string, $suppress); 1663 1664If a second argument is supplied (of any value including undef) 1665the Label() is never prefixed. This means that this routine can 1666be called to create a Label() without prefixing a previous setting. 1667 1668=cut 1669 1670sub _create_label { 1671 my $self = shift; 1672 my $paragraph = shift; 1673 my $suppress = (@_ ? 1 : 0 ); 1674 1675 # Remove latex commands 1676 $paragraph = $self->_clean_latex_commands($paragraph); 1677 1678 # Remove non alphanumerics from the label and replace with underscores 1679 # want to protect '-' though so use negated character classes 1680 $paragraph =~ s/[^-:\w]/_/g; 1681 1682 # Multiple underscores will look unsightly so remove repeats 1683 # This will also have the advantage of tidying up the end and 1684 # start of string 1685 $paragraph =~ s/_+/_/g; 1686 1687 # If required need to make sure that the label is unique 1688 # since it is possible to have multiple pods in a single 1689 # document 1690 if (!$suppress && $self->UniqueLabels() && defined $self->Label) { 1691 $paragraph = $self->Label() .'_'. $paragraph; 1692 } 1693 1694 return $paragraph; 1695} 1696 1697 1698=item B<_create_index> 1699 1700Similar to C<_create_label> except an index entry is created. 1701If C<UniqueLabels> is true, the index entry is prefixed by 1702the current C<Label> and an exclamation mark. 1703 1704 $ind = $parser->_create_index($paragraph); 1705 1706An exclamation mark is used by C<makeindex> to generate 1707sub-entries in an index. 1708 1709=cut 1710 1711sub _create_index { 1712 my $self = shift; 1713 my $paragraph = shift; 1714 my $suppress = (@_ ? 1 : 0 ); 1715 1716 # Remove latex commands 1717 $paragraph = $self->_clean_latex_commands($paragraph); 1718 1719 # If required need to make sure that the index entry is unique 1720 # since it is possible to have multiple pods in a single 1721 # document 1722 if (!$suppress && $self->UniqueLabels() && defined $self->Label) { 1723 $paragraph = $self->Label() .'!'. $paragraph; 1724 } 1725 1726 # Need to replace _ with space 1727 $paragraph =~ s/_/ /g; 1728 1729 return $paragraph; 1730 1731} 1732 1733=item B<_clean_latex_commands> 1734 1735Removes latex commands from text. The latex command is assumed to be of the 1736form C<\command{ text }>. "C<text>" is retained 1737 1738 $clean = $parser->_clean_latex_commands($text); 1739 1740=cut 1741 1742sub _clean_latex_commands { 1743 my $self = shift; 1744 my $paragraph = shift; 1745 1746 # Remove latex commands of the form \text{ } 1747 # and replace with the contents of the { } 1748 # need to make this non-greedy so that it can handle 1749 # "\text{a} and \text2{b}" 1750 # without converting it to 1751 # "a} and \text2{b" 1752 # This match will still get into trouble if \} is present 1753 # This is not vital since the subsequent replacement of non-alphanumeric 1754 # characters will tidy it up anyway 1755 $paragraph =~ s/\\\w+{(.*?)}/$1/g; 1756 1757 return $paragraph 1758} 1759 1760=item B<_split_delimited> 1761 1762Split the supplied string into two parts at approximately the 1763specified word boundary. Special care is made to make sure that it 1764does not split in the middle of some curly brackets. 1765 1766e.g. "this text is \textbf{very bold}" would not be split into 1767"this text is \textbf{very" and " bold". 1768 1769 ($hunk1, $hunk2) = $self->_split_delimited( $para, $length); 1770 1771The length indicates the maximum length of hunk1. 1772 1773=cut 1774 1775# initially Supplied by hsmyers@sdragons.com 1776# 10/25/01, utility to split \hbox 1777# busting lines. Reformatted by TimJ to match module style. 1778sub _split_delimited { 1779 my $self = shift; 1780 my $input = shift; 1781 my $limit = shift; 1782 1783 # Return immediately if already small 1784 return ($input, '') if length($input) < $limit; 1785 1786 my @output; 1787 my $s = ''; 1788 my $t = ''; 1789 my $depth = 0; 1790 my $token; 1791 1792 $input =~ s/\n/ /gm; 1793 $input .= ' '; 1794 foreach ( split ( //, $input ) ) { 1795 $token .= $_; 1796 if (/\{/) { 1797 $depth++; 1798 } elsif ( /}/ ) { 1799 $depth--; 1800 } elsif ( / / and $depth == 0) { 1801 push @output, $token if ( $token and $token ne ' ' ); 1802 $token = ''; 1803 } 1804 } 1805 1806 foreach (@output) { 1807 if (length($s) < $limit) { 1808 $s .= $_; 1809 } else { 1810 $t .= $_; 1811 } 1812 } 1813 1814 # Tidy up 1815 $s =~ s/\s+$//; 1816 $t =~ s/\s+$//; 1817 return ($s,$t); 1818} 1819 1820=back 1821 1822=end __PRIVATE__ 1823 1824=head1 NOTES 1825 1826Compatible with C<latex2e> only. Can not be used with C<latex> v2.09 1827or earlier. 1828 1829A subclass of C<Pod::Select> so that specific pod sections can be 1830converted to C<latex> by using the C<select> method. 1831 1832Some HTML escapes are missing and many have not been tested. 1833 1834=head1 SEE ALSO 1835 1836L<Pod::Parser>, L<Pod::Select>, L<pod2latex> 1837 1838=head1 AUTHORS 1839 1840Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt> 1841 1842Bug fixes and improvements have been received from: Simon Cozens 1843E<lt>simon@cozens.netE<gt>, Mark A. Hershberger 1844E<lt>mah@everybody.orgE<gt>, Marcel Grunauer 1845E<lt>marcel@codewerk.comE<gt>, Hugh S Myers 1846E<lt>hsmyers@sdragons.comE<gt>, Peter J Acklam 1847E<lt>jacklam@math.uio.noE<gt>, Sudhi Herle E<lt>sudhi@herle.netE<gt> 1848and Ariel Scolnicov E<lt>ariels@compugen.co.ilE<gt>. 1849 1850 1851=head1 COPYRIGHT 1852 1853Copyright (C) 2000-2003 Tim Jenness. All Rights Reserved. 1854 1855This program is free software; you can redistribute it and/or modify 1856it under the same terms as Perl itself. 1857 1858=begin __PRIVATE__ 1859 1860=head1 REVISION 1861 1862$Id: LaTeX.pm,v 1.17 2003/04/05 21:25:49 timj Exp $ 1863 1864=end __PRIVATE__ 1865 1866=cut 1867 18681; 1869