home *** CD-ROM | disk | FTP | other *** search
/ PC World 2005 June / PCWorld_2005-06_cd.bin / software / vyzkuste / firewally / firewally.exe / framework-2.3.exe / LaTeX.pm < prev    next >
Text File  |  2003-11-07  |  59KB  |  1,869 lines
  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.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.  
  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.
  860.  
  861. =cut
  862.  
  863. sub 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.  
  945. Write the closing C<latex> code.
  946.  
  947. =cut
  948.  
  949. sub 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.  
  978. Process basic pod commands.
  979.  
  980. =cut
  981.  
  982. sub 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.  
  1098. Verbatim text
  1099.  
  1100. =cut
  1101.  
  1102. sub 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.  
  1140. Plain text paragraph.
  1141.  
  1142. =cut
  1143.  
  1144. sub 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.  
  1213. Interior sequence expansion
  1214.  
  1215. =cut
  1216.  
  1217. sub 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.  
  1327. Methods used to handle lists.
  1328.  
  1329. =over 4
  1330.  
  1331. =item B<begin_list>
  1332.  
  1333. Called when a new list is found (via the C<over> directive).
  1334. Creates a new C<Pod::List> object and stores it on the 
  1335. list stack.
  1336.  
  1337.   $parser->begin_list($indent, $line_num);
  1338.  
  1339. =cut
  1340.  
  1341. sub 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.  
  1358. Called when the end of a list is found (the C<back> directive).
  1359. Pops the C<Pod::List> object off the stack of lists and writes
  1360. the C<latex> code required to close a list.
  1361.  
  1362.   $parser->end_list($line_num);
  1363.  
  1364. =cut
  1365.  
  1366. sub 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.  
  1392. Add items to the list. The first time an item is encountered 
  1393. (determined from the state of the current C<Pod::List> object)
  1394. the type of list is determined (ordered, unnumbered or description)
  1395. and the relevant latex code issued.
  1396.  
  1397.   $parser->add_item($paragraph, $line_num);
  1398.  
  1399. =cut
  1400.  
  1401. sub 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.  
  1483. Print a heading of the required level.
  1484.  
  1485.   $parser->head($level, $paragraph, $parobj);
  1486.  
  1487. The first argument is the pod heading level. The second argument
  1488. is the contents of the heading. The 3rd argument is a Pod::Paragraph
  1489. object so that the line number can be extracted.
  1490.  
  1491. =cut
  1492.  
  1493. sub 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.  
  1540. Internal routines are described in this section. They do not form part of the
  1541. public interface. All private methods start with an underscore.
  1542.  
  1543. =over 4
  1544.  
  1545. =item B<_output>
  1546.  
  1547. Output text to the output filehandle. This method must be always be called
  1548. to output parsed text.
  1549.  
  1550.    $parser->_output($text);
  1551.  
  1552. Does not write anything if a =begin is active that should be
  1553. ignored.
  1554.  
  1555. =cut
  1556.  
  1557. sub _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.  
  1569. Subroutine to replace characters that are special in C<latex>
  1570. with the escaped forms
  1571.  
  1572.   $escaped = $parser->_replace_special_chars($paragraph);
  1573.  
  1574. Need to call this routine before interior_sequences are munged but not
  1575. if verbatim. It must be called before interpolation of interior
  1576. sequences so that curly brackets and special latex characters inserted
  1577. during interpolation are not themselves escaped. This means that < and
  1578. > can not be modified here since the text still contains interior
  1579. sequences.
  1580.  
  1581. Special characters and the C<latex> equivalents are:
  1582.  
  1583.   }     \}
  1584.   {     \{
  1585.   _     \_
  1586.   $     \$
  1587.   %     \%
  1588.   &     \&
  1589.   \     $\backslash$
  1590.   ^     \^{}
  1591.   ~     \~{}
  1592.   #     \#
  1593.  
  1594. =cut
  1595.  
  1596. sub _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.  
  1623. Replace special characters that can not be replaced before interior
  1624. sequence interpolation. See C<_replace_special_chars> for a routine
  1625. to replace special characters prior to interpolation of interior
  1626. sequences.
  1627.  
  1628. Does the following transformation:
  1629.  
  1630.   <   $<$
  1631.   >   $>$
  1632.   |   $|$
  1633.  
  1634.  
  1635. =cut
  1636.  
  1637. sub _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.  
  1654. Return a string that can be used as an internal reference
  1655. in a C<latex> document (i.e. accepted by the C<\label> command)
  1656.  
  1657.  $label = $parser->_create_label($string)
  1658.  
  1659. If UniqueLabels is true returns a label prefixed by Label()
  1660. This can be suppressed with an optional second argument.
  1661.  
  1662.  $label = $parser->_create_label($string, $suppress);
  1663.  
  1664. If a second argument is supplied (of any value including undef)
  1665. the Label() is never prefixed. This means that this routine can
  1666. be called to create a Label() without prefixing a previous setting.
  1667.  
  1668. =cut
  1669.  
  1670. sub _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.  
  1700. Similar to C<_create_label> except an index entry is created.
  1701. If C<UniqueLabels> is true, the index entry is prefixed by 
  1702. the current C<Label> and an exclamation mark.
  1703.  
  1704.   $ind = $parser->_create_index($paragraph);
  1705.  
  1706. An exclamation mark is used by C<makeindex> to generate 
  1707. sub-entries in an index.
  1708.  
  1709. =cut
  1710.  
  1711. sub _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.  
  1735. Removes latex commands from text. The latex command is assumed to be of the
  1736. form C<\command{ text }>. "C<text>" is retained
  1737.  
  1738.   $clean = $parser->_clean_latex_commands($text);
  1739.  
  1740. =cut
  1741.  
  1742. sub _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.  
  1762. Split the supplied string into two parts at approximately the
  1763. specified word boundary. Special care is made to make sure that it
  1764. does not split in the middle of some curly brackets.
  1765.  
  1766. e.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.  
  1771. The 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.
  1778. sub _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.  
  1826. Compatible with C<latex2e> only. Can not be used with C<latex> v2.09
  1827. or earlier.
  1828.  
  1829. A subclass of C<Pod::Select> so that specific pod sections can be
  1830. converted to C<latex> by using the C<select> method.
  1831.  
  1832. Some HTML escapes are missing and many have not been tested.
  1833.  
  1834. =head1 SEE ALSO
  1835.  
  1836. L<Pod::Parser>, L<Pod::Select>, L<pod2latex>
  1837.  
  1838. =head1 AUTHORS
  1839.  
  1840. Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt>
  1841.  
  1842. Bug fixes and improvements have been received from: Simon Cozens
  1843. E<lt>simon@cozens.netE<gt>, Mark A. Hershberger
  1844. E<lt>mah@everybody.orgE<gt>, Marcel Grunauer
  1845. E<lt>marcel@codewerk.comE<gt>, Hugh S Myers
  1846. E<lt>hsmyers@sdragons.comE<gt>, Peter J Acklam
  1847. E<lt>jacklam@math.uio.noE<gt>, Sudhi Herle E<lt>sudhi@herle.netE<gt>
  1848. and Ariel Scolnicov E<lt>ariels@compugen.co.ilE<gt>.
  1849.  
  1850.  
  1851. =head1 COPYRIGHT
  1852.  
  1853. Copyright (C) 2000-2003 Tim Jenness. All Rights Reserved.
  1854.  
  1855. This program is free software; you can redistribute it and/or modify
  1856. it 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.  
  1868. 1;
  1869.