| [ Index ] |
PHP Cross Reference of Unnamed Project |
[Summary view] [Print] [Text view]
1 # Pod::Text -- Convert POD data to formatted ASCII text. 2 # $Id: Text.pm,v 3.8 2006-09-16 20:55:41 eagle Exp $ 3 # 4 # Copyright 1999, 2000, 2001, 2002, 2004, 2006 5 # by Russ Allbery <rra@stanford.edu> 6 # 7 # This program is free software; you may redistribute it and/or modify it 8 # under the same terms as Perl itself. 9 # 10 # This module converts POD to formatted text. It replaces the old Pod::Text 11 # module that came with versions of Perl prior to 5.6.0 and attempts to match 12 # its output except for some specific circumstances where other decisions 13 # seemed to produce better output. It uses Pod::Parser and is designed to be 14 # very easy to subclass. 15 # 16 # Perl core hackers, please note that this module is also separately 17 # maintained outside of the Perl core as part of the podlators. Please send 18 # me any patches at the address above in addition to sending them to the 19 # standard Perl mailing lists. 20 21 ############################################################################## 22 # Modules and declarations 23 ############################################################################## 24 25 package Pod::Text; 26 27 require 5.004; 28 29 use strict; 30 use vars qw(@ISA @EXPORT %ESCAPES $VERSION); 31 32 use Carp qw(carp croak); 33 use Exporter (); 34 use Pod::Simple (); 35 36 @ISA = qw(Pod::Simple Exporter); 37 38 # We have to export pod2text for backward compatibility. 39 @EXPORT = qw(pod2text); 40 41 # Don't use the CVS revision as the version, since this module is also in Perl 42 # core and too many things could munge CVS magic revision strings. This 43 # number should ideally be the same as the CVS revision in podlators, however. 44 $VERSION = 3.08; 45 46 ############################################################################## 47 # Initialization 48 ############################################################################## 49 50 # This function handles code blocks. It's registered as a callback to 51 # Pod::Simple and therefore doesn't work as a regular method call, but all it 52 # does is call output_code with the line. 53 sub handle_code { 54 my ($line, $number, $parser) = @_; 55 $parser->output_code ($line . "\n"); 56 } 57 58 # Initialize the object and set various Pod::Simple options that we need. 59 # Here, we also process any additional options passed to the constructor or 60 # set up defaults if none were given. Note that all internal object keys are 61 # in all-caps, reserving all lower-case object keys for Pod::Simple and user 62 # arguments. 63 sub new { 64 my $class = shift; 65 my $self = $class->SUPER::new; 66 67 # Tell Pod::Simple to handle S<> by automatically inserting . 68 $self->nbsp_for_S (1); 69 70 # Tell Pod::Simple to keep whitespace whenever possible. 71 if ($self->can ('preserve_whitespace')) { 72 $self->preserve_whitespace (1); 73 } else { 74 $self->fullstop_space_harden (1); 75 } 76 77 # The =for and =begin targets that we accept. 78 $self->accept_targets (qw/text TEXT/); 79 80 # Ensure that contiguous blocks of code are merged together. Otherwise, 81 # some of the guesswork heuristics don't work right. 82 $self->merge_text (1); 83 84 # Pod::Simple doesn't do anything useful with our arguments, but we want 85 # to put them in our object as hash keys and values. This could cause 86 # problems if we ever clash with Pod::Simple's own internal class 87 # variables. 88 my %opts = @_; 89 my @opts = map { ("opt_$_", $opts{$_}) } keys %opts; 90 %$self = (%$self, @opts); 91 92 # Initialize various things from our parameters. 93 $$self{opt_alt} = 0 unless defined $$self{opt_alt}; 94 $$self{opt_indent} = 4 unless defined $$self{opt_indent}; 95 $$self{opt_margin} = 0 unless defined $$self{opt_margin}; 96 $$self{opt_loose} = 0 unless defined $$self{opt_loose}; 97 $$self{opt_sentence} = 0 unless defined $$self{opt_sentence}; 98 $$self{opt_width} = 76 unless defined $$self{opt_width}; 99 100 # Figure out what quotes we'll be using for C<> text. 101 $$self{opt_quotes} ||= '"'; 102 if ($$self{opt_quotes} eq 'none') { 103 $$self{LQUOTE} = $$self{RQUOTE} = ''; 104 } elsif (length ($$self{opt_quotes}) == 1) { 105 $$self{LQUOTE} = $$self{RQUOTE} = $$self{opt_quotes}; 106 } elsif ($$self{opt_quotes} =~ /^(.)(.)$/ 107 || $$self{opt_quotes} =~ /^(..)(..)$/) { 108 $$self{LQUOTE} = $1; 109 $$self{RQUOTE} = $2; 110 } else { 111 croak qq(Invalid quote specification "$$self{opt_quotes}"); 112 } 113 114 # If requested, do something with the non-POD text. 115 $self->code_handler (\&handle_code) if $$self{opt_code}; 116 117 # Return the created object. 118 return $self; 119 } 120 121 ############################################################################## 122 # Core parsing 123 ############################################################################## 124 125 # This is the glue that connects the code below with Pod::Simple itself. The 126 # goal is to convert the event stream coming from the POD parser into method 127 # calls to handlers once the complete content of a tag has been seen. Each 128 # paragraph or POD command will have textual content associated with it, and 129 # as soon as all of a paragraph or POD command has been seen, that content 130 # will be passed in to the corresponding method for handling that type of 131 # object. The exceptions are handlers for lists, which have opening tag 132 # handlers and closing tag handlers that will be called right away. 133 # 134 # The internal hash key PENDING is used to store the contents of a tag until 135 # all of it has been seen. It holds a stack of open tags, each one 136 # represented by a tuple of the attributes hash for the tag and the contents 137 # of the tag. 138 139 # Add a block of text to the contents of the current node, formatting it 140 # according to the current formatting instructions as we do. 141 sub _handle_text { 142 my ($self, $text) = @_; 143 my $tag = $$self{PENDING}[-1]; 144 $$tag[1] .= $text; 145 } 146 147 # Given an element name, get the corresponding method name. 148 sub method_for_element { 149 my ($self, $element) = @_; 150 $element =~ tr/-/_/; 151 $element =~ tr/A-Z/a-z/; 152 $element =~ tr/_a-z0-9//cd; 153 return $element; 154 } 155 156 # Handle the start of a new element. If cmd_element is defined, assume that 157 # we need to collect the entire tree for this element before passing it to the 158 # element method, and create a new tree into which we'll collect blocks of 159 # text and nested elements. Otherwise, if start_element is defined, call it. 160 sub _handle_element_start { 161 my ($self, $element, $attrs) = @_; 162 my $method = $self->method_for_element ($element); 163 164 # If we have a command handler, we need to accumulate the contents of the 165 # tag before calling it. 166 if ($self->can ("cmd_$method")) { 167 push (@{ $$self{PENDING} }, [ $attrs, '' ]); 168 } elsif ($self->can ("start_$method")) { 169 my $method = 'start_' . $method; 170 $self->$method ($attrs, ''); 171 } 172 } 173 174 # Handle the end of an element. If we had a cmd_ method for this element, 175 # this is where we pass along the text that we've accumulated. Otherwise, if 176 # we have an end_ method for the element, call that. 177 sub _handle_element_end { 178 my ($self, $element) = @_; 179 my $method = $self->method_for_element ($element); 180 181 # If we have a command handler, pull off the pending text and pass it to 182 # the handler along with the saved attribute hash. 183 if ($self->can ("cmd_$method")) { 184 my $tag = pop @{ $$self{PENDING} }; 185 my $method = 'cmd_' . $method; 186 my $text = $self->$method (@$tag); 187 if (defined $text) { 188 if (@{ $$self{PENDING} } > 1) { 189 $$self{PENDING}[-1][1] .= $text; 190 } else { 191 $self->output ($text); 192 } 193 } 194 } elsif ($self->can ("end_$method")) { 195 my $method = 'end_' . $method; 196 $self->$method (); 197 } 198 } 199 200 ############################################################################## 201 # Output formatting 202 ############################################################################## 203 204 # Wrap a line, indenting by the current left margin. We can't use Text::Wrap 205 # because it plays games with tabs. We can't use formline, even though we'd 206 # really like to, because it screws up non-printing characters. So we have to 207 # do the wrapping ourselves. 208 sub wrap { 209 my $self = shift; 210 local $_ = shift; 211 my $output = ''; 212 my $spaces = ' ' x $$self{MARGIN}; 213 my $width = $$self{opt_width} - $$self{MARGIN}; 214 while (length > $width) { 215 if (s/^([^\n]{0,$width})\s+// || s/^([^\n]{$width})//) { 216 $output .= $spaces . $1 . "\n"; 217 } else { 218 last; 219 } 220 } 221 $output .= $spaces . $_; 222 $output =~ s/\s+$/\n\n/; 223 return $output; 224 } 225 226 # Reformat a paragraph of text for the current margin. Takes the text to 227 # reformat and returns the formatted text. 228 sub reformat { 229 my $self = shift; 230 local $_ = shift; 231 232 # If we're trying to preserve two spaces after sentences, do some munging 233 # to support that. Otherwise, smash all repeated whitespace. 234 if ($$self{opt_sentence}) { 235 s/ +$//mg; 236 s/\.\n/. \n/g; 237 s/\n/ /g; 238 s/ +/ /g; 239 } else { 240 s/\s+/ /g; 241 } 242 return $self->wrap ($_); 243 } 244 245 # Output text to the output device. 246 sub output { 247 my ($self, $text) = @_; 248 $text =~ tr/\240\255/ /d; 249 print { $$self{output_fh} } $text; 250 } 251 252 # Output a block of code (something that isn't part of the POD text). Called 253 # by preprocess_paragraph only if we were given the code option. Exists here 254 # only so that it can be overridden by subclasses. 255 sub output_code { $_[0]->output ($_[1]) } 256 257 ############################################################################## 258 # Document initialization 259 ############################################################################## 260 261 # Set up various things that have to be initialized on a per-document basis. 262 sub start_document { 263 my $self = shift; 264 my $margin = $$self{opt_indent} + $$self{opt_margin}; 265 266 # Initialize a few per-document variables. 267 $$self{INDENTS} = []; # Stack of indentations. 268 $$self{MARGIN} = $margin; # Default left margin. 269 $$self{PENDING} = [[]]; # Pending output. 270 271 return ''; 272 } 273 274 ############################################################################## 275 # Text blocks 276 ############################################################################## 277 278 # This method is called whenever an =item command is complete (in other words, 279 # we've seen its associated paragraph or know for certain that it doesn't have 280 # one). It gets the paragraph associated with the item as an argument. If 281 # that argument is empty, just output the item tag; if it contains a newline, 282 # output the item tag followed by the newline. Otherwise, see if there's 283 # enough room for us to output the item tag in the margin of the text or if we 284 # have to put it on a separate line. 285 sub item { 286 my ($self, $text) = @_; 287 my $tag = $$self{ITEM}; 288 unless (defined $tag) { 289 carp "Item called without tag"; 290 return; 291 } 292 undef $$self{ITEM}; 293 294 # Calculate the indentation and margin. $fits is set to true if the tag 295 # will fit into the margin of the paragraph given our indentation level. 296 my $indent = $$self{INDENTS}[-1]; 297 $indent = $$self{opt_indent} unless defined $indent; 298 my $margin = ' ' x $$self{opt_margin}; 299 my $fits = ($$self{MARGIN} - $indent >= length ($tag) + 1); 300 301 # If the tag doesn't fit, or if we have no associated text, print out the 302 # tag separately. Otherwise, put the tag in the margin of the paragraph. 303 if (!$text || $text =~ /^\s+$/ || !$fits) { 304 my $realindent = $$self{MARGIN}; 305 $$self{MARGIN} = $indent; 306 my $output = $self->reformat ($tag); 307 $output =~ s/^$margin /$margin:/ if ($$self{opt_alt} && $indent > 0); 308 $output =~ s/\n*$/\n/; 309 310 # If the text is just whitespace, we have an empty item paragraph; 311 # this can result from =over/=item/=back without any intermixed 312 # paragraphs. Insert some whitespace to keep the =item from merging 313 # into the next paragraph. 314 $output .= "\n" if $text && $text =~ /^\s*$/; 315 316 $self->output ($output); 317 $$self{MARGIN} = $realindent; 318 $self->output ($self->reformat ($text)) if ($text && $text =~ /\S/); 319 } else { 320 my $space = ' ' x $indent; 321 $space =~ s/^$margin /$margin:/ if $$self{opt_alt}; 322 $text = $self->reformat ($text); 323 $text =~ s/^$margin /$margin:/ if ($$self{opt_alt} && $indent > 0); 324 my $tagspace = ' ' x length $tag; 325 $text =~ s/^($space)$tagspace/$1$tag/ or warn "Bizarre space in item"; 326 $self->output ($text); 327 } 328 } 329 330 # Handle a basic block of text. The only tricky thing here is that if there 331 # is a pending item tag, we need to format this as an item paragraph. 332 sub cmd_para { 333 my ($self, $attrs, $text) = @_; 334 $text =~ s/\s+$/\n/; 335 if (defined $$self{ITEM}) { 336 $self->item ($text . "\n"); 337 } else { 338 $self->output ($self->reformat ($text . "\n")); 339 } 340 return ''; 341 } 342 343 # Handle a verbatim paragraph. Just print it out, but indent it according to 344 # our margin. 345 sub cmd_verbatim { 346 my ($self, $attrs, $text) = @_; 347 $self->item if defined $$self{ITEM}; 348 return if $text =~ /^\s*$/; 349 $text =~ s/^(\n*)(\s*\S+)/$1 . (' ' x $$self{MARGIN}) . $2/gme; 350 $text =~ s/\s*$/\n\n/; 351 $self->output ($text); 352 return ''; 353 } 354 355 # Handle literal text (produced by =for and similar constructs). Just output 356 # it with the minimum of changes. 357 sub cmd_data { 358 my ($self, $attrs, $text) = @_; 359 $text =~ s/^\n+//; 360 $text =~ s/\n{0,2}$/\n/; 361 $self->output ($text); 362 return ''; 363 } 364 365 ############################################################################## 366 # Headings 367 ############################################################################## 368 369 # The common code for handling all headers. Takes the header text, the 370 # indentation, and the surrounding marker for the alt formatting method. 371 sub heading { 372 my ($self, $text, $indent, $marker) = @_; 373 $self->item ("\n\n") if defined $$self{ITEM}; 374 $text =~ s/\s+$//; 375 if ($$self{opt_alt}) { 376 my $closemark = reverse (split (//, $marker)); 377 my $margin = ' ' x $$self{opt_margin}; 378 $self->output ("\n" . "$margin$marker $text $closemark" . "\n\n"); 379 } else { 380 $text .= "\n" if $$self{opt_loose}; 381 my $margin = ' ' x ($$self{opt_margin} + $indent); 382 $self->output ($margin . $text . "\n"); 383 } 384 return ''; 385 } 386 387 # First level heading. 388 sub cmd_head1 { 389 my ($self, $attrs, $text) = @_; 390 $self->heading ($text, 0, '===='); 391 } 392 393 # Second level heading. 394 sub cmd_head2 { 395 my ($self, $attrs, $text) = @_; 396 $self->heading ($text, $$self{opt_indent} / 2, '== '); 397 } 398 399 # Third level heading. 400 sub cmd_head3 { 401 my ($self, $attrs, $text) = @_; 402 $self->heading ($text, $$self{opt_indent} * 2 / 3 + 0.5, '= '); 403 } 404 405 # Fourth level heading. 406 sub cmd_head4 { 407 my ($self, $attrs, $text) = @_; 408 $self->heading ($text, $$self{opt_indent} * 3 / 4 + 0.5, '- '); 409 } 410 411 ############################################################################## 412 # List handling 413 ############################################################################## 414 415 # Handle the beginning of an =over block. Takes the type of the block as the 416 # first argument, and then the attr hash. This is called by the handlers for 417 # the four different types of lists (bullet, number, text, and block). 418 sub over_common_start { 419 my ($self, $attrs) = @_; 420 $self->item ("\n\n") if defined $$self{ITEM}; 421 422 # Find the indentation level. 423 my $indent = $$attrs{indent}; 424 unless (defined ($indent) && $indent =~ /^\s*[-+]?\d{1,4}\s*$/) { 425 $indent = $$self{opt_indent}; 426 } 427 428 # Add this to our stack of indents and increase our current margin. 429 push (@{ $$self{INDENTS} }, $$self{MARGIN}); 430 $$self{MARGIN} += ($indent + 0); 431 return ''; 432 } 433 434 # End an =over block. Takes no options other than the class pointer. Output 435 # any pending items and then pop one level of indentation. 436 sub over_common_end { 437 my ($self) = @_; 438 $self->item ("\n\n") if defined $$self{ITEM}; 439 $$self{MARGIN} = pop @{ $$self{INDENTS} }; 440 return ''; 441 } 442 443 # Dispatch the start and end calls as appropriate. 444 sub start_over_bullet { $_[0]->over_common_start ($_[1]) } 445 sub start_over_number { $_[0]->over_common_start ($_[1]) } 446 sub start_over_text { $_[0]->over_common_start ($_[1]) } 447 sub start_over_block { $_[0]->over_common_start ($_[1]) } 448 sub end_over_bullet { $_[0]->over_common_end } 449 sub end_over_number { $_[0]->over_common_end } 450 sub end_over_text { $_[0]->over_common_end } 451 sub end_over_block { $_[0]->over_common_end } 452 453 # The common handler for all item commands. Takes the type of the item, the 454 # attributes, and then the text of the item. 455 sub item_common { 456 my ($self, $type, $attrs, $text) = @_; 457 $self->item if defined $$self{ITEM}; 458 459 # Clean up the text. We want to end up with two variables, one ($text) 460 # which contains any body text after taking out the item portion, and 461 # another ($item) which contains the actual item text. Note the use of 462 # the internal Pod::Simple attribute here; that's a potential land mine. 463 $text =~ s/\s+$//; 464 my ($item, $index); 465 if ($type eq 'bullet') { 466 $item = '*'; 467 } elsif ($type eq 'number') { 468 $item = $$attrs{'~orig_content'}; 469 } else { 470 $item = $text; 471 $item =~ s/\s*\n\s*/ /g; 472 $text = ''; 473 } 474 $$self{ITEM} = $item; 475 476 # If body text for this item was included, go ahead and output that now. 477 if ($text) { 478 $text =~ s/\s*$/\n/; 479 $self->item ($text); 480 } 481 return ''; 482 } 483 484 # Dispatch the item commands to the appropriate place. 485 sub cmd_item_bullet { my $self = shift; $self->item_common ('bullet', @_) } 486 sub cmd_item_number { my $self = shift; $self->item_common ('number', @_) } 487 sub cmd_item_text { my $self = shift; $self->item_common ('text', @_) } 488 sub cmd_item_block { my $self = shift; $self->item_common ('block', @_) } 489 490 ############################################################################## 491 # Formatting codes 492 ############################################################################## 493 494 # The simple ones. 495 sub cmd_b { return $_[0]{alt} ? "``$_[2]''" : $_[2] } 496 sub cmd_f { return $_[0]{alt} ? "\"$_[2]\"" : $_[2] } 497 sub cmd_i { return '*' . $_[2] . '*' } 498 sub cmd_x { return '' } 499 500 # Apply a whole bunch of messy heuristics to not quote things that don't 501 # benefit from being quoted. These originally come from Barrie Slaymaker and 502 # largely duplicate code in Pod::Man. 503 sub cmd_c { 504 my ($self, $attrs, $text) = @_; 505 506 # A regex that matches the portion of a variable reference that's the 507 # array or hash index, separated out just because we want to use it in 508 # several places in the following regex. 509 my $index = '(?: \[.*\] | \{.*\} )?'; 510 511 # Check for things that we don't want to quote, and if we find any of 512 # them, return the string with just a font change and no quoting. 513 $text =~ m{ 514 ^\s* 515 (?: 516 ( [\'\`\"] ) .* \1 # already quoted 517 | \` .* \' # `quoted' 518 | \$+ [\#^]? \S $index # special ($^Foo, $") 519 | [\$\@%&*]+ \#? [:\'\w]+ $index # plain var or func 520 | [\$\@%&*]* [:\'\w]+ (?: -> )? \(\s*[^\s,]\s*\) # 0/1-arg func call 521 | [+-]? ( \d[\d.]* | \.\d+ ) (?: [eE][+-]?\d+ )? # a number 522 | 0x [a-fA-F\d]+ # a hex constant 523 ) 524 \s*\z 525 }xo && return $text; 526 527 # If we didn't return, go ahead and quote the text. 528 return $$self{opt_alt} 529 ? "``$text''" 530 : "$$self{LQUOTE}$text$$self{RQUOTE}"; 531 } 532 533 # Links reduce to the text that we're given, wrapped in angle brackets if it's 534 # a URL. 535 sub cmd_l { 536 my ($self, $attrs, $text) = @_; 537 return $$attrs{type} eq 'url' ? "<$text>" : $text; 538 } 539 540 ############################################################################## 541 # Backwards compatibility 542 ############################################################################## 543 544 # The old Pod::Text module did everything in a pod2text() function. This 545 # tries to provide the same interface for legacy applications. 546 sub pod2text { 547 my @args; 548 549 # This is really ugly; I hate doing option parsing in the middle of a 550 # module. But the old Pod::Text module supported passing flags to its 551 # entry function, so handle -a and -<number>. 552 while ($_[0] =~ /^-/) { 553 my $flag = shift; 554 if ($flag eq '-a') { push (@args, alt => 1) } 555 elsif ($flag =~ /^-(\d+)$/) { push (@args, width => $1) } 556 else { 557 unshift (@_, $flag); 558 last; 559 } 560 } 561 562 # Now that we know what arguments we're using, create the parser. 563 my $parser = Pod::Text->new (@args); 564 565 # If two arguments were given, the second argument is going to be a file 566 # handle. That means we want to call parse_from_filehandle(), which means 567 # we need to turn the first argument into a file handle. Magic open will 568 # handle the <&STDIN case automagically. 569 if (defined $_[1]) { 570 my @fhs = @_; 571 local *IN; 572 unless (open (IN, $fhs[0])) { 573 croak ("Can't open $fhs[0] for reading: $!\n"); 574 return; 575 } 576 $fhs[0] = \*IN; 577 $parser->output_fh ($fhs[1]); 578 my $retval = $parser->parse_file ($fhs[0]); 579 my $fh = $parser->output_fh (); 580 close $fh; 581 return $retval; 582 } else { 583 return $parser->parse_file (@_); 584 } 585 } 586 587 # Reset the underlying Pod::Simple object between calls to parse_from_file so 588 # that the same object can be reused to convert multiple pages. 589 sub parse_from_file { 590 my $self = shift; 591 $self->reinit; 592 593 # Fake the old cutting option to Pod::Parser. This fiddings with internal 594 # Pod::Simple state and is quite ugly; we need a better approach. 595 if (ref ($_[0]) eq 'HASH') { 596 my $opts = shift @_; 597 if (defined ($$opts{-cutting}) && !$$opts{-cutting}) { 598 $$self{in_pod} = 1; 599 $$self{last_was_blank} = 1; 600 } 601 } 602 603 # Do the work. 604 my $retval = $self->Pod::Simple::parse_from_file (@_); 605 606 # Flush output, since Pod::Simple doesn't do this. Ideally we should also 607 # close the file descriptor if we had to open one, but we can't easily 608 # figure this out. 609 my $fh = $self->output_fh (); 610 my $oldfh = select $fh; 611 my $oldflush = $|; 612 $| = 1; 613 print $fh ''; 614 $| = $oldflush; 615 select $oldfh; 616 return $retval; 617 } 618 619 # Pod::Simple failed to provide this backward compatibility function, so 620 # implement it ourselves. File handles are one of the inputs that 621 # parse_from_file supports. 622 sub parse_from_filehandle { 623 my $self = shift; 624 $self->parse_from_file (@_); 625 } 626 627 ############################################################################## 628 # Module return value and documentation 629 ############################################################################## 630 631 1; 632 __END__ 633 634 =head1 NAME 635 636 Pod::Text - Convert POD data to formatted ASCII text 637 638 =head1 SYNOPSIS 639 640 use Pod::Text; 641 my $parser = Pod::Text->new (sentence => 0, width => 78); 642 643 # Read POD from STDIN and write to STDOUT. 644 $parser->parse_from_filehandle; 645 646 # Read POD from file.pod and write to file.txt. 647 $parser->parse_from_file ('file.pod', 'file.txt'); 648 649 =head1 DESCRIPTION 650 651 Pod::Text is a module that can convert documentation in the POD format (the 652 preferred language for documenting Perl) into formatted ASCII. It uses no 653 special formatting controls or codes whatsoever, and its output is therefore 654 suitable for nearly any device. 655 656 As a derived class from Pod::Simple, Pod::Text supports the same methods and 657 interfaces. See L<Pod::Simple> for all the details; briefly, one creates a 658 new parser with C<< Pod::Text->new() >> and then normally calls parse_file(). 659 660 new() can take options, in the form of key/value pairs, that control the 661 behavior of the parser. The currently recognized options are: 662 663 =over 4 664 665 =item alt 666 667 If set to a true value, selects an alternate output format that, among other 668 things, uses a different heading style and marks C<=item> entries with a 669 colon in the left margin. Defaults to false. 670 671 =item code 672 673 If set to a true value, the non-POD parts of the input file will be included 674 in the output. Useful for viewing code documented with POD blocks with the 675 POD rendered and the code left intact. 676 677 =item indent 678 679 The number of spaces to indent regular text, and the default indentation for 680 C<=over> blocks. Defaults to 4. 681 682 =item loose 683 684 If set to a true value, a blank line is printed after a C<=head1> heading. 685 If set to false (the default), no blank line is printed after C<=head1>, 686 although one is still printed after C<=head2>. This is the default because 687 it's the expected formatting for manual pages; if you're formatting 688 arbitrary text documents, setting this to true may result in more pleasing 689 output. 690 691 =item margin 692 693 The width of the left margin in spaces. Defaults to 0. This is the margin 694 for all text, including headings, not the amount by which regular text is 695 indented; for the latter, see the I<indent> option. To set the right 696 margin, see the I<width> option. 697 698 =item quotes 699 700 Sets the quote marks used to surround CE<lt>> text. If the value is a 701 single character, it is used as both the left and right quote; if it is two 702 characters, the first character is used as the left quote and the second as 703 the right quoted; and if it is four characters, the first two are used as 704 the left quote and the second two as the right quote. 705 706 This may also be set to the special value C<none>, in which case no quote 707 marks are added around CE<lt>> text. 708 709 =item sentence 710 711 If set to a true value, Pod::Text will assume that each sentence ends in two 712 spaces, and will try to preserve that spacing. If set to false, all 713 consecutive whitespace in non-verbatim paragraphs is compressed into a 714 single space. Defaults to true. 715 716 =item width 717 718 The column at which to wrap text on the right-hand side. Defaults to 76. 719 720 =back 721 722 The standard Pod::Simple method parse_file() takes one argument, the file or 723 file handle to read from, and writes output to standard output unless that 724 has been changed with the output_fh() method. See L<Pod::Simple> for the 725 specific details and for other alternative interfaces. 726 727 =head1 DIAGNOSTICS 728 729 =over 4 730 731 =item Bizarre space in item 732 733 =item Item called without tag 734 735 (W) Something has gone wrong in internal C<=item> processing. These 736 messages indicate a bug in Pod::Text; you should never see them. 737 738 =item Can't open %s for reading: %s 739 740 (F) Pod::Text was invoked via the compatibility mode pod2text() interface 741 and the input file it was given could not be opened. 742 743 =item Invalid quote specification "%s" 744 745 (F) The quote specification given (the quotes option to the constructor) was 746 invalid. A quote specification must be one, two, or four characters long. 747 748 =back 749 750 =head1 NOTES 751 752 This is a replacement for an earlier Pod::Text module written by Tom 753 Christiansen. It has a revamped interface, since it now uses Pod::Simple, 754 but an interface roughly compatible with the old Pod::Text::pod2text() 755 function is still available. Please change to the new calling convention, 756 though. 757 758 The original Pod::Text contained code to do formatting via termcap 759 sequences, although it wasn't turned on by default and it was problematic to 760 get it to work at all. This rewrite doesn't even try to do that, but a 761 subclass of it does. Look for L<Pod::Text::Termcap>. 762 763 =head1 SEE ALSO 764 765 L<Pod::Simple>, L<Pod::Text::Termcap>, L<pod2text(1)> 766 767 The current version of this module is always available from its web site at 768 L<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the 769 Perl core distribution as of 5.6.0. 770 771 =head1 AUTHOR 772 773 Russ Allbery <rra@stanford.edu>, based I<very> heavily on the original 774 Pod::Text by Tom Christiansen <tchrist@mox.perl.com> and its conversion to 775 Pod::Parser by Brad Appleton <bradapp@enteract.com>. Sean Burke's initial 776 conversion of Pod::Man to use Pod::Simple provided much-needed guidance on 777 how to use Pod::Simple. 778 779 =head1 COPYRIGHT AND LICENSE 780 781 Copyright 1999, 2000, 2001, 2002, 2004, 2006 Russ Allbery <rra@stanford.edu>. 782 783 This program is free software; you may redistribute it and/or modify it 784 under the same terms as Perl itself. 785 786 =cut
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Tue Mar 17 22:47:18 2015 | Cross-referenced by PHPXref 0.7.1 |