[Summary view] [Print] [Text view]

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