Pod-LaTeX-0.61000755000765000024 012076247421 12371 5ustar00timjstaff000000000000Pod-LaTeX-0.61/Build.PL000444000765000024 207212076247421 14023 0ustar00timjstaff000000000000#!perl use strict; use warnings; use Module::Build; use File::Spec; my $path = File::Spec->catfile( "lib", "Pod", "LaTeX.pm" ); # Set it up. my $build = Module::Build->new ( module_name => 'Pod::LaTeX', license => 'perl', dist_author => 'Tim Jenness ', version_from => $path, abstract_from => $path, meta_merge => { resources => {repository => "git://github.com/timj/perl-Pod-LaTeX.git", homepage => "http://github.com/timj/perl-Pod-LaTeX/tree/master", }, }, requires => { 'Pod::Find' => 0, 'Pod::Parser' => 0, 'Pod::ParseUtils' => 0.30, 'Pod::Select' => 0, 'if' => 0, }, PL_files => { 'pod2latex.PL' => 'pod2latex' }, script_files => [ 'pod2latex' ], build_requires => { 'Test::More' => 0, }, installdirs => ( $] > 5.006 and $] <= 5.012 ? "core" : "site" ), ); $build->create_build_script; Pod-LaTeX-0.61/ChangeLog000444000765000024 772312076247420 14310 0ustar00timjstaff0000000000002011-01-04 Tim Jenness ---- Version 0.59 CPAN ---- * t/*.t: Use Test::More for tests. * Build.PL: Use Module::Build * LaTeX.pm: Fix typo in pod (RT #46887 via Dave Mitchell) 2004-12-29 Tim Jenness ---- VERSION 0.58 CPAN ---- * t/pod2latex.t: Add test for square bracket in item * LaTeX.pm (add_item): Fix items when the item contains a square bracket (thanks to R. de Vries - RT#7570) 2004-03-07 Tim Jenness * Version 0.57 CPAN * README: Forgot to update prior to 0.56 release. 2004-03-07 Tim Jenness * Version 0.56 CPAN * LaTeX.pm (end_pod): Fix bug where UserPostamble and UserPreamble were written even if AddPostamble and AddPreamble were false. * pod2latex.PL: Add -pre/postfile and -pre/postamble to pod2latex. (thanks to Adriano Rodrigues Ferreira) * LaTeX.pm (end_pod): Fix doubling up of \end{document} when user postamble is used (and add new test t/user.t). (thanks to Adriano Rodrigues Ferreira). 2003-07-27 Tim Jenness * MANIFEST: Forgot to add MANIFEST to the MANIFEST!! 2003-04-05 Tim Jenness * Version 0.55 CPAN * t/pod2latex.t: Update the test to work with Pod::ParseUtils v0.30 but retain backwards compatibility. (thanks to Mark Veltzer for pointing this out). * pod2latex.PL: Change pod2latex so that the binary is generated from a .PL (this allows it to work on VMS). Imported from bleadperl. * LaTeX.pm (begin_pod): Add usepackage{textcomp} to preamble. * t/pod2latex.t: Fix test to take into account current patches. Add additional test for enumerate environments. 2003-04-03 Tim Jenness * LaTeX.pm (add_item): Apply patch from Ariel Scolnicov to correct =item 1 blah so that it becomes "1 blah" and not "1. 1 blah" (and duplicate patch from Sudhi Herle). * pod2latex: Apply Jarkko's pod typo * LaTeX.pm: Add Peter J. Acklam's patch to allow much improved unicode entity support. 2001-11-20 Tim Jenness * Version 0.54 on CPAN * LaTeX.pm (command): Fix the logic in =for blocks (found because perlpod.pod was not formatting correctly with "=for comment". 2001-11-19 Tim Jenness * LaTeX.pm (verbatim): Use a cleverer approach to tabs. (Hugh S Myers ) (_replace_special_chars_late): verbar escape was happening in the wrong place and this was ruining link expansion. (add_item): Tweak so that we for long items we have some content in the item description itself and some bold. This makes sure that everything lines up. (thanks to Hugh S Myers for the original idea and for the _split_delimited method). 2001-11-16 Tim Jenness * LaTeX.pm (_replace_special_chars_late): Finally agree to escape < and > (thanks to some more prodding from Hugh S Myers) 2000-10-10 Tim Jenness * pod2latex: Add strict and version number. Add -h1level option. 2000-09-22 Tim Jenness * Release 0.53 to CPAN 2000-08-20 Tim Jenness * LaTeX.pm (add_item): Fix problem with '* text' items 2000-08-20 Tim Jenness * LaTeX.pm (add_item): Handle long item strings (from Mark A. Hershberger ) (_replace_special_chars): Escape ~ (from Simon Cozens ) Escape | (thanks to Marcel Grunauer ) Add support for E and E 2000-05-15 Tim Jenness * V0.52 for CPAN release 2000-05-09 Tim Jenness * pod2latex: Make sure that argument order is preserved. 2000-05-08 Tim Jenness * LaTeX.pm: Version 0.51 2000-05-05 Tim Jenness * pod2latex: Set INFILE name when using filehandle. * LaTeX.pm: Fix warning messages so that they correctly list file name and line number. Fix escaping of ^ and {}. 2000-03-30 Tim Jenness * LaTeX.pm: Version 0.50 Pod-LaTeX-0.61/MANIFEST000444000765000024 15512076247420 13637 0ustar00timjstaff000000000000README MANIFEST lib/Pod/LaTeX.pm ChangeLog pod2latex.PL Build.PL t/require.t t/pod2latex.t t/user.t META.yml Pod-LaTeX-0.61/META.yml000444000765000024 124612076247420 14001 0ustar00timjstaff000000000000--- abstract: 'Convert Pod data to formatted Latex' author: - 'Tim Jenness ' build_requires: Test::More: 0 configure_requires: Module::Build: 0.36 generated_by: 'Module::Build version 0.3603' license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: 1.4 name: Pod-LaTeX provides: Pod::LaTeX: file: lib/Pod/LaTeX.pm version: 0.61 requires: Pod::Find: 0 Pod::ParseUtils: 0.3 Pod::Parser: 0 Pod::Select: 0 if: 0 resources: homepage: http://github.com/timj/perl-Pod-LaTeX/tree/master license: http://dev.perl.org/licenses/ repository: git://github.com/timj/perl-Pod-LaTeX.git version: 0.61 Pod-LaTeX-0.61/pod2latex.PL000444000765000024 2630412076247421 14712 0ustar00timjstaff000000000000#!/usr/local/bin/perl use Config; use File::Basename qw(&basename &dirname); use Cwd; # List explicitly here the variables you want Configure to # generate. Metaconfig only looks for shell variables, so you # have to mention them as if they were shell variables, not # %Config entries. Thus you write # $startperl # to ensure Configure will look for $Config{startperl}. # This forces PL files to create target in same directory as PL file. # This is so that make depend always knows where to find PL derivatives. $origdir = cwd; chdir dirname($0); $file = basename($0, '.PL'); $file .= '.com' if $^O eq 'VMS'; open OUT,">$file" or die "Can't create $file: $!"; print "Extracting $file (with variable substitutions)\n"; # In this section, perl variables will be expanded during extraction. # You can use $Config{...} to use Configure variables. print OUT <<"!GROK!THIS!"; $Config{startperl} eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}' if \$running_under_some_shell; !GROK!THIS! # In the following, perl variables are not expanded during extraction. print OUT <<'!NO!SUBS!'; # pod2latex conversion program use strict; use Pod::LaTeX; use Pod::Find qw/ pod_find /; use Pod::Usage; use Getopt::Long; use File::Basename; use Symbol; my $VERSION = "1.01"; # return the entire contents of a text file # whose name is given as argument sub _get { my $fn = shift; my $infh = gensym; open $infh, $fn or die "Could not open file $fn: $!\n"; local $/; return <$infh>; } # Read command line arguments my %options = ( "help" => 0, "man" => 0, "sections" => [], "full" => 0, "out" => undef, "verbose" => 0, "modify" => 0, "h1level" => 1, # section is equivalent to H1 "preamble" => [], "postamble" => [], ); # "prefile" is just like "preamble", but the argument # comes from the file named by the argument $options{"prefile"} = sub { shift; push @{$options{"preamble"}}, _get(shift) }; # the same between "postfile" and "postamble" $options{"postfile"} = sub { shift; push @{$options{"postamble"}}, _get(shift) }; GetOptions(\%options, "help", "man", "verbose", "full", "sections=s@", "out=s", "modify", "h1level=i", "preamble=s@", "postamble=s@", "prefile=s", "postfile=s" ) || pod2usage(2); pod2usage(1) if ($options{help}); pod2usage(-verbose => 2) if ($options{man}); # Read all the files from the command line my @files = @ARGV; # Now find which ones are real pods and convert # directories to their contents. # Extract the pods from each arg since some of them might # be directories # This is not as efficient as using pod_find to search through # everything at once but it allows us to preserve the order # supplied by the user my @pods; foreach my $arg (@files) { my %pods = pod_find($arg); push(@pods, sort keys %pods); } # Abort if nothing to do if ($#pods == -1) { warn "None of the supplied Pod files actually exist\n"; exit; } # Only want to override the preamble and postamble if we have # been given values. my %User; $User{UserPreamble} = join("\n", @{$options{'preamble'}}) if ($options{preamble} && @{$options{preamble}}); $User{UserPostamble} = join("\n", @{$options{'postamble'}}) if ($options{postamble} && @{$options{postamble}}); # If $options{'out'} is set we are processing to a single output file my $multi_documents; if (exists $options{'out'} && defined $options{'out'}) { $multi_documents = 0; } else { $multi_documents = 1; } # If the output file is not specified it is assumed that # a single output file is required per input file using # a .tex extension rather than any existing extension if ($multi_documents) { # Case where we just generate one input per output foreach my $pod (@pods) { if (-f $pod) { my $output = $pod; $output = basename($output, '.pm', '.pod','.pl') . '.tex'; # Create a new parser object my $parser = new Pod::LaTeX( AddPreamble => $options{'full'}, AddPostamble => $options{'full'}, MakeIndex => $options{'full'}, TableOfContents => $options{'full'}, ReplaceNAMEwithSection => $options{'modify'}, UniqueLabels => $options{'modify'}, Head1Level => $options{'h1level'}, LevelNoNum => $options{'h1level'} + 1, %User, ); # Select sections if supplied $parser->select(@{ $options{'sections'}}) if @{$options{'sections'}}; # Derive the input file from the output file $parser->parse_from_file($pod, $output); print "Written output to $output\n" if $options{'verbose'}; } else { warn "File $pod not found\n"; } } } else { # Case where we want everything to be in a single document # Need to open the output file ourselves my $output = $options{'out'}; $output .= '.tex' unless $output =~ /\.tex$/; # Use auto-vivified file handle in perl 5.6 my $outfh = gensym; open ($outfh, ">$output") || die "Could not open output file: $!\n"; # Flag to indicate whether we have converted at least one file # indicates how many files have been converted my $converted = 0; # Loop over the input files foreach my $pod (@pods) { if (-f $pod) { warn "Converting $pod\n" if $options{'verbose'}; # Open the file (need the handle) # Use auto-vivified handle in perl 5.6 my $podfh = gensym; open ($podfh, "<$pod") || die "Could not open pod file $pod: $!\n"; # if this is the first file to be converted we may want to add # a preamble (controlled by command line option) my $preamble = 0; $preamble = 1 if ($converted == 0 && $options{'full'}); # if this is the last file to be converted may want to add # a postamble (controlled by command line option) # relies on a previous pass to check existence of all pods we # are converting. my $postamble = ( ($converted == $#pods && $options{'full'}) ? 1 : 0 ); # Open parser object # May want to start with a preamble for the first one and # end with an index for the last my $parser = new Pod::LaTeX( MakeIndex => $options{'full'}, TableOfContents => $preamble, ReplaceNAMEwithSection => $options{'modify'}, UniqueLabels => $options{'modify'}, StartWithNewPage => $options{'full'}, AddPreamble => $preamble, AddPostamble => $postamble, Head1Level => $options{'h1level'}, LevelNoNum => $options{'h1level'} + 1, %User ); # Store the file name for error messages # This is a kluge that breaks the data hiding of the object $parser->{_INFILE} = $pod; # Select sections if supplied $parser->select(@{ $options{'sections'}}) if @{$options{'sections'}}; # Parse it $parser->parse_from_filehandle($podfh, $outfh); # We have converted at least one file $converted++; } else { warn "File $pod not found\n"; } } # Should unlink the file if we didn't convert anything! # dont check for return status of unlink # since there is not a lot to be done if the unlink failed # and the program does not rely upon it. unlink "$output" unless $converted; # If verbose warn "Converted $converted files\n" if $options{'verbose'}; } exit; __END__ =head1 NAME pod2latex - convert pod documentation to latex format =head1 SYNOPSIS pod2latex *.pm pod2latex -out mytex.tex *.pod pod2latex -full -sections 'DESCRIPTION|NAME' SomeDir pod2latex -prefile h.tex -postfile t.tex my.pod =head1 DESCRIPTION C is a program to convert POD format documentation (L) into latex. It can process multiple input documents at a time and either generate a latex file per input document or a single combined output file. =head1 OPTIONS AND ARGUMENTS This section describes the supported command line options. Minimum matching is supported. =over 4 =item B<-out> Name of the output file to be used. If there are multiple input pods it is assumed that the intention is to write all translated output into a single file. C<.tex> is appended if not present. If the argument is not supplied, a single document will be created for each input file. =item B<-full> Creates a complete C file that can be processed immediately (unless C<=for/=begin> directives are used that rely on extra packages). Table of contents and index generation commands are included in the wrapper C code. =item B<-sections> Specify pod sections to include (or remove if negated) in the translation. See L for the format to use for I. This option may be given multiple times on the command line.This is identical to the similar option in the C command. =item B<-modify> This option causes the output C to be slightly modified from the input pod such that when a C<=head1 NAME> is encountered a section is created containing the actual pod name (rather than B) and all subsequent C<=head1> directives are treated as subsections. This has the advantage that the description of a module will be in its own section which is helpful for including module descriptions in documentation. Also forces C label and index entries to be prefixed by the name of the module. =item B<-h1level> Specifies the C section that is equivalent to a C

pod directive. This is an integer between 0 and 5 with 0 equivalent to a C chapter, 1 equivalent to a C section etc. The default is 1 (C

equivalent to a latex section). =item B<-help> Print a brief help message and exit. =item B<-man> Print the manual page and exit. =item B<-verbose> Print information messages as each document is processed. =item B<-preamble> A user-supplied preamble for the LaTeX code. Multiple values are supported and appended in order separated by "\n". See B<-prefile> for reading the preamble from a file. =item B<-postamble> A user supplied postamble for the LaTeX code. Multiple values are supported and appended in order separated by "\n". See B<-postfile> for reading the postamble from a file. =item B<-prefile> A user-supplied preamble for the LaTeX code to be read from the named file. Multiple values are supported and appended in order. See B<-preamble>. =item B<-postfile> A user-supplied postamble for the LaTeX code to be read from the named file. Multiple values are supported and appended in order. See B<-postamble>. =back =head1 BUGS Known bugs are: =over 4 =item * Cross references between documents are not resolved when multiple pod documents are converted into a single output C file. =item * Functions and variables are not automatically recognized and they will therefore not be marked up in any special way unless instructed by an explicit pod command. =back =head1 SEE ALSO L =head1 AUTHOR Tim Jenness Etjenness@cpan.orgE This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Copyright (C) 2000, 2003, 2004 Tim Jenness. All Rights Reserved. =cut !NO!SUBS! close OUT or die "Can't close $file: $!"; chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':'; chdir $origdir; Pod-LaTeX-0.61/README000444000765000024 665512076247421 13422 0ustar00timjstaff000000000000Pod::LaTeX - convert Pod to latex using Pod::Parser This is version 0.60 of Pod::LaTeX. This module can be used to convert pod data to latex. It uses the standard Pod::Parser module. A pod2latex replacement command is provided. This can be installed over the pod2latex command distributed with perl. Please let me know of any problems. INSTALLATION % perl Build.PL % ./Build % ./Build test % ./Build install Currently the tests are not very good (only a simple test is provided). REQUIREMENTS Requires perl 5.005 or newer. Written completely in Perl. XS is not required. Requires the PodParser package from CPAN. This is standard with perl 5.6.0. This module is part of the standard perl distribution and has been since perl 5.6.1. AUTHOR Tim Jenness Copyright (C) 2011-2012 Tim Jenness. Copyright (C) 1999-2004 Tim Jenness and the UK Particle Physics and Astronomy Research Council. All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. CHANGES V0.61 - Update site vs perl install for perl v5.12 and above - Issue a deprecation warning if the module is being used in perl 5.17.0 and above. This module will be removed from perl Core for perl 5.20. (Ricardo Signes) It will still be available on CPAN. V0.60 - Patch for "--" from Dima Kogan (RT #72518) V0.59 - Use Module::Build - Fix trivial pod typo (RT #46887) V0.58 - Fix problem with [] in items (R. de Vries) V0.57 - Missing README file for V0.56 now added. No changes to code. V0.56 - Add -prefile/-postfile and -preamble/-postamble options to pod2latex and fix double printing of user postamble. (thanks to Adriano Rodrigues Ferreira) - UserPostamble and UserPreamble were erroneously being written even when AddPostamble and AddPreamble were false. V0.55 - Fix enumerated lists so that they do not double up the number (Aerial Scolnicov and Sudhi Herle) - Strip "." and ")" from numbers when looking for enumerated lists (Sudhi Herle) - Module now returns a true value (add 1; at end) (Dan Kogai) - Many new Pod escapes supported (Peter J Acklam) - The module now installs into the PERL dirs and not the site install if the perl version is greater than 5.6.0 (since this module is part of core perl as of v5.6.1). - The pod2latex script is now configured as a true pod2latex.PL application (imported changes from bleadperl) - Should now pass tests with Pod::ParseUtils v0.30 installed (thanks to Mark Veltzer for pointing out the problem) V0.54 - Fix misunderstanding with =for - Add fixes for < and > (and also |) - Fix tabbing (thanks to Hugh S Myers) - Fix strange indenting with long items (Hugh S Myers) - add a real test - Fix L<> since the fix to escape | had broken it - add -h1level to pod2latex V0.53 - Handle long items (Mark A Hershberge) - Escape ~ (Simon Cozens) - Add verbar and sol support as well as | escape (Marcel Grunauer) V0.52 - minor fix to pod2latex to preserve order of supplied arguments V0.51 - Fix some of the warning messages so that they report the line number in the pod file correctly for errors. - Fix escaping of ^, { and } V0.50 - First public release KNOWN BUGS - Does not automatically convert func() to B and $a to C<$a> - Probably does not match the new perlpodspec Pod-LaTeX-0.61/lib000755000765000024 012076247420 13136 5ustar00timjstaff000000000000Pod-LaTeX-0.61/lib/Pod000755000765000024 012076247420 13660 5ustar00timjstaff000000000000Pod-LaTeX-0.61/lib/Pod/LaTeX.pm000444000765000024 16430512076247420 15401 0ustar00timjstaff000000000000package Pod::LaTeX; =head1 NAME Pod::LaTeX - Convert Pod data to formatted Latex =head1 SYNOPSIS use Pod::LaTeX; my $parser = Pod::LaTeX->new ( ); $parser->parse_from_filehandle; $parser->parse_from_file ('file.pod', 'file.tex'); =head1 DESCRIPTION C is a module to convert documentation in the Pod format into Latex. The L|pod2latex> X command uses this module for translation. C is a derived class from L. =cut use strict; require Pod::ParseUtils; use base qw/ Pod::Select /; use if $] > 5.017, 'deprecate'; # use Data::Dumper; # for debugging use Carp; use vars qw/ $VERSION %HTML_Escapes @LatexSections /; $VERSION = '0.61'; # Definitions of =headN -> latex mapping @LatexSections = (qw/ chapter section subsection subsubsection paragraph subparagraph /); # Standard escape sequences converted to Latex. # The Unicode name of each character is given in the comments. # Complete LaTeX set added by Peter Acklam. %HTML_Escapes = ( 'sol' => '\textfractionsolidus{}', # xxx - or should it be just '/' 'verbar' => '|', # The stuff below is based on the information available at # http://www.w3.org/TR/html401/sgml/entities.html # All characters in the range 0xA0-0xFF of the ISO 8859-1 character set. # Several of these characters require the `textcomp' LaTeX package. 'nbsp' => q|~|, # 0xA0 - no-break space = non-breaking space 'iexcl' => q|\textexclamdown{}|, # 0xA1 - inverted exclamation mark 'cent' => q|\textcent{}|, # 0xA2 - cent sign 'pound' => q|\textsterling{}|, # 0xA3 - pound sign 'curren' => q|\textcurrency{}|, # 0xA4 - currency sign 'yen' => q|\textyen{}|, # 0xA5 - yen sign = yuan sign 'brvbar' => q|\textbrokenbar{}|, # 0xA6 - broken bar = broken vertical bar 'sect' => q|\textsection{}|, # 0xA7 - section sign 'uml' => q|\textasciidieresis{}|, # 0xA8 - diaeresis = spacing diaeresis 'copy' => q|\textcopyright{}|, # 0xA9 - copyright sign 'ordf' => q|\textordfeminine{}|, # 0xAA - feminine ordinal indicator 'laquo' => q|\guillemotleft{}|, # 0xAB - left-pointing double angle quotation mark = left pointing guillemet 'not' => q|\textlnot{}|, # 0xAC - not sign 'shy' => q|\-|, # 0xAD - soft hyphen = discretionary hyphen 'reg' => q|\textregistered{}|, # 0xAE - registered sign = registered trade mark sign 'macr' => q|\textasciimacron{}|, # 0xAF - macron = spacing macron = overline = APL overbar 'deg' => q|\textdegree{}|, # 0xB0 - degree sign 'plusmn' => q|\textpm{}|, # 0xB1 - plus-minus sign = plus-or-minus sign 'sup2' => q|\texttwosuperior{}|, # 0xB2 - superscript two = superscript digit two = squared 'sup3' => q|\textthreesuperior{}|, # 0xB3 - superscript three = superscript digit three = cubed 'acute' => q|\textasciiacute{}|, # 0xB4 - acute accent = spacing acute 'micro' => q|\textmu{}|, # 0xB5 - micro sign 'para' => q|\textparagraph{}|, # 0xB6 - pilcrow sign = paragraph sign 'middot' => q|\textperiodcentered{}|, # 0xB7 - middle dot = Georgian comma = Greek middle dot 'cedil' => q|\c{}|, # 0xB8 - cedilla = spacing cedilla 'sup1' => q|\textonesuperior{}|, # 0xB9 - superscript one = superscript digit one 'ordm' => q|\textordmasculine{}|, # 0xBA - masculine ordinal indicator 'raquo' => q|\guillemotright{}|, # 0xBB - right-pointing double angle quotation mark = right pointing guillemet 'frac14' => q|\textonequarter{}|, # 0xBC - vulgar fraction one quarter = fraction one quarter 'frac12' => q|\textonehalf{}|, # 0xBD - vulgar fraction one half = fraction one half 'frac34' => q|\textthreequarters{}|, # 0xBE - vulgar fraction three quarters = fraction three quarters 'iquest' => q|\textquestiondown{}|, # 0xBF - inverted question mark = turned question mark 'Agrave' => q|\`A|, # 0xC0 - latin capital letter A with grave = latin capital letter A grave 'Aacute' => q|\'A|, # 0xC1 - latin capital letter A with acute 'Acirc' => q|\^A|, # 0xC2 - latin capital letter A with circumflex 'Atilde' => q|\~A|, # 0xC3 - latin capital letter A with tilde 'Auml' => q|\"A|, # 0xC4 - latin capital letter A with diaeresis 'Aring' => q|\AA{}|, # 0xC5 - latin capital letter A with ring above = latin capital letter A ring 'AElig' => q|\AE{}|, # 0xC6 - latin capital letter AE = latin capital ligature AE 'Ccedil' => q|\c{C}|, # 0xC7 - latin capital letter C with cedilla 'Egrave' => q|\`E|, # 0xC8 - latin capital letter E with grave 'Eacute' => q|\'E|, # 0xC9 - latin capital letter E with acute 'Ecirc' => q|\^E|, # 0xCA - latin capital letter E with circumflex 'Euml' => q|\"E|, # 0xCB - latin capital letter E with diaeresis 'Igrave' => q|\`I|, # 0xCC - latin capital letter I with grave 'Iacute' => q|\'I|, # 0xCD - latin capital letter I with acute 'Icirc' => q|\^I|, # 0xCE - latin capital letter I with circumflex 'Iuml' => q|\"I|, # 0xCF - latin capital letter I with diaeresis 'ETH' => q|\DH{}|, # 0xD0 - latin capital letter ETH 'Ntilde' => q|\~N|, # 0xD1 - latin capital letter N with tilde 'Ograve' => q|\`O|, # 0xD2 - latin capital letter O with grave 'Oacute' => q|\'O|, # 0xD3 - latin capital letter O with acute 'Ocirc' => q|\^O|, # 0xD4 - latin capital letter O with circumflex 'Otilde' => q|\~O|, # 0xD5 - latin capital letter O with tilde 'Ouml' => q|\"O|, # 0xD6 - latin capital letter O with diaeresis 'times' => q|\texttimes{}|, # 0xD7 - multiplication sign 'Oslash' => q|\O{}|, # 0xD8 - latin capital letter O with stroke = latin capital letter O slash 'Ugrave' => q|\`U|, # 0xD9 - latin capital letter U with grave 'Uacute' => q|\'U|, # 0xDA - latin capital letter U with acute 'Ucirc' => q|\^U|, # 0xDB - latin capital letter U with circumflex 'Uuml' => q|\"U|, # 0xDC - latin capital letter U with diaeresis 'Yacute' => q|\'Y|, # 0xDD - latin capital letter Y with acute 'THORN' => q|\TH{}|, # 0xDE - latin capital letter THORN 'szlig' => q|\ss{}|, # 0xDF - latin small letter sharp s = ess-zed 'agrave' => q|\`a|, # 0xE0 - latin small letter a with grave = latin small letter a grave 'aacute' => q|\'a|, # 0xE1 - latin small letter a with acute 'acirc' => q|\^a|, # 0xE2 - latin small letter a with circumflex 'atilde' => q|\~a|, # 0xE3 - latin small letter a with tilde 'auml' => q|\"a|, # 0xE4 - latin small letter a with diaeresis 'aring' => q|\aa{}|, # 0xE5 - latin small letter a with ring above = latin small letter a ring 'aelig' => q|\ae{}|, # 0xE6 - latin small letter ae = latin small ligature ae 'ccedil' => q|\c{c}|, # 0xE7 - latin small letter c with cedilla 'egrave' => q|\`e|, # 0xE8 - latin small letter e with grave 'eacute' => q|\'e|, # 0xE9 - latin small letter e with acute 'ecirc' => q|\^e|, # 0xEA - latin small letter e with circumflex 'euml' => q|\"e|, # 0xEB - latin small letter e with diaeresis 'igrave' => q|\`i|, # 0xEC - latin small letter i with grave 'iacute' => q|\'i|, # 0xED - latin small letter i with acute 'icirc' => q|\^i|, # 0xEE - latin small letter i with circumflex 'iuml' => q|\"i|, # 0xEF - latin small letter i with diaeresis 'eth' => q|\dh{}|, # 0xF0 - latin small letter eth 'ntilde' => q|\~n|, # 0xF1 - latin small letter n with tilde 'ograve' => q|\`o|, # 0xF2 - latin small letter o with grave 'oacute' => q|\'o|, # 0xF3 - latin small letter o with acute 'ocirc' => q|\^o|, # 0xF4 - latin small letter o with circumflex 'otilde' => q|\~o|, # 0xF5 - latin small letter o with tilde 'ouml' => q|\"o|, # 0xF6 - latin small letter o with diaeresis 'divide' => q|\textdiv{}|, # 0xF7 - division sign 'oslash' => q|\o{}|, # 0xF8 - latin small letter o with stroke, = latin small letter o slash 'ugrave' => q|\`u|, # 0xF9 - latin small letter u with grave 'uacute' => q|\'u|, # 0xFA - latin small letter u with acute 'ucirc' => q|\^u|, # 0xFB - latin small letter u with circumflex 'uuml' => q|\"u|, # 0xFC - latin small letter u with diaeresis 'yacute' => q|\'y|, # 0xFD - latin small letter y with acute 'thorn' => q|\th{}|, # 0xFE - latin small letter thorn 'yuml' => q|\"y|, # 0xFF - latin small letter y with diaeresis # Latin Extended-B 'fnof' => q|\textflorin{}|, # latin small f with hook = function = florin # Greek 'Alpha' => q|$\mathrm{A}$|, # greek capital letter alpha 'Beta' => q|$\mathrm{B}$|, # greek capital letter beta 'Gamma' => q|$\Gamma$|, # greek capital letter gamma 'Delta' => q|$\Delta$|, # greek capital letter delta 'Epsilon' => q|$\mathrm{E}$|, # greek capital letter epsilon 'Zeta' => q|$\mathrm{Z}$|, # greek capital letter zeta 'Eta' => q|$\mathrm{H}$|, # greek capital letter eta 'Theta' => q|$\Theta$|, # greek capital letter theta 'Iota' => q|$\mathrm{I}$|, # greek capital letter iota 'Kappa' => q|$\mathrm{K}$|, # greek capital letter kappa 'Lambda' => q|$\Lambda$|, # greek capital letter lambda 'Mu' => q|$\mathrm{M}$|, # greek capital letter mu 'Nu' => q|$\mathrm{N}$|, # greek capital letter nu 'Xi' => q|$\Xi$|, # greek capital letter xi 'Omicron' => q|$\mathrm{O}$|, # greek capital letter omicron 'Pi' => q|$\Pi$|, # greek capital letter pi 'Rho' => q|$\mathrm{R}$|, # greek capital letter rho 'Sigma' => q|$\Sigma$|, # greek capital letter sigma 'Tau' => q|$\mathrm{T}$|, # greek capital letter tau 'Upsilon' => q|$\Upsilon$|, # greek capital letter upsilon 'Phi' => q|$\Phi$|, # greek capital letter phi 'Chi' => q|$\mathrm{X}$|, # greek capital letter chi 'Psi' => q|$\Psi$|, # greek capital letter psi 'Omega' => q|$\Omega$|, # greek capital letter omega 'alpha' => q|$\alpha$|, # greek small letter alpha 'beta' => q|$\beta$|, # greek small letter beta 'gamma' => q|$\gamma$|, # greek small letter gamma 'delta' => q|$\delta$|, # greek small letter delta 'epsilon' => q|$\epsilon$|, # greek small letter epsilon 'zeta' => q|$\zeta$|, # greek small letter zeta 'eta' => q|$\eta$|, # greek small letter eta 'theta' => q|$\theta$|, # greek small letter theta 'iota' => q|$\iota$|, # greek small letter iota 'kappa' => q|$\kappa$|, # greek small letter kappa 'lambda' => q|$\lambda$|, # greek small letter lambda 'mu' => q|$\mu$|, # greek small letter mu 'nu' => q|$\nu$|, # greek small letter nu 'xi' => q|$\xi$|, # greek small letter xi 'omicron' => q|$o$|, # greek small letter omicron 'pi' => q|$\pi$|, # greek small letter pi 'rho' => q|$\rho$|, # greek small letter rho # 'sigmaf' => q||, # greek small letter final sigma 'sigma' => q|$\sigma$|, # greek small letter sigma 'tau' => q|$\tau$|, # greek small letter tau 'upsilon' => q|$\upsilon$|, # greek small letter upsilon 'phi' => q|$\phi$|, # greek small letter phi 'chi' => q|$\chi$|, # greek small letter chi 'psi' => q|$\psi$|, # greek small letter psi 'omega' => q|$\omega$|, # greek small letter omega # 'thetasym' => q||, # greek small letter theta symbol # 'upsih' => q||, # greek upsilon with hook symbol # 'piv' => q||, # greek pi symbol # General Punctuation 'bull' => q|\textbullet{}|, # bullet = black small circle # bullet is NOT the same as bullet operator 'hellip' => q|\textellipsis{}|, # horizontal ellipsis = three dot leader 'prime' => q|\textquotesingle{}|, # prime = minutes = feet 'Prime' => q|\textquotedbl{}|, # double prime = seconds = inches 'oline' => q|\textasciimacron{}|, # overline = spacing overscore 'frasl' => q|\textfractionsolidus{}|, # fraction slash # Letterlike Symbols 'weierp' => q|$\wp$|, # script capital P = power set = Weierstrass p 'image' => q|$\Re$|, # blackletter capital I = imaginary part 'real' => q|$\Im$|, # blackletter capital R = real part symbol 'trade' => q|\texttrademark{}|, # trade mark sign # 'alefsym' => q||, # alef symbol = first transfinite cardinal # alef symbol is NOT the same as hebrew letter alef, although the same # glyph could be used to depict both characters # Arrows 'larr' => q|\textleftarrow{}|, # leftwards arrow 'uarr' => q|\textuparrow{}|, # upwards arrow 'rarr' => q|\textrightarrow{}|, # rightwards arrow 'darr' => q|\textdownarrow{}|, # downwards arrow 'harr' => q|$\leftrightarrow$|, # left right arrow # 'crarr' => q||, # downwards arrow with corner leftwards = carriage return 'lArr' => q|$\Leftarrow$|, # leftwards double arrow # ISO 10646 does not say that lArr is the same as the 'is implied by' # arrow but also does not have any other character for that function. So # lArr can be used for 'is implied by' as ISOtech suggests 'uArr' => q|$\Uparrow$|, # upwards double arrow 'rArr' => q|$\Rightarrow$|, # rightwards double arrow # ISO 10646 does not say this is the 'implies' character but does not # have another character with this function so ? rArr can be used for # 'implies' as ISOtech suggests 'dArr' => q|$\Downarrow$|, # downwards double arrow 'hArr' => q|$\Leftrightarrow$|, # left right double arrow # Mathematical Operators. # Some of these require the `amssymb' package. 'forall' => q|$\forall$|, # for all 'part' => q|$\partial$|, # partial differential 'exist' => q|$\exists$|, # there exists 'empty' => q|$\emptyset$|, # empty set = null set = diameter 'nabla' => q|$\nabla$|, # nabla = backward difference 'isin' => q|$\in$|, # element of 'notin' => q|$\notin$|, # not an element of 'ni' => q|$\ni$|, # contains as member 'prod' => q|$\prod$|, # n-ary product = product sign # prod is NOT the same character as 'greek capital letter pi' though the # same glyph might be used for both 'sum' => q|$\sum$|, # n-ary summation # sum is NOT the same character as 'greek capital letter sigma' though # the same glyph might be used for both 'minus' => q|$-$|, # minus sign 'lowast' => q|$\ast$|, # asterisk operator 'radic' => q|$\surd$|, # square root = radical sign 'prop' => q|$\propto$|, # proportional to 'infin' => q|$\infty$|, # infinity 'ang' => q|$\angle$|, # angle 'and' => q|$\wedge$|, # logical and = wedge 'or' => q|$\vee$|, # logical or = vee 'cap' => q|$\cap$|, # intersection = cap 'cup' => q|$\cup$|, # union = cup 'int' => q|$\int$|, # integral 'there4' => q|$\therefore$|, # therefore 'sim' => q|$\sim$|, # tilde operator = varies with = similar to # tilde operator is NOT the same character as the tilde 'cong' => q|$\cong$|, # approximately equal to 'asymp' => q|$\asymp$|, # almost equal to = asymptotic to 'ne' => q|$\neq$|, # not equal to 'equiv' => q|$\equiv$|, # identical to 'le' => q|$\leq$|, # less-than or equal to 'ge' => q|$\geq$|, # greater-than or equal to 'sub' => q|$\subset$|, # subset of 'sup' => q|$\supset$|, # superset of # note that nsup, 'not a superset of' is not covered by the Symbol font # encoding and is not included. 'nsub' => q|$\not\subset$|, # not a subset of 'sube' => q|$\subseteq$|, # subset of or equal to 'supe' => q|$\supseteq$|, # superset of or equal to 'oplus' => q|$\oplus$|, # circled plus = direct sum 'otimes' => q|$\otimes$|, # circled times = vector product 'perp' => q|$\perp$|, # up tack = orthogonal to = perpendicular 'sdot' => q|$\cdot$|, # dot operator # dot operator is NOT the same character as middle dot # Miscellaneous Technical 'lceil' => q|$\lceil$|, # left ceiling = apl upstile 'rceil' => q|$\rceil$|, # right ceiling 'lfloor' => q|$\lfloor$|, # left floor = apl downstile 'rfloor' => q|$\rfloor$|, # right floor 'lang' => q|$\langle$|, # left-pointing angle bracket = bra # lang is NOT the same character as 'less than' or 'single left-pointing # angle quotation mark' 'rang' => q|$\rangle$|, # right-pointing angle bracket = ket # rang is NOT the same character as 'greater than' or 'single # right-pointing angle quotation mark' # Geometric Shapes 'loz' => q|$\lozenge$|, # lozenge # Miscellaneous Symbols 'spades' => q|$\spadesuit$|, # black spade suit 'clubs' => q|$\clubsuit$|, # black club suit = shamrock 'hearts' => q|$\heartsuit$|, # black heart suit = valentine 'diams' => q|$\diamondsuit$|, # black diamond suit # C0 Controls and Basic Latin 'quot' => q|"|, # quotation mark = APL quote ["] 'amp' => q|\&|, # ampersand 'lt' => q|<|, # less-than sign 'gt' => q|>|, # greater-than sign 'OElig' => q|\OE{}|, # latin capital ligature OE 'oelig' => q|\oe{}|, # latin small ligature oe 'Scaron' => q|\v{S}|, # latin capital letter S with caron 'scaron' => q|\v{s}|, # latin small letter s with caron 'Yuml' => q|\"Y|, # latin capital letter Y with diaeresis 'circ' => q|\textasciicircum{}|, # modifier letter circumflex accent 'tilde' => q|\textasciitilde{}|, # small tilde 'ensp' => q|\phantom{n}|, # en space 'emsp' => q|\hspace{1em}|, # em space 'thinsp' => q|\,|, # thin space 'zwnj' => q|{}|, # zero width non-joiner # 'zwj' => q||, # zero width joiner # 'lrm' => q||, # left-to-right mark # 'rlm' => q||, # right-to-left mark 'ndash' => q|--|, # en dash 'mdash' => q|---|, # em dash 'lsquo' => q|\textquoteleft{}|, # left single quotation mark 'rsquo' => q|\textquoteright{}|, # right single quotation mark 'sbquo' => q|\quotesinglbase{}|, # single low-9 quotation mark 'ldquo' => q|\textquotedblleft{}|, # left double quotation mark 'rdquo' => q|\textquotedblright{}|, # right double quotation mark 'bdquo' => q|\quotedblbase{}|, # double low-9 quotation mark 'dagger' => q|\textdagger{}|, # dagger 'Dagger' => q|\textdaggerdbl{}|, # double dagger 'permil' => q|\textperthousand{}|, # per mille sign 'lsaquo' => q|\guilsinglleft{}|, # single left-pointing angle quotation mark 'rsaquo' => q|\guilsinglright{}|, # single right-pointing angle quotation mark 'euro' => q|\texteuro{}|, # euro sign ); =head1 OBJECT METHODS The following methods are provided in this module. Methods inherited from C are not described in the public interface. =over 4 =begin __PRIVATE__ =item C Initialise the object. This method is subclassed from C. The base class method is invoked. This method defines the default behaviour of the object unless overridden by supplying arguments to the constructor. Internal settings are defaulted as well as the public instance data. Internal hash values are accessed directly (rather than through a method) and start with an underscore. This method should not be invoked by the user directly. =end __PRIVATE__ =cut # - An array for nested lists # Arguments have already been read by this point sub initialize { my $self = shift; # print Dumper($self); # Internals $self->{_Lists} = []; # For nested lists $self->{_suppress_all_para} = 0; # For =begin blocks $self->{_dont_modify_any_para}=0; # For =begin blocks $self->{_CURRENT_HEAD1} = ''; # Name of current HEAD1 section # Options - only initialise if not already set # Cause the '=head1 NAME' field to be treated specially # The contents of the NAME paragraph will be converted # to a section title. All subsequent =head1 will be converted # to =head2 and down. Will not affect =head1's prior to NAME # Assumes: 'Module - purpose' format # Also creates a purpose field # The name is used for Labeling of the subsequent subsections $self->{ReplaceNAMEwithSection} = 0 unless exists $self->{ReplaceNAMEwithSection}; $self->{AddPreamble} = 1 # make full latex document unless exists $self->{AddPreamble}; $self->{StartWithNewPage} = 0 # Start new page for pod section unless exists $self->{StartWithNewPage}; $self->{TableOfContents} = 0 # Add table of contents unless exists $self->{TableOfContents}; # only relevant if AddPreamble=1 $self->{AddPostamble} = 1 # Add closing latex code at end unless exists $self->{AddPostamble}; # effectively end{document} and index $self->{MakeIndex} = 1 # Add index (only relevant AddPostamble unless exists $self->{MakeIndex}; # and AddPreamble) $self->{UniqueLabels} = 1 # Use label unique for each pod unless exists $self->{UniqueLabels}; # either based on the filename # or supplied # Control the level of =head1. default is \section # $self->{Head1Level} = 1 # Offset in latex sections unless exists $self->{Head1Level}; # 0 is chapter, 2 is subsection # Control at which level numbering of sections is turned off # ie subsection becomes subsection* # The numbering is relative to the latex sectioning commands # and is independent of Pod heading level # default is to number \section but not \subsection $self->{LevelNoNum} = 2 unless exists $self->{LevelNoNum}; # Label to be used as prefix to all internal section names # If not defined will attempt to derive it from the filename # This can not happen when running parse_from_filehandle though # hence the ability to set the label externally # The label could then be Pod::Parser_DESCRIPTION or somesuch $self->{Label} = undef # label to be used as prefix unless exists $self->{Label}; # to all internal section names # These allow the caller to add arbitrary latex code to # start and end of document. AddPreamble and AddPostamble are ignored # if these are set. # Also MakeIndex and TableOfContents are also ignored. $self->{UserPreamble} = undef # User supplied start (AddPreamble =1) unless exists $self->{Label}; $self->{UserPostamble} = undef # Use supplied end (AddPostamble=1) unless exists $self->{Label}; # Run base initialize $self->SUPER::initialize; } =back =head2 Data Accessors The following methods are provided for accessing instance data. These methods should be used for accessing configuration parameters rather than assuming the object is a hash. Default values can be supplied by using these names as keys to a hash of arguments when using the C constructor. =over 4 =item B Logical to control whether a C preamble is to be written. If true, a valid C preamble is written before the pod data is written. This is similar to: \documentclass{article} \usepackage[T1]{fontenc} \usepackage{textcomp} \begin{document} but will be more complicated if table of contents and indexing are required. Can be used to set or retrieve the current value. $add = $parser->AddPreamble(); $parser->AddPreamble(1); If used in conjunction with C a full latex document will be written that could be immediately processed by C. For some pod escapes it may be necessary to include the amsmath package. This is not yet added to the preamble automatically. =cut sub AddPreamble { my $self = shift; if (@_) { $self->{AddPreamble} = shift; } return $self->{AddPreamble}; } =item B Logical to control whether a standard C 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 a full latex document will be written that could be immediately processed by C. =cut sub AddPostamble { my $self = shift; if (@_) { $self->{AddPostamble} = shift; } return $self->{AddPostamble}; } =item B The C 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 C. 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 section (C<=head1> would correspond to a C). 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
). =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