Edit File: LaTeX.pm
package Pod::LaTeX; =head1 NAME Pod::LaTeX - Convert Pod data to formatted Latex =head1 SYNOPSIS use Pod::LaTeX; my $parser = Pod::LaTeX->new ( ); $parser->parse_from_filehandle; $parser->parse_from_file ('file.pod', 'file.tex'); =head1 DESCRIPTION C<Pod::LaTeX> is a module to convert documentation in the Pod format into Latex. The L<B<pod2latex>|pod2latex> X<pod2latex> command uses this module for translation. C<Pod::LaTeX> is a derived class from L<Pod::Select|Pod::Select>. =cut use strict; require Pod::ParseUtils; use base qw/ Pod::Select /; use if $] > 5.017, 'deprecate'; # use Data::Dumper; # for debugging use Carp; use vars qw/ $VERSION %HTML_Escapes @LatexSections /; $VERSION = '0.61'; # Definitions of =headN -> latex mapping @LatexSections = (qw/ chapter section subsection subsubsection paragraph subparagraph /); # Standard escape sequences converted to Latex. # The Unicode name of each character is given in the comments. # Complete LaTeX set added by Peter Acklam. %HTML_Escapes = ( 'sol' => '\textfractionsolidus{}', # xxx - or should it be just '/' 'verbar' => '|', # The stuff below is based on the information available at # http://www.w3.org/TR/html401/sgml/entities.html # All characters in the range 0xA0-0xFF of the ISO 8859-1 character set. # Several of these characters require the `textcomp' LaTeX package. 'nbsp' => q|~|, # 0xA0 - no-break space = non-breaking space 'iexcl' => q|\textexclamdown{}|, # 0xA1 - inverted exclamation mark 'cent' => q|\textcent{}|, # 0xA2 - cent sign 'pound' => q|\textsterling{}|, # 0xA3 - pound sign 'curren' => q|\textcurrency{}|, # 0xA4 - currency sign 'yen' => q|\textyen{}|, # 0xA5 - yen sign = yuan sign 'brvbar' => q|\textbrokenbar{}|, # 0xA6 - broken bar = broken vertical bar 'sect' => q|\textsection{}|, # 0xA7 - section sign 'uml' => q|\textasciidieresis{}|, # 0xA8 - diaeresis = spacing diaeresis 'copy' => q|\textcopyright{}|, # 0xA9 - copyright sign 'ordf' => q|\textordfeminine{}|, # 0xAA - feminine ordinal indicator 'laquo' => q|\guillemotleft{}|, # 0xAB - left-pointing double angle quotation mark = left pointing guillemet 'not' => q|\textlnot{}|, # 0xAC - not sign 'shy' => q|\-|, # 0xAD - soft hyphen = discretionary hyphen 'reg' => q|\textregistered{}|, # 0xAE - registered sign = registered trade mark sign 'macr' => q|\textasciimacron{}|, # 0xAF - macron = spacing macron = overline = APL overbar 'deg' => q|\textdegree{}|, # 0xB0 - degree sign 'plusmn' => q|\textpm{}|, # 0xB1 - plus-minus sign = plus-or-minus sign 'sup2' => q|\texttwosuperior{}|, # 0xB2 - superscript two = superscript digit two = squared 'sup3' => q|\textthreesuperior{}|, # 0xB3 - superscript three = superscript digit three = cubed 'acute' => q|\textasciiacute{}|, # 0xB4 - acute accent = spacing acute 'micro' => q|\textmu{}|, # 0xB5 - micro sign 'para' => q|\textparagraph{}|, # 0xB6 - pilcrow sign = paragraph sign 'middot' => q|\textperiodcentered{}|, # 0xB7 - middle dot = Georgian comma = Greek middle dot 'cedil' => q|\c{}|, # 0xB8 - cedilla = spacing cedilla 'sup1' => q|\textonesuperior{}|, # 0xB9 - superscript one = superscript digit one 'ordm' => q|\textordmasculine{}|, # 0xBA - masculine ordinal indicator 'raquo' => q|\guillemotright{}|, # 0xBB - right-pointing double angle quotation mark = right pointing guillemet 'frac14' => q|\textonequarter{}|, # 0xBC - vulgar fraction one quarter = fraction one quarter 'frac12' => q|\textonehalf{}|, # 0xBD - vulgar fraction one half = fraction one half 'frac34' => q|\textthreequarters{}|, # 0xBE - vulgar fraction three quarters = fraction three quarters 'iquest' => q|\textquestiondown{}|, # 0xBF - inverted question mark = turned question mark 'Agrave' => q|\`A|, # 0xC0 - latin capital letter A with grave = latin capital letter A grave 'Aacute' => q|\'A|, # 0xC1 - latin capital letter A with acute 'Acirc' => q|\^A|, # 0xC2 - latin capital letter A with circumflex 'Atilde' => q|\~A|, # 0xC3 - latin capital letter A with tilde 'Auml' => q|\"A|, # 0xC4 - latin capital letter A with diaeresis 'Aring' => q|\AA{}|, # 0xC5 - latin capital letter A with ring above = latin capital letter A ring 'AElig' => q|\AE{}|, # 0xC6 - latin capital letter AE = latin capital ligature AE 'Ccedil' => q|\c{C}|, # 0xC7 - latin capital letter C with cedilla 'Egrave' => q|\`E|, # 0xC8 - latin capital letter E with grave 'Eacute' => q|\'E|, # 0xC9 - latin capital letter E with acute 'Ecirc' => q|\^E|, # 0xCA - latin capital letter E with circumflex 'Euml' => q|\"E|, # 0xCB - latin capital letter E with diaeresis 'Igrave' => q|\`I|, # 0xCC - latin capital letter I with grave 'Iacute' => q|\'I|, # 0xCD - latin capital letter I with acute 'Icirc' => q|\^I|, # 0xCE - latin capital letter I with circumflex 'Iuml' => q|\"I|, # 0xCF - latin capital letter I with diaeresis 'ETH' => q|\DH{}|, # 0xD0 - latin capital letter ETH 'Ntilde' => q|\~N|, # 0xD1 - latin capital letter N with tilde 'Ograve' => q|\`O|, # 0xD2 - latin capital letter O with grave 'Oacute' => q|\'O|, # 0xD3 - latin capital letter O with acute 'Ocirc' => q|\^O|, # 0xD4 - latin capital letter O with circumflex 'Otilde' => q|\~O|, # 0xD5 - latin capital letter O with tilde 'Ouml' => q|\"O|, # 0xD6 - latin capital letter O with diaeresis 'times' => q|\texttimes{}|, # 0xD7 - multiplication sign 'Oslash' => q|\O{}|, # 0xD8 - latin capital letter O with stroke = latin capital letter O slash 'Ugrave' => q|\`U|, # 0xD9 - latin capital letter U with grave 'Uacute' => q|\'U|, # 0xDA - latin capital letter U with acute 'Ucirc' => q|\^U|, # 0xDB - latin capital letter U with circumflex 'Uuml' => q|\"U|, # 0xDC - latin capital letter U with diaeresis 'Yacute' => q|\'Y|, # 0xDD - latin capital letter Y with acute 'THORN' => q|\TH{}|, # 0xDE - latin capital letter THORN 'szlig' => q|\ss{}|, # 0xDF - latin small letter sharp s = ess-zed 'agrave' => q|\`a|, # 0xE0 - latin small letter a with grave = latin small letter a grave 'aacute' => q|\'a|, # 0xE1 - latin small letter a with acute 'acirc' => q|\^a|, # 0xE2 - latin small letter a with circumflex 'atilde' => q|\~a|, # 0xE3 - latin small letter a with tilde 'auml' => q|\"a|, # 0xE4 - latin small letter a with diaeresis 'aring' => q|\aa{}|, # 0xE5 - latin small letter a with ring above = latin small letter a ring 'aelig' => q|\ae{}|, # 0xE6 - latin small letter ae = latin small ligature ae 'ccedil' => q|\c{c}|, # 0xE7 - latin small letter c with cedilla 'egrave' => q|\`e|, # 0xE8 - latin small letter e with grave 'eacute' => q|\'e|, # 0xE9 - latin small letter e with acute 'ecirc' => q|\^e|, # 0xEA - latin small letter e with circumflex 'euml' => q|\"e|, # 0xEB - latin small letter e with diaeresis 'igrave' => q|\`i|, # 0xEC - latin small letter i with grave 'iacute' => q|\'i|, # 0xED - latin small letter i with acute 'icirc' => q|\^i|, # 0xEE - latin small letter i with circumflex 'iuml' => q|\"i|, # 0xEF - latin small letter i with diaeresis 'eth' => q|\dh{}|, # 0xF0 - latin small letter eth 'ntilde' => q|\~n|, # 0xF1 - latin small letter n with tilde 'ograve' => q|\`o|, # 0xF2 - latin small letter o with grave 'oacute' => q|\'o|, # 0xF3 - latin small letter o with acute 'ocirc' => q|\^o|, # 0xF4 - latin small letter o with circumflex 'otilde' => q|\~o|, # 0xF5 - latin small letter o with tilde 'ouml' => q|\"o|, # 0xF6 - latin small letter o with diaeresis 'divide' => q|\textdiv{}|, # 0xF7 - division sign 'oslash' => q|\o{}|, # 0xF8 - latin small letter o with stroke, = latin small letter o slash 'ugrave' => q|\`u|, # 0xF9 - latin small letter u with grave 'uacute' => q|\'u|, # 0xFA - latin small letter u with acute 'ucirc' => q|\^u|, # 0xFB - latin small letter u with circumflex 'uuml' => q|\"u|, # 0xFC - latin small letter u with diaeresis 'yacute' => q|\'y|, # 0xFD - latin small letter y with acute 'thorn' => q|\th{}|, # 0xFE - latin small letter thorn 'yuml' => q|\"y|, # 0xFF - latin small letter y with diaeresis # Latin Extended-B 'fnof' => q|\textflorin{}|, # latin small f with hook = function = florin # Greek 'Alpha' => q|$\mathrm{A}$|, # greek capital letter alpha 'Beta' => q|$\mathrm{B}$|, # greek capital letter beta 'Gamma' => q|$\Gamma$|, # greek capital letter gamma 'Delta' => q|$\Delta$|, # greek capital letter delta 'Epsilon' => q|$\mathrm{E}$|, # greek capital letter epsilon 'Zeta' => q|$\mathrm{Z}$|, # greek capital letter zeta 'Eta' => q|$\mathrm{H}$|, # greek capital letter eta 'Theta' => q|$\Theta$|, # greek capital letter theta 'Iota' => q|$\mathrm{I}$|, # greek capital letter iota 'Kappa' => q|$\mathrm{K}$|, # greek capital letter kappa 'Lambda' => q|$\Lambda$|, # greek capital letter lambda 'Mu' => q|$\mathrm{M}$|, # greek capital letter mu 'Nu' => q|$\mathrm{N}$|, # greek capital letter nu 'Xi' => q|$\Xi$|, # greek capital letter xi 'Omicron' => q|$\mathrm{O}$|, # greek capital letter omicron 'Pi' => q|$\Pi$|, # greek capital letter pi 'Rho' => q|$\mathrm{R}$|, # greek capital letter rho 'Sigma' => q|$\Sigma$|, # greek capital letter sigma 'Tau' => q|$\mathrm{T}$|, # greek capital letter tau 'Upsilon' => q|$\Upsilon$|, # greek capital letter upsilon 'Phi' => q|$\Phi$|, # greek capital letter phi 'Chi' => q|$\mathrm{X}$|, # greek capital letter chi 'Psi' => q|$\Psi$|, # greek capital letter psi 'Omega' => q|$\Omega$|, # greek capital letter omega 'alpha' => q|$\alpha$|, # greek small letter alpha 'beta' => q|$\beta$|, # greek small letter beta 'gamma' => q|$\gamma$|, # greek small letter gamma 'delta' => q|$\delta$|, # greek small letter delta 'epsilon' => q|$\epsilon$|, # greek small letter epsilon 'zeta' => q|$\zeta$|, # greek small letter zeta 'eta' => q|$\eta$|, # greek small letter eta 'theta' => q|$\theta$|, # greek small letter theta 'iota' => q|$\iota$|, # greek small letter iota 'kappa' => q|$\kappa$|, # greek small letter kappa 'lambda' => q|$\lambda$|, # greek small letter lambda 'mu' => q|$\mu$|, # greek small letter mu 'nu' => q|$\nu$|, # greek small letter nu 'xi' => q|$\xi$|, # greek small letter xi 'omicron' => q|$o$|, # greek small letter omicron 'pi' => q|$\pi$|, # greek small letter pi 'rho' => q|$\rho$|, # greek small letter rho # 'sigmaf' => q||, # greek small letter final sigma 'sigma' => q|$\sigma$|, # greek small letter sigma 'tau' => q|$\tau$|, # greek small letter tau 'upsilon' => q|$\upsilon$|, # greek small letter upsilon 'phi' => q|$\phi$|, # greek small letter phi 'chi' => q|$\chi$|, # greek small letter chi 'psi' => q|$\psi$|, # greek small letter psi 'omega' => q|$\omega$|, # greek small letter omega # 'thetasym' => q||, # greek small letter theta symbol # 'upsih' => q||, # greek upsilon with hook symbol # 'piv' => q||, # greek pi symbol # General Punctuation 'bull' => q|\textbullet{}|, # bullet = black small circle # bullet is NOT the same as bullet operator 'hellip' => q|\textellipsis{}|, # horizontal ellipsis = three dot leader 'prime' => q|\textquotesingle{}|, # prime = minutes = feet 'Prime' => q|\textquotedbl{}|, # double prime = seconds = inches 'oline' => q|\textasciimacron{}|, # overline = spacing overscore 'frasl' => q|\textfractionsolidus{}|, # fraction slash # Letterlike Symbols 'weierp' => q|$\wp$|, # script capital P = power set = Weierstrass p 'image' => q|$\Re$|, # blackletter capital I = imaginary part 'real' => q|$\Im$|, # blackletter capital R = real part symbol 'trade' => q|\texttrademark{}|, # trade mark sign # 'alefsym' => q||, # alef symbol = first transfinite cardinal # alef symbol is NOT the same as hebrew letter alef, although the same # glyph could be used to depict both characters # Arrows 'larr' => q|\textleftarrow{}|, # leftwards arrow 'uarr' => q|\textuparrow{}|, # upwards arrow 'rarr' => q|\textrightarrow{}|, # rightwards arrow 'darr' => q|\textdownarrow{}|, # downwards arrow 'harr' => q|$\leftrightarrow$|, # left right arrow # 'crarr' => q||, # downwards arrow with corner leftwards = carriage return 'lArr' => q|$\Leftarrow$|, # leftwards double arrow # ISO 10646 does not say that lArr is the same as the 'is implied by' # arrow but also does not have any other character for that function. So # lArr can be used for 'is implied by' as ISOtech suggests 'uArr' => q|$\Uparrow$|, # upwards double arrow 'rArr' => q|$\Rightarrow$|, # rightwards double arrow # ISO 10646 does not say this is the 'implies' character but does not # have another character with this function so ? rArr can be used for # 'implies' as ISOtech suggests 'dArr' => q|$\Downarrow$|, # downwards double arrow 'hArr' => q|$\Leftrightarrow$|, # left right double arrow # Mathematical Operators. # Some of these require the `amssymb' package. 'forall' => q|$\forall$|, # for all 'part' => q|$\partial$|, # partial differential 'exist' => q|$\exists$|, # there exists 'empty' => q|$\emptyset$|, # empty set = null set = diameter 'nabla' => q|$\nabla$|, # nabla = backward difference 'isin' => q|$\in$|, # element of 'notin' => q|$\notin$|, # not an element of 'ni' => q|$\ni$|, # contains as member 'prod' => q|$\prod$|, # n-ary product = product sign # prod is NOT the same character as 'greek capital letter pi' though the # same glyph might be used for both 'sum' => q|$\sum$|, # n-ary summation # sum is NOT the same character as 'greek capital letter sigma' though # the same glyph might be used for both 'minus' => q|$-$|, # minus sign 'lowast' => q|$\ast$|, # asterisk operator 'radic' => q|$\surd$|, # square root = radical sign 'prop' => q|$\propto$|, # proportional to 'infin' => q|$\infty$|, # infinity 'ang' => q|$\angle$|, # angle 'and' => q|$\wedge$|, # logical and = wedge 'or' => q|$\vee$|, # logical or = vee 'cap' => q|$\cap$|, # intersection = cap 'cup' => q|$\cup$|, # union = cup 'int' => q|$\int$|, # integral 'there4' => q|$\therefore$|, # therefore 'sim' => q|$\sim$|, # tilde operator = varies with = similar to # tilde operator is NOT the same character as the tilde 'cong' => q|$\cong$|, # approximately equal to 'asymp' => q|$\asymp$|, # almost equal to = asymptotic to 'ne' => q|$\neq$|, # not equal to 'equiv' => q|$\equiv$|, # identical to 'le' => q|$\leq$|, # less-than or equal to 'ge' => q|$\geq$|, # greater-than or equal to 'sub' => q|$\subset$|, # subset of 'sup' => q|$\supset$|, # superset of # note that nsup, 'not a superset of' is not covered by the Symbol font # encoding and is not included. 'nsub' => q|$\not\subset$|, # not a subset of 'sube' => q|$\subseteq$|, # subset of or equal to 'supe' => q|$\supseteq$|, # superset of or equal to 'oplus' => q|$\oplus$|, # circled plus = direct sum 'otimes' => q|$\otimes$|, # circled times = vector product 'perp' => q|$\perp$|, # up tack = orthogonal to = perpendicular 'sdot' => q|$\cdot$|, # dot operator # dot operator is NOT the same character as middle dot # Miscellaneous Technical 'lceil' => q|$\lceil$|, # left ceiling = apl upstile 'rceil' => q|$\rceil$|, # right ceiling 'lfloor' => q|$\lfloor$|, # left floor = apl downstile 'rfloor' => q|$\rfloor$|, # right floor 'lang' => q|$\langle$|, # left-pointing angle bracket = bra # lang is NOT the same character as 'less than' or 'single left-pointing # angle quotation mark' 'rang' => q|$\rangle$|, # right-pointing angle bracket = ket # rang is NOT the same character as 'greater than' or 'single # right-pointing angle quotation mark' # Geometric Shapes 'loz' => q|$\lozenge$|, # lozenge # Miscellaneous Symbols 'spades' => q|$\spadesuit$|, # black spade suit 'clubs' => q|$\clubsuit$|, # black club suit = shamrock 'hearts' => q|$\heartsuit$|, # black heart suit = valentine 'diams' => q|$\diamondsuit$|, # black diamond suit # C0 Controls and Basic Latin 'quot' => q|"|, # quotation mark = APL quote ["] 'amp' => q|\&|, # ampersand 'lt' => q|<|, # less-than sign 'gt' => q|>|, # greater-than sign 'OElig' => q|\OE{}|, # latin capital ligature OE 'oelig' => q|\oe{}|, # latin small ligature oe 'Scaron' => q|\v{S}|, # latin capital letter S with caron 'scaron' => q|\v{s}|, # latin small letter s with caron 'Yuml' => q|\"Y|, # latin capital letter Y with diaeresis 'circ' => q|\textasciicircum{}|, # modifier letter circumflex accent 'tilde' => q|\textasciitilde{}|, # small tilde 'ensp' => q|\phantom{n}|, # en space 'emsp' => q|\hspace{1em}|, # em space 'thinsp' => q|\,|, # thin space 'zwnj' => q|{}|, # zero width non-joiner # 'zwj' => q||, # zero width joiner # 'lrm' => q||, # left-to-right mark # 'rlm' => q||, # right-to-left mark 'ndash' => q|--|, # en dash 'mdash' => q|---|, # em dash 'lsquo' => q|\textquoteleft{}|, # left single quotation mark 'rsquo' => q|\textquoteright{}|, # right single quotation mark 'sbquo' => q|\quotesinglbase{}|, # single low-9 quotation mark 'ldquo' => q|\textquotedblleft{}|, # left double quotation mark 'rdquo' => q|\textquotedblright{}|, # right double quotation mark 'bdquo' => q|\quotedblbase{}|, # double low-9 quotation mark 'dagger' => q|\textdagger{}|, # dagger 'Dagger' => q|\textdaggerdbl{}|, # double dagger 'permil' => q|\textperthousand{}|, # per mille sign 'lsaquo' => q|\guilsinglleft{}|, # single left-pointing angle quotation mark 'rsaquo' => q|\guilsinglright{}|, # single right-pointing angle quotation mark 'euro' => q|\texteuro{}|, # euro sign ); =head1 OBJECT METHODS The following methods are provided in this module. Methods inherited from C<Pod::Select> are not described in the public interface. =over 4 =begin __PRIVATE__ =item C<initialize> Initialise the object. This method is subclassed from C<Pod::Parser>. The base class method is invoked. This method defines the default behaviour of the object unless overridden by supplying arguments to the constructor. Internal settings are defaulted as well as the public instance data. Internal hash values are accessed directly (rather than through a method) and start with an underscore. This method should not be invoked by the user directly. =end __PRIVATE__ =cut # - An array for nested lists # Arguments have already been read by this point sub initialize { my $self = shift; # print Dumper($self); # Internals $self->{_Lists} = []; # For nested lists $self->{_suppress_all_para} = 0; # For =begin blocks $self->{_dont_modify_any_para}=0; # For =begin blocks $self->{_CURRENT_HEAD1} = ''; # Name of current HEAD1 section # Options - only initialise if not already set # Cause the '=head1 NAME' field to be treated specially # The contents of the NAME paragraph will be converted # to a section title. All subsequent =head1 will be converted # to =head2 and down. Will not affect =head1's prior to NAME # Assumes: 'Module - purpose' format # Also creates a purpose field # The name is used for Labeling of the subsequent subsections $self->{ReplaceNAMEwithSection} = 0 unless exists $self->{ReplaceNAMEwithSection}; $self->{AddPreamble} = 1 # make full latex document unless exists $self->{AddPreamble}; $self->{StartWithNewPage} = 0 # Start new page for pod section unless exists $self->{StartWithNewPage}; $self->{TableOfContents} = 0 # Add table of contents unless exists $self->{TableOfContents}; # only relevant if AddPreamble=1 $self->{AddPostamble} = 1 # Add closing latex code at end unless exists $self->{AddPostamble}; # effectively end{document} and index $self->{MakeIndex} = 1 # Add index (only relevant AddPostamble unless exists $self->{MakeIndex}; # and AddPreamble) $self->{UniqueLabels} = 1 # Use label unique for each pod unless exists $self->{UniqueLabels}; # either based on the filename # or supplied # Control the level of =head1. default is \section # $self->{Head1Level} = 1 # Offset in latex sections unless exists $self->{Head1Level}; # 0 is chapter, 2 is subsection # Control at which level numbering of sections is turned off # ie subsection becomes subsection* # The numbering is relative to the latex sectioning commands # and is independent of Pod heading level # default is to number \section but not \subsection $self->{LevelNoNum} = 2 unless exists $self->{LevelNoNum}; # Label to be used as prefix to all internal section names # If not defined will attempt to derive it from the filename # This can not happen when running parse_from_filehandle though # hence the ability to set the label externally # The label could then be Pod::Parser_DESCRIPTION or somesuch $self->{Label} = undef # label to be used as prefix unless exists $self->{Label}; # to all internal section names # These allow the caller to add arbitrary latex code to # start and end of document. AddPreamble and AddPostamble are ignored # if these are set. # Also MakeIndex and TableOfContents are also ignored. $self->{UserPreamble} = undef # User supplied start (AddPreamble =1) unless exists $self->{Label}; $self->{UserPostamble} = undef # Use supplied end (AddPostamble=1) unless exists $self->{Label}; # Run base initialize $self->SUPER::initialize; } =back =head2 Data Accessors The following methods are provided for accessing instance data. These methods should be used for accessing configuration parameters rather than assuming the object is a hash. Default values can be supplied by using these names as keys to a hash of arguments when using the C<new()> constructor. =over 4 =item B<AddPreamble> Logical to control whether a C<latex> preamble is to be written. If true, a valid C<latex> preamble is written before the pod data is written. This is similar to: \documentclass{article} \usepackage[T1]{fontenc} \usepackage{textcomp} \begin{document} but will be more complicated if table of contents and indexing are required. Can be used to set or retrieve the current value. $add = $parser->AddPreamble(); $parser->AddPreamble(1); If used in conjunction with C<AddPostamble> a full latex document will be written that could be immediately processed by C<latex>. For some pod escapes it may be necessary to include the amsmath package. This is not yet added to the preamble automatically. =cut sub AddPreamble { my $self = shift; if (@_) { $self->{AddPreamble} = shift; } return $self->{AddPreamble}; } =item B<AddPostamble> Logical to control whether a standard C<latex> ending is written to the output file after the document has been processed. In its simplest form this is simply: \end{document} but can be more complicated if a index is required. Can be used to set or retrieve the current value. $add = $parser->AddPostamble(); $parser->AddPostamble(1); If used in conjunction with C<AddPreaamble> a full latex document will be written that could be immediately processed by C<latex>. =cut sub AddPostamble { my $self = shift; if (@_) { $self->{AddPostamble} = shift; } return $self->{AddPostamble}; } =item B<Head1Level> The C<latex> sectioning level that should be used to correspond to a pod C<=head1> directive. This can be used, for example, to turn a C<=head1> into a C<latex> C<subsection>. This should hold a number corresponding to the required position in an array containing the following elements: [0] chapter [1] section [2] subsection [3] subsubsection [4] paragraph [5] subparagraph Can be used to set or retrieve the current value: $parser->Head1Level(2); $sect = $parser->Head1Level; Setting this number too high can result in sections that may not be reproducible in the expected way. For example, setting this to 4 would imply that C<=head3> do not have a corresponding C<latex> section (C<=head1> would correspond to a C<paragraph>). A check is made to ensure that the supplied value is an integer in the range 0 to 5. Default is for a value of 1 (i.e. a C<section>). =cut sub Head1Level { my $self = shift; if (@_) { my $arg = shift; if ($arg =~ /^\d$/ && $arg <= $#LatexSections) { $self->{Head1Level} = $arg; } else { carp "Head1Level supplied ($arg) must be integer in range 0 to ".$#LatexSections . "- Ignoring\n"; } } return $self->{Head1Level}; } =item B<Label> This is the label that is prefixed to all C<latex> label and index entries to make them unique. In general, pods have similarly titled sections (NAME, DESCRIPTION etc) and a C<latex> label will be multiply defined if more than one pod document is to be included in a single C<latex> file. To overcome this, this label is prefixed to a label whenever a label is required (joined with an underscore) or to an index entry (joined by an exclamation mark which is the normal index separator). For example, C<\label{text}> becomes C<\label{Label_text}>. Can be used to set or retrieve the current value: $label = $parser->Label; $parser->Label($label); This label is only used if C<UniqueLabels> is true. Its value is set automatically from the C<NAME> field if C<ReplaceNAMEwithSection> is true. If this is not the case it must be set manually before starting the parse. Default value is C<undef>. =cut sub Label { my $self = shift; if (@_) { $self->{Label} = shift; } return $self->{Label}; } =item B<LevelNoNum> Control the point at which C<latex> section numbering is turned off. For example, this can be used to make sure that C<latex> sections are numbered but subsections are not. Can be used to set or retrieve the current value: $lev = $parser->LevelNoNum; $parser->LevelNoNum(2); The argument must be an integer between 0 and 5 and is the same as the number described in C<Head1Level> method description. The number has nothing to do with the pod heading number, only the C<latex> sectioning. Default is 2. (i.e. C<latex> subsections are written as C<subsection*> but sections are numbered). =cut sub LevelNoNum { my $self = shift; if (@_) { $self->{LevelNoNum} = shift; } return $self->{LevelNoNum}; } =item B<MakeIndex> Controls whether C<latex> commands for creating an index are to be inserted into the preamble and postamble $makeindex = $parser->MakeIndex; $parser->MakeIndex(0); Irrelevant if both C<AddPreamble> and C<AddPostamble> are false (or equivalently, C<UserPreamble> and C<UserPostamble> are set). Default is for an index to be created. =cut sub MakeIndex { my $self = shift; if (@_) { $self->{MakeIndex} = shift; } return $self->{MakeIndex}; } =item B<ReplaceNAMEwithSection> This controls whether the C<NAME> section in the pod is to be translated literally or converted to a slightly modified output where the section name is the pod name rather than "NAME". If true, the pod segment =head1 NAME pod::name - purpose =head1 SYNOPSIS is converted to the C<latex> \section{pod::name\label{pod_name}\index{pod::name}} Purpose \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}% \index{pod::name!SYNOPSIS}} (dependent on the value of C<Head1Level> and C<LevelNoNum>). Note that subsequent C<head1> directives translate to subsections rather than sections and that the labels and index now include the pod name (dependent on the value of C<UniqueLabels>). The C<Label> is set from the pod name regardless of any current value of C<Label>. $mod = $parser->ReplaceNAMEwithSection; $parser->ReplaceNAMEwithSection(0); Default is to translate the pod literally. =cut sub ReplaceNAMEwithSection { my $self = shift; if (@_) { $self->{ReplaceNAMEwithSection} = shift; } return $self->{ReplaceNAMEwithSection}; } =item B<StartWithNewPage> If true, each pod translation will begin with a C<latex> C<\clearpage>. $parser->StartWithNewPage(1); $newpage = $parser->StartWithNewPage; Default is false. =cut sub StartWithNewPage { my $self = shift; if (@_) { $self->{StartWithNewPage} = shift; } return $self->{StartWithNewPage}; } =item B<TableOfContents> If true, a table of contents will be created. Irrelevant if C<AddPreamble> is false or C<UserPreamble> is set. $toc = $parser->TableOfContents; $parser->TableOfContents(1); Default is false. =cut sub TableOfContents { my $self = shift; if (@_) { $self->{TableOfContents} = shift; } return $self->{TableOfContents}; } =item B<UniqueLabels> If true, the translator will attempt to make sure that each C<latex> label or index entry will be uniquely identified by prefixing the contents of C<Label>. This allows multiple documents to be combined without clashing common labels such as C<DESCRIPTION> and C<SYNOPSIS> $parser->UniqueLabels(1); $unq = $parser->UniqueLabels; Default is true. =cut sub UniqueLabels { my $self = shift; if (@_) { $self->{UniqueLabels} = shift; } return $self->{UniqueLabels}; } =item B<UserPreamble> User supplied C<latex> preamble. Added before the pod translation data. If set, the contents will be prepended to the output file before the translated data regardless of the value of C<AddPreamble>. C<MakeIndex> and C<TableOfContents> will also be ignored. =cut sub UserPreamble { my $self = shift; if (@_) { $self->{UserPreamble} = shift; } return $self->{UserPreamble}; } =item B<UserPostamble> User supplied C<latex> postamble. Added after the pod translation data. If set, the contents will be prepended to the output file after the translated data regardless of the value of C<AddPostamble>. C<MakeIndex> will also be ignored. =cut sub UserPostamble { my $self = shift; if (@_) { $self->{UserPostamble} = shift; } return $self->{UserPostamble}; } =begin __PRIVATE__ =item B<Lists> Contains details of the currently active lists. The array contains C<Pod::List> objects. A new C<Pod::List> object is created each time a list is encountered and it is pushed onto this stack. When the list context ends, it is popped from the stack. The array will be empty if no lists are active. Returns array of list information in list context Returns array ref in scalar context =cut sub lists { my $self = shift; return @{ $self->{_Lists} } if wantarray(); return $self->{_Lists}; } =end __PRIVATE__ =back =begin __PRIVATE__ =head2 Subclassed methods The following methods override methods provided in the C<Pod::Select> base class. See C<Pod::Parser> and C<Pod::Select> for more information on what these methods require. =over 4 =cut ######### END ACCESSORS ################### # Opening pod =item B<begin_pod> Writes the C<latex> preamble if requested. Only writes something if AddPreamble is true. Writes a standard header unless a UserPreamble is defined. =cut sub begin_pod { my $self = shift; # Get the pod identification # This should really come from the '=head1 NAME' paragraph my $infile = $self->input_file; my $class = ref($self); my $date = gmtime(time); # Comment message to say where this came from my $comment = << "__TEX_COMMENT__"; %% Latex generated from POD in document $infile %% Using the perl module $class %% Converted on $date __TEX_COMMENT__ # Write the preamble # If the caller has supplied one then we just use that my $preamble = ''; if ($self->AddPreamble) { if (defined $self->UserPreamble) { $preamble = $self->UserPreamble; # Add the description of where this came from $preamble .= "\n$comment\n%% Preamble supplied by user.\n\n"; } else { # Write our own preamble # Code to initialise index making # Use an array so that we can prepend comment if required my @makeidx = ( '\usepackage{makeidx}', '\makeindex', ); unless ($self->MakeIndex) { foreach (@makeidx) { $_ = '%% ' . $_; } } my $makeindex = join("\n",@makeidx) . "\n"; # Table of contents my $tableofcontents = '\tableofcontents'; $tableofcontents = '%% ' . $tableofcontents unless $self->TableOfContents; # Roll our own $preamble = << "__TEX_HEADER__"; \\documentclass{article} \\usepackage[T1]{fontenc} \\usepackage{textcomp} $comment $makeindex \\begin{document} $tableofcontents __TEX_HEADER__ } } # Write the header (blank if none) $self->_output($preamble); # Start on new page if requested $self->_output("\\clearpage\n") if $self->StartWithNewPage; } =item B<end_pod> Write the closing C<latex> code. Only writes something if AddPostamble is true. Writes a standard header unless a UserPostamble is defined. =cut sub end_pod { my $self = shift; # End string my $end = ''; # Use the user version of the postamble if defined if ($self->AddPostamble) { if (defined $self->UserPostamble) { $end = $self->UserPostamble; } else { # Check for index my $makeindex = '\printindex'; $makeindex = '%% '. $makeindex unless $self->MakeIndex; $end = "$makeindex\n\n\\end{document}\n"; } } $self->_output($end); } =item B<command> Process basic pod commands. =cut sub command { my $self = shift; my ($command, $paragraph, $line_num, $parobj) = @_; # return if we dont care return if $command eq 'pod'; # Store a copy of the raw text in case we are in a =for # block and need to preserve the existing latex my $rawpara = $paragraph; # Do the latex escapes $paragraph = $self->_replace_special_chars($paragraph); # Interpolate pod sequences in paragraph $paragraph = $self->interpolate($paragraph, $line_num); $paragraph =~ s/\s+$//; # Replace characters that can only be done after # interpolation of interior sequences $paragraph = $self->_replace_special_chars_late($paragraph); # Now run the command if ($command eq 'over') { $self->begin_list($paragraph, $line_num); } elsif ($command eq 'item') { $self->add_item($paragraph, $line_num); } elsif ($command eq 'back') { $self->end_list($line_num); } elsif ($command eq 'head1') { # Store the name of the section $self->{_CURRENT_HEAD1} = $paragraph; # Print it $self->head(1, $paragraph, $parobj); } elsif ($command eq 'head2') { $self->head(2, $paragraph, $parobj); } elsif ($command eq 'head3') { $self->head(3, $paragraph, $parobj); } elsif ($command eq 'head4') { $self->head(4, $paragraph, $parobj); } elsif ($command eq 'head5') { $self->head(5, $paragraph, $parobj); } elsif ($command eq 'head6') { $self->head(6, $paragraph, $parobj); } elsif ($command eq 'begin') { # pass through if latex if ($paragraph =~ /^latex/i) { # Make sure that subsequent paragraphs are not modfied before printing $self->{_dont_modify_any_para} = 1; } else { # Suppress all subsequent paragraphs unless # it is explicitly intended for latex $self->{_suppress_all_para} = 1; } } elsif ($command eq 'for') { # =for latex # some latex # With =for we will get the text for the full paragraph # as well as the format name. # We do not get an additional paragraph later on. The next # paragraph is not governed by the =for # The first line contains the format and the rest is the # raw code. my ($format, $chunk) = split(/\n/, $rawpara, 2); # If we have got some latex code print it out immediately # unmodified. Else do nothing. if ($format =~ /^latex/i) { # Make sure that next paragraph is not modfied before printing $self->_output( $chunk ); } } elsif ($command eq 'end') { # Reset suppression $self->{_suppress_all_para} = 0; $self->{_dont_modify_any_para} = 0; } elsif ($command eq 'pod') { # Do nothing } else { carp "Command $command not recognised at line $line_num\n"; } } =item B<verbatim> Verbatim text =cut sub verbatim { my $self = shift; my ($paragraph, $line_num, $parobj) = @_; # Expand paragraph unless in =begin block if ($self->{_dont_modify_any_para}) { # Just print as is $self->_output($paragraph); } else { return if $paragraph =~ /^\s+$/; # Clean trailing space $paragraph =~ s/\s+$//; # Clean tabs. Routine taken from Tabs.pm # by David Muir Sharnoff muir@idiom.com, # slightly modified by hsmyers@sdragons.com 10/22/01 my @l = split("\n",$paragraph); foreach (@l) { 1 while s/(^|\n)([^\t\n]*)(\t+)/ $1. $2 . (" " x (8 * length($3) - (length($2) % 8))) /sex; } $paragraph = join("\n",@l); # End of change. $self->_output('\begin{verbatim}' . "\n$paragraph\n". '\end{verbatim}'."\n"); } } =item B<textblock> Plain text paragraph. =cut sub textblock { my $self = shift; my ($paragraph, $line_num, $parobj) = @_; # print Dumper($self); # Expand paragraph unless in =begin block if ($self->{_dont_modify_any_para}) { # Just print as is $self->_output($paragraph); return; } # Escape latex special characters $paragraph = $self->_replace_special_chars($paragraph); # Interpolate interior sequences my $expansion = $self->interpolate($paragraph, $line_num); $expansion =~ s/\s+$//; # Escape special characters that can not be done earlier $expansion = $self->_replace_special_chars_late($expansion); # If we are replacing 'head1 NAME' with a section # we need to look in the paragraph and rewrite things # Need to make sure this is called only on the first paragraph # following 'head1 NAME' and not on subsequent paragraphs that may be # present. if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()) { # Strip white space from start and end $paragraph =~ s/^\s+//; $paragraph =~ s/\s$//; # Split the string into 2 parts my ($name, $purpose) = split(/\s+-\s+/, $expansion,2); # Now prevent this from triggering until a new head1 NAME is set $self->{_CURRENT_HEAD1} = '_NAME'; # Might want to clear the Label() before doing this (CHECK) # Print the heading $self->head(1, $name, $parobj); # Set the labeling in case we want unique names later $self->Label( $self->_create_label( $name, 1 ) ); # Raise the Head1Level by one so that subsequent =head1 appear # as subsections of the main name section unless we are already # at maximum [Head1Level() could check this itself - CHECK] $self->Head1Level( $self->Head1Level() + 1) unless $self->Head1Level == $#LatexSections; # Now write out the new latex paragraph $purpose = ucfirst($purpose); $self->_output("\n\n$purpose\n\n"); } else { # Just write the output $self->_output("\n\n$expansion\n\n"); } } =item B<interior_sequence> Interior sequence expansion =cut sub interior_sequence { my $self = shift; my ($seq_command, $seq_argument, $pod_seq) = @_; if ($seq_command eq 'B') { return "\\textbf{$seq_argument}"; } elsif ($seq_command eq 'I') { return "\\textit{$seq_argument}"; } elsif ($seq_command eq 'E') { # If it is simply a number if ($seq_argument =~ /^\d+$/) { return chr($seq_argument); # Look up escape in hash table } elsif (exists $HTML_Escapes{$seq_argument}) { return $HTML_Escapes{$seq_argument}; } else { my ($file, $line) = $pod_seq->file_line(); warn "Escape sequence $seq_argument not recognised at line $line of file $file\n"; return; } } elsif ($seq_command eq 'Z') { # Zero width space return '{}'; } elsif ($seq_command eq 'C') { return "\\texttt{$seq_argument}"; } elsif ($seq_command eq 'F') { return "\\emph{$seq_argument}"; } elsif ($seq_command eq 'S') { # non breakable spaces my $nbsp = '~'; $seq_argument =~ s/\s/$nbsp/g; return $seq_argument; } elsif ($seq_command eq 'L') { my $link = new Pod::Hyperlink($seq_argument); # undef on failure unless (defined $link) { carp $@; return; } # Handle internal links differently my $type = $link->type; my $page = $link->page; if ($type eq 'section' && $page eq '') { # Use internal latex reference my $node = $link->node; # Convert to a label $node = $self->_create_label($node); return "\\S\\ref{$node}"; } else { # Use default markup for external references # (although Starlink would use \xlabel) my $markup = $link->markup; my ($file, $line) = $pod_seq->file_line(); return $self->interpolate($link->markup, $line); } } elsif ($seq_command eq 'P') { # Special markup for Pod::Hyperlink # Replace :: with / - but not sure if I want to do this # any more. my $link = $seq_argument; $link =~ s|::|/|g; my $ref = "\\emph{$seq_argument}"; return $ref; } elsif ($seq_command eq 'Q') { # Special markup for Pod::Hyperlink return "\\textsf{$seq_argument}"; } elsif ($seq_command eq 'X') { # Index entries # use \index command # I will let '!' go through for now # not sure how sub categories are handled in X<> my $index = $self->_create_index($seq_argument); return "\\index{$index}\n"; } else { carp "Unknown sequence $seq_command<$seq_argument>"; } } =back =head2 List Methods Methods used to handle lists. =over 4 =item B<begin_list> Called when a new list is found (via the C<over> directive). Creates a new C<Pod::List> object and stores it on the list stack. $parser->begin_list($indent, $line_num); =cut sub begin_list { my $self = shift; my $indent = shift; my $line_num = shift; # Indicate that a list should be started for the next item # need to do this to work out the type of list push ( @{$self->lists}, new Pod::List(-indent => $indent, -start => $line_num, -file => $self->input_file, ) ); } =item B<end_list> Called when the end of a list is found (the C<back> directive). Pops the C<Pod::List> object off the stack of lists and writes the C<latex> code required to close a list. $parser->end_list($line_num); =cut sub end_list { my $self = shift; my $line_num = shift; unless (defined $self->lists->[-1]) { my $file = $self->input_file; warn "No list is active at line $line_num (file=$file). Missing =over?\n"; return; } # What to write depends on list type my $type = $self->lists->[-1]->type; # Don't write anything if the list type is not set # iomplying that a list was created but no entries were # placed in it (eg because of a =begin/=end combination) $self->_output("\\end{$type}\n") if (defined $type && length($type) > 0); # Clear list pop(@{ $self->lists}); } =item B<add_item> Add items to the list. The first time an item is encountered (determined from the state of the current C<Pod::List> object) the type of list is determined (ordered, unnumbered or description) and the relevant latex code issued. $parser->add_item($paragraph, $line_num); =cut sub add_item { my $self = shift; my $paragraph = shift; my $line_num = shift; unless (defined $self->lists->[-1]) { my $file = $self->input_file; warn "List has already ended by line $line_num of file $file. Missing =over?\n"; # Replace special chars # $paragraph = $self->_replace_special_chars($paragraph); $self->_output("$paragraph\n\n"); return; } # If paragraphs printing is turned off via =begin/=end or whatever # simply return immediately return if $self->{_suppress_all_para}; # Check to see whether we are starting a new lists if (scalar($self->lists->[-1]->item) == 0) { # Examine the paragraph to determine what type of list # we have $paragraph =~ s/\s+$//; $paragraph =~ s/^\s+//; my $type; if (substr($paragraph, 0,1) eq '*') { $type = 'itemize'; } elsif ($paragraph =~ /^\d/) { $type = 'enumerate'; } else { $type = 'description'; } $self->lists->[-1]->type($type); $self->_output("\\begin{$type}\n"); } my $type = $self->lists->[-1]->type; if ($type eq 'description') { # Handle long items - long items do not wrap # If the string is longer than 40 characters we split # it into a real item header and some bold text. my $maxlen = 40; my ($hunk1, $hunk2) = $self->_split_delimited( $paragraph, $maxlen ); # Print the first hunk $self->_output("\n\\item[{$hunk1}] "); # and the second hunk if it is defined if ($hunk2) { $self->_output("\\textbf{$hunk2}"); } else { # Not there so make sure we have a new line $self->_output("\\mbox{}"); } } else { # If the item was '* Something' or '\d+ something' we still need to write # out the something. Also allow 1) and 1. my $extra_info = $paragraph; $extra_info =~ s/^(\*|\d+[\.\)]?)\s*//; $self->_output("\n\\item $extra_info"); } # Store the item name in the object. Required so that # we can tell if the list is new or not $self->lists->[-1]->item($paragraph); } =back =head2 Methods for headings =over 4 =item B<head> Print a heading of the required level. $parser->head($level, $paragraph, $parobj); The first argument is the pod heading level. The second argument is the contents of the heading. The 3rd argument is a Pod::Paragraph object so that the line number can be extracted. =cut sub head { my $self = shift; my $num = shift; my $paragraph = shift; my $parobj = shift; # If we are replace 'head1 NAME' with a section # we return immediately if we get it return if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()); # Create a label my $label = $self->_create_label($paragraph); # Create an index entry my $index = $self->_create_index($paragraph); # Work out position in the above array taking into account # that =head1 is equivalent to $self->Head1Level my $level = $self->Head1Level() - 1 + $num; # Warn if heading to large if ($num > $#LatexSections) { my $line = $parobj->file_line; my $file = $self->input_file; warn "Heading level too large ($level) for LaTeX at line $line of file $file\n"; $level = $#LatexSections; } # Check to see whether section should be unnumbered my $star = ($level >= $self->LevelNoNum ? '*' : ''); # Section $self->_output("\\" .$LatexSections[$level] .$star ."{$paragraph\\label{".$label ."}\\index{".$index."}}\n"); } =back =end __PRIVATE__ =begin __PRIVATE__ =head2 Internal methods Internal routines are described in this section. They do not form part of the public interface. All private methods start with an underscore. =over 4 =item B<_output> Output text to the output filehandle. This method must be always be called to output parsed text. $parser->_output($text); Does not write anything if a =begin is active that should be ignored. =cut sub _output { my $self = shift; my $text = shift; print { $self->output_handle } $text unless $self->{_suppress_all_para}; } =item B<_replace_special_chars> Subroutine to replace characters that are special in C<latex> with the escaped forms $escaped = $parser->_replace_special_chars($paragraph); Need to call this routine before interior_sequences are munged but not if verbatim. It must be called before interpolation of interior sequences so that curly brackets and special latex characters inserted during interpolation are not themselves escaped. This means that < and > can not be modified here since the text still contains interior sequences. Special characters and the C<latex> equivalents are: } \} { \{ _ \_ $ \$ % \% & \& \ $\backslash$ ^ \^{} ~ \~{} # \# =cut sub _replace_special_chars { my $self = shift; my $paragraph = shift; # Replace a \ with $\backslash$ # This is made more complicated because the dollars will be escaped # by the subsequent replacement. Easiest to add \backslash # now and then add the dollars $paragraph =~ s/\\/\\backslash/g; # Must be done after escape of \ since this command adds latex escapes # Replace characters that can be escaped $paragraph =~ s/([\$\#&%_{}])/\\$1/g; # Replace ^ characters with \^{} so that $^F works okay $paragraph =~ s/(\^)/\\$1\{\}/g; # Replace tilde (~) with \texttt{\~{}} $paragraph =~ s/~/\\texttt\{\\~\{\}\}/g; # Now add the dollars around each \backslash $paragraph =~ s/(\\backslash)/\$$1\$/g; # Convert ------ to -{}-{}-{}-{}-{}- $paragraph =~ s/-(?=-)/-{}/g; return $paragraph; } =item B<_replace_special_chars_late> Replace special characters that can not be replaced before interior sequence interpolation. See C<_replace_special_chars> for a routine to replace special characters prior to interpolation of interior sequences. Does the following transformation: < $<$ > $>$ | $|$ =cut sub _replace_special_chars_late { my $self = shift; my $paragraph = shift; # < and > $paragraph =~ s/(<|>)/\$$1\$/g; # Replace | with $|$ $paragraph =~ s'\|'$|$'g; return $paragraph; } =item B<_create_label> Return a string that can be used as an internal reference in a C<latex> document (i.e. accepted by the C<\label> command) $label = $parser->_create_label($string) If UniqueLabels is true returns a label prefixed by Label() This can be suppressed with an optional second argument. $label = $parser->_create_label($string, $suppress); If a second argument is supplied (of any value including undef) the Label() is never prefixed. This means that this routine can be called to create a Label() without prefixing a previous setting. =cut sub _create_label { my $self = shift; my $paragraph = shift; my $suppress = (@_ ? 1 : 0 ); # Remove latex commands $paragraph = $self->_clean_latex_commands($paragraph); # Remove non alphanumerics from the label and replace with underscores # want to protect '-' though so use negated character classes $paragraph =~ s/[^-:\w]/_/g; # Multiple underscores will look unsightly so remove repeats # This will also have the advantage of tidying up the end and # start of string $paragraph =~ s/_+/_/g; # If required need to make sure that the label is unique # since it is possible to have multiple pods in a single # document if (!$suppress && $self->UniqueLabels() && defined $self->Label) { $paragraph = $self->Label() .'_'. $paragraph; } return $paragraph; } =item B<_create_index> Similar to C<_create_label> except an index entry is created. If C<UniqueLabels> is true, the index entry is prefixed by the current C<Label> and an exclamation mark. $ind = $parser->_create_index($paragraph); An exclamation mark is used by C<makeindex> to generate sub-entries in an index. =cut sub _create_index { my $self = shift; my $paragraph = shift; my $suppress = (@_ ? 1 : 0 ); # Remove latex commands $paragraph = $self->_clean_latex_commands($paragraph); # If required need to make sure that the index entry is unique # since it is possible to have multiple pods in a single # document if (!$suppress && $self->UniqueLabels() && defined $self->Label) { $paragraph = $self->Label() .'!'. $paragraph; } # Need to replace _ with space $paragraph =~ s/_/ /g; return $paragraph; } =item B<_clean_latex_commands> Removes latex commands from text. The latex command is assumed to be of the form C<\command{ text }>. "C<text>" is retained $clean = $parser->_clean_latex_commands($text); =cut sub _clean_latex_commands { my $self = shift; my $paragraph = shift; # Remove latex commands of the form \text{ } # and replace with the contents of the { } # need to make this non-greedy so that it can handle # "\text{a} and \text2{b}" # without converting it to # "a} and \text2{b" # This match will still get into trouble if \} is present # This is not vital since the subsequent replacement of non-alphanumeric # characters will tidy it up anyway $paragraph =~ s/\\\w+{(.*?)}/$1/g; return $paragraph } =item B<_split_delimited> Split the supplied string into two parts at approximately the specified word boundary. Special care is made to make sure that it does not split in the middle of some curly brackets. e.g. "this text is \textbf{very bold}" would not be split into "this text is \textbf{very" and " bold". ($hunk1, $hunk2) = $self->_split_delimited( $para, $length); The length indicates the maximum length of hunk1. =cut # initially Supplied by hsmyers@sdragons.com # 10/25/01, utility to split \hbox # busting lines. Reformatted by TimJ to match module style. sub _split_delimited { my $self = shift; my $input = shift; my $limit = shift; # Return immediately if already small return ($input, '') if length($input) < $limit; my @output; my $s = ''; my $t = ''; my $depth = 0; my $token; $input =~ s/\n/ /gm; $input .= ' '; foreach ( split ( //, $input ) ) { $token .= $_; if (/\{/) { $depth++; } elsif ( /}/ ) { $depth--; } elsif ( / / and $depth == 0) { push @output, $token if ( $token and $token ne ' ' ); $token = ''; } } foreach (@output) { if (length($s) < $limit) { $s .= $_; } else { $t .= $_; } } # Tidy up $s =~ s/\s+$//; $t =~ s/\s+$//; return ($s,$t); } =back =end __PRIVATE__ =head1 NOTES Compatible with C<latex2e> only. Can not be used with C<latex> v2.09 or earlier. A subclass of C<Pod::Select> so that specific pod sections can be converted to C<latex> by using the C<select> method. Some HTML escapes are missing and many have not been tested. =head1 SEE ALSO L<Pod::Parser>, L<Pod::Select>, L<pod2latex>, L<Pod::Simple>. =head1 AUTHORS Tim Jenness E<lt>tjenness@cpan.orgE<gt> Bug fixes and improvements have been received from: Simon Cozens E<lt>simon@cozens.netE<gt>, Mark A. Hershberger E<lt>mah@everybody.orgE<gt>, Marcel Grunauer E<lt>marcel@codewerk.comE<gt>, Hugh S Myers E<lt>hsmyers@sdragons.comE<gt>, Peter J Acklam E<lt>jacklam@math.uio.noE<gt>, Sudhi Herle E<lt>sudhi@herle.netE<gt>, Ariel Scolnicov E<lt>ariels@compugen.co.ilE<gt>, Adriano Rodrigues Ferreira E<lt>ferreira@triang.com.brE<gt>, R. de Vries E<lt>r.de.vries@dutchspace.nlE<gt> and Dave Mitchell E<lt>davem@iabyn.comE<gt>. =head1 COPYRIGHT Copyright (C) 2011 Tim Jenness. Copyright (C) 2000-2004 Tim Jenness. All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =begin __PRIVATE__ =head1 REVISION $Id$ =end __PRIVATE__ =cut 1;