3 # Copyright (C) 2000 by Tim Jenness <t.jenness@jach.hawaii.edu>
8 Pod::LaTeX - Convert Pod data to formatted Latex
13 my $parser = Pod::LaTeX->new ( );
15 $parser->parse_from_filehandle;
17 $parser->parse_from_file ('file.pod', 'file.tex');
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.
25 C<Pod::LaTeX> is a derived class from L<Pod::Select|Pod::Select>.
31 require Pod::ParseUtils;
32 use base qw/ Pod::Select /;
34 # use Data::Dumper; # for debugging
37 use vars qw/ $VERSION %HTML_Escapes @LatexSections /;
41 # Definitions of =headN -> latex mapping
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)
56 'amp' => '&', # ampersand
57 'lt' => '$<$', # ' left chevron, less-than
58 'gt' => '$>$', # ' right chevron, greater-than
59 'quot' => '"', # double quote
61 "Aacute" => "\\'{A}", # capital A, acute accent
62 "aacute" => "\\'{a}", # small a, acute accent
63 "Acirc" => "\\^{A}", # capital A, circumflex accent
64 "acirc" => "\\^{a}", # small a, circumflex accent
65 "AElig" => '\\AE', # capital AE diphthong (ligature)
66 "aelig" => '\\ae', # small ae diphthong (ligature)
67 "Agrave" => "\\`{A}", # capital A, grave accent
68 "agrave" => "\\`{a}", # small a, grave accent
69 "Aring" => '\\u{A}', # capital A, ring
70 "aring" => '\\u{a}', # small a, ring
71 "Atilde" => '\\~{A}', # capital A, tilde
72 "atilde" => '\\~{a}', # small a, tilde
73 "Auml" => '\\"{A}', # capital A, dieresis or umlaut mark
74 "auml" => '\\"{a}', # small a, dieresis or umlaut mark
75 "Ccedil" => '\\c{C}', # capital C, cedilla
76 "ccedil" => '\\c{c}', # small c, cedilla
77 "Eacute" => "\\'{E}", # capital E, acute accent
78 "eacute" => "\\'{e}", # small e, acute accent
79 "Ecirc" => "\\^{E}", # capital E, circumflex accent
80 "ecirc" => "\\^{e}", # small e, circumflex accent
81 "Egrave" => "\\`{E}", # capital E, grave accent
82 "egrave" => "\\`{e}", # small e, grave accent
83 "ETH" => '\\OE', # capital Eth, Icelandic
84 "eth" => '\\oe', # small eth, Icelandic
85 "Euml" => '\\"{E}', # capital E, dieresis or umlaut mark
86 "euml" => '\\"{e}', # small e, dieresis or umlaut mark
87 "Iacute" => "\\'{I}", # capital I, acute accent
88 "iacute" => "\\'{i}", # small i, acute accent
89 "Icirc" => "\\^{I}", # capital I, circumflex accent
90 "icirc" => "\\^{i}", # small i, circumflex accent
91 "Igrave" => "\\`{I}", # capital I, grave accent
92 "igrave" => "\\`{i}", # small i, grave accent
93 "Iuml" => '\\"{I}', # capital I, dieresis or umlaut mark
94 "iuml" => '\\"{i}', # small i, dieresis or umlaut mark
95 "Ntilde" => '\\~{N}', # capital N, tilde
96 "ntilde" => '\\~{n}', # small n, tilde
97 "Oacute" => "\\'{O}", # capital O, acute accent
98 "oacute" => "\\'{o}", # small o, acute accent
99 "Ocirc" => "\\^{O}", # capital O, circumflex accent
100 "ocirc" => "\\^{o}", # small o, circumflex accent
101 "Ograve" => "\\`{O}", # capital O, grave accent
102 "ograve" => "\\`{o}", # small o, grave accent
103 "Oslash" => "\\O", # capital O, slash
104 "oslash" => "\\o", # small o, slash
105 "Otilde" => "\\~{O}", # capital O, tilde
106 "otilde" => "\\~{o}", # small o, tilde
107 "Ouml" => '\\"{O}', # capital O, dieresis or umlaut mark
108 "ouml" => '\\"{o}', # small o, dieresis or umlaut mark
109 "szlig" => '\\ss{}', # small sharp s, German (sz ligature)
110 "THORN" => '\\L', # capital THORN, Icelandic
111 "thorn" => '\\l',, # small thorn, Icelandic
112 "Uacute" => "\\'{U}", # capital U, acute accent
113 "uacute" => "\\'{u}", # small u, acute accent
114 "Ucirc" => "\\^{U}", # capital U, circumflex accent
115 "ucirc" => "\\^{u}", # small u, circumflex accent
116 "Ugrave" => "\\`{U}", # capital U, grave accent
117 "ugrave" => "\\`{u}", # small u, grave accent
118 "Uuml" => '\\"{U}', # capital U, dieresis or umlaut mark
119 "uuml" => '\\"{u}', # small u, dieresis or umlaut mark
120 "Yacute" => "\\'{Y}", # capital Y, acute accent
121 "yacute" => "\\'{y}", # small y, acute accent
122 "yuml" => '\\"{y}', # small y, dieresis or umlaut mark
126 "iexcl" => '!`', # inverted exclamation mark
127 # "cent" => ' ', # cent sign
128 "pound" => '\pounds', # (UK) pound sign
129 # "curren" => ' ', # currency sign
130 # "yen" => ' ', # yen sign
131 # "brvbar" => ' ', # broken vertical bar
132 "sect" => '\S', # section sign
133 "uml" => '\"{}', # diaresis
134 "copy" => '\copyright', # Copyright symbol
135 # "ordf" => ' ', # feminine ordinal indicator
136 "laquo" => '$\ll$', # ' # left pointing double angle quotation mark
137 "not" => '$\neg$', # ' # not sign
138 "shy" => '-', # soft hyphen
139 # "reg" => ' ', # registered trademark
140 "macr" => '$^-$', # ' # macron, overline
141 "deg" => '$^\circ$', # ' # degree sign
142 "plusmn" => '$\pm$', # ' # plus-minus sign
143 "sup2" => '$^2$', # ' # superscript 2
144 "sup3" => '$^3$', # ' # superscript 3
145 "acute" => "\\'{}", # acute accent
146 "micro" => '$\mu$', # micro sign
147 "para" => '\P', # pilcrow sign = paragraph sign
148 "middot" => '$\cdot$', # middle dot = Georgian comma
149 "cedil" => '\c{}', # cedilla
150 "sup1" => '$^1$', # ' # superscript 1
151 # "ordm" => ' ', # masculine ordinal indicator
152 "raquo" => '$\gg$', # ' # right pointing double angle quotation mark
153 "frac14" => '$\frac{1}{4}$', # ' # vulgar fraction one quarter
154 "frac12" => '$\frac{1}{2}$', # ' # vulgar fraction one half
155 "frac34" => '$\frac{3}{4}$', # ' # vulgar fraction three quarters
156 "iquest" => "?'", # inverted question mark
157 "times" => '$\times$', # ' # multiplication sign
158 "divide" => '$\div$', # division sign
160 # Greek letters using HTML codes
161 "alpha" => '$\alpha$', # '
162 "beta" => '$\beta$', # '
163 "gamma" => '$\gamma$', # '
164 "delta" => '$\delta$', # '
165 "epsilon"=> '$\epsilon$', # '
166 "zeta" => '$\zeta$', # '
167 "eta" => '$\eta$', # '
168 "theta" => '$\theta$', # '
169 "iota" => '$\iota$', # '
170 "kappa" => '$\kappa$', # '
171 "lambda" => '$\lambda$', # '
175 "omicron"=> '$o$', # '
177 "rho" => '$\rho$', # '
178 "sigma" => '$\sigma$', # '
179 "tau" => '$\tau$', # '
180 "upsilon"=> '$\upsilon$', # '
181 "phi" => '$\phi$', # '
182 "chi" => '$\chi$', # '
183 "psi" => '$\psi$', # '
184 "omega" => '$\omega$', # '
186 "Alpha" => '$A$', # '
188 "Gamma" => '$\Gamma$', # '
189 "Delta" => '$\Delta$', # '
190 "Epsilon"=> '$E$', # '
193 "Theta" => '$\Theta$', # '
195 "Kappa" => '$K$', # '
196 "Lambda" => '$\Lambda$', # '
200 "Omicron"=> '$O$', # '
203 "Sigma" => '$\Sigma$', # '
205 "Upsilon"=> '$\Upsilon$', # '
206 "Phi" => '$\Phi$', # '
208 "Psi" => '$\Psi$', # '
209 "Omega" => '$\Omega$', # '
215 =head1 OBJECT METHODS
217 The following methods are provided in this module. Methods inherited
218 from C<Pod::Select> are not described in the public interface.
226 Initialise the object. This method is subclassed from C<Pod::Parser>.
227 The base class method is invoked. This method defines the default
228 behaviour of the object unless overridden by supplying arguments to
231 Internal settings are defaulted as well as the public instance data.
232 Internal hash values are accessed directly (rather than through
233 a method) and start with an underscore.
235 This method should not be invoked by the user directly.
243 # - An array for nested lists
245 # Arguments have already been read by this point
250 # print Dumper($self);
253 $self->{_Lists} = []; # For nested lists
254 $self->{_suppress_all_para} = 0; # For =begin blocks
255 $self->{_suppress_next_para} = 0; # For =for blocks
256 $self->{_dont_modify_any_para}=0; # For =begin blocks
257 $self->{_dont_modify_next_para}=0; # For =for blocks
258 $self->{_CURRENT_HEAD1} = ''; # Name of current HEAD1 section
260 # Options - only initialise if not already set
262 # Cause the '=head1 NAME' field to be treated specially
263 # The contents of the NAME paragraph will be converted
264 # to a section title. All subsequent =head1 will be converted
265 # to =head2 and down. Will not affect =head1's prior to NAME
266 # Assumes: 'Module - purpose' format
267 # Also creates a purpose field
268 # The name is used for Labeling of the subsequent subsections
269 $self->{ReplaceNAMEwithSection} = 0
270 unless exists $self->{ReplaceNAMEwithSection};
271 $self->{AddPreamble} = 1 # make full latex document
272 unless exists $self->{AddPreamble};
273 $self->{StartWithNewPage} = 0 # Start new page for pod section
274 unless exists $self->{StartWithNewPage};
275 $self->{TableOfContents} = 0 # Add table of contents
276 unless exists $self->{TableOfContents}; # only relevent if AddPreamble=1
277 $self->{AddPostamble} = 1 # Add closing latex code at end
278 unless exists $self->{AddPostamble}; # effectively end{document} and index
279 $self->{MakeIndex} = 1 # Add index (only relevant AddPostamble
280 unless exists $self->{MakeIndex}; # and AddPreamble)
282 $self->{UniqueLabels} = 1 # Use label unique for each pod
283 unless exists $self->{UniqueLabels}; # either based on the filename
286 # Control the level of =head1. default is \section
288 $self->{Head1Level} = 1 # Offset in latex sections
289 unless exists $self->{Head1Level}; # 0 is chapter, 2 is subsection
291 # Control at which level numbering of sections is turned off
292 # ie subsection becomes subsection*
293 # The numbering is relative to the latex sectioning commands
294 # and is independent of Pod heading level
295 # default is to number \section but not \subsection
296 $self->{LevelNoNum} = 2
297 unless exists $self->{LevelNoNum};
299 # Label to be used as prefix to all internal section names
300 # If not defined will attempt to derive it from the filename
301 # This can not happen when running parse_from_filehandle though
302 # hence the ability to set the label externally
303 # The label could then be Pod::Parser_DESCRIPTION or somesuch
305 $self->{Label} = undef # label to be used as prefix
306 unless exists $self->{Label}; # to all internal section names
308 # These allow the caller to add arbritrary latex code to
309 # start and end of document. AddPreamble and AddPostamble are ignored
311 # Also MakeIndex and TableOfContents are also ignored.
312 $self->{UserPreamble} = undef # User supplied start (AddPreamble =1)
313 unless exists $self->{Label};
314 $self->{UserPostamble} = undef # Use supplied end (AddPostamble=1)
315 unless exists $self->{Label};
317 # Run base initialize
318 $self->SUPER::initialize;
324 =head2 Data Accessors
326 The following methods are provided for accessing instance data. These
327 methods should be used for accessing configuration parameters rather
328 than assuming the object is a hash.
330 Default values can be supplied by using these names as keys to a hash
331 of arguments when using the C<new()> constructor.
337 Logical to control whether a C<latex> preamble is to be written.
338 If true, a valid C<latex> preamble is written before the pod data is written.
341 \documentclass{article}
344 but will be more complicated if table of contents and indexing are required.
345 Can be used to set or retrieve the current value.
347 $add = $parser->AddPreamble();
348 $parser->AddPreamble(1);
350 If used in conjunction with C<AddPostamble> a full latex document will
351 be written that could be immediately processed by C<latex>.
358 $self->{AddPreamble} = shift;
360 return $self->{AddPreamble};
363 =item B<AddPostamble>
365 Logical to control whether a standard C<latex> ending is written to the output
366 file after the document has been processed.
367 In its simplest form this is simply:
371 but can be more complicated if a index is required.
372 Can be used to set or retrieve the current value.
374 $add = $parser->AddPostamble();
375 $parser->AddPostamble(1);
377 If used in conjunction with C<AddPreaamble> a full latex document will
378 be written that could be immediately processed by C<latex>.
385 $self->{AddPostamble} = shift;
387 return $self->{AddPostamble};
392 The C<latex> sectioning level that should be used to correspond to
393 a pod C<=head1> directive. This can be used, for example, to turn
394 a C<=head1> into a C<latex> C<subsection>. This should hold a number
395 corresponding to the required position in an array containing the
405 Can be used to set or retrieve the current value:
407 $parser->Head1Level(2);
408 $sect = $parser->Head1Level;
410 Setting this number too high can result in sections that may not be reproducible
411 in the expected way. For example, setting this to 4 would imply that C<=head3>
412 do not have a corresponding C<latex> section (C<=head1> would correspond to
415 A check is made to ensure that the supplied value is an integer in the
418 Default is for a value of 1 (i.e. a C<section>).
426 if ($arg =~ /^\d$/ && $arg <= $#LatexSections) {
427 $self->{Head1Level} = $arg;
429 carp "Head1Level supplied ($arg) must be integer in range 0 to ".$#LatexSections . "- Ignoring\n";
432 return $self->{Head1Level};
437 This is the label that is prefixed to all C<latex> label and index
438 entries to make them unique. In general, pods have similarly titled
439 sections (NAME, DESCRIPTION etc) and a C<latex> label will be multiply
440 defined if more than one pod document is to be included in a single
441 C<latex> file. To overcome this, this label is prefixed to a label
442 whenever a label is required (joined with an underscore) or to an
443 index entry (joined by an exclamation mark which is the normal index
444 separator). For example, C<\label{text}> becomes C<\label{Label_text}>.
446 Can be used to set or retrieve the current value:
448 $label = $parser->Label;
449 $parser->Label($label);
451 This label is only used if C<UniqueLabels> is true.
452 Its value is set automatically from the C<NAME> field
453 if C<ReplaceNAMEwithSection> is true. If this is not the case
454 it must be set manually before starting the parse.
456 Default value is C<undef>.
463 $self->{Label} = shift;
465 return $self->{Label};
470 Control the point at which C<latex> section numbering is turned off.
471 For example, this can be used to make sure that C<latex> sections
472 are numbered but subsections are not.
474 Can be used to set or retrieve the current value:
476 $lev = $parser->LevelNoNum;
477 $parser->LevelNoNum(2);
479 The argument must be an integer between 0 and 5 and is the same as the
480 number described in C<Head1Level> method description. The number has
481 nothing to do with the pod heading number, only the C<latex> sectioning.
483 Default is 2. (i.e. C<latex> subsections are written as C<subsection*>
484 but sections are numbered).
491 $self->{LevelNoNum} = shift;
493 return $self->{LevelNoNum};
498 Controls whether C<latex> commands for creating an index are to be inserted
499 into the preamble and postamble
501 $makeindex = $parser->MakeIndex;
502 $parser->MakeIndex(0);
504 Irrelevant if both C<AddPreamble> and C<AddPostamble> are false (or equivalently,
505 C<UserPreamble> and C<UserPostamble> are set).
507 Default is for an index to be created.
514 $self->{MakeIndex} = shift;
516 return $self->{MakeIndex};
519 =item B<ReplaceNAMEwithSection>
521 This controls whether the C<NAME> section in the pod is to be translated
522 literally or converted to a slightly modified output where the section
523 name is the pod name rather than "NAME".
525 If true, the pod segment
533 is converted to the C<latex>
535 \section{pod::name\label{pod_name}\index{pod::name}}
539 \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
540 \index{pod::name!SYNOPSIS}}
542 (dependent on the value of C<Head1Level> and C<LevelNoNum>). Note that
543 subsequent C<head1> directives translate to subsections rather than
544 sections and that the labels and index now include the pod name (dependent
545 on the value of C<UniqueLabels>).
547 The C<Label> is set from the pod name regardless of any current value
550 $mod = $parser->ReplaceNAMEwithSection;
551 $parser->ReplaceNAMEwithSection(0);
553 Default is to translate the pod literally.
557 sub ReplaceNAMEwithSection {
560 $self->{ReplaceNAMEwithSection} = shift;
562 return $self->{ReplaceNAMEwithSection};
565 =item B<StartWithNewPage>
567 If true, each pod translation will begin with a C<latex>
570 $parser->StartWithNewPage(1);
571 $newpage = $parser->StartWithNewPage;
577 sub StartWithNewPage {
580 $self->{StartWithNewPage} = shift;
582 return $self->{StartWithNewPage};
585 =item B<TableOfContents>
587 If true, a table of contents will be created.
588 Irrelevant if C<AddPreamble> is false or C<UserPreamble>
591 $toc = $parser->TableOfContents;
592 $parser->TableOfContents(1);
598 sub TableOfContents {
601 $self->{TableOfContents} = shift;
603 return $self->{TableOfContents};
606 =item B<UniqueLabels>
608 If true, the translator will attempt to make sure that
609 each C<latex> label or index entry will be uniquely identified
610 by prefixing the contents of C<Label>. This allows
611 multiple documents to be combined without clashing
612 common labels such as C<DESCRIPTION> and C<SYNOPSIS>
614 $parser->UniqueLabels(1);
615 $unq = $parser->UniqueLabels;
624 $self->{UniqueLabels} = shift;
626 return $self->{UniqueLabels};
629 =item B<UserPreamble>
631 User supplied C<latex> preamble. Added before the pod translation
634 If set, the contents will be prepended to the output file before the translated
635 data regardless of the value of C<AddPreamble>.
636 C<MakeIndex> and C<TableOfContents> will also be ignored.
643 $self->{UserPreamble} = shift;
645 return $self->{UserPreamble};
648 =item B<UserPostamble>
650 User supplied C<latex> postamble. Added after the pod translation
653 If set, the contents will be prepended to the output file after the translated
654 data regardless of the value of C<AddPostamble>.
655 C<MakeIndex> will also be ignored.
662 $self->{UserPostamble} = shift;
664 return $self->{UserPostamble};
671 Contains details of the currently active lists.
672 The array contains C<Pod::List> objects. A new C<Pod::List>
673 object is created each time a list is encountered and it is
674 pushed onto this stack. When the list context ends, it
675 is popped from the stack. The array will be empty if no
678 Returns array of list information in array context
679 Returns array ref in scalar context
687 return @{ $self->{_Lists} } if wantarray();
688 return $self->{_Lists};
697 =head2 Subclassed methods
699 The following methods override methods provided in the C<Pod::Select>
700 base class. See C<Pod::Parser> and C<Pod::Select> for more information
701 on what these methods require.
707 ######### END ACCESSORS ###################
713 Writes the C<latex> preamble if requested.
720 # Get the pod identification
721 # This should really come from the '=head1 NAME' paragraph
723 my $infile = $self->input_file;
724 my $class = ref($self);
725 my $date = gmtime(time);
727 # Comment message to say where this came from
728 my $comment = << "__TEX_COMMENT__";
729 %% Latex generated from POD in document $infile
730 %% Using the perl module $class
731 %% Converted on $date
735 # If the caller has supplied one then we just use that
738 if (defined $self->UserPreamble) {
740 $preamble = $self->UserPreamble;
742 # Add the description of where this came from
743 $preamble .= "\n$comment";
746 } elsif ($self->AddPreamble) {
747 # Write our own preamble
749 # Code to initialise index making
750 # Use an array so that we can prepend comment if required
752 '\usepackage{makeidx}',
756 unless ($self->MakeIndex) {
761 my $makeindex = join("\n",@makeidx) . "\n";
765 my $tableofcontents = '\tableofcontents';
767 $tableofcontents = '%% ' . $tableofcontents
768 unless $self->TableOfContents;
771 $preamble = << "__TEX_HEADER__";
772 \\documentclass{article}
786 # Write the header (blank if none)
787 $self->_output($preamble);
789 # Start on new page if requested
790 $self->_output("\\clearpage\n") if $self->StartWithNewPage;
797 Write the closing C<latex> code.
807 # Use the user version of the postamble if deinfed
808 if (defined $self->UserPostamble) {
809 $end = $self->UserPostamble;
811 $self->_output($end);
813 } elsif ($self->AddPostamble) {
816 my $makeindex = '\printindex';
818 $makeindex = '%% '. $makeindex unless $self->MakeIndex;
820 $end = "$makeindex\n\n\\end{document}\n";
824 $self->_output($end);
830 Process basic pod commands.
836 my ($command, $paragraph, $line_num, $parobj) = @_;
838 # return if we dont care
839 return if $command eq 'pod';
841 $paragraph = $self->_replace_special_chars($paragraph);
843 # Interpolate pod sequences in paragraph
844 $paragraph = $self->interpolate($paragraph, $line_num);
846 $paragraph =~ s/\s+$//;
848 # Now run the command
849 if ($command eq 'over') {
851 $self->begin_list($paragraph, $line_num);
853 } elsif ($command eq 'item') {
855 $self->add_item($paragraph, $line_num);
857 } elsif ($command eq 'back') {
859 $self->end_list($line_num);
861 } elsif ($command eq 'head1') {
863 # Store the name of the section
864 $self->{_CURRENT_HEAD1} = $paragraph;
867 $self->head(1, $paragraph, $parobj);
869 } elsif ($command eq 'head2') {
871 $self->head(2, $paragraph, $parobj);
873 } elsif ($command eq 'head3') {
875 $self->head(3, $paragraph, $parobj);
877 } elsif ($command eq 'head4') {
879 $self->head(4, $paragraph, $parobj);
881 } elsif ($command eq 'head5') {
883 $self->head(5, $paragraph, $parobj);
885 } elsif ($command eq 'head6') {
887 $self->head(6, $paragraph, $parobj);
889 } elsif ($command eq 'begin') {
891 # pass through if latex
892 if ($paragraph =~ /^latex/i) {
893 # Make sure that subsequent paragraphs are not modfied before printing
894 $self->{_dont_modify_any_para} = 1;
897 # Suppress all subsequent paragraphs unless
898 # it is explcitly intended for latex
899 $self->{_suppress_all_para} = 1;
902 } elsif ($command eq 'for') {
904 # pass through if latex
905 if ($paragraph =~ /^latex/i) {
906 # Make sure that next paragraph is not modfied before printing
907 $self->{_dont_modify_next_para} = 1;
910 # Suppress the next paragraph unless it is latex
911 $self->{_suppress_next_para} = 1
914 } elsif ($command eq 'end') {
917 $self->{_suppress_all_para} = 0;
918 $self->{_dont_modify_any_para} = 0;
920 } elsif ($command eq 'pod') {
925 carp "Command $command not recognised at line $line_num\n";
938 my ($paragraph, $line_num, $parobj) = @_;
940 # Expand paragraph unless in =for or =begin block
941 if ($self->{_dont_modify_any_para} || $self->{_dont_modify_next_para}) {
943 $self->_output($paragraph);
945 # Reset flag if in =for
946 $self->{_dont_modify_next_para} = 0;
950 return if $paragraph =~ /^\s+$/;
952 # Clean trailing space
953 $paragraph =~ s/\s+$//;
955 $self->_output('\begin{verbatim}' . "\n$paragraph\n". '\end{verbatim}'."\n");
961 Plain text paragraph.
967 my ($paragraph, $line_num, $parobj) = @_;
969 # print Dumper($self);
971 # Expand paragraph unless in =for or =begin block
972 if ($self->{_dont_modify_any_para} || $self->{_dont_modify_next_para}) {
974 $self->_output($paragraph);
976 # Reset flag if in =for
977 $self->{_dont_modify_next_para} = 0;
983 # Escape latex special characters
984 $paragraph = $self->_replace_special_chars($paragraph);
986 # Interpolate interior sequences
987 my $expansion = $self->interpolate($paragraph, $line_num);
988 $expansion =~ s/\s+$//;
991 # If we are replacing 'head1 NAME' with a section
992 # we need to look in the paragraph and rewrite things
993 # Need to make sure this is called only on the first paragraph
994 # following 'head1 NAME' and not on subsequent paragraphs that may be
996 if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()) {
998 # Strip white space from start and end
999 $paragraph =~ s/^\s+//;
1000 $paragraph =~ s/\s$//;
1002 # Split the string into 2 parts
1003 my ($name, $purpose) = split(/\s+-\s+/, $expansion,2);
1005 # Now prevent this from triggering until a new head1 NAME is set
1006 $self->{_CURRENT_HEAD1} = '_NAME';
1008 # Might want to clear the Label() before doing this (CHECK)
1011 $self->head(1, $name, $parobj);
1013 # Set the labeling in case we want unique names later
1014 $self->Label( $self->_create_label( $name, 1 ) );
1016 # Raise the Head1Level by one so that subsequent =head1 appear
1017 # as subsections of the main name section unless we are already
1018 # at maximum [Head1Level() could check this itself - CHECK]
1019 $self->Head1Level( $self->Head1Level() + 1)
1020 unless $self->Head1Level == $#LatexSections;
1022 # Now write out the new latex paragraph
1023 $purpose = ucfirst($purpose);
1024 $self->_output("\n\n$purpose\n\n");
1027 # Just write the output
1028 $self->_output("\n\n$expansion\n\n");
1033 =item B<interior_sequence>
1035 Interior sequence expansion
1039 sub interior_sequence {
1042 my ($seq_command, $seq_argument, $pod_seq) = @_;
1044 if ($seq_command eq 'B') {
1045 return "\\textbf{$seq_argument}";
1047 } elsif ($seq_command eq 'I') {
1048 return "\\textit{$seq_argument}";
1050 } elsif ($seq_command eq 'E') {
1052 # If it is simply a number
1053 if ($seq_argument =~ /^\d+$/) {
1054 return chr($seq_argument);
1055 # Look up escape in hash table
1056 } elsif (exists $HTML_Escapes{$seq_argument}) {
1057 return $HTML_Escapes{$seq_argument};
1060 my ($file, $line) = $pod_seq->file_line();
1061 warn "Escape sequence $seq_argument not recognised at line $line of file $file\n";
1065 } elsif ($seq_command eq 'Z') {
1070 } elsif ($seq_command eq 'C') {
1071 return "\\texttt{$seq_argument}";
1073 } elsif ($seq_command eq 'F') {
1074 return "\\emph{$seq_argument}";
1076 } elsif ($seq_command eq 'S') {
1077 # non breakable spaces
1078 my $nbsp = '$\:$'; #'
1080 $seq_argument =~ s/\s/$nbsp/g;
1081 return $seq_argument;
1083 } elsif ($seq_command eq 'L') {
1085 my $link = new Pod::Hyperlink($seq_argument);
1088 unless (defined $link) {
1093 # Handle internal links differently
1094 my $type = $link->type;
1095 my $page = $link->page;
1097 if ($type eq 'section' && $page eq '') {
1098 # Use internal latex reference
1099 my $node = $link->node;
1101 # Convert to a label
1102 $node = $self->_create_label($node);
1104 return "\\S\\ref{$node}";
1107 # Use default markup for external references
1108 # (although Starlink would use \xlabel)
1109 my $markup = $link->markup;
1111 my ($file, $line) = $pod_seq->file_line();
1113 return $self->interpolate($link->markup, $line);
1118 } elsif ($seq_command eq 'P') {
1119 # Special markup for Pod::Hyperlink
1121 my $link = $seq_argument;
1124 my $ref = "\\emph{$seq_argument}";
1127 } elsif ($seq_command eq 'Q') {
1128 # Special markup for Pod::Hyperlink
1129 return "\\textsf{$seq_argument}\n";
1131 } elsif ($seq_command eq 'X') {
1134 # use \index command
1135 # I will let '!' go through for now
1136 # not sure how sub categories are handled in X<>
1137 my $index = $self->_create_index($seq_argument);
1138 return "\\index{$index}\n";
1141 carp "Unknown sequence $seq_command<$seq_argument>";
1150 Methods used to handle lists.
1156 Called when a new list is found (via the C<over> directive).
1157 Creates a new C<Pod::List> object and stores it on the
1160 $parser->begin_list($indent, $line_num);
1167 my $line_num = shift;
1169 # Indicate that a list should be started for the next item
1170 # need to do this to work out the type of list
1171 push ( @{$self->lists}, new Pod::List(-indent => $indent,
1172 -start => $line_num,
1173 -file => $self->input_file,
1181 Called when the end of a list is found (the C<back> directive).
1182 Pops the C<Pod::List> object off the stack of lists and writes
1183 the C<latex> code required to close a list.
1185 $parser->end_list($line_num);
1191 my $line_num = shift;
1193 unless (defined $self->lists->[-1]) {
1194 my $file = $self->input_file;
1195 warn "No list is active at line $line_num (file=$file). Missing =over?\n";
1199 # What to write depends on list type
1200 my $type = $self->lists->[-1]->type;
1202 # Dont write anything if the list type is not set
1203 # iomplying that a list was created but no entries were
1204 # placed in it (eg because of a =begin/=end combination)
1205 $self->_output("\\end{$type}\n")
1206 if (defined $type && length($type) > 0);
1209 pop(@{ $self->lists});
1215 Add items to the list. The first time an item is encountered
1216 (determined from the state of the current C<Pod::List> object)
1217 the type of list is determined (ordered, unnumbered or description)
1218 and the relevant latex code issued.
1220 $parser->add_item($paragraph, $line_num);
1226 my $paragraph = shift;
1227 my $line_num = shift;
1229 unless (defined $self->lists->[-1]) {
1230 my $file = $self->input_file;
1231 warn "List has already ended by line $line_num of file $file. Missing =over?\n";
1232 # Replace special chars
1233 # $paragraph = $self->_replace_special_chars($paragraph);
1234 $self->_output("$paragraph\n\n");
1238 # If paragraphs printing is turned off via =begin/=end or whatver
1239 # simply return immediately
1240 return if ($self->{_suppress_all_para} || $self->{_suppress_next_para});
1242 # Check to see whether we are starting a new lists
1243 if (scalar($self->lists->[-1]->item) == 0) {
1245 # Examine the paragraph to determine what type of list
1247 $paragraph =~ s/\s+$//;
1248 $paragraph =~ s/^\s+//;
1251 if ($paragraph eq '*') {
1253 } elsif ($paragraph =~ /^\d/) {
1254 $type = 'enumerate';
1256 $type = 'description';
1258 $self->lists->[-1]->type($type);
1260 $self->_output("\\begin{$type}\n");
1264 my $type = $self->lists->[-1]->type;
1266 if ($type eq 'description') {
1268 $self->_output("\\item[$paragraph] \\mbox{}");
1270 $self->_output('\item ');
1273 # Store the item name in the object. Required so that
1274 # we can tell if the list is new or not
1275 $self->lists->[-1]->item($paragraph);
1281 =head2 Methods for headings
1287 Print a heading of the required level.
1289 $parser->head($level, $paragraph, $parobj);
1291 The first argument is the pod heading level. The second argument
1292 is the contents of the heading. The 3rd argument is a Pod::Paragraph
1293 object so that the line number can be extracted.
1300 my $paragraph = shift;
1303 # If we are replace 'head1 NAME' with a section
1304 # we return immediately if we get it
1306 if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection());
1309 my $label = $self->_create_label($paragraph);
1311 # Create an index entry
1312 my $index = $self->_create_index($paragraph);
1314 # Work out position in the above array taking into account
1315 # that =head1 is equivalent to $self->Head1Level
1317 my $level = $self->Head1Level() - 1 + $num;
1319 # Warn if heading to large
1320 if ($num > $#LatexSections) {
1321 my $line = $parobj->file_line;
1322 my $file = $self->input_file;
1323 warn "Heading level too large ($level) for LaTeX at line $line of file $file\n";
1324 $level = $#LatexSections;
1327 # Check to see whether section should be unnumbered
1328 my $star = ($level >= $self->LevelNoNum ? '*' : '');
1331 $self->_output("\\" .$LatexSections[$level] .$star ."{$paragraph\\label{".$label ."}\\index{".$index."}}");
1342 =head2 Internal methods
1344 Internal routines are described in this section. They do not form part of the
1345 public interface. All private methods start with an underscore.
1351 Output text to the output filehandle. This method must be always be called
1352 to output parsed text.
1354 $parser->_output($text);
1356 Does not write anything if a =begin or =for is active that should be
1365 print { $self->output_handle } $text
1366 unless $self->{_suppress_all_para} ||
1367 $self->{_suppress_next_para};
1369 # Reset pargraph stuff for =for
1370 $self->{_suppress_next_para} = 0
1371 if $self->{_suppress_next_para};
1375 =item B<_replace_special_chars>
1377 Subroutine to replace characters that are special in C<latex>
1378 with the escaped forms
1380 $escaped = $parser->_replace_special_chars($paragraph);
1382 Need to call this routine before interior_sequences are munged but
1385 Special characters and the C<latex> equivalents are:
1398 sub _replace_special_chars {
1400 my $paragraph = shift;
1402 # Replace a \ with $\backslash$
1403 # This is made more complicated because the dollars will be escaped
1404 # by the subsequent replacement. Easiest to add \backslash
1405 # now and then add the dollars
1406 $paragraph =~ s/\\/\\backslash/g;
1408 # Must be done after escape of \ since this command adds latex escapes
1409 # Replace characters that can be escaped
1410 $paragraph =~ s/([\$\#&%_{}])/\\$1/g;
1412 # Replace ^ characters with \^{} so that $^F works okay
1413 $paragraph =~ s/(\^)/\\$1\{\}/g;
1415 # Now add the dollars around each \backslash
1416 $paragraph =~ s/(\\backslash)/\$$1\$/g;
1422 =item B<_create_label>
1424 Return a string that can be used as an internal reference
1425 in a C<latex> document (i.e. accepted by the C<\label> command)
1427 $label = $parser->_create_label($string)
1429 If UniqueLabels is true returns a label prefixed by Label()
1430 This can be suppressed with an optional second argument.
1432 $label = $parser->_create_label($string, $suppress);
1434 If a second argument is supplied (of any value including undef)
1435 the Label() is never prefixed. This means that this routine can
1436 be called to create a Label() without prefixing a previous setting.
1442 my $paragraph = shift;
1443 my $suppress = (@_ ? 1 : 0 );
1445 # Remove latex commands
1446 $paragraph = $self->_clean_latex_commands($paragraph);
1448 # Remove non alphanumerics from the label and replace with underscores
1449 # want to protect '-' though so use negated character classes
1450 $paragraph =~ s/[^-:\w]/_/g;
1452 # Multiple underscores will look unsightly so remove repeats
1453 # This will also have the advantage of tidying up the end and
1455 $paragraph =~ s/_+/_/g;
1457 # If required need to make sure that the label is unique
1458 # since it is possible to have multiple pods in a single
1460 if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
1461 $paragraph = $self->Label() .'_'. $paragraph;
1468 =item B<_create_index>
1470 Similar to C<_create_label> except an index entry is created.
1471 If C<UniqueLabels> is true, the index entry is prefixed by
1472 the current C<Label> and an exclamation mark.
1474 $ind = $parser->_create_index($paragraph);
1476 An exclamation mark is used by C<makeindex> to generate
1477 sub-entries in an index.
1483 my $paragraph = shift;
1484 my $suppress = (@_ ? 1 : 0 );
1486 # Remove latex commands
1487 $paragraph = $self->_clean_latex_commands($paragraph);
1489 # If required need to make sure that the index entry is unique
1490 # since it is possible to have multiple pods in a single
1492 if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
1493 $paragraph = $self->Label() .'!'. $paragraph;
1496 # Need to replace _ with space
1497 $paragraph =~ s/_/ /g;
1503 =item B<_clean_latex_commands>
1505 Removes latex commands from text. The latex command is assumed to be of the
1506 form C<\command{ text }>. "C<text>" is retained
1508 $clean = $parser->_clean_latex_commands($text);
1512 sub _clean_latex_commands {
1514 my $paragraph = shift;
1516 # Remove latex commands of the form \text{ }
1517 # and replace with the contents of the { }
1518 # need to make this non-greedy so that it can handle
1519 # "\text{a} and \text2{b}"
1520 # without converting it to
1522 # This match will still get into trouble if \} is present
1523 # This is not vital since the subsequent replacement of non-alphanumeric
1524 # characters will tidy it up anyway
1525 $paragraph =~ s/\\\w+{(.*?)}/$1/g;
1536 Compatible with C<latex2e> only. Can not be used with C<latex> v2.09
1539 A subclass of C<Pod::Select> so that specific pod sections can be
1540 converted to C<latex> by using the C<select> method.
1542 Some HTML escapes are missing and many have not been tested.
1546 L<Pod::Parser>, L<Pod::Select>, L<pod2latex>
1550 Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt>
1554 Copyright (C) 2000 Tim Jenness. All Rights Reserved.
1556 This program is free software; you can redistribute it and/or modify it
1557 under the same terms as Perl itself.
1563 $Id: LaTeX.pm,v 1.4 2000/05/16 01:26:55 timj Exp $