lib/Pod/LaTeX.pm

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