1 2=for comment 3This document is in Pod format. To read this, use a Pod formatter, 4like "perldoc perlpod". 5 6=head1 NAME 7X<POD> X<plain old documentation> 8 9perlpod - the Plain Old Documentation format 10 11=head1 DESCRIPTION 12 13Pod is a simple-to-use markup language used for writing documentation 14for Perl, Perl programs, and Perl modules. 15 16Translators are available for converting Pod to various formats 17like plain text, HTML, man pages, and more. 18 19Pod markup consists of three basic kinds of paragraphs: 20L<ordinary|/"Ordinary Paragraph">, 21L<verbatim|/"Verbatim Paragraph">, and 22L<command|/"Command Paragraph">. 23 24 25=head2 Ordinary Paragraph 26X<POD, ordinary paragraph> 27 28Most paragraphs in your documentation will be ordinary blocks 29of text, like this one. You can simply type in your text without 30any markup whatsoever, and with just a blank line before and 31after. When it gets formatted, it will undergo minimal formatting, 32like being rewrapped, probably put into a proportionally spaced 33font, and maybe even justified. 34 35You can use formatting codes in ordinary paragraphs, for B<bold>, 36I<italic>, C<code-style>, L<hyperlinks|perlfaq>, and more. Such 37codes are explained in the "L<Formatting Codes|/"Formatting Codes">" 38section, below. 39 40 41=head2 Verbatim Paragraph 42X<POD, verbatim paragraph> X<verbatim> 43 44Verbatim paragraphs are usually used for presenting a codeblock or 45other text which does not require any special parsing or formatting, 46and which shouldn't be wrapped. 47 48A verbatim paragraph is distinguished by having its first character 49be a space or a tab. (And commonly, all its lines begin with spaces 50and/or tabs.) It should be reproduced exactly, with tabs assumed to 51be on 8-column boundaries. There are no special formatting codes, 52so you can't italicize or anything like that. A \ means \, and 53nothing else. 54 55 56=head2 Command Paragraph 57X<POD, command> 58 59A command paragraph is used for special treatment of whole chunks 60of text, usually as headings or parts of lists. 61 62All command paragraphs (which are typically only one line long) start 63with "=", followed by an identifier, followed by arbitrary text that 64the command can use however it pleases. Currently recognized commands 65are 66 67 =pod 68 =head1 Heading Text 69 =head2 Heading Text 70 =head3 Heading Text 71 =head4 Heading Text 72 =over indentlevel 73 =item stuff 74 =back 75 =begin format 76 =end format 77 =for format text... 78 =encoding type 79 =cut 80 81To explain them each in detail: 82 83=over 84 85=item C<=head1 I<Heading Text>> 86X<=head1> X<=head2> X<=head3> X<=head4> 87X<head1> X<head2> X<head3> X<head4> 88 89=item C<=head2 I<Heading Text>> 90 91=item C<=head3 I<Heading Text>> 92 93=item C<=head4 I<Heading Text>> 94 95Head1 through head4 produce headings, head1 being the highest 96level. The text in the rest of this paragraph is the content of the 97heading. For example: 98 99 =head2 Object Attributes 100 101The text "Object Attributes" comprises the heading there. 102The text in these heading commands can use formatting codes, as seen here: 103 104 =head2 Possible Values for C<$/> 105 106Such commands are explained in the 107"L<Formatting Codes|/"Formatting Codes">" section, below. 108 109=item C<=over I<indentlevel>> 110X<=over> X<=item> X<=back> X<over> X<item> X<back> 111 112=item C<=item I<stuff...>> 113 114=item C<=back> 115 116Item, over, and back require a little more explanation: "=over" starts 117a region specifically for the generation of a list using "=item" 118commands, or for indenting (groups of) normal paragraphs. At the end 119of your list, use "=back" to end it. The I<indentlevel> option to 120"=over" indicates how far over to indent, generally in ems (where 121one em is the width of an "M" in the document's base font) or roughly 122comparable units; if there is no I<indentlevel> option, it defaults 123to four. (And some formatters may just ignore whatever I<indentlevel> 124you provide.) In the I<stuff> in C<=item I<stuff...>>, you may 125use formatting codes, as seen here: 126 127 =item Using C<$|> to Control Buffering 128 129Such commands are explained in the 130"L<Formatting Codes|/"Formatting Codes">" section, below. 131 132Note also that there are some basic rules to using "=over" ... 133"=back" regions: 134 135=over 136 137=item * 138 139Don't use "=item"s outside of an "=over" ... "=back" region. 140 141=item * 142 143The first thing after the "=over" command should be an "=item", unless 144there aren't going to be any items at all in this "=over" ... "=back" 145region. 146 147=item * 148 149Don't put "=headI<n>" commands inside an "=over" ... "=back" region. 150 151=item * 152 153And perhaps most importantly, keep the items consistent: either use 154"=item *" for all of them, to produce bullets; or use "=item 1.", 155"=item 2.", etc., to produce numbered lists; or use "=item foo", 156"=item bar", etc.--namely, things that look nothing like bullets or 157numbers. (If you have a list that contains both: 1) things that don't 158look like bullets nor numbers, plus 2) things that do, you should 159preface the bullet- or number-like items with C<ZE<lt>E<gt>>. See 160L<ZE<lt>E<gt>|/ZE<lt>E<gt> -- a null (zero-effect) formatting code> 161below for an example.) 162 163If you start with bullets or numbers, stick with them, as 164formatters use the first "=item" type to decide how to format the 165list. 166 167=back 168 169=item C<=cut> 170X<=cut> X<cut> 171 172To end a Pod block, use a blank line, 173then a line beginning with "=cut", and a blank 174line after it. This lets Perl (and the Pod formatter) know that 175this is where Perl code is resuming. (The blank line before the "=cut" 176is not technically necessary, but many older Pod processors require it.) 177 178=item C<=pod> 179X<=pod> X<pod> 180 181The "=pod" command by itself doesn't do much of anything, but it 182signals to Perl (and Pod formatters) that a Pod block starts here. A 183Pod block starts with I<any> command paragraph, so a "=pod" command is 184usually used just when you want to start a Pod block with an ordinary 185paragraph or a verbatim paragraph. For example: 186 187 =item stuff() 188 189 This function does stuff. 190 191 =cut 192 193 sub stuff { 194 ... 195 } 196 197 =pod 198 199 Remember to check its return value, as in: 200 201 stuff() || die "Couldn't do stuff!"; 202 203 =cut 204 205=item C<=begin I<formatname>> 206X<=begin> X<=end> X<=for> X<begin> X<end> X<for> 207 208=item C<=end I<formatname>> 209 210=item C<=for I<formatname> I<text...>> 211 212For, begin, and end will let you have regions of text/code/data that 213are not generally interpreted as normal Pod text, but are passed 214directly to particular formatters, or are otherwise special. A 215formatter that can use that format will use the region, otherwise it 216will be completely ignored. 217 218A command "=begin I<formatname>", some paragraphs, and a 219command "=end I<formatname>", mean that the text/data in between 220is meant for formatters that understand the special format 221called I<formatname>. For example, 222 223 =begin html 224 225 <hr> <img src="thang.png"> 226 <p> This is a raw HTML paragraph </p> 227 228 =end html 229 230The command "=for I<formatname> I<text...>" 231specifies that the remainder of just this paragraph (starting 232right after I<formatname>) is in that special format. 233 234 =for html <hr> <img src="thang.png"> 235 <p> This is a raw HTML paragraph </p> 236 237This means the same thing as the above "=begin html" ... "=end html" 238region. 239 240That is, with "=for", you can have only one paragraph's worth 241of text (i.e., the text in "=foo targetname text..."), but with 242"=begin targetname" ... "=end targetname", you can have any amount 243of stuff in between. (Note that there still must be a blank line 244after the "=begin" command and a blank line before the "=end" 245command.) 246 247Here are some examples of how to use these: 248 249 =begin html 250 251 <br>Figure 1.<br><IMG SRC="figure1.png"><br> 252 253 =end html 254 255 =begin text 256 257 --------------- 258 | foo | 259 | bar | 260 --------------- 261 262 ^^^^ Figure 1. ^^^^ 263 264 =end text 265 266Some format names that formatters currently are known to accept 267include "roff", "man", "latex", "tex", "text", and "html". (Some 268formatters will treat some of these as synonyms.) 269 270A format name of "comment" is common for just making notes (presumably 271to yourself) that won't appear in any formatted version of the Pod 272document: 273 274 =for comment 275 Make sure that all the available options are documented! 276 277Some I<formatnames> will require a leading colon (as in 278C<"=for :formatname">, or 279C<"=begin :formatname" ... "=end :formatname">), 280to signal that the text is not raw data, but instead I<is> Pod text 281(i.e., possibly containing formatting codes) that's just not for 282normal formatting (e.g., may not be a normal-use paragraph, but might 283be for formatting as a footnote). 284 285=item C<=encoding I<encodingname>> 286X<=encoding> X<encoding> 287 288This command is used for declaring the encoding of a document. Most 289users won't need this; but if your encoding isn't US-ASCII, 290then put a C<=encoding I<encodingname>> command very early in the document so 291that pod formatters will know how to decode the document. For 292I<encodingname>, use a name recognized by the L<Encode::Supported> 293module. Some pod formatters may try to guess between a Latin-1 or 294CP-1252 versus 295UTF-8 encoding, but they may guess wrong. It's best to be explicit if 296you use anything besides strict ASCII. Examples: 297 298 =encoding latin1 299 300 =encoding utf8 301 302 =encoding koi8-r 303 304 =encoding ShiftJIS 305 306 =encoding big5 307 308C<=encoding> affects the whole document, and must occur only once. 309 310=back 311 312And don't forget, all commands but C<=encoding> last up 313until the end of its I<paragraph>, not its line. So in the 314examples below, you can see that every command needs the blank 315line after it, to end its paragraph. (And some older Pod translators 316may require the C<=encoding> line to have a following blank line as 317well, even though it should be legal to omit.) 318 319Some examples of lists include: 320 321 =over 322 323 =item * 324 325 First item 326 327 =item * 328 329 Second item 330 331 =back 332 333 =over 334 335 =item Foo() 336 337 Description of Foo function 338 339 =item Bar() 340 341 Description of Bar function 342 343 =back 344 345 346=head2 Formatting Codes 347X<POD, formatting code> X<formatting code> 348X<POD, interior sequence> X<interior sequence> 349 350In ordinary paragraphs and in some command paragraphs, various 351formatting codes (a.k.a. "interior sequences") can be used: 352 353=for comment 354 "interior sequences" is such an opaque term. 355 Prefer "formatting codes" instead. 356 357=over 358 359=item C<IE<lt>textE<gt>> -- italic text 360X<I> X<< IZ<><> >> X<POD, formatting code, italic> X<italic> 361 362Used for emphasis ("C<be IE<lt>careful!E<gt>>") and parameters 363("C<redo IE<lt>LABELE<gt>>") 364 365=item C<BE<lt>textE<gt>> -- bold text 366X<B> X<< BZ<><> >> X<POD, formatting code, bold> X<bold> 367 368Used for switches ("C<perl's BE<lt>-nE<gt> switch>"), programs 369("C<some systems provide a BE<lt>chfnE<gt> for that>"), 370emphasis ("C<be BE<lt>careful!E<gt>>"), and so on 371("C<and that feature is known as BE<lt>autovivificationE<gt>>"). 372 373=item C<CE<lt>codeE<gt>> -- code text 374X<C> X<< CZ<><> >> X<POD, formatting code, code> X<code> 375 376Renders code in a typewriter font, or gives some other indication that 377this represents program text ("C<CE<lt>gmtime($^T)E<gt>>") or some other 378form of computerese ("C<CE<lt>drwxr-xr-xE<gt>>"). 379 380=item C<LE<lt>nameE<gt>> -- a hyperlink 381X<L> X<< LZ<><> >> X<POD, formatting code, hyperlink> X<hyperlink> 382 383There are various syntaxes, listed below. In the syntaxes given, 384C<text>, C<name>, and C<section> cannot contain the characters 385'/' and '|'; and any '<' or '>' should be matched. 386 387=over 388 389=item * 390 391C<LE<lt>nameE<gt>> 392 393Link to a Perl manual page (e.g., C<LE<lt>Net::PingE<gt>>). Note 394that C<name> should not contain spaces. This syntax 395is also occasionally used for references to Unix man pages, as in 396C<LE<lt>crontab(5)E<gt>>. 397 398=item * 399 400C<LE<lt>name/"sec"E<gt>> or C<LE<lt>name/secE<gt>> 401 402Link to a section in other manual page. E.g., 403C<LE<lt>perlsyn/"For Loops"E<gt>> 404 405=item * 406 407C<LE<lt>/"sec"E<gt>> or C<LE<lt>/secE<gt>> 408 409Link to a section in this manual page. E.g., 410C<LE<lt>/"Object Methods"E<gt>> 411 412=back 413 414A section is started by the named heading or item. For 415example, C<LE<lt>perlvar/$.E<gt>> or C<LE<lt>perlvar/"$."E<gt>> both 416link to the section started by "C<=item $.>" in perlvar. And 417C<LE<lt>perlsyn/For LoopsE<gt>> or C<LE<lt>perlsyn/"For Loops"E<gt>> 418both link to the section started by "C<=head2 For Loops>" 419in perlsyn. 420 421To control what text is used for display, you 422use "C<LE<lt>text|...E<gt>>", as in: 423 424=over 425 426=item * 427 428C<LE<lt>text|nameE<gt>> 429 430Link this text to that manual page. E.g., 431C<LE<lt>Perl Error Messages|perldiagE<gt>> 432 433=item * 434 435C<LE<lt>text|name/"sec"E<gt>> or C<LE<lt>text|name/secE<gt>> 436 437Link this text to that section in that manual page. E.g., 438C<LE<lt>postfix "if"|perlsyn/"Statement Modifiers"E<gt>> 439 440=item * 441 442C<LE<lt>text|/"sec"E<gt>> or C<LE<lt>text|/secE<gt>> 443or C<LE<lt>text|"sec"E<gt>> 444 445Link this text to that section in this manual page. E.g., 446C<LE<lt>the various attributes|/"Member Data"E<gt>> 447 448=back 449 450Or you can link to a web page: 451 452=over 453 454=item * 455 456C<LE<lt>scheme:...E<gt>> 457 458C<LE<lt>text|scheme:...E<gt>> 459 460Links to an absolute URL. For example, C<LE<lt>http://www.perl.org/E<gt>> or 461C<LE<lt>The Perl Home Page|http://www.perl.org/E<gt>>. 462 463=back 464 465=item C<EE<lt>escapeE<gt>> -- a character escape 466X<E> X<< EZ<><> >> X<POD, formatting code, escape> X<escape> 467 468Very similar to HTML/XML C<&I<foo>;> "entity references": 469 470=over 471 472=item * 473 474C<EE<lt>ltE<gt>> -- a literal E<lt> (less than) 475 476=item * 477 478C<EE<lt>gtE<gt>> -- a literal E<gt> (greater than) 479 480=item * 481 482C<EE<lt>verbarE<gt>> -- a literal | (I<ver>tical I<bar>) 483 484=item * 485 486C<EE<lt>solE<gt>> -- a literal / (I<sol>idus) 487 488The above four are optional except in other formatting codes, 489notably C<LE<lt>...E<gt>>, and when preceded by a 490capital letter. 491 492=item * 493 494C<EE<lt>htmlnameE<gt>> 495 496Some non-numeric HTML entity name, such as C<EE<lt>eacuteE<gt>>, 497meaning the same thing as C<é> in HTML -- i.e., a lowercase 498e with an acute (/-shaped) accent. 499 500=item * 501 502C<EE<lt>numberE<gt>> 503 504The ASCII/Latin-1/Unicode character with that number. A 505leading "0x" means that I<number> is hex, as in 506C<EE<lt>0x201EE<gt>>. A leading "0" means that I<number> is octal, 507as in C<EE<lt>075E<gt>>. Otherwise I<number> is interpreted as being 508in decimal, as in C<EE<lt>181E<gt>>. 509 510Note that older Pod formatters might not recognize octal or 511hex numeric escapes, and that many formatters cannot reliably 512render characters above 255. (Some formatters may even have 513to use compromised renderings of Latin-1/CP-1252 characters, like 514rendering C<EE<lt>eacuteE<gt>> as just a plain "e".) 515 516=back 517 518=item C<FE<lt>filenameE<gt>> -- used for filenames 519X<F> X<< FZ<><> >> X<POD, formatting code, filename> X<filename> 520 521Typically displayed in italics. Example: "C<FE<lt>.cshrcE<gt>>" 522 523=item C<SE<lt>textE<gt>> -- text contains non-breaking spaces 524X<S> X<< SZ<><> >> X<POD, formatting code, non-breaking space> 525X<non-breaking space> 526 527This means that the words in I<text> should not be broken 528across lines. Example: S<C<SE<lt>$x ? $y : $zE<gt>>>. 529 530=item C<XE<lt>topic nameE<gt>> -- an index entry 531X<X> X<< XZ<><> >> X<POD, formatting code, index entry> X<index entry> 532 533This is ignored by most formatters, but some may use it for building 534indexes. It always renders as empty-string. 535Example: C<XE<lt>absolutizing relative URLsE<gt>> 536 537=item C<ZE<lt>E<gt>> -- a null (zero-effect) formatting code 538X<Z> X<< ZZ<><> >> X<POD, formatting code, null> X<null> 539 540This is rarely used. It's one way to get around using an 541EE<lt>...E<gt> code sometimes. For example, instead of 542"C<NEE<lt>ltE<gt>3>" (for "NE<lt>3") you could write 543"C<NZE<lt>E<gt>E<lt>3>" (the "ZE<lt>E<gt>" breaks up the "N" and 544the "E<lt>" so they can't be considered 545the part of a (fictitious) "NE<lt>...E<gt>" code). 546 547Another use is to indicate that I<stuff> in C<=item ZE<lt>E<gt>I<stuff...>> 548is not to be considered to be a bullet or number. For example, 549without the C<ZE<lt>E<gt>>, the line 550 551 =item Z<>500 Server error 552 553could possibly be parsed as an item in a numbered list when it isn't 554meant to be. 555 556Still another use is to maintain visual space between C<=item> lines. 557If you specify 558 559 =item foo 560 561 =item bar 562 563it will typically get rendered as 564 565 foo 566 bar 567 568That may be what you want, but if what you really want is 569 570 foo 571 572 bar 573 574you can use C<ZE<lt>E<gt>> to accomplish that 575 576 =item foo 577 578 Z<> 579 580 =item bar 581 582=for comment 583 This was formerly explained as a "zero-width character". But it in 584 most parser models, it parses to nothing at all, as opposed to parsing 585 as if it were a E<zwnj> or E<zwj>, which are REAL zero-width characters. 586 So "width" and "character" are exactly the wrong words. 587 588=back 589 590Most of the time, you will need only a single set of angle brackets to 591delimit the beginning and end of formatting codes. However, 592sometimes you will want to put a real right angle bracket (a 593greater-than sign, '>') inside of a formatting code. This is particularly 594common when using a formatting code to provide a different font-type for a 595snippet of code. As with all things in Perl, there is more than 596one way to do it. One way is to simply escape the closing bracket 597using an C<E> code: 598 599 C<$a E<lt>=E<gt> $b> 600 601This will produce: "C<$a E<lt>=E<gt> $b>" 602 603A more readable, and perhaps more "plain" way is to use an alternate 604set of delimiters that doesn't require a single ">" to be escaped. 605Doubled angle brackets ("<<" and ">>") may be used I<if and only if there is 606whitespace right after the opening delimiter and whitespace right 607before the closing delimiter!> For example, the following will 608do the trick: 609X<POD, formatting code, escaping with multiple brackets> 610 611 C<< $a <=> $b >> 612 613In fact, you can use as many repeated angle-brackets as you like so 614long as you have the same number of them in the opening and closing 615delimiters, and make sure that whitespace immediately follows the last 616'<' of the opening delimiter, and immediately precedes the first '>' 617of the closing delimiter. (The whitespace is ignored.) So the 618following will also work: 619X<POD, formatting code, escaping with multiple brackets> 620 621 C<<< $a <=> $b >>> 622 C<<<< $a <=> $b >>>> 623 624And they all mean exactly the same as this: 625 626 C<$a E<lt>=E<gt> $b> 627 628The multiple-bracket form does not affect the interpretation of the contents of 629the formatting code, only how it must end. That means that the examples above 630are also exactly the same as this: 631 632 C<< $a E<lt>=E<gt> $b >> 633 634As a further example, this means that if you wanted to put these bits of 635code in C<C> (code) style: 636 637 open(X, ">>thing.dat") || die $! 638 $foo->bar(); 639 640you could do it like so: 641 642 C<<< open(X, ">>thing.dat") || die $! >>> 643 C<< $foo->bar(); >> 644 645which is presumably easier to read than the old way: 646 647 C<open(X, "E<gt>E<gt>thing.dat") || die $!> 648 C<$foo-E<gt>bar();> 649 650This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man), 651and any other pod2xxx or Pod::Xxxx translators that use 652Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later. 653 654=head2 The Intent 655X<POD, intent of> 656 657The intent is simplicity of use, not power of expression. Paragraphs 658look like paragraphs (block format), so that they stand out 659visually, and so that I could run them through C<fmt> easily to reformat 660them (that's F7 in my version of B<vi>, or Esc Q in my version of 661B<emacs>). I wanted the translator to always leave the C<'> and C<`> and 662C<"> quotes alone, in verbatim mode, so I could slurp in a 663working program, shift it over four spaces, and have it print out, er, 664verbatim. And presumably in a monospace font. 665 666The Pod format is not necessarily sufficient for writing a book. Pod 667is just meant to be an idiot-proof common source for nroff, HTML, 668TeX, and other markup languages, as used for online 669documentation. Translators exist for B<pod2text>, B<pod2html>, 670B<pod2man> (that's for nroff(1) and troff(1)), B<pod2latex>, and 671B<pod2fm>. Various others are available in CPAN. 672 673 674=head2 Embedding Pods in Perl Modules 675X<POD, embedding> 676 677You can embed Pod documentation in your Perl modules and scripts. Start 678your documentation with an empty line, a "=head1" command at the 679beginning, and end it with a "=cut" command and an empty line. The 680B<perl> executable will ignore the Pod text. You can place a Pod 681statement where B<perl> expects the beginning of a new statement, but 682not within a statement, as that would result in an error. See any of 683the supplied library modules for examples. 684 685If you're going to put your Pod at the end of the file, and you're using 686an C<__END__> or C<__DATA__> cut mark, make sure to put an empty line there 687before the first Pod command. 688 689 __END__ 690 691 =head1 NAME 692 693 Time::Local - efficiently compute time from local and GMT time 694 695Without that empty line before the "=head1", many translators wouldn't 696have recognized the "=head1" as starting a Pod block. 697 698=head2 Hints for Writing Pod 699 700=over 701 702=item * 703X<podchecker> X<POD, validating> 704 705The B<podchecker> command is provided for checking Pod syntax for errors 706and warnings. For example, it checks for completely blank lines in 707Pod blocks and for unknown commands and formatting codes. You should 708still also pass your document through one or more translators and proofread 709the result, or print out the result and proofread that. Some of the 710problems found may be bugs in the translators, which you may or may not 711wish to work around. 712 713=item * 714 715If you're more familiar with writing in HTML than with writing in Pod, you 716can try your hand at writing documentation in simple HTML, and converting 717it to Pod with the experimental L<Pod::HTML2Pod|Pod::HTML2Pod> module, 718(available in CPAN), and looking at the resulting code. The experimental 719L<Pod::PXML|Pod::PXML> module in CPAN might also be useful. 720 721=item * 722 723Many older Pod translators require the lines before every Pod 724command and after every Pod command (including "=cut"!) to be a blank 725line. Having something like this: 726 727 # - - - - - - - - - - - - 728 =item $firecracker->boom() 729 730 This noisily detonates the firecracker object. 731 =cut 732 sub boom { 733 ... 734 735...will make such Pod translators completely fail to see the Pod block 736at all. 737 738Instead, have it like this: 739 740 # - - - - - - - - - - - - 741 742 =item $firecracker->boom() 743 744 This noisily detonates the firecracker object. 745 746 =cut 747 748 sub boom { 749 ... 750 751=item * 752 753Some older Pod translators require paragraphs (including command 754paragraphs like "=head2 Functions") to be separated by I<completely> 755empty lines. If you have an apparently empty line with some spaces 756on it, this might not count as a separator for those translators, and 757that could cause odd formatting. 758 759=item * 760 761Older translators might add wording around an LE<lt>E<gt> link, so that 762C<LE<lt>Foo::BarE<gt>> may become "the Foo::Bar manpage", for example. 763So you shouldn't write things like C<the LE<lt>fooE<gt> 764documentation>, if you want the translated document to read sensibly. 765Instead, write C<the LE<lt>Foo::Bar|Foo::BarE<gt> documentation> or 766C<LE<lt>the Foo::Bar documentation|Foo::BarE<gt>>, to control how the 767link comes out. 768 769=item * 770 771Going past the 70th column in a verbatim block might be ungracefully 772wrapped by some formatters. 773 774=back 775 776=head1 SEE ALSO 777 778L<perlpodspec>, L<perlsyn/"PODs: Embedded Documentation">, 779L<perlnewmod>, L<perldoc>, L<pod2html>, L<pod2man>, L<podchecker>. 780 781=head1 AUTHOR 782 783Larry Wall, Sean M. Burke 784 785=cut 786