5 Pod::LaTeX - Convert Pod data to formatted Latex
10 my $parser = Pod::LaTeX->new ( );
12 $parser->parse_from_filehandle;
14 $parser->parse_from_file ('file.pod', 'file.tex');
18 C<Pod::LaTeX> is a module to convert documentation in the Pod format
19 into Latex. The L<B<pod2latex>|pod2latex> X<pod2latex> command uses
20 this module for translation.
22 C<Pod::LaTeX> is a derived class from L<Pod::Select|Pod::Select>.
28 require Pod::ParseUtils;
29 use base qw/ Pod::Select /;
31 # use Data::Dumper; # for debugging
34 use vars qw/ $VERSION %HTML_Escapes @LatexSections /;
38 # Definitions of =headN -> latex mapping
48 # Standard escape sequences converted to Latex
49 # Up to "yuml" these are taken from the original pod2latex
50 # command written by Taro Kawagish (kawagish@imslab.co.jp)
54 # lt, gt and verbar are inserted without math mode
55 # since the $$ will be added during general correction
56 # for those escape characters
57 'amp' => '\&', # ampersand
58 'lt' => '<', # ' left chevron, less-than
59 'gt' => '>', # ' right chevron, greater-than
60 'quot' => '"', # double quote
64 "Aacute" => "\\'{A}", # capital A, acute accent
65 "aacute" => "\\'{a}", # small a, acute accent
66 "Acirc" => "\\^{A}", # capital A, circumflex accent
67 "acirc" => "\\^{a}", # small a, circumflex accent
68 "AElig" => '\\AE', # capital AE diphthong (ligature)
69 "aelig" => '\\ae', # small ae diphthong (ligature)
70 "Agrave" => "\\`{A}", # capital A, grave accent
71 "agrave" => "\\`{a}", # small a, grave accent
72 "Aring" => '\\u{A}', # capital A, ring
73 "aring" => '\\u{a}', # small a, ring
74 "Atilde" => '\\~{A}', # capital A, tilde
75 "atilde" => '\\~{a}', # small a, tilde
76 "Auml" => '\\"{A}', # capital A, dieresis or umlaut mark
77 "auml" => '\\"{a}', # small a, dieresis or umlaut mark
78 "Ccedil" => '\\c{C}', # capital C, cedilla
79 "ccedil" => '\\c{c}', # small c, cedilla
80 "Eacute" => "\\'{E}", # capital E, acute accent
81 "eacute" => "\\'{e}", # small e, acute accent
82 "Ecirc" => "\\^{E}", # capital E, circumflex accent
83 "ecirc" => "\\^{e}", # small e, circumflex accent
84 "Egrave" => "\\`{E}", # capital E, grave accent
85 "egrave" => "\\`{e}", # small e, grave accent
86 "ETH" => '\\OE', # capital Eth, Icelandic
87 "eth" => '\\oe', # small eth, Icelandic
88 "Euml" => '\\"{E}', # capital E, dieresis or umlaut mark
89 "euml" => '\\"{e}', # small e, dieresis or umlaut mark
90 "Iacute" => "\\'{I}", # capital I, acute accent
91 "iacute" => "\\'{i}", # small i, acute accent
92 "Icirc" => "\\^{I}", # capital I, circumflex accent
93 "icirc" => "\\^{i}", # small i, circumflex accent
94 "Igrave" => "\\`{I}", # capital I, grave accent
95 "igrave" => "\\`{i}", # small i, grave accent
96 "Iuml" => '\\"{I}', # capital I, dieresis or umlaut mark
97 "iuml" => '\\"{i}', # small i, dieresis or umlaut mark
98 "Ntilde" => '\\~{N}', # capital N, tilde
99 "ntilde" => '\\~{n}', # small n, tilde
100 "Oacute" => "\\'{O}", # capital O, acute accent
101 "oacute" => "\\'{o}", # small o, acute accent
102 "Ocirc" => "\\^{O}", # capital O, circumflex accent
103 "ocirc" => "\\^{o}", # small o, circumflex accent
104 "Ograve" => "\\`{O}", # capital O, grave accent
105 "ograve" => "\\`{o}", # small o, grave accent
106 "Oslash" => "\\O", # capital O, slash
107 "oslash" => "\\o", # small o, slash
108 "Otilde" => "\\~{O}", # capital O, tilde
109 "otilde" => "\\~{o}", # small o, tilde
110 "Ouml" => '\\"{O}', # capital O, dieresis or umlaut mark
111 "ouml" => '\\"{o}', # small o, dieresis or umlaut mark
112 "szlig" => '\\ss{}', # small sharp s, German (sz ligature)
113 "THORN" => '\\L', # capital THORN, Icelandic
114 "thorn" => '\\l',, # small thorn, Icelandic
115 "Uacute" => "\\'{U}", # capital U, acute accent
116 "uacute" => "\\'{u}", # small u, acute accent
117 "Ucirc" => "\\^{U}", # capital U, circumflex accent
118 "ucirc" => "\\^{u}", # small u, circumflex accent
119 "Ugrave" => "\\`{U}", # capital U, grave accent
120 "ugrave" => "\\`{u}", # small u, grave accent
121 "Uuml" => '\\"{U}', # capital U, dieresis or umlaut mark
122 "uuml" => '\\"{u}', # small u, dieresis or umlaut mark
123 "Yacute" => "\\'{Y}", # capital Y, acute accent
124 "yacute" => "\\'{y}", # small y, acute accent
125 "yuml" => '\\"{y}', # small y, dieresis or umlaut mark
129 "iexcl" => '!`', # inverted exclamation mark
130 # "cent" => ' ', # cent sign
131 "pound" => '\pounds', # (UK) pound sign
132 # "curren" => ' ', # currency sign
133 # "yen" => ' ', # yen sign
134 # "brvbar" => ' ', # broken vertical bar
135 "sect" => '\S', # section sign
136 "uml" => '\"{}', # diaresis
137 "copy" => '\copyright', # Copyright symbol
138 # "ordf" => ' ', # feminine ordinal indicator
139 "laquo" => '$\ll$', # ' # left pointing double angle quotation mark
140 "not" => '$\neg$', # ' # not sign
141 "shy" => '-', # soft hyphen
142 # "reg" => ' ', # registered trademark
143 "macr" => '$^-$', # ' # macron, overline
144 "deg" => '$^\circ$', # ' # degree sign
145 "plusmn" => '$\pm$', # ' # plus-minus sign
146 "sup2" => '$^2$', # ' # superscript 2
147 "sup3" => '$^3$', # ' # superscript 3
148 "acute" => "\\'{}", # acute accent
149 "micro" => '$\mu$', # micro sign
150 "para" => '\P', # pilcrow sign = paragraph sign
151 "middot" => '$\cdot$', # middle dot = Georgian comma
152 "cedil" => '\c{}', # cedilla
153 "sup1" => '$^1$', # ' # superscript 1
154 # "ordm" => ' ', # masculine ordinal indicator
155 "raquo" => '$\gg$', # ' # right pointing double angle quotation mark
156 "frac14" => '$\frac{1}{4}$', # ' # vulgar fraction one quarter
157 "frac12" => '$\frac{1}{2}$', # ' # vulgar fraction one half
158 "frac34" => '$\frac{3}{4}$', # ' # vulgar fraction three quarters
159 "iquest" => "?'", # inverted question mark
160 "times" => '$\times$', # ' # multiplication sign
161 "divide" => '$\div$', # division sign
163 # Greek letters using HTML codes
164 "alpha" => '$\alpha$', # '
165 "beta" => '$\beta$', # '
166 "gamma" => '$\gamma$', # '
167 "delta" => '$\delta$', # '
168 "epsilon"=> '$\epsilon$', # '
169 "zeta" => '$\zeta$', # '
170 "eta" => '$\eta$', # '
171 "theta" => '$\theta$', # '
172 "iota" => '$\iota$', # '
173 "kappa" => '$\kappa$', # '
174 "lambda" => '$\lambda$', # '
178 "omicron"=> '$o$', # '
180 "rho" => '$\rho$', # '
181 "sigma" => '$\sigma$', # '
182 "tau" => '$\tau$', # '
183 "upsilon"=> '$\upsilon$', # '
184 "phi" => '$\phi$', # '
185 "chi" => '$\chi$', # '
186 "psi" => '$\psi$', # '
187 "omega" => '$\omega$', # '
189 "Alpha" => '$A$', # '
191 "Gamma" => '$\Gamma$', # '
192 "Delta" => '$\Delta$', # '
193 "Epsilon"=> '$E$', # '
196 "Theta" => '$\Theta$', # '
198 "Kappa" => '$K$', # '
199 "Lambda" => '$\Lambda$', # '
203 "Omicron"=> '$O$', # '
206 "Sigma" => '$\Sigma$', # '
208 "Upsilon"=> '$\Upsilon$', # '
209 "Phi" => '$\Phi$', # '
211 "Psi" => '$\Psi$', # '
212 "Omega" => '$\Omega$', # '
218 =head1 OBJECT METHODS
220 The following methods are provided in this module. Methods inherited
221 from C<Pod::Select> are not described in the public interface.
229 Initialise the object. This method is subclassed from C<Pod::Parser>.
230 The base class method is invoked. This method defines the default
231 behaviour of the object unless overridden by supplying arguments to
234 Internal settings are defaulted as well as the public instance data.
235 Internal hash values are accessed directly (rather than through
236 a method) and start with an underscore.
238 This method should not be invoked by the user directly.
246 # - An array for nested lists
248 # Arguments have already been read by this point
253 # print Dumper($self);
256 $self->{_Lists} = []; # For nested lists
257 $self->{_suppress_all_para} = 0; # For =begin blocks
258 $self->{_dont_modify_any_para}=0; # For =begin blocks
259 $self->{_CURRENT_HEAD1} = ''; # Name of current HEAD1 section
261 # Options - only initialise if not already set
263 # Cause the '=head1 NAME' field to be treated specially
264 # The contents of the NAME paragraph will be converted
265 # to a section title. All subsequent =head1 will be converted
266 # to =head2 and down. Will not affect =head1's prior to NAME
267 # Assumes: 'Module - purpose' format
268 # Also creates a purpose field
269 # The name is used for Labeling of the subsequent subsections
270 $self->{ReplaceNAMEwithSection} = 0
271 unless exists $self->{ReplaceNAMEwithSection};
272 $self->{AddPreamble} = 1 # make full latex document
273 unless exists $self->{AddPreamble};
274 $self->{StartWithNewPage} = 0 # Start new page for pod section
275 unless exists $self->{StartWithNewPage};
276 $self->{TableOfContents} = 0 # Add table of contents
277 unless exists $self->{TableOfContents}; # only relevent if AddPreamble=1
278 $self->{AddPostamble} = 1 # Add closing latex code at end
279 unless exists $self->{AddPostamble}; # effectively end{document} and index
280 $self->{MakeIndex} = 1 # Add index (only relevant AddPostamble
281 unless exists $self->{MakeIndex}; # and AddPreamble)
283 $self->{UniqueLabels} = 1 # Use label unique for each pod
284 unless exists $self->{UniqueLabels}; # either based on the filename
287 # Control the level of =head1. default is \section
289 $self->{Head1Level} = 1 # Offset in latex sections
290 unless exists $self->{Head1Level}; # 0 is chapter, 2 is subsection
292 # Control at which level numbering of sections is turned off
293 # ie subsection becomes subsection*
294 # The numbering is relative to the latex sectioning commands
295 # and is independent of Pod heading level
296 # default is to number \section but not \subsection
297 $self->{LevelNoNum} = 2
298 unless exists $self->{LevelNoNum};
300 # Label to be used as prefix to all internal section names
301 # If not defined will attempt to derive it from the filename
302 # This can not happen when running parse_from_filehandle though
303 # hence the ability to set the label externally
304 # The label could then be Pod::Parser_DESCRIPTION or somesuch
306 $self->{Label} = undef # label to be used as prefix
307 unless exists $self->{Label}; # to all internal section names
309 # These allow the caller to add arbritrary latex code to
310 # start and end of document. AddPreamble and AddPostamble are ignored
312 # Also MakeIndex and TableOfContents are also ignored.
313 $self->{UserPreamble} = undef # User supplied start (AddPreamble =1)
314 unless exists $self->{Label};
315 $self->{UserPostamble} = undef # Use supplied end (AddPostamble=1)
316 unless exists $self->{Label};
318 # Run base initialize
319 $self->SUPER::initialize;
325 =head2 Data Accessors
327 The following methods are provided for accessing instance data. These
328 methods should be used for accessing configuration parameters rather
329 than assuming the object is a hash.
331 Default values can be supplied by using these names as keys to a hash
332 of arguments when using the C<new()> constructor.
338 Logical to control whether a C<latex> preamble is to be written.
339 If true, a valid C<latex> preamble is written before the pod data
340 is written. This is similar to:
342 \documentclass{article}
345 but will be more complicated if table of contents and indexing are required.
346 Can be used to set or retrieve the current value.
348 $add = $parser->AddPreamble();
349 $parser->AddPreamble(1);
351 If used in conjunction with C<AddPostamble> a full latex document will
352 be written that could be immediately processed by C<latex>.
359 $self->{AddPreamble} = shift;
361 return $self->{AddPreamble};
364 =item B<AddPostamble>
366 Logical to control whether a standard C<latex> ending is written to
367 the output file after the document has been processed. In its
368 simplest form this is simply:
372 but can be more complicated if an index is required.
373 Can be used to set or retrieve the current value.
375 $add = $parser->AddPostamble();
376 $parser->AddPostamble(1);
378 If used in conjunction with C<AddPreaamble> a full latex document will
379 be written that could be immediately processed by C<latex>.
386 $self->{AddPostamble} = shift;
388 return $self->{AddPostamble};
393 The C<latex> sectioning level that should be used to correspond to
394 a pod C<=head1> directive. This can be used, for example, to turn
395 a C<=head1> into a C<latex> C<subsection>. This should hold a number
396 corresponding to the required position in an array containing the
406 Can be used to set or retrieve the current value:
408 $parser->Head1Level(2);
409 $sect = $parser->Head1Level;
411 Setting this number too high can result in sections that may not be
412 reproducible in the expected way. For example, setting this to 4 would
413 imply that C<=head3> do not have a corresponding C<latex> section
414 (C<=head1> would correspond to a C<paragraph>).
416 A check is made to ensure that the supplied value is an integer in the
419 Default is for a value of 1 (i.e. a C<section>).
427 if ($arg =~ /^\d$/ && $arg <= $#LatexSections) {
428 $self->{Head1Level} = $arg;
430 carp "Head1Level supplied ($arg) must be integer in range 0 to ".$#LatexSections . "- Ignoring\n";
433 return $self->{Head1Level};
438 This is the label that is prefixed to all C<latex> label and index
439 entries to make them unique. In general, pods have similarly titled
440 sections (NAME, DESCRIPTION etc) and a C<latex> label will be multiply
441 defined if more than one pod document is to be included in a single
442 C<latex> file. To overcome this, this label is prefixed to a label
443 whenever a label is required (joined with an underscore) or to an
444 index entry (joined by an exclamation mark which is the normal index
445 separator). For example, C<\label{text}> becomes C<\label{Label_text}>.
447 Can be used to set or retrieve the current value:
449 $label = $parser->Label;
450 $parser->Label($label);
452 This label is only used if C<UniqueLabels> is true.
453 Its value is set automatically from the C<NAME> field
454 if C<ReplaceNAMEwithSection> is true. If this is not the case
455 it must be set manually before starting the parse.
457 Default value is C<undef>.
464 $self->{Label} = shift;
466 return $self->{Label};
471 Control the point at which C<latex> section numbering is turned off.
472 For example, this can be used to make sure that C<latex> sections
473 are numbered but subsections are not.
475 Can be used to set or retrieve the current value:
477 $lev = $parser->LevelNoNum;
478 $parser->LevelNoNum(2);
480 The argument must be an integer between 0 and 5 and is the same as the
481 number described in C<Head1Level> method description. The number has
482 nothing to do with the pod heading number, only the C<latex> sectioning.
484 Default is 2. (i.e. C<latex> subsections are written as C<subsection*>
485 but sections are numbered).
492 $self->{LevelNoNum} = shift;
494 return $self->{LevelNoNum};
499 Controls whether C<latex> commands for creating an index are to be inserted
500 into the preamble and postamble
502 $makeindex = $parser->MakeIndex;
503 $parser->MakeIndex(0);
505 Irrelevant if both C<AddPreamble> and C<AddPostamble> are false
506 (or equivalently, C<UserPreamble> and C<UserPostamble> are set).
508 Default is for an index to be created.
515 $self->{MakeIndex} = shift;
517 return $self->{MakeIndex};
520 =item B<ReplaceNAMEwithSection>
522 This controls whether the C<NAME> section in the pod is to be translated
523 literally or converted to a slightly modified output where the section
524 name is the pod name rather than "NAME".
526 If true, the pod segment
534 is converted to the C<latex>
536 \section{pod::name\label{pod_name}\index{pod::name}}
540 \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
541 \index{pod::name!SYNOPSIS}}
543 (dependent on the value of C<Head1Level> and C<LevelNoNum>). Note that
544 subsequent C<head1> directives translate to subsections rather than
545 sections and that the labels and index now include the pod name (dependent
546 on the value of C<UniqueLabels>).
548 The C<Label> is set from the pod name regardless of any current value
551 $mod = $parser->ReplaceNAMEwithSection;
552 $parser->ReplaceNAMEwithSection(0);
554 Default is to translate the pod literally.
558 sub ReplaceNAMEwithSection {
561 $self->{ReplaceNAMEwithSection} = shift;
563 return $self->{ReplaceNAMEwithSection};
566 =item B<StartWithNewPage>
568 If true, each pod translation will begin with a C<latex>
571 $parser->StartWithNewPage(1);
572 $newpage = $parser->StartWithNewPage;
578 sub StartWithNewPage {
581 $self->{StartWithNewPage} = shift;
583 return $self->{StartWithNewPage};
586 =item B<TableOfContents>
588 If true, a table of contents will be created.
589 Irrelevant if C<AddPreamble> is false or C<UserPreamble>
592 $toc = $parser->TableOfContents;
593 $parser->TableOfContents(1);
599 sub TableOfContents {
602 $self->{TableOfContents} = shift;
604 return $self->{TableOfContents};
607 =item B<UniqueLabels>
609 If true, the translator will attempt to make sure that
610 each C<latex> label or index entry will be uniquely identified
611 by prefixing the contents of C<Label>. This allows
612 multiple documents to be combined without clashing
613 common labels such as C<DESCRIPTION> and C<SYNOPSIS>
615 $parser->UniqueLabels(1);
616 $unq = $parser->UniqueLabels;
625 $self->{UniqueLabels} = shift;
627 return $self->{UniqueLabels};
630 =item B<UserPreamble>
632 User supplied C<latex> preamble. Added before the pod translation
635 If set, the contents will be prepended to the output file before
636 the translated data regardless of the value of C<AddPreamble>.
637 C<MakeIndex> and C<TableOfContents> will also be ignored.
644 $self->{UserPreamble} = shift;
646 return $self->{UserPreamble};
649 =item B<UserPostamble>
651 User supplied C<latex> postamble. Added after the pod translation
654 If set, the contents will be prepended to the output file after
655 the translated data regardless of the value of C<AddPostamble>.
656 C<MakeIndex> will also be ignored.
663 $self->{UserPostamble} = shift;
665 return $self->{UserPostamble};
672 Contains details of the currently active lists.
673 The array contains C<Pod::List> objects. A new C<Pod::List>
674 object is created each time a list is encountered and it is
675 pushed onto this stack. When the list context ends, it
676 is popped from the stack. The array will be empty if no
679 Returns array of list information in list context
680 Returns array ref in scalar context
688 return @{ $self->{_Lists} } if wantarray();
689 return $self->{_Lists};
698 =head2 Subclassed methods
700 The following methods override methods provided in the C<Pod::Select>
701 base class. See C<Pod::Parser> and C<Pod::Select> for more information
702 on what these methods require.
708 ######### END ACCESSORS ###################
714 Writes the C<latex> preamble if requested.
721 # Get the pod identification
722 # This should really come from the '=head1 NAME' paragraph
724 my $infile = $self->input_file;
725 my $class = ref($self);
726 my $date = gmtime(time);
728 # Comment message to say where this came from
729 my $comment = << "__TEX_COMMENT__";
730 %% Latex generated from POD in document $infile
731 %% Using the perl module $class
732 %% Converted on $date
736 # If the caller has supplied one then we just use that
739 if (defined $self->UserPreamble) {
741 $preamble = $self->UserPreamble;
743 # Add the description of where this came from
744 $preamble .= "\n$comment";
747 } elsif ($self->AddPreamble) {
748 # Write our own preamble
750 # Code to initialise index making
751 # Use an array so that we can prepend comment if required
753 '\usepackage{makeidx}',
757 unless ($self->MakeIndex) {
762 my $makeindex = join("\n",@makeidx) . "\n";
766 my $tableofcontents = '\tableofcontents';
768 $tableofcontents = '%% ' . $tableofcontents
769 unless $self->TableOfContents;
772 $preamble = << "__TEX_HEADER__";
773 \\documentclass{article}
787 # Write the header (blank if none)
788 $self->_output($preamble);
790 # Start on new page if requested
791 $self->_output("\\clearpage\n") if $self->StartWithNewPage;
798 Write the closing C<latex> code.
808 # Use the user version of the postamble if deinfed
809 if (defined $self->UserPostamble) {
810 $end = $self->UserPostamble;
812 $self->_output($end);
814 } elsif ($self->AddPostamble) {
817 my $makeindex = '\printindex';
819 $makeindex = '%% '. $makeindex unless $self->MakeIndex;
821 $end = "$makeindex\n\n\\end{document}\n";
825 $self->_output($end);
831 Process basic pod commands.
837 my ($command, $paragraph, $line_num, $parobj) = @_;
839 # return if we dont care
840 return if $command eq 'pod';
842 # Store a copy of the raw text in case we are in a =for
843 # block and need to preserve the existing latex
844 my $rawpara = $paragraph;
846 # Do the latex escapes
847 $paragraph = $self->_replace_special_chars($paragraph);
849 # Interpolate pod sequences in paragraph
850 $paragraph = $self->interpolate($paragraph, $line_num);
851 $paragraph =~ s/\s+$//;
853 # Replace characters that can only be done after
854 # interpolation of interior sequences
855 $paragraph = $self->_replace_special_chars_late($paragraph);
857 # Now run the command
858 if ($command eq 'over') {
860 $self->begin_list($paragraph, $line_num);
862 } elsif ($command eq 'item') {
864 $self->add_item($paragraph, $line_num);
866 } elsif ($command eq 'back') {
868 $self->end_list($line_num);
870 } elsif ($command eq 'head1') {
872 # Store the name of the section
873 $self->{_CURRENT_HEAD1} = $paragraph;
876 $self->head(1, $paragraph, $parobj);
878 } elsif ($command eq 'head2') {
880 $self->head(2, $paragraph, $parobj);
882 } elsif ($command eq 'head3') {
884 $self->head(3, $paragraph, $parobj);
886 } elsif ($command eq 'head4') {
888 $self->head(4, $paragraph, $parobj);
890 } elsif ($command eq 'head5') {
892 $self->head(5, $paragraph, $parobj);
894 } elsif ($command eq 'head6') {
896 $self->head(6, $paragraph, $parobj);
898 } elsif ($command eq 'begin') {
900 # pass through if latex
901 if ($paragraph =~ /^latex/i) {
902 # Make sure that subsequent paragraphs are not modfied before printing
903 $self->{_dont_modify_any_para} = 1;
906 # Suppress all subsequent paragraphs unless
907 # it is explcitly intended for latex
908 $self->{_suppress_all_para} = 1;
911 } elsif ($command eq 'for') {
916 # With =for we will get the text for the full paragraph
917 # as well as the format name.
918 # We do not get an additional paragraph later on. The next
919 # paragraph is not governed by the =for
921 # The first line contains the format and the rest is the
923 my ($format, $chunk) = split(/\n/, $rawpara, 2);
925 # If we have got some latex code print it out immediately
926 # unmodified. Else do nothing.
927 if ($format =~ /^latex/i) {
928 # Make sure that next paragraph is not modfied before printing
929 $self->_output( $chunk );
933 } elsif ($command eq 'end') {
936 $self->{_suppress_all_para} = 0;
937 $self->{_dont_modify_any_para} = 0;
939 } elsif ($command eq 'pod') {
944 carp "Command $command not recognised at line $line_num\n";
957 my ($paragraph, $line_num, $parobj) = @_;
959 # Expand paragraph unless in =begin block
960 if ($self->{_dont_modify_any_para}) {
962 $self->_output($paragraph);
966 return if $paragraph =~ /^\s+$/;
968 # Clean trailing space
969 $paragraph =~ s/\s+$//;
971 # Clean tabs. Routine taken from Tabs.pm
972 # by David Muir Sharnoff muir@idiom.com,
973 # slightly modified by hsmyers@sdragons.com 10/22/01
974 my @l = split("\n",$paragraph);
976 1 while s/(^|\n)([^\t\n]*)(\t+)/
982 $paragraph = join("\n",@l);
987 $self->_output('\begin{verbatim}' . "\n$paragraph\n". '\end{verbatim}'."\n");
993 Plain text paragraph.
999 my ($paragraph, $line_num, $parobj) = @_;
1001 # print Dumper($self);
1003 # Expand paragraph unless in =begin block
1004 if ($self->{_dont_modify_any_para}) {
1006 $self->_output($paragraph);
1012 # Escape latex special characters
1013 $paragraph = $self->_replace_special_chars($paragraph);
1015 # Interpolate interior sequences
1016 my $expansion = $self->interpolate($paragraph, $line_num);
1017 $expansion =~ s/\s+$//;
1019 # Escape special characters that can not be done earlier
1020 $expansion = $self->_replace_special_chars_late($expansion);
1022 # If we are replacing 'head1 NAME' with a section
1023 # we need to look in the paragraph and rewrite things
1024 # Need to make sure this is called only on the first paragraph
1025 # following 'head1 NAME' and not on subsequent paragraphs that may be
1027 if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()) {
1029 # Strip white space from start and end
1030 $paragraph =~ s/^\s+//;
1031 $paragraph =~ s/\s$//;
1033 # Split the string into 2 parts
1034 my ($name, $purpose) = split(/\s+-\s+/, $expansion,2);
1036 # Now prevent this from triggering until a new head1 NAME is set
1037 $self->{_CURRENT_HEAD1} = '_NAME';
1039 # Might want to clear the Label() before doing this (CHECK)
1042 $self->head(1, $name, $parobj);
1044 # Set the labeling in case we want unique names later
1045 $self->Label( $self->_create_label( $name, 1 ) );
1047 # Raise the Head1Level by one so that subsequent =head1 appear
1048 # as subsections of the main name section unless we are already
1049 # at maximum [Head1Level() could check this itself - CHECK]
1050 $self->Head1Level( $self->Head1Level() + 1)
1051 unless $self->Head1Level == $#LatexSections;
1053 # Now write out the new latex paragraph
1054 $purpose = ucfirst($purpose);
1055 $self->_output("\n\n$purpose\n\n");
1058 # Just write the output
1059 $self->_output("\n\n$expansion\n\n");
1064 =item B<interior_sequence>
1066 Interior sequence expansion
1070 sub interior_sequence {
1073 my ($seq_command, $seq_argument, $pod_seq) = @_;
1075 if ($seq_command eq 'B') {
1076 return "\\textbf{$seq_argument}";
1078 } elsif ($seq_command eq 'I') {
1079 return "\\textit{$seq_argument}";
1081 } elsif ($seq_command eq 'E') {
1083 # If it is simply a number
1084 if ($seq_argument =~ /^\d+$/) {
1085 return chr($seq_argument);
1086 # Look up escape in hash table
1087 } elsif (exists $HTML_Escapes{$seq_argument}) {
1088 return $HTML_Escapes{$seq_argument};
1091 my ($file, $line) = $pod_seq->file_line();
1092 warn "Escape sequence $seq_argument not recognised at line $line of file $file\n";
1096 } elsif ($seq_command eq 'Z') {
1101 } elsif ($seq_command eq 'C') {
1102 return "\\texttt{$seq_argument}";
1104 } elsif ($seq_command eq 'F') {
1105 return "\\emph{$seq_argument}";
1107 } elsif ($seq_command eq 'S') {
1108 # non breakable spaces
1109 my $nbsp = '$\:$'; #'
1111 $seq_argument =~ s/\s/$nbsp/g;
1112 return $seq_argument;
1114 } elsif ($seq_command eq 'L') {
1116 my $link = new Pod::Hyperlink($seq_argument);
1119 unless (defined $link) {
1124 # Handle internal links differently
1125 my $type = $link->type;
1126 my $page = $link->page;
1128 if ($type eq 'section' && $page eq '') {
1129 # Use internal latex reference
1130 my $node = $link->node;
1132 # Convert to a label
1133 $node = $self->_create_label($node);
1135 return "\\S\\ref{$node}";
1138 # Use default markup for external references
1139 # (although Starlink would use \xlabel)
1140 my $markup = $link->markup;
1142 my ($file, $line) = $pod_seq->file_line();
1144 return $self->interpolate($link->markup, $line);
1149 } elsif ($seq_command eq 'P') {
1150 # Special markup for Pod::Hyperlink
1151 # Replace :: with / - but not sure if I want to do this
1153 my $link = $seq_argument;
1156 my $ref = "\\emph{$seq_argument}";
1159 } elsif ($seq_command eq 'Q') {
1160 # Special markup for Pod::Hyperlink
1161 return "\\textsf{$seq_argument}";
1163 } elsif ($seq_command eq 'X') {
1166 # use \index command
1167 # I will let '!' go through for now
1168 # not sure how sub categories are handled in X<>
1169 my $index = $self->_create_index($seq_argument);
1170 return "\\index{$index}\n";
1173 carp "Unknown sequence $seq_command<$seq_argument>";
1182 Methods used to handle lists.
1188 Called when a new list is found (via the C<over> directive).
1189 Creates a new C<Pod::List> object and stores it on the
1192 $parser->begin_list($indent, $line_num);
1199 my $line_num = shift;
1201 # Indicate that a list should be started for the next item
1202 # need to do this to work out the type of list
1203 push ( @{$self->lists}, new Pod::List(-indent => $indent,
1204 -start => $line_num,
1205 -file => $self->input_file,
1213 Called when the end of a list is found (the C<back> directive).
1214 Pops the C<Pod::List> object off the stack of lists and writes
1215 the C<latex> code required to close a list.
1217 $parser->end_list($line_num);
1223 my $line_num = shift;
1225 unless (defined $self->lists->[-1]) {
1226 my $file = $self->input_file;
1227 warn "No list is active at line $line_num (file=$file). Missing =over?\n";
1231 # What to write depends on list type
1232 my $type = $self->lists->[-1]->type;
1234 # Dont write anything if the list type is not set
1235 # iomplying that a list was created but no entries were
1236 # placed in it (eg because of a =begin/=end combination)
1237 $self->_output("\\end{$type}\n")
1238 if (defined $type && length($type) > 0);
1241 pop(@{ $self->lists});
1247 Add items to the list. The first time an item is encountered
1248 (determined from the state of the current C<Pod::List> object)
1249 the type of list is determined (ordered, unnumbered or description)
1250 and the relevant latex code issued.
1252 $parser->add_item($paragraph, $line_num);
1258 my $paragraph = shift;
1259 my $line_num = shift;
1261 unless (defined $self->lists->[-1]) {
1262 my $file = $self->input_file;
1263 warn "List has already ended by line $line_num of file $file. Missing =over?\n";
1264 # Replace special chars
1265 # $paragraph = $self->_replace_special_chars($paragraph);
1266 $self->_output("$paragraph\n\n");
1270 # If paragraphs printing is turned off via =begin/=end or whatver
1271 # simply return immediately
1272 return if $self->{_suppress_all_para};
1274 # Check to see whether we are starting a new lists
1275 if (scalar($self->lists->[-1]->item) == 0) {
1277 # Examine the paragraph to determine what type of list
1279 $paragraph =~ s/\s+$//;
1280 $paragraph =~ s/^\s+//;
1283 if (substr($paragraph, 0,1) eq '*') {
1285 } elsif ($paragraph =~ /^\d/) {
1286 $type = 'enumerate';
1288 $type = 'description';
1290 $self->lists->[-1]->type($type);
1292 $self->_output("\\begin{$type}\n");
1296 my $type = $self->lists->[-1]->type;
1298 if ($type eq 'description') {
1299 # Handle long items - long items do not wrap
1300 # If the string is longer than 40 characters we split
1301 # it into a real item header and some bold text.
1303 my ($hunk1, $hunk2) = $self->_split_delimited( $paragraph, $maxlen );
1305 # Print the first hunk
1306 $self->_output("\n\\item[$hunk1] ");
1308 # and the second hunk if it is defined
1310 $self->_output("\\textbf{$hunk2}");
1312 # Not there so make sure we have a new line
1313 $self->_output("\\mbox{}");
1317 # If the item was '* Something' we still need to write
1319 my $extra_info = $paragraph;
1320 $extra_info =~ s/^\*\s*//;
1321 $self->_output("\n\\item $extra_info");
1324 # Store the item name in the object. Required so that
1325 # we can tell if the list is new or not
1326 $self->lists->[-1]->item($paragraph);
1332 =head2 Methods for headings
1338 Print a heading of the required level.
1340 $parser->head($level, $paragraph, $parobj);
1342 The first argument is the pod heading level. The second argument
1343 is the contents of the heading. The 3rd argument is a Pod::Paragraph
1344 object so that the line number can be extracted.
1351 my $paragraph = shift;
1354 # If we are replace 'head1 NAME' with a section
1355 # we return immediately if we get it
1357 if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection());
1360 my $label = $self->_create_label($paragraph);
1362 # Create an index entry
1363 my $index = $self->_create_index($paragraph);
1365 # Work out position in the above array taking into account
1366 # that =head1 is equivalent to $self->Head1Level
1368 my $level = $self->Head1Level() - 1 + $num;
1370 # Warn if heading to large
1371 if ($num > $#LatexSections) {
1372 my $line = $parobj->file_line;
1373 my $file = $self->input_file;
1374 warn "Heading level too large ($level) for LaTeX at line $line of file $file\n";
1375 $level = $#LatexSections;
1378 # Check to see whether section should be unnumbered
1379 my $star = ($level >= $self->LevelNoNum ? '*' : '');
1382 $self->_output("\\" .$LatexSections[$level] .$star ."{$paragraph\\label{".$label ."}\\index{".$index."}}\n");
1393 =head2 Internal methods
1395 Internal routines are described in this section. They do not form part of the
1396 public interface. All private methods start with an underscore.
1402 Output text to the output filehandle. This method must be always be called
1403 to output parsed text.
1405 $parser->_output($text);
1407 Does not write anything if a =begin is active that should be
1416 print { $self->output_handle } $text
1417 unless $self->{_suppress_all_para};
1422 =item B<_replace_special_chars>
1424 Subroutine to replace characters that are special in C<latex>
1425 with the escaped forms
1427 $escaped = $parser->_replace_special_chars($paragraph);
1429 Need to call this routine before interior_sequences are munged but not
1430 if verbatim. It must be called before interpolation of interior
1431 sequences so that curly brackets and special latex characters inserted
1432 during interpolation are not themselves escaped. This means that < and
1433 > can not be modified here since the text still contains interior
1436 Special characters and the C<latex> equivalents are:
1450 sub _replace_special_chars {
1452 my $paragraph = shift;
1454 # Replace a \ with $\backslash$
1455 # This is made more complicated because the dollars will be escaped
1456 # by the subsequent replacement. Easiest to add \backslash
1457 # now and then add the dollars
1458 $paragraph =~ s/\\/\\backslash/g;
1460 # Must be done after escape of \ since this command adds latex escapes
1461 # Replace characters that can be escaped
1462 $paragraph =~ s/([\$\#&%_{}])/\\$1/g;
1464 # Replace ^ characters with \^{} so that $^F works okay
1465 $paragraph =~ s/(\^)/\\$1\{\}/g;
1467 # Replace tilde (~) with \texttt{\~{}}
1468 $paragraph =~ s/~/\\texttt\{\\~\{\}\}/g;
1470 # Now add the dollars around each \backslash
1471 $paragraph =~ s/(\\backslash)/\$$1\$/g;
1475 =item B<_replace_special_chars_late>
1477 Replace special characters that can not be replaced before interior
1478 sequence interpolation. See C<_replace_special_chars> for a routine
1479 to replace special characters prior to interpolation of interior
1482 Does the following transformation:
1491 sub _replace_special_chars_late {
1493 my $paragraph = shift;
1496 $paragraph =~ s/(<|>)/\$$1\$/g;
1498 # Replace | with $|$
1499 $paragraph =~ s'\|'$|$'g;
1506 =item B<_create_label>
1508 Return a string that can be used as an internal reference
1509 in a C<latex> document (i.e. accepted by the C<\label> command)
1511 $label = $parser->_create_label($string)
1513 If UniqueLabels is true returns a label prefixed by Label()
1514 This can be suppressed with an optional second argument.
1516 $label = $parser->_create_label($string, $suppress);
1518 If a second argument is supplied (of any value including undef)
1519 the Label() is never prefixed. This means that this routine can
1520 be called to create a Label() without prefixing a previous setting.
1526 my $paragraph = shift;
1527 my $suppress = (@_ ? 1 : 0 );
1529 # Remove latex commands
1530 $paragraph = $self->_clean_latex_commands($paragraph);
1532 # Remove non alphanumerics from the label and replace with underscores
1533 # want to protect '-' though so use negated character classes
1534 $paragraph =~ s/[^-:\w]/_/g;
1536 # Multiple underscores will look unsightly so remove repeats
1537 # This will also have the advantage of tidying up the end and
1539 $paragraph =~ s/_+/_/g;
1541 # If required need to make sure that the label is unique
1542 # since it is possible to have multiple pods in a single
1544 if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
1545 $paragraph = $self->Label() .'_'. $paragraph;
1552 =item B<_create_index>
1554 Similar to C<_create_label> except an index entry is created.
1555 If C<UniqueLabels> is true, the index entry is prefixed by
1556 the current C<Label> and an exclamation mark.
1558 $ind = $parser->_create_index($paragraph);
1560 An exclamation mark is used by C<makeindex> to generate
1561 sub-entries in an index.
1567 my $paragraph = shift;
1568 my $suppress = (@_ ? 1 : 0 );
1570 # Remove latex commands
1571 $paragraph = $self->_clean_latex_commands($paragraph);
1573 # If required need to make sure that the index entry is unique
1574 # since it is possible to have multiple pods in a single
1576 if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
1577 $paragraph = $self->Label() .'!'. $paragraph;
1580 # Need to replace _ with space
1581 $paragraph =~ s/_/ /g;
1587 =item B<_clean_latex_commands>
1589 Removes latex commands from text. The latex command is assumed to be of the
1590 form C<\command{ text }>. "C<text>" is retained
1592 $clean = $parser->_clean_latex_commands($text);
1596 sub _clean_latex_commands {
1598 my $paragraph = shift;
1600 # Remove latex commands of the form \text{ }
1601 # and replace with the contents of the { }
1602 # need to make this non-greedy so that it can handle
1603 # "\text{a} and \text2{b}"
1604 # without converting it to
1606 # This match will still get into trouble if \} is present
1607 # This is not vital since the subsequent replacement of non-alphanumeric
1608 # characters will tidy it up anyway
1609 $paragraph =~ s/\\\w+{(.*?)}/$1/g;
1614 =item B<_split_delimited>
1616 Split the supplied string into two parts at approximately the
1617 specified word boundary. Special care is made to make sure that it
1618 does not split in the middle of some curly brackets.
1620 e.g. "this text is \textbf{very bold}" would not be split into
1621 "this text is \textbf{very" and " bold".
1623 ($hunk1, $hunk2) = $self->_split_delimited( $para, $length);
1625 The length indicates the maximum length of hunk1.
1629 # initially Supplied by hsmyers@sdragons.com
1630 # 10/25/01, utility to split \hbox
1631 # busting lines. Reformatted by TimJ to match module style.
1632 sub _split_delimited {
1637 # Return immediately if already small
1638 return ($input, '') if length($input) < $limit;
1646 $input =~ s/\n/ /gm;
1648 foreach ( split ( //, $input ) ) {
1654 } elsif ( / / and $depth == 0) {
1655 push @output, $token if ( $token and $token ne ' ' );
1661 if (length($s) < $limit) {
1680 Compatible with C<latex2e> only. Can not be used with C<latex> v2.09
1683 A subclass of C<Pod::Select> so that specific pod sections can be
1684 converted to C<latex> by using the C<select> method.
1686 Some HTML escapes are missing and many have not been tested.
1690 L<Pod::Parser>, L<Pod::Select>, L<pod2latex>
1694 Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt>
1696 Bug fixes have been received from: Simon Cozens
1697 E<lt>simon@cozens.netE<gt>, Mark A. Hershberger
1698 E<lt>mah@everybody.orgE<gt>, Marcel Grunauer
1699 E<lt>marcel@codewerk.comE<gt> and Hugh S Myers
1700 E<lt>hsmyers@sdragons.comE<gt>.
1704 Copyright (C) 2000-2001 Tim Jenness. All Rights Reserved.
1706 This program is free software; you can redistribute it and/or modify
1707 it under the same terms as Perl itself.
1713 $Id: LaTeX.pm,v 1.12 2001/11/20 20:59:26 timj Exp $