1884 lines
58 KiB
Perl
1884 lines
58 KiB
Perl
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;
|