Commit | Line | Data |
076c2fc0 |
1 | package Pod::LaTeX; |
2 | |
076c2fc0 |
3 | =head1 NAME |
4 | |
5 | Pod::LaTeX - Convert Pod data to formatted Latex |
6 | |
7 | =head1 SYNOPSIS |
8 | |
9 | use Pod::LaTeX; |
10 | my $parser = Pod::LaTeX->new ( ); |
11 | |
12 | $parser->parse_from_filehandle; |
13 | |
14 | $parser->parse_from_file ('file.pod', 'file.tex'); |
15 | |
16 | =head1 DESCRIPTION |
17 | |
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. |
21 | |
22 | C<Pod::LaTeX> is a derived class from L<Pod::Select|Pod::Select>. |
23 | |
24 | =cut |
25 | |
26 | |
27 | use strict; |
28 | require Pod::ParseUtils; |
29 | use base qw/ Pod::Select /; |
30 | |
31 | # use Data::Dumper; # for debugging |
32 | use Carp; |
33 | |
34 | use vars qw/ $VERSION %HTML_Escapes @LatexSections /; |
35 | |
1826411a |
36 | $VERSION = '0.54'; |
076c2fc0 |
37 | |
38 | # Definitions of =headN -> latex mapping |
39 | @LatexSections = (qw/ |
40 | chapter |
41 | section |
42 | subsection |
43 | subsubsection |
44 | paragraph |
45 | subparagraph |
46 | /); |
47 | |
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) |
51 | |
1826411a |
52 | |
076c2fc0 |
53 | %HTML_Escapes = ( |
1826411a |
54 | # lt, gt and verbar are inserted without math mode |
55 | # since the $$ will be added during general correction |
1c292947 |
56 | # for those escape characters |
1826411a |
57 | 'amp' => '\&', # ampersand |
58 | 'lt' => '<', # ' left chevron, less-than |
59 | 'gt' => '>', # ' right chevron, greater-than |
076c2fc0 |
60 | 'quot' => '"', # double quote |
4d4a0c66 |
61 | 'sol' => '/', |
1826411a |
62 | 'verbar' => '|', |
076c2fc0 |
63 | |
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 |
126 | |
127 | # Added by TimJ |
128 | |
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 |
162 | |
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$', # ' |
175 | "mu" => '$\mu$', # ' |
176 | "nu" => '$\nu$', # ' |
177 | "xi" => '$\xi$', # ' |
178 | "omicron"=> '$o$', # ' |
179 | "pi" => '$\pi$', # ' |
180 | "rho" => '$\rho$', # ' |
181 | "sigma" => '$\sigma$', # ' |
182 | "tau" => '$\tau$', # ' |
183 | "upsilon"=> '$\upsilon$', # ' |
184 | "phi" => '$\phi$', # ' |
185 | "chi" => '$\chi$', # ' |
186 | "psi" => '$\psi$', # ' |
187 | "omega" => '$\omega$', # ' |
188 | |
189 | "Alpha" => '$A$', # ' |
190 | "Beta" => '$B$', # ' |
191 | "Gamma" => '$\Gamma$', # ' |
192 | "Delta" => '$\Delta$', # ' |
193 | "Epsilon"=> '$E$', # ' |
194 | "Zeta" => '$Z$', # ' |
195 | "Eta" => '$H$', # ' |
196 | "Theta" => '$\Theta$', # ' |
197 | "Iota" => '$I$', # ' |
198 | "Kappa" => '$K$', # ' |
199 | "Lambda" => '$\Lambda$', # ' |
200 | "Mu" => '$M$', # ' |
201 | "Nu" => '$N$', # ' |
202 | "Xi" => '$\Xi$', # ' |
203 | "Omicron"=> '$O$', # ' |
204 | "Pi" => '$\Pi$', # ' |
205 | "Rho" => '$R$', # ' |
206 | "Sigma" => '$\Sigma$', # ' |
207 | "Tau" => '$T$', # ' |
208 | "Upsilon"=> '$\Upsilon$', # ' |
209 | "Phi" => '$\Phi$', # ' |
210 | "Chi" => '$X$', # ' |
211 | "Psi" => '$\Psi$', # ' |
212 | "Omega" => '$\Omega$', # ' |
213 | |
214 | |
215 | ); |
216 | |
217 | |
218 | =head1 OBJECT METHODS |
219 | |
220 | The following methods are provided in this module. Methods inherited |
221 | from C<Pod::Select> are not described in the public interface. |
222 | |
223 | =over 4 |
224 | |
225 | =begin __PRIVATE__ |
226 | |
227 | =item C<initialize> |
228 | |
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 |
232 | the constructor. |
233 | |
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. |
237 | |
238 | This method should not be invoked by the user directly. |
239 | |
240 | =end __PRIVATE__ |
241 | |
242 | =cut |
243 | |
244 | |
245 | |
246 | # - An array for nested lists |
247 | |
248 | # Arguments have already been read by this point |
249 | |
250 | sub initialize { |
251 | my $self = shift; |
252 | |
253 | # print Dumper($self); |
254 | |
255 | # Internals |
256 | $self->{_Lists} = []; # For nested lists |
257 | $self->{_suppress_all_para} = 0; # For =begin blocks |
076c2fc0 |
258 | $self->{_dont_modify_any_para}=0; # For =begin blocks |
076c2fc0 |
259 | $self->{_CURRENT_HEAD1} = ''; # Name of current HEAD1 section |
260 | |
261 | # Options - only initialise if not already set |
262 | |
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) |
282 | |
283 | $self->{UniqueLabels} = 1 # Use label unique for each pod |
284 | unless exists $self->{UniqueLabels}; # either based on the filename |
285 | # or supplied |
286 | |
287 | # Control the level of =head1. default is \section |
288 | # |
289 | $self->{Head1Level} = 1 # Offset in latex sections |
290 | unless exists $self->{Head1Level}; # 0 is chapter, 2 is subsection |
291 | |
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}; |
299 | |
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 |
305 | |
306 | $self->{Label} = undef # label to be used as prefix |
307 | unless exists $self->{Label}; # to all internal section names |
308 | |
309 | # These allow the caller to add arbritrary latex code to |
310 | # start and end of document. AddPreamble and AddPostamble are ignored |
311 | # if these are set. |
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}; |
317 | |
318 | # Run base initialize |
319 | $self->SUPER::initialize; |
320 | |
321 | } |
322 | |
323 | =back |
324 | |
325 | =head2 Data Accessors |
326 | |
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. |
330 | |
331 | Default values can be supplied by using these names as keys to a hash |
332 | of arguments when using the C<new()> constructor. |
333 | |
334 | =over 4 |
335 | |
336 | =item B<AddPreamble> |
337 | |
338 | Logical to control whether a C<latex> preamble is to be written. |
1c292947 |
339 | If true, a valid C<latex> preamble is written before the pod data |
340 | is written. This is similar to: |
076c2fc0 |
341 | |
342 | \documentclass{article} |
343 | \begin{document} |
344 | |
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. |
347 | |
348 | $add = $parser->AddPreamble(); |
349 | $parser->AddPreamble(1); |
350 | |
351 | If used in conjunction with C<AddPostamble> a full latex document will |
352 | be written that could be immediately processed by C<latex>. |
353 | |
354 | =cut |
355 | |
356 | sub AddPreamble { |
357 | my $self = shift; |
358 | if (@_) { |
359 | $self->{AddPreamble} = shift; |
360 | } |
361 | return $self->{AddPreamble}; |
362 | } |
363 | |
364 | =item B<AddPostamble> |
365 | |
1c292947 |
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: |
076c2fc0 |
369 | |
370 | \end{document} |
371 | |
1c292947 |
372 | but can be more complicated if an index is required. |
076c2fc0 |
373 | Can be used to set or retrieve the current value. |
374 | |
375 | $add = $parser->AddPostamble(); |
376 | $parser->AddPostamble(1); |
377 | |
378 | If used in conjunction with C<AddPreaamble> a full latex document will |
379 | be written that could be immediately processed by C<latex>. |
380 | |
381 | =cut |
382 | |
383 | sub AddPostamble { |
384 | my $self = shift; |
385 | if (@_) { |
386 | $self->{AddPostamble} = shift; |
387 | } |
388 | return $self->{AddPostamble}; |
389 | } |
390 | |
391 | =item B<Head1Level> |
392 | |
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 |
397 | following elements: |
398 | |
399 | [0] chapter |
400 | [1] section |
401 | [2] subsection |
402 | [3] subsubsection |
403 | [4] paragraph |
404 | [5] subparagraph |
405 | |
406 | Can be used to set or retrieve the current value: |
407 | |
408 | $parser->Head1Level(2); |
409 | $sect = $parser->Head1Level; |
410 | |
1c292947 |
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>). |
076c2fc0 |
415 | |
416 | A check is made to ensure that the supplied value is an integer in the |
417 | range 0 to 5. |
418 | |
419 | Default is for a value of 1 (i.e. a C<section>). |
420 | |
421 | =cut |
422 | |
423 | sub Head1Level { |
424 | my $self = shift; |
425 | if (@_) { |
426 | my $arg = shift; |
427 | if ($arg =~ /^\d$/ && $arg <= $#LatexSections) { |
428 | $self->{Head1Level} = $arg; |
429 | } else { |
430 | carp "Head1Level supplied ($arg) must be integer in range 0 to ".$#LatexSections . "- Ignoring\n"; |
431 | } |
432 | } |
433 | return $self->{Head1Level}; |
434 | } |
435 | |
436 | =item B<Label> |
437 | |
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}>. |
446 | |
447 | Can be used to set or retrieve the current value: |
448 | |
449 | $label = $parser->Label; |
450 | $parser->Label($label); |
451 | |
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. |
456 | |
457 | Default value is C<undef>. |
458 | |
459 | =cut |
460 | |
461 | sub Label { |
462 | my $self = shift; |
463 | if (@_) { |
464 | $self->{Label} = shift; |
465 | } |
466 | return $self->{Label}; |
467 | } |
468 | |
469 | =item B<LevelNoNum> |
470 | |
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. |
474 | |
475 | Can be used to set or retrieve the current value: |
476 | |
477 | $lev = $parser->LevelNoNum; |
478 | $parser->LevelNoNum(2); |
479 | |
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. |
483 | |
484 | Default is 2. (i.e. C<latex> subsections are written as C<subsection*> |
485 | but sections are numbered). |
486 | |
487 | =cut |
488 | |
489 | sub LevelNoNum { |
490 | my $self = shift; |
491 | if (@_) { |
492 | $self->{LevelNoNum} = shift; |
493 | } |
494 | return $self->{LevelNoNum}; |
495 | } |
496 | |
497 | =item B<MakeIndex> |
498 | |
499 | Controls whether C<latex> commands for creating an index are to be inserted |
500 | into the preamble and postamble |
501 | |
502 | $makeindex = $parser->MakeIndex; |
503 | $parser->MakeIndex(0); |
504 | |
1c292947 |
505 | Irrelevant if both C<AddPreamble> and C<AddPostamble> are false |
506 | (or equivalently, C<UserPreamble> and C<UserPostamble> are set). |
076c2fc0 |
507 | |
508 | Default is for an index to be created. |
509 | |
510 | =cut |
511 | |
512 | sub MakeIndex { |
513 | my $self = shift; |
514 | if (@_) { |
515 | $self->{MakeIndex} = shift; |
516 | } |
517 | return $self->{MakeIndex}; |
518 | } |
519 | |
520 | =item B<ReplaceNAMEwithSection> |
521 | |
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". |
525 | |
526 | If true, the pod segment |
527 | |
528 | =head1 NAME |
529 | |
530 | pod::name - purpose |
531 | |
532 | =head1 SYNOPSIS |
533 | |
534 | is converted to the C<latex> |
535 | |
536 | \section{pod::name\label{pod_name}\index{pod::name}} |
537 | |
538 | Purpose |
539 | |
540 | \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}% |
541 | \index{pod::name!SYNOPSIS}} |
542 | |
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>). |
547 | |
548 | The C<Label> is set from the pod name regardless of any current value |
549 | of C<Label>. |
550 | |
551 | $mod = $parser->ReplaceNAMEwithSection; |
552 | $parser->ReplaceNAMEwithSection(0); |
553 | |
554 | Default is to translate the pod literally. |
555 | |
556 | =cut |
557 | |
558 | sub ReplaceNAMEwithSection { |
559 | my $self = shift; |
560 | if (@_) { |
561 | $self->{ReplaceNAMEwithSection} = shift; |
562 | } |
563 | return $self->{ReplaceNAMEwithSection}; |
564 | } |
565 | |
566 | =item B<StartWithNewPage> |
567 | |
568 | If true, each pod translation will begin with a C<latex> |
569 | C<\clearpage>. |
570 | |
571 | $parser->StartWithNewPage(1); |
572 | $newpage = $parser->StartWithNewPage; |
573 | |
574 | Default is false. |
575 | |
576 | =cut |
577 | |
578 | sub StartWithNewPage { |
579 | my $self = shift; |
580 | if (@_) { |
581 | $self->{StartWithNewPage} = shift; |
582 | } |
583 | return $self->{StartWithNewPage}; |
584 | } |
585 | |
586 | =item B<TableOfContents> |
587 | |
588 | If true, a table of contents will be created. |
589 | Irrelevant if C<AddPreamble> is false or C<UserPreamble> |
590 | is set. |
591 | |
592 | $toc = $parser->TableOfContents; |
593 | $parser->TableOfContents(1); |
594 | |
595 | Default is false. |
596 | |
597 | =cut |
598 | |
599 | sub TableOfContents { |
600 | my $self = shift; |
601 | if (@_) { |
602 | $self->{TableOfContents} = shift; |
603 | } |
604 | return $self->{TableOfContents}; |
605 | } |
606 | |
607 | =item B<UniqueLabels> |
608 | |
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> |
614 | |
615 | $parser->UniqueLabels(1); |
616 | $unq = $parser->UniqueLabels; |
617 | |
618 | Default is true. |
619 | |
620 | =cut |
621 | |
622 | sub UniqueLabels { |
623 | my $self = shift; |
624 | if (@_) { |
625 | $self->{UniqueLabels} = shift; |
626 | } |
627 | return $self->{UniqueLabels}; |
628 | } |
629 | |
630 | =item B<UserPreamble> |
631 | |
632 | User supplied C<latex> preamble. Added before the pod translation |
633 | data. |
634 | |
1c292947 |
635 | If set, the contents will be prepended to the output file before |
636 | the translated data regardless of the value of C<AddPreamble>. |
076c2fc0 |
637 | C<MakeIndex> and C<TableOfContents> will also be ignored. |
638 | |
639 | =cut |
640 | |
641 | sub UserPreamble { |
642 | my $self = shift; |
643 | if (@_) { |
644 | $self->{UserPreamble} = shift; |
645 | } |
646 | return $self->{UserPreamble}; |
647 | } |
648 | |
649 | =item B<UserPostamble> |
650 | |
651 | User supplied C<latex> postamble. Added after the pod translation |
652 | data. |
653 | |
1c292947 |
654 | If set, the contents will be prepended to the output file after |
655 | the translated data regardless of the value of C<AddPostamble>. |
076c2fc0 |
656 | C<MakeIndex> will also be ignored. |
657 | |
658 | =cut |
659 | |
660 | sub UserPostamble { |
661 | my $self = shift; |
662 | if (@_) { |
663 | $self->{UserPostamble} = shift; |
664 | } |
665 | return $self->{UserPostamble}; |
666 | } |
667 | |
668 | =begin __PRIVATE__ |
669 | |
670 | =item B<Lists> |
671 | |
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 |
677 | lists are active. |
678 | |
91e74348 |
679 | Returns array of list information in list context |
076c2fc0 |
680 | Returns array ref in scalar context |
681 | |
682 | =cut |
683 | |
684 | |
685 | |
686 | sub lists { |
687 | my $self = shift; |
688 | return @{ $self->{_Lists} } if wantarray(); |
689 | return $self->{_Lists}; |
690 | } |
691 | |
692 | =end __PRIVATE__ |
693 | |
694 | =back |
695 | |
696 | =begin __PRIVATE__ |
697 | |
698 | =head2 Subclassed methods |
699 | |
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. |
703 | |
704 | =over 4 |
705 | |
706 | =cut |
707 | |
708 | ######### END ACCESSORS ################### |
709 | |
710 | # Opening pod |
711 | |
712 | =item B<begin_pod> |
713 | |
714 | Writes the C<latex> preamble if requested. |
715 | |
716 | =cut |
717 | |
718 | sub begin_pod { |
719 | my $self = shift; |
720 | |
721 | # Get the pod identification |
722 | # This should really come from the '=head1 NAME' paragraph |
723 | |
724 | my $infile = $self->input_file; |
725 | my $class = ref($self); |
726 | my $date = gmtime(time); |
727 | |
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 |
733 | __TEX_COMMENT__ |
734 | |
735 | # Write the preamble |
736 | # If the caller has supplied one then we just use that |
737 | |
738 | my $preamble = ''; |
739 | if (defined $self->UserPreamble) { |
740 | |
741 | $preamble = $self->UserPreamble; |
742 | |
743 | # Add the description of where this came from |
744 | $preamble .= "\n$comment"; |
745 | |
746 | |
747 | } elsif ($self->AddPreamble) { |
748 | # Write our own preamble |
749 | |
750 | # Code to initialise index making |
751 | # Use an array so that we can prepend comment if required |
752 | my @makeidx = ( |
753 | '\usepackage{makeidx}', |
754 | '\makeindex', |
755 | ); |
756 | |
757 | unless ($self->MakeIndex) { |
758 | foreach (@makeidx) { |
759 | $_ = '%% ' . $_; |
760 | } |
761 | } |
762 | my $makeindex = join("\n",@makeidx) . "\n"; |
763 | |
764 | |
765 | # Table of contents |
766 | my $tableofcontents = '\tableofcontents'; |
767 | |
768 | $tableofcontents = '%% ' . $tableofcontents |
769 | unless $self->TableOfContents; |
770 | |
771 | # Roll our own |
772 | $preamble = << "__TEX_HEADER__"; |
773 | \\documentclass{article} |
774 | |
775 | $comment |
776 | |
777 | $makeindex |
778 | |
779 | \\begin{document} |
780 | |
781 | $tableofcontents |
782 | |
783 | __TEX_HEADER__ |
784 | |
785 | } |
786 | |
787 | # Write the header (blank if none) |
788 | $self->_output($preamble); |
789 | |
790 | # Start on new page if requested |
791 | $self->_output("\\clearpage\n") if $self->StartWithNewPage; |
792 | |
793 | } |
794 | |
795 | |
796 | =item B<end_pod> |
797 | |
798 | Write the closing C<latex> code. |
799 | |
800 | =cut |
801 | |
802 | sub end_pod { |
803 | my $self = shift; |
804 | |
805 | # End string |
806 | my $end = ''; |
807 | |
808 | # Use the user version of the postamble if deinfed |
809 | if (defined $self->UserPostamble) { |
810 | $end = $self->UserPostamble; |
811 | |
812 | $self->_output($end); |
813 | |
814 | } elsif ($self->AddPostamble) { |
815 | |
816 | # Check for index |
817 | my $makeindex = '\printindex'; |
818 | |
819 | $makeindex = '%% '. $makeindex unless $self->MakeIndex; |
820 | |
821 | $end = "$makeindex\n\n\\end{document}\n"; |
822 | } |
823 | |
824 | |
825 | $self->_output($end); |
826 | |
827 | } |
828 | |
829 | =item B<command> |
830 | |
831 | Process basic pod commands. |
832 | |
833 | =cut |
834 | |
835 | sub command { |
836 | my $self = shift; |
837 | my ($command, $paragraph, $line_num, $parobj) = @_; |
838 | |
839 | # return if we dont care |
840 | return if $command eq 'pod'; |
841 | |
1826411a |
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; |
845 | |
846 | # Do the latex escapes |
076c2fc0 |
847 | $paragraph = $self->_replace_special_chars($paragraph); |
848 | |
849 | # Interpolate pod sequences in paragraph |
850 | $paragraph = $self->interpolate($paragraph, $line_num); |
076c2fc0 |
851 | $paragraph =~ s/\s+$//; |
852 | |
1826411a |
853 | # Replace characters that can only be done after |
854 | # interpolation of interior sequences |
855 | $paragraph = $self->_replace_special_chars_late($paragraph); |
856 | |
076c2fc0 |
857 | # Now run the command |
858 | if ($command eq 'over') { |
859 | |
860 | $self->begin_list($paragraph, $line_num); |
861 | |
862 | } elsif ($command eq 'item') { |
863 | |
864 | $self->add_item($paragraph, $line_num); |
865 | |
866 | } elsif ($command eq 'back') { |
867 | |
868 | $self->end_list($line_num); |
869 | |
870 | } elsif ($command eq 'head1') { |
871 | |
872 | # Store the name of the section |
873 | $self->{_CURRENT_HEAD1} = $paragraph; |
874 | |
875 | # Print it |
876 | $self->head(1, $paragraph, $parobj); |
877 | |
878 | } elsif ($command eq 'head2') { |
879 | |
880 | $self->head(2, $paragraph, $parobj); |
881 | |
882 | } elsif ($command eq 'head3') { |
883 | |
884 | $self->head(3, $paragraph, $parobj); |
885 | |
886 | } elsif ($command eq 'head4') { |
887 | |
888 | $self->head(4, $paragraph, $parobj); |
889 | |
890 | } elsif ($command eq 'head5') { |
891 | |
892 | $self->head(5, $paragraph, $parobj); |
893 | |
894 | } elsif ($command eq 'head6') { |
895 | |
896 | $self->head(6, $paragraph, $parobj); |
897 | |
898 | } elsif ($command eq 'begin') { |
899 | |
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; |
904 | |
905 | } else { |
906 | # Suppress all subsequent paragraphs unless |
907 | # it is explcitly intended for latex |
908 | $self->{_suppress_all_para} = 1; |
909 | } |
910 | |
911 | } elsif ($command eq 'for') { |
912 | |
1826411a |
913 | # =for latex |
914 | # some latex |
915 | |
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 |
920 | |
921 | # The first line contains the format and the rest is the |
922 | # raw code. |
923 | my ($format, $chunk) = split(/\n/, $rawpara, 2); |
924 | |
925 | # If we have got some latex code print it out immediately |
926 | # unmodified. Else do nothing. |
927 | if ($format =~ /^latex/i) { |
076c2fc0 |
928 | # Make sure that next paragraph is not modfied before printing |
1826411a |
929 | $self->_output( $chunk ); |
076c2fc0 |
930 | |
076c2fc0 |
931 | } |
932 | |
933 | } elsif ($command eq 'end') { |
934 | |
935 | # Reset suppression |
936 | $self->{_suppress_all_para} = 0; |
937 | $self->{_dont_modify_any_para} = 0; |
938 | |
939 | } elsif ($command eq 'pod') { |
940 | |
941 | # Do nothing |
942 | |
943 | } else { |
944 | carp "Command $command not recognised at line $line_num\n"; |
945 | } |
946 | |
947 | } |
948 | |
949 | =item B<verbatim> |
950 | |
951 | Verbatim text |
952 | |
953 | =cut |
954 | |
955 | sub verbatim { |
956 | my $self = shift; |
957 | my ($paragraph, $line_num, $parobj) = @_; |
958 | |
1826411a |
959 | # Expand paragraph unless in =begin block |
960 | if ($self->{_dont_modify_any_para}) { |
076c2fc0 |
961 | # Just print as is |
962 | $self->_output($paragraph); |
963 | |
076c2fc0 |
964 | } else { |
965 | |
966 | return if $paragraph =~ /^\s+$/; |
967 | |
968 | # Clean trailing space |
969 | $paragraph =~ s/\s+$//; |
970 | |
1826411a |
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); |
975 | foreach (@l) { |
976 | 1 while s/(^|\n)([^\t\n]*)(\t+)/ |
977 | $1. $2 . (" " x |
978 | (8 * length($3) |
979 | - (length($2) % 8))) |
980 | /sex; |
981 | } |
982 | $paragraph = join("\n",@l); |
983 | # End of change. |
984 | |
985 | |
4d4a0c66 |
986 | |
076c2fc0 |
987 | $self->_output('\begin{verbatim}' . "\n$paragraph\n". '\end{verbatim}'."\n"); |
988 | } |
989 | } |
990 | |
991 | =item B<textblock> |
992 | |
993 | Plain text paragraph. |
994 | |
995 | =cut |
996 | |
997 | sub textblock { |
998 | my $self = shift; |
999 | my ($paragraph, $line_num, $parobj) = @_; |
1000 | |
1001 | # print Dumper($self); |
1826411a |
1002 | |
1003 | # Expand paragraph unless in =begin block |
1004 | if ($self->{_dont_modify_any_para}) { |
076c2fc0 |
1005 | # Just print as is |
1006 | $self->_output($paragraph); |
1007 | |
076c2fc0 |
1008 | return; |
1826411a |
1009 | } |
1010 | |
076c2fc0 |
1011 | |
076c2fc0 |
1012 | # Escape latex special characters |
1013 | $paragraph = $self->_replace_special_chars($paragraph); |
1014 | |
1015 | # Interpolate interior sequences |
1016 | my $expansion = $self->interpolate($paragraph, $line_num); |
1017 | $expansion =~ s/\s+$//; |
1018 | |
1826411a |
1019 | # Escape special characters that can not be done earlier |
1020 | $expansion = $self->_replace_special_chars_late($expansion); |
076c2fc0 |
1021 | |
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 |
1026 | # present. |
1027 | if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()) { |
1028 | |
1029 | # Strip white space from start and end |
1030 | $paragraph =~ s/^\s+//; |
1031 | $paragraph =~ s/\s$//; |
1032 | |
1033 | # Split the string into 2 parts |
1034 | my ($name, $purpose) = split(/\s+-\s+/, $expansion,2); |
1035 | |
1036 | # Now prevent this from triggering until a new head1 NAME is set |
1037 | $self->{_CURRENT_HEAD1} = '_NAME'; |
1038 | |
1039 | # Might want to clear the Label() before doing this (CHECK) |
1040 | |
1041 | # Print the heading |
1042 | $self->head(1, $name, $parobj); |
1043 | |
1044 | # Set the labeling in case we want unique names later |
1045 | $self->Label( $self->_create_label( $name, 1 ) ); |
1046 | |
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; |
1052 | |
1053 | # Now write out the new latex paragraph |
1054 | $purpose = ucfirst($purpose); |
1055 | $self->_output("\n\n$purpose\n\n"); |
1056 | |
1057 | } else { |
1058 | # Just write the output |
1059 | $self->_output("\n\n$expansion\n\n"); |
1060 | } |
1061 | |
1062 | } |
1063 | |
1064 | =item B<interior_sequence> |
1065 | |
1066 | Interior sequence expansion |
1067 | |
1068 | =cut |
1069 | |
1070 | sub interior_sequence { |
1071 | my $self = shift; |
1072 | |
1073 | my ($seq_command, $seq_argument, $pod_seq) = @_; |
1074 | |
1075 | if ($seq_command eq 'B') { |
1076 | return "\\textbf{$seq_argument}"; |
1077 | |
1078 | } elsif ($seq_command eq 'I') { |
1079 | return "\\textit{$seq_argument}"; |
1080 | |
1081 | } elsif ($seq_command eq 'E') { |
1082 | |
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}; |
1089 | |
1090 | } else { |
1091 | my ($file, $line) = $pod_seq->file_line(); |
1092 | warn "Escape sequence $seq_argument not recognised at line $line of file $file\n"; |
1093 | return; |
1094 | } |
1095 | |
1096 | } elsif ($seq_command eq 'Z') { |
1097 | |
1098 | # Zero width space |
1099 | return '$\!$'; # ' |
1100 | |
1101 | } elsif ($seq_command eq 'C') { |
1102 | return "\\texttt{$seq_argument}"; |
1103 | |
1104 | } elsif ($seq_command eq 'F') { |
1105 | return "\\emph{$seq_argument}"; |
1106 | |
1107 | } elsif ($seq_command eq 'S') { |
1108 | # non breakable spaces |
1109 | my $nbsp = '$\:$'; #' |
1110 | |
1111 | $seq_argument =~ s/\s/$nbsp/g; |
1112 | return $seq_argument; |
1113 | |
1114 | } elsif ($seq_command eq 'L') { |
1115 | |
1116 | my $link = new Pod::Hyperlink($seq_argument); |
1117 | |
1118 | # undef on failure |
1119 | unless (defined $link) { |
1120 | carp $@; |
1121 | return; |
1122 | } |
1123 | |
1124 | # Handle internal links differently |
1125 | my $type = $link->type; |
1126 | my $page = $link->page; |
1127 | |
1128 | if ($type eq 'section' && $page eq '') { |
1129 | # Use internal latex reference |
1130 | my $node = $link->node; |
1131 | |
1132 | # Convert to a label |
1133 | $node = $self->_create_label($node); |
1134 | |
1135 | return "\\S\\ref{$node}"; |
1136 | |
1137 | } else { |
1138 | # Use default markup for external references |
1139 | # (although Starlink would use \xlabel) |
1140 | my $markup = $link->markup; |
1141 | |
1142 | my ($file, $line) = $pod_seq->file_line(); |
1143 | |
1144 | return $self->interpolate($link->markup, $line); |
1145 | } |
1146 | |
1147 | |
1148 | |
1149 | } elsif ($seq_command eq 'P') { |
1150 | # Special markup for Pod::Hyperlink |
1826411a |
1151 | # Replace :: with / - but not sure if I want to do this |
1152 | # any more. |
076c2fc0 |
1153 | my $link = $seq_argument; |
1154 | $link =~ s/::/\//g; |
1155 | |
1156 | my $ref = "\\emph{$seq_argument}"; |
1157 | return $ref; |
1158 | |
1159 | } elsif ($seq_command eq 'Q') { |
1160 | # Special markup for Pod::Hyperlink |
1826411a |
1161 | return "\\textsf{$seq_argument}"; |
076c2fc0 |
1162 | |
1163 | } elsif ($seq_command eq 'X') { |
1164 | # Index entries |
1165 | |
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"; |
1171 | |
1172 | } else { |
1173 | carp "Unknown sequence $seq_command<$seq_argument>"; |
1174 | } |
1175 | |
1176 | } |
1177 | |
1178 | =back |
1179 | |
1180 | =head2 List Methods |
1181 | |
1182 | Methods used to handle lists. |
1183 | |
1184 | =over 4 |
1185 | |
1186 | =item B<begin_list> |
1187 | |
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 |
1190 | list stack. |
1191 | |
1192 | $parser->begin_list($indent, $line_num); |
1193 | |
1194 | =cut |
1195 | |
1196 | sub begin_list { |
1197 | my $self = shift; |
1198 | my $indent = shift; |
1199 | my $line_num = shift; |
1200 | |
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, |
1206 | ) |
1207 | ); |
1208 | |
1209 | } |
1210 | |
1211 | =item B<end_list> |
1212 | |
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. |
1216 | |
1217 | $parser->end_list($line_num); |
1218 | |
1219 | =cut |
1220 | |
1221 | sub end_list { |
1222 | my $self = shift; |
1223 | my $line_num = shift; |
1224 | |
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"; |
1228 | return; |
1229 | } |
1230 | |
1231 | # What to write depends on list type |
1232 | my $type = $self->lists->[-1]->type; |
1233 | |
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); |
1239 | |
1240 | # Clear list |
1241 | pop(@{ $self->lists}); |
1242 | |
1243 | } |
1244 | |
1245 | =item B<add_item> |
1246 | |
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. |
1251 | |
1252 | $parser->add_item($paragraph, $line_num); |
1253 | |
1254 | =cut |
1255 | |
1256 | sub add_item { |
1257 | my $self = shift; |
1258 | my $paragraph = shift; |
1259 | my $line_num = shift; |
1260 | |
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"); |
1267 | return; |
1268 | } |
1269 | |
1270 | # If paragraphs printing is turned off via =begin/=end or whatver |
1271 | # simply return immediately |
1826411a |
1272 | return if $self->{_suppress_all_para}; |
076c2fc0 |
1273 | |
1274 | # Check to see whether we are starting a new lists |
1275 | if (scalar($self->lists->[-1]->item) == 0) { |
1276 | |
1277 | # Examine the paragraph to determine what type of list |
1278 | # we have |
1279 | $paragraph =~ s/\s+$//; |
1280 | $paragraph =~ s/^\s+//; |
1281 | |
1282 | my $type; |
4d4a0c66 |
1283 | if (substr($paragraph, 0,1) eq '*') { |
076c2fc0 |
1284 | $type = 'itemize'; |
1285 | } elsif ($paragraph =~ /^\d/) { |
1286 | $type = 'enumerate'; |
1287 | } else { |
1288 | $type = 'description'; |
1289 | } |
1290 | $self->lists->[-1]->type($type); |
1291 | |
1292 | $self->_output("\\begin{$type}\n"); |
1293 | |
1294 | } |
1295 | |
1296 | my $type = $self->lists->[-1]->type; |
1297 | |
1298 | if ($type eq 'description') { |
4d4a0c66 |
1299 | # Handle long items - long items do not wrap |
1826411a |
1300 | # If the string is longer than 40 characters we split |
1301 | # it into a real item header and some bold text. |
1302 | my $maxlen = 40; |
1303 | my ($hunk1, $hunk2) = $self->_split_delimited( $paragraph, $maxlen ); |
1304 | |
1305 | # Print the first hunk |
1306 | $self->_output("\n\\item[$hunk1] "); |
1307 | |
1308 | # and the second hunk if it is defined |
1309 | if ($hunk2) { |
1310 | $self->_output("\\textbf{$hunk2}"); |
4d4a0c66 |
1311 | } else { |
1826411a |
1312 | # Not there so make sure we have a new line |
1313 | $self->_output("\\mbox{}"); |
4d4a0c66 |
1314 | } |
076c2fc0 |
1315 | |
076c2fc0 |
1316 | } else { |
4d4a0c66 |
1317 | # If the item was '* Something' we still need to write |
1318 | # out the something |
1319 | my $extra_info = $paragraph; |
1320 | $extra_info =~ s/^\*\s*//; |
1826411a |
1321 | $self->_output("\n\\item $extra_info"); |
076c2fc0 |
1322 | } |
1323 | |
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); |
1327 | |
1328 | } |
1329 | |
1330 | =back |
1331 | |
1332 | =head2 Methods for headings |
1333 | |
1334 | =over 4 |
1335 | |
1336 | =item B<head> |
1337 | |
1338 | Print a heading of the required level. |
1339 | |
1340 | $parser->head($level, $paragraph, $parobj); |
1341 | |
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. |
1345 | |
1346 | =cut |
1347 | |
1348 | sub head { |
1349 | my $self = shift; |
1350 | my $num = shift; |
1351 | my $paragraph = shift; |
1352 | my $parobj = shift; |
1353 | |
1354 | # If we are replace 'head1 NAME' with a section |
1355 | # we return immediately if we get it |
1356 | return |
1357 | if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()); |
1358 | |
1359 | # Create a label |
1360 | my $label = $self->_create_label($paragraph); |
1361 | |
1362 | # Create an index entry |
1363 | my $index = $self->_create_index($paragraph); |
1364 | |
1365 | # Work out position in the above array taking into account |
1366 | # that =head1 is equivalent to $self->Head1Level |
1367 | |
1368 | my $level = $self->Head1Level() - 1 + $num; |
1369 | |
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; |
1376 | } |
1377 | |
1378 | # Check to see whether section should be unnumbered |
1379 | my $star = ($level >= $self->LevelNoNum ? '*' : ''); |
1380 | |
1381 | # Section |
1826411a |
1382 | $self->_output("\\" .$LatexSections[$level] .$star ."{$paragraph\\label{".$label ."}\\index{".$index."}}\n"); |
076c2fc0 |
1383 | |
1384 | } |
1385 | |
1386 | |
1387 | =back |
1388 | |
1389 | =end __PRIVATE__ |
1390 | |
1391 | =begin __PRIVATE__ |
1392 | |
1393 | =head2 Internal methods |
1394 | |
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. |
1397 | |
1398 | =over 4 |
1399 | |
1400 | =item B<_output> |
1401 | |
1402 | Output text to the output filehandle. This method must be always be called |
1403 | to output parsed text. |
1404 | |
1405 | $parser->_output($text); |
1406 | |
1826411a |
1407 | Does not write anything if a =begin is active that should be |
076c2fc0 |
1408 | ignored. |
1409 | |
1410 | =cut |
1411 | |
1412 | sub _output { |
1413 | my $self = shift; |
1414 | my $text = shift; |
1415 | |
1826411a |
1416 | print { $self->output_handle } $text |
1417 | unless $self->{_suppress_all_para}; |
076c2fc0 |
1418 | |
076c2fc0 |
1419 | } |
1420 | |
1421 | |
1422 | =item B<_replace_special_chars> |
1423 | |
1424 | Subroutine to replace characters that are special in C<latex> |
1425 | with the escaped forms |
1426 | |
1427 | $escaped = $parser->_replace_special_chars($paragraph); |
1428 | |
1826411a |
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 |
1434 | sequences. |
076c2fc0 |
1435 | |
1436 | Special characters and the C<latex> equivalents are: |
1437 | |
1438 | } \} |
1439 | { \{ |
1440 | _ \_ |
1441 | $ \$ |
1442 | % \% |
1443 | & \& |
1444 | \ $\backslash$ |
1445 | ^ \^{} |
4d4a0c66 |
1446 | ~ \~{} |
076c2fc0 |
1447 | |
1448 | =cut |
1449 | |
1450 | sub _replace_special_chars { |
1451 | my $self = shift; |
1452 | my $paragraph = shift; |
1453 | |
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; |
1459 | |
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; |
1463 | |
1464 | # Replace ^ characters with \^{} so that $^F works okay |
1465 | $paragraph =~ s/(\^)/\\$1\{\}/g; |
1466 | |
4d4a0c66 |
1467 | # Replace tilde (~) with \texttt{\~{}} |
1468 | $paragraph =~ s/~/\\texttt\{\\~\{\}\}/g; |
1469 | |
1826411a |
1470 | # Now add the dollars around each \backslash |
1471 | $paragraph =~ s/(\\backslash)/\$$1\$/g; |
1472 | return $paragraph; |
1473 | } |
1474 | |
1475 | =item B<_replace_special_chars_late> |
1476 | |
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 |
1480 | sequences. |
1481 | |
1482 | Does the following transformation: |
1483 | |
1484 | < $<$ |
1485 | > $>$ |
1486 | | $|$ |
1487 | |
1488 | |
1489 | =cut |
1490 | |
1491 | sub _replace_special_chars_late { |
1492 | my $self = shift; |
1493 | my $paragraph = shift; |
1494 | |
1495 | # < and > |
1496 | $paragraph =~ s/(<|>)/\$$1\$/g; |
1497 | |
4d4a0c66 |
1498 | # Replace | with $|$ |
1499 | $paragraph =~ s'\|'$|$'g; |
1500 | |
076c2fc0 |
1501 | |
1502 | return $paragraph; |
1503 | } |
1504 | |
1505 | |
1506 | =item B<_create_label> |
1507 | |
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) |
1510 | |
1511 | $label = $parser->_create_label($string) |
1512 | |
1513 | If UniqueLabels is true returns a label prefixed by Label() |
1514 | This can be suppressed with an optional second argument. |
1515 | |
1516 | $label = $parser->_create_label($string, $suppress); |
1517 | |
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. |
1521 | |
1522 | =cut |
1523 | |
1524 | sub _create_label { |
1525 | my $self = shift; |
1526 | my $paragraph = shift; |
1527 | my $suppress = (@_ ? 1 : 0 ); |
1528 | |
1529 | # Remove latex commands |
1530 | $paragraph = $self->_clean_latex_commands($paragraph); |
1531 | |
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; |
1535 | |
1536 | # Multiple underscores will look unsightly so remove repeats |
1537 | # This will also have the advantage of tidying up the end and |
1538 | # start of string |
1539 | $paragraph =~ s/_+/_/g; |
1540 | |
1541 | # If required need to make sure that the label is unique |
1542 | # since it is possible to have multiple pods in a single |
1543 | # document |
1544 | if (!$suppress && $self->UniqueLabels() && defined $self->Label) { |
1545 | $paragraph = $self->Label() .'_'. $paragraph; |
1546 | } |
1547 | |
1548 | return $paragraph; |
1549 | } |
1550 | |
1551 | |
1552 | =item B<_create_index> |
1553 | |
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. |
1557 | |
1558 | $ind = $parser->_create_index($paragraph); |
1559 | |
1560 | An exclamation mark is used by C<makeindex> to generate |
1561 | sub-entries in an index. |
1562 | |
1563 | =cut |
1564 | |
1565 | sub _create_index { |
1566 | my $self = shift; |
1567 | my $paragraph = shift; |
1568 | my $suppress = (@_ ? 1 : 0 ); |
1569 | |
1570 | # Remove latex commands |
1571 | $paragraph = $self->_clean_latex_commands($paragraph); |
1572 | |
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 |
1575 | # document |
1576 | if (!$suppress && $self->UniqueLabels() && defined $self->Label) { |
1577 | $paragraph = $self->Label() .'!'. $paragraph; |
1578 | } |
1579 | |
1580 | # Need to replace _ with space |
1581 | $paragraph =~ s/_/ /g; |
1582 | |
1583 | return $paragraph; |
1584 | |
1585 | } |
1586 | |
1587 | =item B<_clean_latex_commands> |
1588 | |
1589 | Removes latex commands from text. The latex command is assumed to be of the |
1590 | form C<\command{ text }>. "C<text>" is retained |
1591 | |
1592 | $clean = $parser->_clean_latex_commands($text); |
1593 | |
1594 | =cut |
1595 | |
1596 | sub _clean_latex_commands { |
1597 | my $self = shift; |
1598 | my $paragraph = shift; |
1599 | |
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 |
1605 | # "a} and \text2{b" |
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; |
1610 | |
1611 | return $paragraph |
1612 | } |
1613 | |
1826411a |
1614 | =item B<_split_delimited> |
1615 | |
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. |
1619 | |
1620 | e.g. "this text is \textbf{very bold}" would not be split into |
1621 | "this text is \textbf{very" and " bold". |
1622 | |
1623 | ($hunk1, $hunk2) = $self->_split_delimited( $para, $length); |
1624 | |
1625 | The length indicates the maximum length of hunk1. |
1626 | |
1627 | =cut |
1628 | |
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 { |
1633 | my $self = shift; |
1634 | my $input = shift; |
1635 | my $limit = shift; |
1636 | |
1637 | # Return immediately if already small |
1638 | return ($input, '') if length($input) < $limit; |
1639 | |
1640 | my @output; |
1641 | my $s = ''; |
1642 | my $t = ''; |
1643 | my $depth = 0; |
1644 | my $token; |
1645 | |
1646 | $input =~ s/\n/ /gm; |
1647 | $input .= ' '; |
1648 | foreach ( split ( //, $input ) ) { |
1649 | $token .= $_; |
1650 | if (/\{/) { |
1651 | $depth++; |
1652 | } elsif ( /}/ ) { |
1653 | $depth--; |
1654 | } elsif ( / / and $depth == 0) { |
1655 | push @output, $token if ( $token and $token ne ' ' ); |
1656 | $token = ''; |
1657 | } |
1658 | } |
1659 | |
1660 | foreach (@output) { |
1661 | if (length($s) < $limit) { |
1662 | $s .= $_; |
1663 | } else { |
1664 | $t .= $_; |
1665 | } |
1666 | } |
1667 | |
1668 | # Tidy up |
1669 | $s =~ s/\s+$//; |
1670 | $t =~ s/\s+$//; |
1671 | return ($s,$t); |
1672 | } |
1673 | |
076c2fc0 |
1674 | =back |
1675 | |
1676 | =end __PRIVATE__ |
1677 | |
1678 | =head1 NOTES |
1679 | |
1680 | Compatible with C<latex2e> only. Can not be used with C<latex> v2.09 |
1681 | or earlier. |
1682 | |
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. |
1685 | |
1686 | Some HTML escapes are missing and many have not been tested. |
1687 | |
1688 | =head1 SEE ALSO |
1689 | |
1690 | L<Pod::Parser>, L<Pod::Select>, L<pod2latex> |
1691 | |
1692 | =head1 AUTHORS |
1693 | |
1694 | Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt> |
1695 | |
1826411a |
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>. |
1701 | |
076c2fc0 |
1702 | =head1 COPYRIGHT |
1703 | |
1826411a |
1704 | Copyright (C) 2000-2001 Tim Jenness. All Rights Reserved. |
076c2fc0 |
1705 | |
1826411a |
1706 | This program is free software; you can redistribute it and/or modify |
1707 | it under the same terms as Perl itself. |
076c2fc0 |
1708 | |
1709 | =begin __PRIVATE__ |
1710 | |
1711 | =head1 REVISION |
1712 | |
1826411a |
1713 | $Id: LaTeX.pm,v 1.12 2001/11/20 20:59:26 timj Exp $ |
076c2fc0 |
1714 | |
1715 | =end __PRIVATE__ |
1716 | |
1717 | =cut |