home *** CD-ROM | disk | FTP | other *** search
/ PC World 2003 March / PCWorld_2003-03_cd.bin / Software / Topware / activeperl / ActivePerl / Perl / lib / Pod / LaTeX.pm < prev    next >
Encoding:
Perl POD Document  |  2002-06-19  |  46.4 KB  |  1,718 lines
  1. package Pod::LaTeX;
  2.  
  3. =head1 NAME
  4.  
  5. Pod::LaTeX - Convert Pod data to formatted Latex
  6.  
  7. =head1 SYNOPSIS
  8.  
  9.   use Pod::LaTeX;
  10.   my $parser = Pod::LaTeX->new ( );
  11.  
  12.   $parser->parse_from_filehandle;
  13.  
  14.   $parser->parse_from_file ('file.pod', 'file.tex');
  15.  
  16. =head1 DESCRIPTION
  17.  
  18. C<Pod::LaTeX> is a module to convert documentation in the Pod format
  19. into Latex. The L<B<pod2latex>|pod2latex> X<pod2latex> command uses
  20. this module for translation.
  21.  
  22. C<Pod::LaTeX> is a derived class from L<Pod::Select|Pod::Select>.
  23.  
  24. =cut
  25.  
  26.  
  27. use strict;
  28. require Pod::ParseUtils;
  29. use base qw/ Pod::Select /;
  30.  
  31. # use Data::Dumper; # for debugging
  32. use Carp;
  33.  
  34. use vars qw/ $VERSION %HTML_Escapes @LatexSections /;
  35.  
  36. $VERSION = '0.54';
  37.  
  38. # Definitions of =headN -> latex mapping
  39. @LatexSections = (qw/
  40.           chapter
  41.           section
  42.           subsection
  43.           subsubsection
  44.           paragraph
  45.           subparagraph
  46.           /);
  47.  
  48. # Standard escape sequences converted to Latex
  49. # Up to "yuml" these are taken from the original pod2latex
  50. # command written by Taro Kawagish (kawagish@imslab.co.jp)
  51.  
  52.  
  53. %HTML_Escapes = (
  54.     # lt, gt and verbar are inserted without math mode
  55.     # since the $$ will be added during general correction
  56.     # for those escape characters
  57.     'amp'       =>      '\&',      #   ampersand
  58.     'lt'        =>      '<',    #   ' left chevron, less-than
  59.     'gt'        =>      '>',    #   ' right chevron, greater-than
  60.     'quot'      =>      '"',      #   double quote
  61.     'sol'       =>      '/',
  62.     'verbar'    =>      '|',
  63.  
  64.     "Aacute"    =>      "\\'{A}",       #   capital A, acute accent
  65.     "aacute"    =>      "\\'{a}",       #   small a, acute accent
  66.     "Acirc"     =>      "\\^{A}",       #   capital A, circumflex accent
  67.     "acirc"     =>      "\\^{a}",       #   small a, circumflex accent
  68.     "AElig"     =>      '\\AE',         #   capital AE diphthong (ligature)
  69.     "aelig"     =>      '\\ae',         #   small ae diphthong (ligature)
  70.     "Agrave"    =>      "\\`{A}",       #   capital A, grave accent
  71.     "agrave"    =>      "\\`{a}",       #   small a, grave accent
  72.     "Aring"     =>      '\\u{A}',       #   capital A, ring
  73.     "aring"     =>      '\\u{a}',       #   small a, ring
  74.     "Atilde"    =>      '\\~{A}',       #   capital A, tilde
  75.     "atilde"    =>      '\\~{a}',       #   small a, tilde
  76.     "Auml"      =>      '\\"{A}',       #   capital A, dieresis or umlaut mark
  77.     "auml"      =>      '\\"{a}',       #   small a, dieresis or umlaut mark
  78.     "Ccedil"    =>      '\\c{C}',       #   capital C, cedilla
  79.     "ccedil"    =>      '\\c{c}',       #   small c, cedilla
  80.     "Eacute"    =>      "\\'{E}",       #   capital E, acute accent
  81.     "eacute"    =>      "\\'{e}",       #   small e, acute accent
  82.     "Ecirc"     =>      "\\^{E}",       #   capital E, circumflex accent
  83.     "ecirc"     =>      "\\^{e}",       #   small e, circumflex accent
  84.     "Egrave"    =>      "\\`{E}",       #   capital E, grave accent
  85.     "egrave"    =>      "\\`{e}",       #   small e, grave accent
  86.     "ETH"       =>      '\\OE',         #   capital Eth, Icelandic
  87.     "eth"       =>      '\\oe',         #   small eth, Icelandic
  88.     "Euml"      =>      '\\"{E}',       #   capital E, dieresis or umlaut mark
  89.     "euml"      =>      '\\"{e}',       #   small e, dieresis or umlaut mark
  90.     "Iacute"    =>      "\\'{I}",       #   capital I, acute accent
  91.     "iacute"    =>      "\\'{i}",       #   small i, acute accent
  92.     "Icirc"     =>      "\\^{I}",       #   capital I, circumflex accent
  93.     "icirc"     =>      "\\^{i}",       #   small i, circumflex accent
  94.     "Igrave"    =>      "\\`{I}",       #   capital I, grave accent
  95.     "igrave"    =>      "\\`{i}",       #   small i, grave accent
  96.     "Iuml"      =>      '\\"{I}',       #   capital I, dieresis or umlaut mark
  97.     "iuml"      =>      '\\"{i}',       #   small i, dieresis or umlaut mark
  98.     "Ntilde"    =>      '\\~{N}',       #   capital N, tilde
  99.     "ntilde"    =>      '\\~{n}',       #   small n, tilde
  100.     "Oacute"    =>      "\\'{O}",       #   capital O, acute accent
  101.     "oacute"    =>      "\\'{o}",       #   small o, acute accent
  102.     "Ocirc"     =>      "\\^{O}",       #   capital O, circumflex accent
  103.     "ocirc"     =>      "\\^{o}",       #   small o, circumflex accent
  104.     "Ograve"    =>      "\\`{O}",       #   capital O, grave accent
  105.     "ograve"    =>      "\\`{o}",       #   small o, grave accent
  106.     "Oslash"    =>      "\\O",          #   capital O, slash
  107.     "oslash"    =>      "\\o",          #   small o, slash
  108.     "Otilde"    =>      "\\~{O}",       #   capital O, tilde
  109.     "otilde"    =>      "\\~{o}",       #   small o, tilde
  110.     "Ouml"      =>      '\\"{O}',       #   capital O, dieresis or umlaut mark
  111.     "ouml"      =>      '\\"{o}',       #   small o, dieresis or umlaut mark
  112.     "szlig"     =>      '\\ss{}',       #   small sharp s, German (sz ligature)
  113.     "THORN"     =>      '\\L',          #   capital THORN, Icelandic
  114.     "thorn"     =>      '\\l',,         #   small thorn, Icelandic
  115.     "Uacute"    =>      "\\'{U}",       #   capital U, acute accent
  116.     "uacute"    =>      "\\'{u}",       #   small u, acute accent
  117.     "Ucirc"     =>      "\\^{U}",       #   capital U, circumflex accent
  118.     "ucirc"     =>      "\\^{u}",       #   small u, circumflex accent
  119.     "Ugrave"    =>      "\\`{U}",       #   capital U, grave accent
  120.     "ugrave"    =>      "\\`{u}",       #   small u, grave accent
  121.     "Uuml"      =>      '\\"{U}',       #   capital U, dieresis or umlaut mark
  122.     "uuml"      =>      '\\"{u}',       #   small u, dieresis or umlaut mark
  123.     "Yacute"    =>      "\\'{Y}",       #   capital Y, acute accent
  124.     "yacute"    =>      "\\'{y}",       #   small y, acute accent
  125.     "yuml"      =>      '\\"{y}',       #   small y, dieresis or umlaut mark
  126.  
  127.     # Added by TimJ
  128.  
  129.     "iexcl"  =>   '!`',           # inverted exclamation mark
  130. #    "cent"   =>   ' ',        # cent sign
  131.     "pound"  =>   '\pounds',      # (UK) pound sign
  132. #    "curren" =>   ' ',        # currency sign
  133. #    "yen"    =>   ' ',        # yen sign
  134. #    "brvbar" =>   ' ',        # broken vertical bar
  135.     "sect"   =>   '\S',           # section sign
  136.     "uml"    =>   '\"{}',        # diaresis
  137.     "copy"   =>   '\copyright',   # Copyright symbol
  138. #    "ordf"   =>   ' ',        # feminine ordinal indicator
  139.     "laquo"  =>   '$\ll$',      # ' # left pointing double angle quotation mark
  140.     "not"    =>   '$\neg$',       # '  # not sign
  141.     "shy"    =>   '-',            # soft hyphen
  142. #    "reg"    =>   ' ',        # registered trademark
  143.     "macr"   =>   '$^-$',         # ' # macron, overline
  144.     "deg"    =>   '$^\circ$',     # '  # degree sign
  145.     "plusmn" =>   '$\pm$',        # ' # plus-minus sign
  146.     "sup2"   =>   '$^2$',         # ' # superscript 2
  147.     "sup3"   =>   '$^3$',         # ' # superscript 3
  148.     "acute"  =>   "\\'{}",        # acute accent
  149.     "micro"  =>   '$\mu$',        # micro sign
  150.     "para"   =>   '\P',           # pilcrow sign = paragraph sign
  151.     "middot" =>   '$\cdot$',      # middle dot = Georgian comma
  152.     "cedil"  =>   '\c{}',        # cedilla
  153.     "sup1"   =>   '$^1$',         # ' # superscript 1
  154. #    "ordm"   =>   ' ',        # masculine ordinal indicator
  155.     "raquo"  =>   '$\gg$',     # ' # right pointing double angle quotation mark
  156.     "frac14" =>   '$\frac{1}{4}$',   # ' # vulgar fraction one quarter
  157.     "frac12" =>   '$\frac{1}{2}$',   # ' # vulgar fraction one half
  158.     "frac34" =>   '$\frac{3}{4}$',   # ' # vulgar fraction three quarters
  159.     "iquest" =>   "?'",              # inverted question mark
  160.     "times"  =>   '$\times$',        # ' # multiplication sign
  161.     "divide" =>   '$\div$',          # division sign
  162.  
  163.     # Greek letters using HTML codes
  164.     "alpha"  =>   '$\alpha$',   # '
  165.     "beta"   =>   '$\beta$',    # '
  166.     "gamma"  =>   '$\gamma$',   # '
  167.     "delta"  =>   '$\delta$',   # '
  168.     "epsilon"=>   '$\epsilon$', # '
  169.     "zeta"   =>   '$\zeta$',    # '
  170.     "eta"    =>   '$\eta$',     # '
  171.     "theta"  =>   '$\theta$',   # '
  172.     "iota"   =>   '$\iota$',    # '
  173.     "kappa"  =>   '$\kappa$',   # '
  174.     "lambda" =>   '$\lambda$',  # '
  175.     "mu"     =>   '$\mu$',      # '
  176.     "nu"     =>   '$\nu$',      # '
  177.     "xi"     =>   '$\xi$',      # '
  178.     "omicron"=>   '$o$',        # '
  179.     "pi"     =>   '$\pi$',      # '
  180.     "rho"    =>   '$\rho$',     # '
  181.     "sigma"  =>   '$\sigma$',   # '
  182.     "tau"    =>   '$\tau$',     # '
  183.     "upsilon"=>   '$\upsilon$', # '
  184.     "phi"    =>   '$\phi$',     # '
  185.     "chi"    =>   '$\chi$',     # '
  186.     "psi"    =>   '$\psi$',     # '
  187.     "omega"  =>   '$\omega$',   # '
  188.  
  189.     "Alpha"  =>   '$A$',   # '
  190.     "Beta"   =>   '$B$',    # '
  191.     "Gamma"  =>   '$\Gamma$',   # '
  192.     "Delta"  =>   '$\Delta$',   # '
  193.     "Epsilon"=>   '$E$', # '
  194.     "Zeta"   =>   '$Z$',    # '
  195.     "Eta"    =>   '$H$',     # '
  196.     "Theta"  =>   '$\Theta$',   # '
  197.     "Iota"   =>   '$I$',    # '
  198.     "Kappa"  =>   '$K$',   # '
  199.     "Lambda" =>   '$\Lambda$',  # '
  200.     "Mu"     =>   '$M$',      # '
  201.     "Nu"     =>   '$N$',      # '
  202.     "Xi"     =>   '$\Xi$',      # '
  203.     "Omicron"=>   '$O$',        # '
  204.     "Pi"     =>   '$\Pi$',      # '
  205.     "Rho"    =>   '$R$',     # '
  206.     "Sigma"  =>   '$\Sigma$',   # '
  207.     "Tau"    =>   '$T$',     # '
  208.     "Upsilon"=>   '$\Upsilon$', # '
  209.     "Phi"    =>   '$\Phi$',     # '
  210.     "Chi"    =>   '$X$',     # '
  211.     "Psi"    =>   '$\Psi$',     # '
  212.     "Omega"  =>   '$\Omega$',   # '
  213.  
  214.  
  215. );
  216.  
  217.  
  218. =head1 OBJECT METHODS
  219.  
  220. The following methods are provided in this module. Methods inherited
  221. from C<Pod::Select> are not described in the public interface.
  222.  
  223. =over 4
  224.  
  225. =begin __PRIVATE__
  226.  
  227. =item C<initialize>
  228.  
  229. Initialise the object. This method is subclassed from C<Pod::Parser>.
  230. The base class method is invoked. This method defines the default
  231. behaviour of the object unless overridden by supplying arguments to
  232. the constructor. 
  233.  
  234. Internal settings are defaulted as well as the public instance data.
  235. Internal hash values are accessed directly (rather than through
  236. a method) and start with an underscore.
  237.  
  238. This method should not be invoked by the user directly.
  239.  
  240. =end __PRIVATE__
  241.  
  242. =cut
  243.  
  244.  
  245.  
  246. #   - An array for nested lists
  247.  
  248. # Arguments have already been read by this point
  249.  
  250. sub initialize {
  251.   my $self = shift;
  252.  
  253.   # print Dumper($self);
  254.  
  255.   # Internals
  256.   $self->{_Lists} = [];             # For nested lists
  257.   $self->{_suppress_all_para}  = 0; # For =begin blocks
  258.   $self->{_dont_modify_any_para}=0; # For =begin blocks
  259.   $self->{_CURRENT_HEAD1}   = '';   # Name of current HEAD1 section
  260.  
  261.   # Options - only initialise if not already set
  262.  
  263.   # Cause the '=head1 NAME' field to be treated specially
  264.   # The contents of the NAME paragraph will be converted
  265.   # to a section title. All subsequent =head1 will be converted
  266.   # to =head2 and down. Will not affect =head1's prior to NAME 
  267.   # Assumes:  'Module - purpose' format
  268.   # Also creates a purpose field
  269.   # The name is used for Labeling of the subsequent subsections
  270.   $self->{ReplaceNAMEwithSection} = 0
  271.     unless exists $self->{ReplaceNAMEwithSection};
  272.   $self->{AddPreamble}      = 1    # make full latex document
  273.     unless exists $self->{AddPreamble};
  274.   $self->{StartWithNewPage} = 0    # Start new page for pod section
  275.     unless exists $self->{StartWithNewPage};
  276.   $self->{TableOfContents}  = 0    # Add table of contents
  277.     unless exists $self->{TableOfContents};  # only relevent if AddPreamble=1
  278.    $self->{AddPostamble}     = 1          # Add closing latex code at end
  279.     unless exists $self->{AddPostamble}; #  effectively end{document} and index
  280.   $self->{MakeIndex}        = 1         # Add index (only relevant AddPostamble
  281.     unless exists $self->{MakeIndex};   # and AddPreamble)
  282.  
  283.   $self->{UniqueLabels}     = 1          # Use label unique for each pod
  284.     unless exists $self->{UniqueLabels}; # either based on the filename
  285.                                          # or supplied
  286.  
  287.   # Control the level of =head1. default is \section
  288.   # 
  289.   $self->{Head1Level}     = 1   # Offset in latex sections
  290.     unless exists $self->{Head1Level}; # 0 is chapter, 2 is subsection
  291.  
  292.   # Control at which level numbering of sections is turned off
  293.   # ie subsection becomes subsection*
  294.   # The numbering is relative to the latex sectioning commands
  295.   # and is independent of Pod heading level
  296.   # default is to number \section but not \subsection
  297.   $self->{LevelNoNum} = 2
  298.     unless exists $self->{LevelNoNum};
  299.  
  300.   # Label to be used as prefix to all internal section names
  301.   # If not defined will attempt to derive it from the filename
  302.   # This can not happen when running parse_from_filehandle though
  303.   # hence the ability to set the label externally
  304.   # The label could then be Pod::Parser_DESCRIPTION or somesuch
  305.  
  306.   $self->{Label}            = undef # label to be used as prefix
  307.     unless exists $self->{Label};   # to all internal section names
  308.  
  309.   # These allow the caller to add arbritrary latex code to
  310.   # start and end of document. AddPreamble and AddPostamble are ignored
  311.   # if these are set.
  312.   # Also MakeIndex and TableOfContents are also ignored.
  313.   $self->{UserPreamble}     = undef # User supplied start (AddPreamble =1)
  314.     unless exists $self->{Label};
  315.   $self->{UserPostamble}    = undef # Use supplied end    (AddPostamble=1)
  316.     unless exists $self->{Label};
  317.  
  318.   # Run base initialize
  319.   $self->SUPER::initialize;
  320.  
  321. }
  322.  
  323. =back
  324.  
  325. =head2 Data Accessors
  326.  
  327. The following methods are provided for accessing instance data. These
  328. methods should be used for accessing configuration parameters rather
  329. than assuming the object is a hash.
  330.  
  331. Default values can be supplied by using these names as keys to a hash
  332. of arguments when using the C<new()> constructor.
  333.  
  334. =over 4
  335.  
  336. =item B<AddPreamble>
  337.  
  338. Logical to control whether a C<latex> preamble is to be written.
  339. If true, a valid C<latex> preamble is written before the pod data
  340. is written.  This is similar to:
  341.  
  342.   \documentclass{article}
  343.   \begin{document}
  344.  
  345. but will be more complicated if table of contents and indexing are required.
  346. Can be used to set or retrieve the current value.
  347.  
  348.   $add = $parser->AddPreamble();
  349.   $parser->AddPreamble(1);
  350.  
  351. If used in conjunction with C<AddPostamble> a full latex document will
  352. be written that could be immediately processed by C<latex>.
  353.  
  354. =cut
  355.  
  356. sub AddPreamble {
  357.    my $self = shift;
  358.    if (@_) {
  359.      $self->{AddPreamble} = shift;
  360.    }
  361.    return $self->{AddPreamble};
  362. }
  363.  
  364. =item B<AddPostamble>
  365.  
  366. Logical to control whether a standard C<latex> ending is written to
  367. the output file after the document has been processed.  In its
  368. simplest form this is simply:
  369.  
  370.   \end{document}
  371.  
  372. but can be more complicated if an index is required.
  373. Can be used to set or retrieve the current value.
  374.  
  375.   $add = $parser->AddPostamble();
  376.   $parser->AddPostamble(1);
  377.  
  378. If used in conjunction with C<AddPreaamble> a full latex document will
  379. be written that could be immediately processed by C<latex>.
  380.  
  381. =cut
  382.  
  383. sub AddPostamble {
  384.    my $self = shift;
  385.    if (@_) {
  386.      $self->{AddPostamble} = shift;
  387.    }
  388.    return $self->{AddPostamble};
  389. }
  390.  
  391. =item B<Head1Level>
  392.  
  393. The C<latex> sectioning level that should be used to correspond to
  394. a pod C<=head1> directive. This can be used, for example, to turn
  395. a C<=head1> into a C<latex> C<subsection>. This should hold a number
  396. corresponding to the required position in an array containing the
  397. following elements:
  398.  
  399.  [0] chapter
  400.  [1] section
  401.  [2] subsection
  402.  [3] subsubsection
  403.  [4] paragraph
  404.  [5] subparagraph
  405.  
  406. Can be used to set or retrieve the current value:
  407.  
  408.   $parser->Head1Level(2);
  409.   $sect = $parser->Head1Level;
  410.  
  411. Setting this number too high can result in sections that may not be
  412. reproducible in the expected way. For example, setting this to 4 would
  413. imply that C<=head3> do not have a corresponding C<latex> section
  414. (C<=head1> would correspond to a C<paragraph>).
  415.  
  416. A check is made to ensure that the supplied value is an integer in the
  417. range 0 to 5.
  418.  
  419. Default is for a value of 1 (i.e. a C<section>).
  420.  
  421. =cut
  422.  
  423. sub Head1Level {
  424.    my $self = shift;
  425.    if (@_) {
  426.      my $arg = shift;
  427.      if ($arg =~ /^\d$/ && $arg <= $#LatexSections) {
  428.        $self->{Head1Level} = $arg;
  429.      } else {
  430.        carp "Head1Level supplied ($arg) must be integer in range 0 to ".$#LatexSections . "- Ignoring\n";
  431.      }
  432.    }
  433.    return $self->{Head1Level};
  434. }
  435.  
  436. =item B<Label>
  437.  
  438. This is the label that is prefixed to all C<latex> label and index
  439. entries to make them unique. In general, pods have similarly titled
  440. sections (NAME, DESCRIPTION etc) and a C<latex> label will be multiply
  441. defined if more than one pod document is to be included in a single
  442. C<latex> file. To overcome this, this label is prefixed to a label
  443. whenever a label is required (joined with an underscore) or to an
  444. index entry (joined by an exclamation mark which is the normal index
  445. separator). For example, C<\label{text}> becomes C<\label{Label_text}>.
  446.  
  447. Can be used to set or retrieve the current value:
  448.  
  449.   $label = $parser->Label;
  450.   $parser->Label($label);
  451.  
  452. This label is only used if C<UniqueLabels> is true.
  453. Its value is set automatically from the C<NAME> field
  454. if C<ReplaceNAMEwithSection> is true. If this is not the case
  455. it must be set manually before starting the parse.
  456.  
  457. Default value is C<undef>.
  458.  
  459. =cut
  460.  
  461. sub Label {
  462.    my $self = shift;
  463.    if (@_) {
  464.      $self->{Label} = shift;
  465.    }
  466.    return $self->{Label};
  467. }
  468.  
  469. =item B<LevelNoNum>
  470.  
  471. Control the point at which C<latex> section numbering is turned off.
  472. For example, this can be used to make sure that C<latex> sections
  473. are numbered but subsections are not.
  474.  
  475. Can be used to set or retrieve the current value:
  476.  
  477.   $lev = $parser->LevelNoNum;
  478.   $parser->LevelNoNum(2);
  479.  
  480. The argument must be an integer between 0 and 5 and is the same as the
  481. number described in C<Head1Level> method description. The number has
  482. nothing to do with the pod heading number, only the C<latex> sectioning.
  483.  
  484. Default is 2. (i.e. C<latex> subsections are written as C<subsection*>
  485. but sections are numbered).
  486.  
  487. =cut
  488.  
  489. sub LevelNoNum {
  490.    my $self = shift;
  491.    if (@_) {
  492.      $self->{LevelNoNum} = shift;
  493.    }
  494.    return $self->{LevelNoNum};
  495. }
  496.  
  497. =item B<MakeIndex>
  498.  
  499. Controls whether C<latex> commands for creating an index are to be inserted
  500. into the preamble and postamble
  501.  
  502.   $makeindex = $parser->MakeIndex;
  503.   $parser->MakeIndex(0);
  504.  
  505. Irrelevant if both C<AddPreamble> and C<AddPostamble> are false
  506. (or equivalently, C<UserPreamble> and C<UserPostamble> are set).
  507.  
  508. Default is for an index to be created.
  509.  
  510. =cut
  511.  
  512. sub MakeIndex {
  513.    my $self = shift;
  514.    if (@_) {
  515.      $self->{MakeIndex} = shift;
  516.    }
  517.    return $self->{MakeIndex};
  518. }
  519.  
  520. =item B<ReplaceNAMEwithSection>
  521.  
  522. This controls whether the C<NAME> section in the pod is to be translated
  523. literally or converted to a slightly modified output where the section
  524. name is the pod name rather than "NAME".
  525.  
  526. If true, the pod segment
  527.  
  528.   =head1 NAME
  529.  
  530.   pod::name - purpose
  531.  
  532.   =head1 SYNOPSIS
  533.  
  534. is converted to the C<latex>
  535.  
  536.   \section{pod::name\label{pod_name}\index{pod::name}}
  537.  
  538.   Purpose
  539.  
  540.   \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
  541.                \index{pod::name!SYNOPSIS}}
  542.  
  543. (dependent on the value of C<Head1Level> and C<LevelNoNum>). Note that
  544. subsequent C<head1> directives translate to subsections rather than
  545. sections and that the labels and index now include the pod name (dependent
  546. on the value of C<UniqueLabels>).
  547.  
  548. The C<Label> is set from the pod name regardless of any current value
  549. of C<Label>.
  550.  
  551.   $mod = $parser->ReplaceNAMEwithSection;
  552.   $parser->ReplaceNAMEwithSection(0);
  553.  
  554. Default is to translate the pod literally.
  555.  
  556. =cut
  557.  
  558. sub ReplaceNAMEwithSection {
  559.    my $self = shift;
  560.    if (@_) {
  561.      $self->{ReplaceNAMEwithSection} = shift;
  562.    }
  563.    return $self->{ReplaceNAMEwithSection};
  564. }
  565.  
  566. =item B<StartWithNewPage>
  567.  
  568. If true, each pod translation will begin with a C<latex>
  569. C<\clearpage>.
  570.  
  571.   $parser->StartWithNewPage(1);
  572.   $newpage = $parser->StartWithNewPage;
  573.  
  574. Default is false.
  575.  
  576. =cut
  577.  
  578. sub StartWithNewPage {
  579.    my $self = shift;
  580.    if (@_) {
  581.      $self->{StartWithNewPage} = shift;
  582.    }
  583.    return $self->{StartWithNewPage};
  584. }
  585.  
  586. =item B<TableOfContents>
  587.  
  588. If true, a table of contents will be created.
  589. Irrelevant if C<AddPreamble> is false or C<UserPreamble>
  590. is set.
  591.  
  592.   $toc = $parser->TableOfContents;
  593.   $parser->TableOfContents(1);
  594.  
  595. Default is false.
  596.  
  597. =cut
  598.  
  599. sub TableOfContents {
  600.    my $self = shift;
  601.    if (@_) {
  602.      $self->{TableOfContents} = shift;
  603.    }
  604.    return $self->{TableOfContents};
  605. }
  606.  
  607. =item B<UniqueLabels>
  608.  
  609. If true, the translator will attempt to make sure that
  610. each C<latex> label or index entry will be uniquely identified
  611. by prefixing the contents of C<Label>. This allows
  612. multiple documents to be combined without clashing 
  613. common labels such as C<DESCRIPTION> and C<SYNOPSIS>
  614.  
  615.   $parser->UniqueLabels(1);
  616.   $unq = $parser->UniqueLabels;
  617.  
  618. Default is true.
  619.  
  620. =cut
  621.  
  622. sub UniqueLabels {
  623.    my $self = shift;
  624.    if (@_) {
  625.      $self->{UniqueLabels} = shift;
  626.    }
  627.    return $self->{UniqueLabels};
  628. }
  629.  
  630. =item B<UserPreamble>
  631.  
  632. User supplied C<latex> preamble. Added before the pod translation
  633. data. 
  634.  
  635. If set, the contents will be prepended to the output file before
  636. the translated data regardless of the value of C<AddPreamble>.
  637. C<MakeIndex> and C<TableOfContents> will also be ignored.
  638.  
  639. =cut
  640.  
  641. sub UserPreamble {
  642.    my $self = shift;
  643.    if (@_) {
  644.      $self->{UserPreamble} = shift;
  645.    }
  646.    return $self->{UserPreamble};
  647. }
  648.  
  649. =item B<UserPostamble>
  650.  
  651. User supplied C<latex> postamble. Added after the pod translation
  652. data. 
  653.  
  654. If set, the contents will be prepended to the output file after
  655. the translated data regardless of the value of C<AddPostamble>.
  656. C<MakeIndex> will also be ignored.
  657.  
  658. =cut
  659.  
  660. sub UserPostamble {
  661.    my $self = shift;
  662.    if (@_) {
  663.      $self->{UserPostamble} = shift;
  664.    }
  665.    return $self->{UserPostamble};
  666. }
  667.  
  668. =begin __PRIVATE__
  669.  
  670. =item B<Lists>
  671.  
  672. Contains details of the currently active lists.
  673.   The array contains C<Pod::List> objects. A new C<Pod::List>
  674. object is created each time a list is encountered and it is
  675. pushed onto this stack. When the list context ends, it 
  676. is popped from the stack. The array will be empty if no
  677. lists are active.
  678.  
  679. Returns array of list information in list context
  680. Returns array ref in scalar context
  681.  
  682. =cut
  683.  
  684.  
  685.  
  686. sub lists {
  687.   my $self = shift;
  688.   return @{ $self->{_Lists} } if wantarray();
  689.   return $self->{_Lists};
  690. }
  691.  
  692. =end __PRIVATE__
  693.  
  694. =back
  695.  
  696. =begin __PRIVATE__
  697.  
  698. =head2 Subclassed methods
  699.  
  700. The following methods override methods provided in the C<Pod::Select>
  701. base class. See C<Pod::Parser> and C<Pod::Select> for more information
  702. on what these methods require.
  703.  
  704. =over 4
  705.  
  706. =cut
  707.  
  708. ######### END ACCESSORS ###################
  709.  
  710. # Opening pod
  711.  
  712. =item B<begin_pod>
  713.  
  714. Writes the C<latex> preamble if requested.
  715.  
  716. =cut
  717.  
  718. sub begin_pod {
  719.   my $self = shift;
  720.  
  721.   # Get the pod identification
  722.   # This should really come from the '=head1 NAME' paragraph
  723.  
  724.   my $infile = $self->input_file;
  725.   my $class = ref($self);
  726.   my $date = gmtime(time);
  727.  
  728.   # Comment message to say where this came from
  729.   my $comment = << "__TEX_COMMENT__";
  730. %%  Latex generated from POD in document $infile
  731. %%  Using the perl module $class
  732. %%  Converted on $date
  733. __TEX_COMMENT__
  734.  
  735.   # Write the preamble
  736.   # If the caller has supplied one then we just use that
  737.  
  738.   my $preamble = '';
  739.   if (defined $self->UserPreamble) {
  740.  
  741.     $preamble = $self->UserPreamble;
  742.  
  743.     # Add the description of where this came from
  744.     $preamble .=  "\n$comment";
  745.     
  746.  
  747.   } elsif ($self->AddPreamble) {
  748.     # Write our own preamble
  749.  
  750.     # Code to initialise index making
  751.     # Use an array so that we can prepend comment if required
  752.     my @makeidx = (
  753.            '\usepackage{makeidx}',
  754.            '\makeindex',
  755.           );
  756.  
  757.     unless ($self->MakeIndex) {
  758.       foreach (@makeidx) {
  759.     $_ = '%% ' . $_;
  760.       }
  761.     }
  762.     my $makeindex = join("\n",@makeidx) . "\n";
  763.  
  764.  
  765.     # Table of contents
  766.     my $tableofcontents = '\tableofcontents';
  767.     
  768.     $tableofcontents = '%% ' . $tableofcontents
  769.       unless $self->TableOfContents;
  770.  
  771.     # Roll our own
  772.     $preamble = << "__TEX_HEADER__";
  773. \\documentclass{article}
  774.  
  775. $comment
  776.  
  777. $makeindex
  778.  
  779. \\begin{document}
  780.  
  781. $tableofcontents
  782.  
  783. __TEX_HEADER__
  784.  
  785.   }
  786.  
  787.   # Write the header (blank if none)
  788.   $self->_output($preamble);
  789.  
  790.   # Start on new page if requested
  791.   $self->_output("\\clearpage\n") if $self->StartWithNewPage;
  792.  
  793. }
  794.  
  795.  
  796. =item B<end_pod>
  797.  
  798. Write the closing C<latex> code.
  799.  
  800. =cut
  801.  
  802. sub end_pod {
  803.   my $self = shift;
  804.  
  805.   # End string
  806.   my $end = '';
  807.  
  808.   # Use the user version of the postamble if deinfed
  809.   if (defined $self->UserPostamble) {
  810.     $end = $self->UserPostamble;
  811.  
  812.     $self->_output($end);
  813.  
  814.   } elsif ($self->AddPostamble) {
  815.  
  816.     # Check for index
  817.     my $makeindex = '\printindex';
  818.  
  819.     $makeindex = '%% '. $makeindex  unless $self->MakeIndex;
  820.  
  821.     $end = "$makeindex\n\n\\end{document}\n";
  822.   }
  823.  
  824.  
  825.   $self->_output($end);
  826.  
  827. }
  828.  
  829. =item B<command>
  830.  
  831. Process basic pod commands.
  832.  
  833. =cut
  834.  
  835. sub command {
  836.   my $self = shift;
  837.   my ($command, $paragraph, $line_num, $parobj) = @_;
  838.  
  839.   # return if we dont care
  840.   return if $command eq 'pod';
  841.  
  842.   # Store a copy of the raw text in case we are in a =for
  843.   # block and need to preserve the existing latex
  844.   my $rawpara = $paragraph;
  845.  
  846.   # Do the latex escapes
  847.   $paragraph = $self->_replace_special_chars($paragraph);
  848.  
  849.   # Interpolate pod sequences in paragraph
  850.   $paragraph = $self->interpolate($paragraph, $line_num);
  851.   $paragraph =~ s/\s+$//;
  852.  
  853.   # Replace characters that can only be done after 
  854.   # interpolation of interior sequences
  855.   $paragraph = $self->_replace_special_chars_late($paragraph);
  856.  
  857.   # Now run the command
  858.   if ($command eq 'over') {
  859.  
  860.     $self->begin_list($paragraph, $line_num);
  861.  
  862.   } elsif ($command eq 'item') {
  863.  
  864.     $self->add_item($paragraph, $line_num);
  865.  
  866.   } elsif ($command eq 'back') {
  867.  
  868.     $self->end_list($line_num);
  869.  
  870.   } elsif ($command eq 'head1') {
  871.  
  872.     # Store the name of the section
  873.     $self->{_CURRENT_HEAD1} = $paragraph;
  874.  
  875.     # Print it
  876.     $self->head(1, $paragraph, $parobj);
  877.  
  878.   } elsif ($command eq 'head2') {
  879.  
  880.     $self->head(2, $paragraph, $parobj);
  881.  
  882.   } elsif ($command eq 'head3') {
  883.  
  884.     $self->head(3, $paragraph, $parobj);
  885.  
  886.   } elsif ($command eq 'head4') {
  887.  
  888.     $self->head(4, $paragraph, $parobj);
  889.  
  890.   } elsif ($command eq 'head5') {
  891.  
  892.     $self->head(5, $paragraph, $parobj);
  893.  
  894.   } elsif ($command eq 'head6') {
  895.  
  896.     $self->head(6, $paragraph, $parobj);
  897.  
  898.   } elsif ($command eq 'begin') {
  899.  
  900.     # pass through if latex
  901.     if ($paragraph =~ /^latex/i) {
  902.       # Make sure that subsequent paragraphs are not modfied before printing
  903.       $self->{_dont_modify_any_para} = 1;
  904.  
  905.     } else {
  906.       # Suppress all subsequent paragraphs unless 
  907.       # it is explcitly intended for latex
  908.       $self->{_suppress_all_para} = 1;
  909.     }
  910.  
  911.   } elsif ($command eq 'for') {
  912.  
  913.     # =for latex
  914.     #   some latex
  915.  
  916.     # With =for we will get the text for the full paragraph
  917.     # as well as the format name.
  918.     # We do not get an additional paragraph later on. The next
  919.     # paragraph is not governed by the =for
  920.  
  921.     # The first line contains the format and the rest is the
  922.     # raw code.
  923.     my ($format, $chunk) = split(/\n/, $rawpara, 2);
  924.  
  925.     # If we have got some latex code print it out immediately
  926.     # unmodified. Else do nothing.
  927.     if ($format =~ /^latex/i) {
  928.       # Make sure that next paragraph is not modfied before printing
  929.       $self->_output( $chunk );
  930.  
  931.     }
  932.  
  933.   } elsif ($command eq 'end') {
  934.  
  935.     # Reset suppression
  936.     $self->{_suppress_all_para} = 0;
  937.     $self->{_dont_modify_any_para} = 0;
  938.  
  939.   } elsif ($command eq 'pod') {
  940.  
  941.     # Do nothing
  942.  
  943.   } else {
  944.     carp "Command $command not recognised at line $line_num\n";
  945.   }
  946.  
  947. }
  948.  
  949. =item B<verbatim>
  950.  
  951. Verbatim text
  952.  
  953. =cut
  954.  
  955. sub verbatim {
  956.   my $self = shift;
  957.   my ($paragraph, $line_num, $parobj) = @_;
  958.  
  959.   # Expand paragraph unless in =begin block
  960.   if ($self->{_dont_modify_any_para}) {
  961.     # Just print as is
  962.     $self->_output($paragraph);
  963.  
  964.   } else {
  965.  
  966.     return if $paragraph =~ /^\s+$/;
  967.  
  968.     # Clean trailing space
  969.     $paragraph =~ s/\s+$//;
  970.  
  971.     # Clean tabs. Routine taken from Tabs.pm
  972.     # by David Muir Sharnoff muir@idiom.com,
  973.     # slightly modified by hsmyers@sdragons.com 10/22/01
  974.     my @l = split("\n",$paragraph);
  975.     foreach (@l) {
  976.       1 while s/(^|\n)([^\t\n]*)(\t+)/
  977.     $1. $2 . (" " x 
  978.           (8 * length($3)
  979.            - (length($2) % 8)))
  980.       /sex;
  981.     }
  982.     $paragraph = join("\n",@l);
  983.     # End of change.
  984.  
  985.  
  986.  
  987.     $self->_output('\begin{verbatim}' . "\n$paragraph\n". '\end{verbatim}'."\n");
  988.   }
  989. }
  990.  
  991. =item B<textblock>
  992.  
  993. Plain text paragraph.
  994.  
  995. =cut
  996.  
  997. sub textblock {
  998.   my $self = shift;
  999.   my ($paragraph, $line_num, $parobj) = @_;
  1000.  
  1001.   # print Dumper($self);
  1002.  
  1003.   # Expand paragraph unless in =begin block
  1004.   if ($self->{_dont_modify_any_para}) {
  1005.     # Just print as is
  1006.     $self->_output($paragraph);
  1007.  
  1008.     return;
  1009.   }
  1010.  
  1011.  
  1012.   # Escape latex special characters
  1013.   $paragraph = $self->_replace_special_chars($paragraph);
  1014.  
  1015.   # Interpolate interior sequences
  1016.   my $expansion = $self->interpolate($paragraph, $line_num);
  1017.   $expansion =~ s/\s+$//;
  1018.  
  1019.   # Escape special characters that can not be done earlier
  1020.   $expansion = $self->_replace_special_chars_late($expansion);
  1021.  
  1022.   # If we are replacing 'head1 NAME' with a section
  1023.   # we need to look in the paragraph and rewrite things
  1024.   # Need to make sure this is called only on the first paragraph
  1025.   # following 'head1 NAME' and not on subsequent paragraphs that may be
  1026.   # present.
  1027.   if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()) {
  1028.  
  1029.     # Strip white space from start and end
  1030.     $paragraph =~ s/^\s+//;
  1031.     $paragraph =~ s/\s$//;
  1032.  
  1033.     # Split the string into 2 parts
  1034.     my ($name, $purpose) = split(/\s+-\s+/, $expansion,2);
  1035.  
  1036.     # Now prevent this from triggering until a new head1 NAME is set
  1037.     $self->{_CURRENT_HEAD1} = '_NAME';
  1038.  
  1039.     # Might want to clear the Label() before doing this (CHECK)
  1040.  
  1041.     # Print the heading
  1042.     $self->head(1, $name, $parobj);
  1043.  
  1044.     # Set the labeling in case we want unique names later
  1045.     $self->Label( $self->_create_label( $name, 1 ) );
  1046.  
  1047.     # Raise the Head1Level by one so that subsequent =head1 appear
  1048.     # as subsections of the main name section unless we are already
  1049.     # at maximum [Head1Level() could check this itself - CHECK]
  1050.     $self->Head1Level( $self->Head1Level() + 1)
  1051.       unless $self->Head1Level == $#LatexSections;
  1052.  
  1053.     # Now write out the new latex paragraph
  1054.     $purpose = ucfirst($purpose);
  1055.     $self->_output("\n\n$purpose\n\n");
  1056.  
  1057.   } else {
  1058.     # Just write the output
  1059.     $self->_output("\n\n$expansion\n\n");
  1060.   }
  1061.  
  1062. }
  1063.  
  1064. =item B<interior_sequence>
  1065.  
  1066. Interior sequence expansion
  1067.  
  1068. =cut
  1069.  
  1070. sub interior_sequence {
  1071.   my $self = shift;
  1072.  
  1073.   my ($seq_command, $seq_argument, $pod_seq) = @_;
  1074.  
  1075.   if ($seq_command eq 'B') {
  1076.     return "\\textbf{$seq_argument}";
  1077.  
  1078.   } elsif ($seq_command eq 'I') {
  1079.     return "\\textit{$seq_argument}";
  1080.  
  1081.   } elsif ($seq_command eq 'E') {
  1082.  
  1083.     # If it is simply a number
  1084.     if ($seq_argument =~ /^\d+$/) {
  1085.       return chr($seq_argument);
  1086.     # Look up escape in hash table
  1087.     } elsif (exists $HTML_Escapes{$seq_argument}) {
  1088.       return $HTML_Escapes{$seq_argument};
  1089.  
  1090.     } else {
  1091.       my ($file, $line) = $pod_seq->file_line();
  1092.       warn "Escape sequence $seq_argument not recognised at line $line of file $file\n";
  1093.       return;
  1094.     }
  1095.  
  1096.   } elsif ($seq_command eq 'Z') {
  1097.  
  1098.     # Zero width space
  1099.     return '$\!$'; # '
  1100.  
  1101.   } elsif ($seq_command eq 'C') {
  1102.     return "\\texttt{$seq_argument}";
  1103.  
  1104.   } elsif ($seq_command eq 'F') {
  1105.     return "\\emph{$seq_argument}";
  1106.  
  1107.   } elsif ($seq_command eq 'S') {
  1108.     # non breakable spaces
  1109.     my $nbsp = '$\:$'; #'
  1110.  
  1111.     $seq_argument =~ s/\s/$nbsp/g;
  1112.     return $seq_argument;
  1113.  
  1114.   } elsif ($seq_command eq 'L') {
  1115.  
  1116.     my $link = new Pod::Hyperlink($seq_argument);
  1117.  
  1118.     # undef on failure
  1119.     unless (defined $link) {
  1120.       carp $@;
  1121.       return;
  1122.     }
  1123.  
  1124.     # Handle internal links differently
  1125.     my $type = $link->type;
  1126.     my $page = $link->page;
  1127.  
  1128.     if ($type eq 'section' && $page eq '') {
  1129.       # Use internal latex reference 
  1130.       my $node = $link->node;
  1131.  
  1132.       # Convert to a label
  1133.       $node = $self->_create_label($node);
  1134.  
  1135.       return "\\S\\ref{$node}";
  1136.  
  1137.     } else {
  1138.       # Use default markup for external references
  1139.       # (although Starlink would use \xlabel)
  1140.       my $markup = $link->markup;
  1141.  
  1142.       my ($file, $line) = $pod_seq->file_line();
  1143.  
  1144.       return $self->interpolate($link->markup, $line);
  1145.     }
  1146.  
  1147.  
  1148.  
  1149.   } elsif ($seq_command eq 'P') {
  1150.     # Special markup for Pod::Hyperlink
  1151.     # Replace :: with / - but not sure if I want to do this
  1152.     # any more.
  1153.     my $link = $seq_argument;
  1154.     $link =~ s/::/\//g;
  1155.  
  1156.     my $ref = "\\emph{$seq_argument}";
  1157.     return $ref;
  1158.  
  1159.   } elsif ($seq_command eq 'Q') {
  1160.     # Special markup for Pod::Hyperlink
  1161.     return "\\textsf{$seq_argument}";
  1162.  
  1163.   } elsif ($seq_command eq 'X') {
  1164.     # Index entries
  1165.  
  1166.     # use \index command
  1167.     # I will let '!' go through for now
  1168.     # not sure how sub categories are handled in X<>
  1169.     my $index = $self->_create_index($seq_argument);
  1170.     return "\\index{$index}\n";
  1171.  
  1172.   } else {
  1173.     carp "Unknown sequence $seq_command<$seq_argument>";
  1174.   }
  1175.  
  1176. }
  1177.  
  1178. =back
  1179.  
  1180. =head2 List Methods
  1181.  
  1182. Methods used to handle lists.
  1183.  
  1184. =over 4
  1185.  
  1186. =item B<begin_list>
  1187.  
  1188. Called when a new list is found (via the C<over> directive).
  1189. Creates a new C<Pod::List> object and stores it on the 
  1190. list stack.
  1191.  
  1192.   $parser->begin_list($indent, $line_num);
  1193.  
  1194. =cut
  1195.  
  1196. sub begin_list {
  1197.   my $self = shift;
  1198.   my $indent = shift;
  1199.   my $line_num = shift;
  1200.  
  1201.   # Indicate that a list should be started for the next item
  1202.   # need to do this to work out the type of list
  1203.   push ( @{$self->lists}, new Pod::List(-indent => $indent, 
  1204.                     -start => $line_num,
  1205.                     -file => $self->input_file,
  1206.                        )     
  1207.        );
  1208.  
  1209. }
  1210.  
  1211. =item B<end_list>
  1212.  
  1213. Called when the end of a list is found (the C<back> directive).
  1214. Pops the C<Pod::List> object off the stack of lists and writes
  1215. the C<latex> code required to close a list.
  1216.  
  1217.   $parser->end_list($line_num);
  1218.  
  1219. =cut
  1220.  
  1221. sub end_list {
  1222.   my $self = shift;
  1223.   my $line_num = shift;
  1224.  
  1225.   unless (defined $self->lists->[-1]) {
  1226.     my $file = $self->input_file;
  1227.     warn "No list is active at line $line_num (file=$file). Missing =over?\n";
  1228.     return;
  1229.   }
  1230.  
  1231.   # What to write depends on list type
  1232.   my $type = $self->lists->[-1]->type;
  1233.  
  1234.   # Dont write anything if the list type is not set
  1235.   # iomplying that a list was created but no entries were
  1236.   # placed in it (eg because of a =begin/=end combination)
  1237.   $self->_output("\\end{$type}\n")
  1238.     if (defined $type && length($type) > 0);
  1239.   
  1240.   # Clear list
  1241.   pop(@{ $self->lists});
  1242.  
  1243. }
  1244.  
  1245. =item B<add_item>
  1246.  
  1247. Add items to the list. The first time an item is encountered 
  1248. (determined from the state of the current C<Pod::List> object)
  1249. the type of list is determined (ordered, unnumbered or description)
  1250. and the relevant latex code issued.
  1251.  
  1252.   $parser->add_item($paragraph, $line_num);
  1253.  
  1254. =cut
  1255.  
  1256. sub add_item {
  1257.   my $self = shift;
  1258.   my $paragraph = shift;
  1259.   my $line_num = shift;
  1260.  
  1261.   unless (defined $self->lists->[-1]) {
  1262.     my $file = $self->input_file;
  1263.     warn "List has already ended by line $line_num of file $file. Missing =over?\n";
  1264.     # Replace special chars
  1265. #    $paragraph = $self->_replace_special_chars($paragraph);
  1266.     $self->_output("$paragraph\n\n");
  1267.     return;
  1268.   }
  1269.  
  1270.   # If paragraphs printing is turned off via =begin/=end or whatver
  1271.   # simply return immediately
  1272.   return if $self->{_suppress_all_para};
  1273.  
  1274.   # Check to see whether we are starting a new lists
  1275.   if (scalar($self->lists->[-1]->item) == 0) {
  1276.  
  1277.     # Examine the paragraph to determine what type of list
  1278.     # we have
  1279.     $paragraph =~ s/\s+$//;
  1280.     $paragraph =~ s/^\s+//;
  1281.  
  1282.     my $type;
  1283.     if (substr($paragraph, 0,1) eq '*') {
  1284.       $type = 'itemize';
  1285.     } elsif ($paragraph =~ /^\d/) {
  1286.       $type = 'enumerate';
  1287.     } else {
  1288.       $type = 'description';
  1289.     }
  1290.     $self->lists->[-1]->type($type);
  1291.  
  1292.     $self->_output("\\begin{$type}\n");
  1293.  
  1294.   }
  1295.  
  1296.   my $type = $self->lists->[-1]->type;
  1297.  
  1298.   if ($type eq 'description') {
  1299.     # Handle long items - long items do not wrap
  1300.     # If the string is longer than 40 characters we split
  1301.     # it into a real item header and some bold text.
  1302.     my $maxlen = 40;
  1303.     my ($hunk1, $hunk2) = $self->_split_delimited( $paragraph, $maxlen );
  1304.  
  1305.     # Print the first hunk
  1306.     $self->_output("\n\\item[$hunk1] ");
  1307.  
  1308.     # and the second hunk if it is defined
  1309.     if ($hunk2) {
  1310.       $self->_output("\\textbf{$hunk2}");
  1311.     } else {
  1312.       # Not there so make sure we have a new line
  1313.       $self->_output("\\mbox{}");
  1314.     }
  1315.  
  1316.   } else {
  1317.     # If the item was '* Something' we still need to write
  1318.     # out the something
  1319.     my $extra_info = $paragraph;
  1320.     $extra_info =~ s/^\*\s*//;
  1321.     $self->_output("\n\\item $extra_info");
  1322.   }
  1323.  
  1324.   # Store the item name in the object. Required so that 
  1325.   # we can tell if the list is new or not
  1326.   $self->lists->[-1]->item($paragraph);
  1327.  
  1328. }
  1329.  
  1330. =back
  1331.  
  1332. =head2 Methods for headings
  1333.  
  1334. =over 4
  1335.  
  1336. =item B<head>
  1337.  
  1338. Print a heading of the required level.
  1339.  
  1340.   $parser->head($level, $paragraph, $parobj);
  1341.  
  1342. The first argument is the pod heading level. The second argument
  1343. is the contents of the heading. The 3rd argument is a Pod::Paragraph
  1344. object so that the line number can be extracted.
  1345.  
  1346. =cut
  1347.  
  1348. sub head {
  1349.   my $self = shift;
  1350.   my $num = shift;
  1351.   my $paragraph = shift;
  1352.   my $parobj = shift;
  1353.  
  1354.   # If we are replace 'head1 NAME' with a section
  1355.   # we return immediately if we get it
  1356.   return 
  1357.     if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection());
  1358.  
  1359.   # Create a label
  1360.   my $label = $self->_create_label($paragraph);
  1361.  
  1362.   # Create an index entry
  1363.   my $index = $self->_create_index($paragraph);
  1364.  
  1365.   # Work out position in the above array taking into account
  1366.   # that =head1 is equivalent to $self->Head1Level
  1367.  
  1368.   my $level = $self->Head1Level() - 1 + $num;
  1369.  
  1370.   # Warn if heading to large
  1371.   if ($num > $#LatexSections) {
  1372.     my $line = $parobj->file_line;
  1373.     my $file = $self->input_file;
  1374.     warn "Heading level too large ($level) for LaTeX at line $line of file $file\n";
  1375.     $level = $#LatexSections;
  1376.   }
  1377.  
  1378.   # Check to see whether section should be unnumbered
  1379.   my $star = ($level >= $self->LevelNoNum ? '*' : '');
  1380.  
  1381.   # Section
  1382.   $self->_output("\\" .$LatexSections[$level] .$star ."{$paragraph\\label{".$label ."}\\index{".$index."}}\n");
  1383.  
  1384. }
  1385.  
  1386.  
  1387. =back
  1388.  
  1389. =end __PRIVATE__
  1390.  
  1391. =begin __PRIVATE__
  1392.  
  1393. =head2 Internal methods
  1394.  
  1395. Internal routines are described in this section. They do not form part of the
  1396. public interface. All private methods start with an underscore.
  1397.  
  1398. =over 4
  1399.  
  1400. =item B<_output>
  1401.  
  1402. Output text to the output filehandle. This method must be always be called
  1403. to output parsed text.
  1404.  
  1405.    $parser->_output($text);
  1406.  
  1407. Does not write anything if a =begin is active that should be
  1408. ignored.
  1409.  
  1410. =cut
  1411.  
  1412. sub _output { 
  1413.   my $self = shift;
  1414.   my $text = shift;
  1415.  
  1416.   print { $self->output_handle } $text
  1417.     unless $self->{_suppress_all_para};
  1418.  
  1419. }
  1420.  
  1421.  
  1422. =item B<_replace_special_chars>
  1423.  
  1424. Subroutine to replace characters that are special in C<latex>
  1425. with the escaped forms
  1426.  
  1427.   $escaped = $parser->_replace_special_chars($paragraph);
  1428.  
  1429. Need to call this routine before interior_sequences are munged but not
  1430. if verbatim. It must be called before interpolation of interior
  1431. sequences so that curly brackets and special latex characters inserted
  1432. during interpolation are not themselves escaped. This means that < and
  1433. > can not be modified here since the text still contains interior
  1434. sequences.
  1435.  
  1436. Special characters and the C<latex> equivalents are:
  1437.  
  1438.   }     \}
  1439.   {     \{
  1440.   _     \_
  1441.   $     \$
  1442.   %     \%
  1443.   &     \&
  1444.   \     $\backslash$
  1445.   ^     \^{}
  1446.   ~     \~{}
  1447.  
  1448. =cut
  1449.  
  1450. sub _replace_special_chars {
  1451.   my $self = shift;
  1452.   my $paragraph = shift;
  1453.  
  1454.   # Replace a \ with $\backslash$
  1455.   # This is made more complicated because the dollars will be escaped
  1456.   # by the subsequent replacement. Easiest to add \backslash 
  1457.   # now and then add the dollars
  1458.   $paragraph =~ s/\\/\\backslash/g;
  1459.  
  1460.   # Must be done after escape of \ since this command adds latex escapes
  1461.   # Replace characters that can be escaped
  1462.   $paragraph =~ s/([\$\#&%_{}])/\\$1/g;
  1463.  
  1464.   # Replace ^ characters with \^{} so that $^F works okay
  1465.   $paragraph =~ s/(\^)/\\$1\{\}/g;
  1466.  
  1467.   # Replace tilde (~) with \texttt{\~{}}
  1468.   $paragraph =~ s/~/\\texttt\{\\~\{\}\}/g;
  1469.  
  1470.   # Now add the dollars around each \backslash
  1471.   $paragraph =~ s/(\\backslash)/\$$1\$/g;
  1472.   return $paragraph;
  1473. }
  1474.  
  1475. =item B<_replace_special_chars_late>
  1476.  
  1477. Replace special characters that can not be replaced before interior
  1478. sequence interpolation. See C<_replace_special_chars> for a routine
  1479. to replace special characters prior to interpolation of interior
  1480. sequences.
  1481.  
  1482. Does the following transformation:
  1483.  
  1484.   <   $<$
  1485.   >   $>$
  1486.   |   $|$
  1487.  
  1488.  
  1489. =cut
  1490.  
  1491. sub _replace_special_chars_late {
  1492.   my $self = shift;
  1493.   my $paragraph = shift;
  1494.  
  1495.   # < and >
  1496.   $paragraph =~ s/(<|>)/\$$1\$/g;
  1497.  
  1498.   # Replace | with $|$
  1499.   $paragraph =~ s'\|'$|$'g;
  1500.  
  1501.  
  1502.   return $paragraph;
  1503. }
  1504.  
  1505.  
  1506. =item B<_create_label>
  1507.  
  1508. Return a string that can be used as an internal reference
  1509. in a C<latex> document (i.e. accepted by the C<\label> command)
  1510.  
  1511.  $label = $parser->_create_label($string)
  1512.  
  1513. If UniqueLabels is true returns a label prefixed by Label()
  1514. This can be suppressed with an optional second argument.
  1515.  
  1516.  $label = $parser->_create_label($string, $suppress);
  1517.  
  1518. If a second argument is supplied (of any value including undef)
  1519. the Label() is never prefixed. This means that this routine can
  1520. be called to create a Label() without prefixing a previous setting.
  1521.  
  1522. =cut
  1523.  
  1524. sub _create_label {
  1525.   my $self = shift;
  1526.   my $paragraph = shift;
  1527.   my $suppress = (@_ ? 1 : 0 );
  1528.  
  1529.   # Remove latex commands
  1530.   $paragraph = $self->_clean_latex_commands($paragraph);
  1531.  
  1532.   # Remove non alphanumerics from the label and replace with underscores
  1533.   # want to protect '-' though so use negated character classes 
  1534.   $paragraph =~ s/[^-:\w]/_/g;
  1535.  
  1536.   # Multiple underscores will look unsightly so remove repeats
  1537.   # This will also have the advantage of tidying up the end and
  1538.   # start of string
  1539.   $paragraph =~ s/_+/_/g;
  1540.  
  1541.   # If required need to make sure that the label is unique
  1542.   # since it is possible to have multiple pods in a single
  1543.   # document
  1544.   if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
  1545.     $paragraph = $self->Label() .'_'. $paragraph;
  1546.   }
  1547.  
  1548.   return $paragraph;
  1549. }
  1550.  
  1551.  
  1552. =item B<_create_index>
  1553.  
  1554. Similar to C<_create_label> except an index entry is created.
  1555. If C<UniqueLabels> is true, the index entry is prefixed by 
  1556. the current C<Label> and an exclamation mark.
  1557.  
  1558.   $ind = $parser->_create_index($paragraph);
  1559.  
  1560. An exclamation mark is used by C<makeindex> to generate 
  1561. sub-entries in an index.
  1562.  
  1563. =cut
  1564.  
  1565. sub _create_index {
  1566.   my $self = shift;
  1567.   my $paragraph = shift;
  1568.   my $suppress = (@_ ? 1 : 0 );
  1569.  
  1570.   # Remove latex commands
  1571.   $paragraph = $self->_clean_latex_commands($paragraph);
  1572.  
  1573.   # If required need to make sure that the index entry is unique
  1574.   # since it is possible to have multiple pods in a single
  1575.   # document
  1576.   if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
  1577.     $paragraph = $self->Label() .'!'. $paragraph;
  1578.   }
  1579.  
  1580.   # Need to replace _ with space
  1581.   $paragraph =~ s/_/ /g;
  1582.  
  1583.   return $paragraph;
  1584.  
  1585. }
  1586.  
  1587. =item B<_clean_latex_commands>
  1588.  
  1589. Removes latex commands from text. The latex command is assumed to be of the
  1590. form C<\command{ text }>. "C<text>" is retained
  1591.  
  1592.   $clean = $parser->_clean_latex_commands($text);
  1593.  
  1594. =cut
  1595.  
  1596. sub _clean_latex_commands {
  1597.   my $self = shift;
  1598.   my $paragraph = shift;
  1599.  
  1600.   # Remove latex commands of the form \text{ }
  1601.   # and replace with the contents of the { }
  1602.   # need to make this non-greedy so that it can handle
  1603.   #  "\text{a} and \text2{b}"
  1604.   # without converting it to
  1605.   #  "a} and \text2{b"
  1606.   # This match will still get into trouble if \} is present 
  1607.   # This is not vital since the subsequent replacement of non-alphanumeric
  1608.   # characters will tidy it up anyway
  1609.   $paragraph =~ s/\\\w+{(.*?)}/$1/g;
  1610.  
  1611.   return $paragraph
  1612. }
  1613.  
  1614. =item B<_split_delimited>
  1615.  
  1616. Split the supplied string into two parts at approximately the
  1617. specified word boundary. Special care is made to make sure that it
  1618. does not split in the middle of some curly brackets.
  1619.  
  1620. e.g. "this text is \textbf{very bold}" would not be split into
  1621. "this text is \textbf{very" and " bold".
  1622.  
  1623.   ($hunk1, $hunk2) = $self->_split_delimited( $para, $length);
  1624.  
  1625. The length indicates the maximum length of hunk1.
  1626.  
  1627. =cut
  1628.  
  1629. # initially Supplied by hsmyers@sdragons.com
  1630. # 10/25/01, utility to split \hbox
  1631. # busting lines. Reformatted by TimJ to match module style.
  1632. sub _split_delimited {
  1633.   my $self = shift;
  1634.   my $input = shift;
  1635.   my $limit = shift;
  1636.  
  1637.   # Return immediately if already small
  1638.   return ($input, '') if length($input) < $limit;
  1639.  
  1640.   my @output;
  1641.   my $s = '';
  1642.   my $t = '';
  1643.   my $depth = 0;
  1644.   my $token;
  1645.  
  1646.   $input =~ s/\n/ /gm;
  1647.   $input .= ' ';
  1648.   foreach ( split ( //, $input ) ) {
  1649.     $token .= $_;
  1650.     if (/\{/) {
  1651.       $depth++;
  1652.     } elsif ( /}/ ) {
  1653.       $depth--;
  1654.     } elsif ( / / and $depth == 0) {
  1655.       push @output, $token if ( $token and $token ne ' ' );
  1656.       $token = '';
  1657.     }
  1658.   }
  1659.  
  1660.   foreach  (@output) {
  1661.     if (length($s) < $limit) {
  1662.       $s .= $_;
  1663.     } else {
  1664.       $t .= $_;
  1665.     }
  1666.   }
  1667.  
  1668.   # Tidy up
  1669.   $s =~ s/\s+$//;
  1670.   $t =~ s/\s+$//;
  1671.   return ($s,$t);
  1672. }
  1673.  
  1674. =back
  1675.  
  1676. =end __PRIVATE__
  1677.  
  1678. =head1 NOTES
  1679.  
  1680. Compatible with C<latex2e> only. Can not be used with C<latex> v2.09
  1681. or earlier.
  1682.  
  1683. A subclass of C<Pod::Select> so that specific pod sections can be
  1684. converted to C<latex> by using the C<select> method.
  1685.  
  1686. Some HTML escapes are missing and many have not been tested.
  1687.  
  1688. =head1 SEE ALSO
  1689.  
  1690. L<Pod::Parser>, L<Pod::Select>, L<pod2latex>
  1691.  
  1692. =head1 AUTHORS
  1693.  
  1694. Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt>
  1695.  
  1696. Bug fixes have been received from: Simon Cozens
  1697. E<lt>simon@cozens.netE<gt>, Mark A. Hershberger
  1698. E<lt>mah@everybody.orgE<gt>, Marcel Grunauer
  1699. E<lt>marcel@codewerk.comE<gt> and Hugh S Myers
  1700. E<lt>hsmyers@sdragons.comE<gt>.
  1701.  
  1702. =head1 COPYRIGHT
  1703.  
  1704. Copyright (C) 2000-2001 Tim Jenness. All Rights Reserved.
  1705.  
  1706. This program is free software; you can redistribute it and/or modify
  1707. it under the same terms as Perl itself.
  1708.  
  1709. =begin __PRIVATE__
  1710.  
  1711. =head1 REVISION
  1712.  
  1713. $Id: LaTeX.pm,v 1.12 2001/11/20 20:59:26 timj Exp $
  1714.  
  1715. =end __PRIVATE__
  1716.  
  1717. =cut
  1718.