latex.pm

MSYS在windows下模拟了一个类unix的终端

package Pod::LaTeX;

# Copyright (C) 2000 by Tim Jenness <[e-mail]>
# All Rights Reserved.

=head1 NAME

Pod::LaTeX - Convert Pod data to formatted Latex

=head1 SYNOPSIS

  use Pod::LaTeX;
  my $parser = Pod::LaTeX->new ( );

  $parser->parse_from_filehandle;

  $parser->parse_from_file ('file.pod', 'file.tex');

=head1 DESCRIPTION

C<Pod::LaTeX> is a module to convert documentation in the Pod format
into Latex. The L<B<pod2latex>|pod2latex> X<pod2latex> command uses
this module for translation.

C<Pod::LaTeX> is a derived class from L<Pod::Select|Pod::Select>.

=cut


use strict;
require Pod::ParseUtils;
use base qw/ Pod::Select /;

# use Data::Dumper; # for debugging
use Carp;

use vars qw/ $VERSION %HTML_Escapes @LatexSections /;

$VERSION = '0.53';

# Definitions of =headN -> latex mapping
@LatexSections = (qw/
		  chapter
		  section
		  subsection
		  subsubsection
		  paragraph
		  subparagraph
		  /);

# Standard escape sequences converted to Latex
# Up to "yuml" these are taken from the original pod2latex
# command written by Taro Kawagish ([e-mail])

%HTML_Escapes = (
    'amp'       =>      '&',      #   ampersand
    'lt'        =>      '$<$',    #   ' left chevron, less-than
    'gt'        =>      '$>$',    #   ' right chevron, greater-than
    'quot'      =>      '"',      #   double quote
    'sol'       =>      '/',
    'verbar'    =>      '$|$',

    "Aacute"    =>      "\\'{A}",       #   capital A, acute accent
    "aacute"    =>      "\\'{a}",       #   small a, acute accent
    "Acirc"     =>      "\\^{A}",       #   capital A, circumflex accent
    "acirc"     =>      "\\^{a}",       #   small a, circumflex accent
    "AElig"     =>      '\\AE',         #   capital AE diphthong (ligature)
    "aelig"     =>      '\\ae',         #   small ae diphthong (ligature)
    "Agrave"    =>      "\\`{A}",       #   capital A, grave accent
    "agrave"    =>      "\\`{a}",       #   small a, grave accent
    "Aring"     =>      '\\u{A}',       #   capital A, ring
    "aring"     =>      '\\u{a}',       #   small a, ring
    "Atilde"    =>      '\\~{A}',       #   capital A, tilde
    "atilde"    =>      '\\~{a}',       #   small a, tilde
    "Auml"      =>      '\\"{A}',       #   capital A, dieresis or umlaut mark
    "auml"      =>      '\\"{a}',       #   small a, dieresis or umlaut mark
    "Ccedil"    =>      '\\c{C}',       #   capital C, cedilla
    "ccedil"    =>      '\\c{c}',       #   small c, cedilla
    "Eacute"    =>      "\\'{E}",       #   capital E, acute accent
    "eacute"    =>      "\\'{e}",       #   small e, acute accent
    "Ecirc"     =>      "\\^{E}",       #   capital E, circumflex accent
    "ecirc"     =>      "\\^{e}",       #   small e, circumflex accent
    "Egrave"    =>      "\\`{E}",       #   capital E, grave accent
    "egrave"    =>      "\\`{e}",       #   small e, grave accent
    "ETH"       =>      '\\OE',         #   capital Eth, Icelandic
    "eth"       =>      '\\oe',         #   small eth, Icelandic
    "Euml"      =>      '\\"{E}',       #   capital E, dieresis or umlaut mark
    "euml"      =>      '\\"{e}',       #   small e, dieresis or umlaut mark
    "Iacute"    =>      "\\'{I}",       #   capital I, acute accent
    "iacute"    =>      "\\'{i}",       #   small i, acute accent
    "Icirc"     =>      "\\^{I}",       #   capital I, circumflex accent
    "icirc"     =>      "\\^{i}",       #   small i, circumflex accent
    "Igrave"    =>      "\\`{I}",       #   capital I, grave accent
    "igrave"    =>      "\\`{i}",       #   small i, grave accent
    "Iuml"      =>      '\\"{I}',       #   capital I, dieresis or umlaut mark
    "iuml"      =>      '\\"{i}',       #   small i, dieresis or umlaut mark
    "Ntilde"    =>      '\\~{N}',       #   capital N, tilde
    "ntilde"    =>      '\\~{n}',       #   small n, tilde
    "Oacute"    =>      "\\'{O}",       #   capital O, acute accent
    "oacute"    =>      "\\'{o}",       #   small o, acute accent
    "Ocirc"     =>      "\\^{O}",       #   capital O, circumflex accent
    "ocirc"     =>      "\\^{o}",       #   small o, circumflex accent
    "Ograve"    =>      "\\`{O}",       #   capital O, grave accent
    "ograve"    =>      "\\`{o}",       #   small o, grave accent
    "Oslash"    =>      "\\O",          #   capital O, slash
    "oslash"    =>      "\\o",          #   small o, slash
    "Otilde"    =>      "\\~{O}",       #   capital O, tilde
    "otilde"    =>      "\\~{o}",       #   small o, tilde
    "Ouml"      =>      '\\"{O}',       #   capital O, dieresis or umlaut mark
    "ouml"      =>      '\\"{o}',       #   small o, dieresis or umlaut mark
    "szlig"     =>      '\\ss{}',       #   small sharp s, German (sz ligature)
    "THORN"     =>      '\\L',          #   capital THORN, Icelandic
    "thorn"     =>      '\\l',,         #   small thorn, Icelandic
    "Uacute"    =>      "\\'{U}",       #   capital U, acute accent
    "uacute"    =>      "\\'{u}",       #   small u, acute accent
    "Ucirc"     =>      "\\^{U}",       #   capital U, circumflex accent
    "ucirc"     =>      "\\^{u}",       #   small u, circumflex accent
    "Ugrave"    =>      "\\`{U}",       #   capital U, grave accent
    "ugrave"    =>      "\\`{u}",       #   small u, grave accent
    "Uuml"      =>      '\\"{U}',       #   capital U, dieresis or umlaut mark
    "uuml"      =>      '\\"{u}',       #   small u, dieresis or umlaut mark
    "Yacute"    =>      "\\'{Y}",       #   capital Y, acute accent
    "yacute"    =>      "\\'{y}",       #   small y, acute accent
    "yuml"      =>      '\\"{y}',       #   small y, dieresis or umlaut mark

    # Added by TimJ

    "iexcl"  =>   '!`',           # inverted exclamation mark
#    "cent"   =>   ' ',        # cent sign
    "pound"  =>   '\pounds',      # (UK) pound sign
#    "curren" =>   ' ',        # currency sign
#    "yen"    =>   ' ',        # yen sign
#    "brvbar" =>   ' ',        # broken vertical bar
    "sect"   =>   '\S',           # section sign
    "uml"    =>   '\"{}',        # diaresis
    "copy"   =>   '\copyright',   # Copyright symbol
#    "ordf"   =>   ' ',        # feminine ordinal indicator
    "laquo"  =>   '$\ll$',      # ' # left pointing double angle quotation mark
    "not"    =>   '$\neg$',       # '  # not sign
    "shy"    =>   '-',            # soft hyphen
#    "reg"    =>   ' ',        # registered trademark
    "macr"   =>   '$^-$',         # ' # macron, overline
    "deg"    =>   '$^\circ$',     # '  # degree sign
    "plusmn" =>   '$\pm$',        # ' # plus-minus sign
    "sup2"   =>   '$^2$',         # ' # superscript 2
    "sup3"   =>   '$^3$',         # ' # superscript 3
    "acute"  =>   "\\'{}",        # acute accent
    "micro"  =>   '$\mu$',        # micro sign
    "para"   =>   '\P',           # pilcrow sign = paragraph sign
    "middot" =>   '$\cdot$',      # middle dot = Georgian comma
    "cedil"  =>   '\c{}',        # cedilla
    "sup1"   =>   '$^1$',         # ' # superscript 1
#    "ordm"   =>   ' ',        # masculine ordinal indicator
    "raquo"  =>   '$\gg$',     # ' # right pointing double angle quotation mark
    "frac14" =>   '$\frac{1}{4}$',   # ' # vulgar fraction one quarter
    "frac12" =>   '$\frac{1}{2}$',   # ' # vulgar fraction one half
    "frac34" =>   '$\frac{3}{4}$',   # ' # vulgar fraction three quarters
    "iquest" =>   "?'",              # inverted question mark
    "times"  =>   '$\times$',        # ' # multiplication sign
    "divide" =>   '$\div$',          # division sign

    # Greek letters using HTML codes
    "alpha"  =>   '$\alpha$',   # '
    "beta"   =>   '$\beta$',    # '
    "gamma"  =>   '$\gamma$',   # '
    "delta"  =>   '$\delta$',   # '
    "epsilon"=>   '$\epsilon$', # '
    "zeta"   =>   '$\zeta$',    # '
    "eta"    =>   '$\eta$',     # '
    "theta"  =>   '$\theta$',   # '
    "iota"   =>   '$\iota$',    # '
    "kappa"  =>   '$\kappa$',   # '
    "lambda" =>   '$\lambda$',  # '
    "mu"     =>   '$\mu$',      # '
    "nu"     =>   '$\nu$',      # '
    "xi"     =>   '$\xi$',      # '
    "omicron"=>   '$o$',        # '
    "pi"     =>   '$\pi$',      # '
    "rho"    =>   '$\rho$',     # '
    "sigma"  =>   '$\sigma$',   # '
    "tau"    =>   '$\tau$',     # '
    "upsilon"=>   '$\upsilon$', # '
    "phi"    =>   '$\phi$',     # '
    "chi"    =>   '$\chi$',     # '
    "psi"    =>   '$\psi$',     # '
    "omega"  =>   '$\omega$',   # '

    "Alpha"  =>   '$A$',   # '
    "Beta"   =>   '$B$',    # '
    "Gamma"  =>   '$\Gamma$',   # '
    "Delta"  =>   '$\Delta$',   # '
    "Epsilon"=>   '$E$', # '
    "Zeta"   =>   '$Z$',    # '
    "Eta"    =>   '$H$',     # '
    "Theta"  =>   '$\Theta$',   # '
    "Iota"   =>   '$I$',    # '
    "Kappa"  =>   '$K$',   # '
    "Lambda" =>   '$\Lambda$',  # '
    "Mu"     =>   '$M$',      # '
    "Nu"     =>   '$N$',      # '
    "Xi"     =>   '$\Xi$',      # '
    "Omicron"=>   '$O$',        # '
    "Pi"     =>   '$\Pi$',      # '
    "Rho"    =>   '$R$',     # '
    "Sigma"  =>   '$\Sigma$',   # '
    "Tau"    =>   '$T$',     # '
    "Upsilon"=>   '$\Upsilon$', # '
    "Phi"    =>   '$\Phi$',     # '
    "Chi"    =>   '$X$',     # '
    "Psi"    =>   '$\Psi$',     # '
    "Omega"  =>   '$\Omega$',   # '


);


=head1 OBJECT METHODS

The following methods are provided in this module. Methods inherited
from C<Pod::Select> are not described in the public interface.

=over 4

=begin __PRIVATE__

=item C<initialize>

Initialise the object. This method is subclassed from C<Pod::Parser>.
The base class method is invoked. This method defines the default
behaviour of the object unless overridden by supplying arguments to
the constructor. 

Internal settings are defaulted as well as the public instance data.
Internal hash values are accessed directly (rather than through
a method) and start with an underscore.

This method should not be invoked by the user directly.

=end __PRIVATE__

=cut



#   - An array for nested lists

# Arguments have already been read by this point

sub initialize {
  my $self = shift;

  # print Dumper($self);

  # Internals
  $self->{_Lists} = [];             # For nested lists
  $self->{_suppress_all_para}  = 0; # For =begin blocks
  $self->{_suppress_next_para} = 0; # For =for blocks
  $self->{_dont_modify_any_para}=0; # For =begin blocks
  $self->{_dont_modify_next_para}=0; # For =for blocks
  $self->{_CURRENT_HEAD1}   = '';   # Name of current HEAD1 section

  # Options - only initialise if not already set

  # Cause the '=head1 NAME' field to be treated specially
  # The contents of the NAME paragraph will be converted
  # to a section title. All subsequent =head1 will be converted
  # to =head2 and down. Will not affect =head1's prior to NAME 
  # Assumes:  'Module - purpose' format
  # Also creates a purpose field
  # The name is used for Labeling of the subsequent subsections
  $self->{ReplaceNAMEwithSection} = 0
    unless exists $self->{ReplaceNAMEwithSection};
  $self->{AddPreamble}      = 1    # make full latex document
    unless exists $self->{AddPreamble};
  $self->{StartWithNewPage} = 0    # Start new page for pod section
    unless exists $self->{StartWithNewPage};
  $self->{TableOfContents}  = 0    # Add table of contents
    unless exists $self->{TableOfContents};  # only relevent if AddPreamble=1
   $self->{AddPostamble}     = 1          # Add closing latex code at end
    unless exists $self->{AddPostamble}; #  effectively end{document} and index
  $self->{MakeIndex}        = 1         # Add index (only relevant AddPostamble
    unless exists $self->{MakeIndex};   # and AddPreamble)

  $self->{UniqueLabels}     = 1          # Use label unique for each pod
    unless exists $self->{UniqueLabels}; # either based on the filename
                                         # or supplied

  # Control the level of =head1. default is \section
  # 
  $self->{Head1Level}     = 1   # Offset in latex sections
    unless exists $self->{Head1Level}; # 0 is chapter, 2 is subsection

  # Control at which level numbering of sections is turned off
  # ie subsection becomes subsection*
  # The numbering is relative to the latex sectioning commands
  # and is independent of Pod heading level
  # default is to number \section but not \subsection
  $self->{LevelNoNum} = 2
    unless exists $self->{LevelNoNum};

  # Label to be used as prefix to all internal section names
  # If not defined will attempt to derive it from the filename
  # This can not happen when running parse_from_filehandle though
  # hence the ability to set the label externally
  # The label could then be Pod::Parser_DESCRIPTION or somesuch

  $self->{Label}            = undef # label to be used as prefix
    unless exists $self->{Label};   # to all internal section names

  # These allow the caller to add arbritrary latex code to
  # start and end of document. AddPreamble and AddPostamble are ignored
  # if these are set.
  # Also MakeIndex and TableOfContents are also ignored.
  $self->{UserPreamble}     = undef # User supplied start (AddPreamble =1)
    unless exists $self->{Label};
  $self->{UserPostamble}    = undef # Use supplied end    (AddPostamble=1)
    unless exists $self->{Label};

  # Run base initialize
  $self->SUPER::initialize;

}

=back

=head2 Data Accessors

The following methods are provided for accessing instance data. These
methods should be used for accessing configuration parameters rather
than assuming the object is a hash.

Default values can be supplied by using these names as keys to a hash
of arguments when using the C<new()> constructor.

=over 4

=item B<AddPreamble>

Logical to control whether a C<latex> preamble is to be written.
If true, a valid C<latex> preamble is written before the pod data is written.
This is similar to:

  \documentclass{article}
  \begin{document}

but will be more complicated if table of contents and indexing are required.
Can be used to set or retrieve the current value.

  $add = $parser->AddPreamble();
  $parser->AddPreamble(1);

If used in conjunction with C<AddPostamble> a full latex document will
be written that could be immediately processed by C<latex>.

=cut

sub AddPreamble {
   my $self = shift;
   if (@_) {
     $self->{AddPreamble} = shift;
   }
   return $self->{AddPreamble};
}

=item B<AddPostamble>

Logical to control whether a standard C<latex> ending is written to the output
file after the document has been processed.
In its simplest form this is simply:

  \end{document}

but can be more complicated if a index is required.
Can be used to set or retrieve the current value.

  $add = $parser->AddPostamble();
  $parser->AddPostamble(1);

If used in conjunction with C<AddPreaamble> a full latex document will
be written that could be immediately processed by C<latex>.

=cut

sub AddPostamble {
   my $self = shift;
   if (@_) {
     $self->{AddPostamble} = shift;
   }
   return $self->{AddPostamble};
}

=item B<Head1Level>

The C<latex> sectioning level that should be used to correspond to
a pod C<=head1> directive. This can be used, for example, to turn
a C<=head1> into a C<latex> C<subsection>. This should hold a number
corresponding to the required position in an array containing the
following elements:

 [0] chapter
 [1] section
 [2] subsection
 [3] subsubsection
 [4] paragraph
 [5] subparagraph

Can be used to set or retrieve the current value:

  $parser->Head1Level(2);
  $sect = $parser->Head1Level;

Setting this number too high can result in sections that may not be reproducible
in the expected way. For example, setting this to 4 would imply that C<=head3>
do not have a corresponding C<latex> section (C<=head1> would correspond to
a C<paragraph>).

A check is made to ensure that the supplied value is an integer in the
range 0 to 5.

Default is for a value of 1 (i.e. a C<section>).

=cut

sub Head1Level {
   my $self = shift;
   if (@_) {
     my $arg = shift;
     if ($arg =~ /^\d$/ && $arg <= $#LatexSections) {
       $self->{Head1Level} = $arg;
     } else {
       carp "Head1Level supplied ($arg) must be integer in range 0 to ".$#LatexSections . "- Ignoring\n";
     }
   }
   return $self->{Head1Level};
}

=item B<Label>

This is the label that is prefixed to all C<latex> label and index
entries to make them unique. In general, pods have similarly titled
sections (NAME, DESCRIPTION etc) and a C<latex> label will be multiply
defined if more than one pod document is to be included in a single
C<latex> file. To overcome this, this label is prefixed to a label
whenever a label is required (joined with an underscore) or to an
index entry (joined by an exclamation mark which is the normal index
separator). For example, C<\label{text}> becomes C<\label{Label_text}>.

Can be used to set or retrieve the current value:

  $label = $parser->Label;
  $parser->Label($label);

This label is only used if C<UniqueLabels> is true.
Its value is set automatically from the C<NAME> field
if C<ReplaceNAMEwithSection> is true. If this is not the case
it must be set manually before starting the parse.

Default value is C<undef>.

=cut

sub Label {
   my $self = shift;
   if (@_) {
     $self->{Label} = shift;
   }
   return $self->{Label};
}

=item B<LevelNoNum>

Control the point at which C<latex> section numbering is turned off.
For example, this can be used to make sure that C<latex> sections
are numbered but subsections are not.

Can be used to set or retrieve the current value:

  $lev = $parser->LevelNoNum;
  $parser->LevelNoNum(2);

The argument must be an integer between 0 and 5 and is the same as the
number described in C<Head1Level> method description. The number has
nothing to do with the pod heading number, only the C<latex> sectioning.

Default is 2. (i.e. C<latex> subsections are written as C<subsection*>
but sections are numbered).

=cut

sub LevelNoNum {
   my $self = shift;
   if (@_) {
     $self->{LevelNoNum} = shift;
   }
   return $self->{LevelNoNum};
}

=item B<MakeIndex>

Controls whether C<latex> commands for creating an index are to be inserted
into the preamble and postamble

  $makeindex = $parser->MakeIndex;
  $parser->MakeIndex(0);

Irrelevant if both C<AddPreamble> and C<AddPostamble> are false (or equivalently,
C<UserPreamble> and C<UserPostamble> are set).

Default is for an index to be created.

=cut

sub MakeIndex {
   my $self = shift;
   if (@_) {
     $self->{MakeIndex} = shift;
   }
   return $self->{MakeIndex};
}

=item B<ReplaceNAMEwithSection>

This controls whether the C<NAME> section in the pod is to be translated
literally or converted to a slightly modified output where the section
name is the pod name rather than "NAME".

If true, the pod segment

  =head1 NAME

  pod::name - purpose