home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl560.zip / pod / perlpod.pod < prev    next >
Text File  |  2000-03-17  |  10KB  |  317 lines

  1. =head1 NAME
  2.  
  3. perlpod - plain old documentation
  4.  
  5. =head1 DESCRIPTION
  6.  
  7. A pod-to-whatever translator reads a pod file paragraph by paragraph,
  8. and translates it to the appropriate output format.  There are
  9. three kinds of paragraphs:
  10. L<verbatim|/"Verbatim Paragraph">,
  11. L<command|/"Command Paragraph">, and
  12. L<ordinary text|/"Ordinary Block of Text">.
  13.  
  14. =head2 Verbatim Paragraph
  15.  
  16. A verbatim paragraph, distinguished by being indented (that is,
  17. it starts with space or tab).  It should be reproduced exactly,
  18. with tabs assumed to be on 8-column boundaries.  There are no
  19. special formatting escapes, so you can't italicize or anything
  20. like that.  A \ means \, and nothing else.
  21.  
  22. =head2 Command Paragraph
  23.  
  24. All command paragraphs start with "=", followed by an
  25. identifier, followed by arbitrary text that the command can
  26. use however it pleases.  Currently recognized commands are
  27.  
  28.     =head1 heading
  29.     =head2 heading
  30.     =item text
  31.     =over N
  32.     =back
  33.     =cut
  34.     =pod
  35.     =for X
  36.     =begin X
  37.     =end X
  38.  
  39. =over 4
  40.  
  41. =item =pod
  42.  
  43. =item =cut
  44.  
  45. The "=pod" directive does nothing beyond telling the compiler to lay
  46. off parsing code through the next "=cut".  It's useful for adding
  47. another paragraph to the doc if you're mixing up code and pod a lot.
  48.  
  49. =item =head1
  50.  
  51. =item =head2
  52.  
  53. Head1 and head2 produce first and second level headings, with the text in
  54. the same paragraph as the "=headn" directive forming the heading description.
  55.  
  56. =item =over
  57.  
  58. =item =back
  59.  
  60. =item =item
  61.  
  62. Item, over, and back require a little more explanation: "=over" starts a
  63. section specifically for the generation of a list using "=item" commands. At
  64. the end of your list, use "=back" to end it. You will probably want to give
  65. "4" as the number to "=over", as some formatters will use this for indentation.
  66. This should probably be a default. Note also that there are some basic rules
  67. to using =item: don't use them outside of an =over/=back block, use at least
  68. one inside an =over/=back block, you don't _have_ to include the =back if
  69. the list just runs off the document, and perhaps most importantly, keep the
  70. items consistent: either use "=item *" for all of them, to produce bullets,
  71. or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use
  72. "=item foo", "=item bar", etc., i.e., things that looks nothing like bullets
  73. or numbers. If you start with bullets or numbers, stick with them, as many
  74. formatters use the first "=item" type to decide how to format the list.
  75.  
  76. =item =for
  77.  
  78. =item =begin
  79.  
  80. =item =end
  81.  
  82. For, begin, and end let you include sections that are not interpreted
  83. as pod text, but passed directly to particular formatters. A formatter
  84. that can utilize that format will use the section, otherwise it will be
  85. completely ignored.  The directive "=for" specifies that the entire next
  86. paragraph is in the format indicated by the first word after
  87. "=for", like this:
  88.  
  89.  =for html <br>
  90.   <p> This is a raw HTML paragraph </p>
  91.  
  92. The paired commands "=begin" and "=end" work very similarly to "=for", but
  93. instead of only accepting a single paragraph, all text from "=begin" to a
  94. paragraph with a matching "=end" are treated as a particular format.
  95.  
  96. Here are some examples of how to use these:
  97.  
  98.  =begin html
  99.  
  100.  <br>Figure 1.<IMG SRC="figure1.png"><br>
  101.  
  102.  =end html
  103.  
  104.  =begin text
  105.  
  106.    ---------------
  107.    |  foo        |
  108.    |        bar  |
  109.    ---------------
  110.  
  111.  ^^^^ Figure 1. ^^^^
  112.  
  113.  =end text
  114.  
  115. Some format names that formatters currently are known to accept include
  116. "roff", "man", "latex", "tex", "text", and "html". (Some formatters will
  117. treat some of these as synonyms.)
  118.  
  119. And don't forget, when using any command, that the command lasts up until
  120. the end of the B<paragraph>, not the line. Hence in the examples below, you
  121. can see the empty lines after each command to end its paragraph.
  122.  
  123. Some examples of lists include:
  124.  
  125.  =over 4
  126.  
  127.  =item *
  128.  
  129.  First item
  130.  
  131.  =item *
  132.  
  133.  Second item
  134.  
  135.  =back
  136.  
  137.  =over 4
  138.  
  139.  =item Foo()
  140.  
  141.  Description of Foo function
  142.  
  143.  =item Bar()
  144.  
  145.  Description of Bar function
  146.  
  147.  =back
  148.  
  149. =back
  150.  
  151. =head2 Ordinary Block of Text
  152.  
  153. It will be filled, and maybe even
  154. justified.  Certain interior sequences are recognized both
  155. here and in commands:
  156.  
  157.     I<text>     Italicize text, used for emphasis or variables
  158.     B<text>     Embolden text, used for switches and programs
  159.     S<text>     Text contains non-breaking spaces
  160.     C<code>     Render code in a typewriter font, or give some other
  161.                 indication that this represents program text
  162.     L<name>     A link (cross reference) to name
  163.             L<name>        manual page
  164.             L<name/ident>    item in manual page
  165.             L<name/"sec">    section in other manual page
  166.             L<"sec">        section in this manual page
  167.                     (the quotes are optional)
  168.             L</"sec">        ditto
  169.         same as above but only 'text' is used for output.
  170.         (Text can not contain the characters '/' and '|', 
  171.         and should contain matched '<' or '>')
  172.             L<text|name>
  173.             L<text|name/ident>
  174.             L<text|name/"sec">
  175.             L<text|"sec">
  176.             L<text|/"sec">
  177.  
  178.     F<file>    Used for filenames
  179.     X<index>    An index entry
  180.     Z<>        A zero-width character
  181.     E<escape>   A named character (very similar to HTML escapes)
  182.             E<lt>        A literal <
  183.             E<gt>        A literal >
  184.             E<sol>        A literal /
  185.             E<verbar>        A literal |
  186.             (these are optional except in other interior
  187.              sequences and when preceded by a capital letter)
  188.             E<n>        Character number n (probably in ASCII)
  189.                     E<html>        Some non-numeric HTML entity, such
  190.                     as E<Agrave>
  191.  
  192. Most of the time, you will only need a single set of angle brackets to
  193. delimit the beginning and end of interior sequences.  However, sometimes
  194. you will want to put a right angle bracket (or greater-than sign '>')
  195. inside of a sequence.  This is particularly common when using a sequence
  196. to provide a different font-type for a snippet of code.  As with all
  197. things in Perl, there is more than one way to do it.  One way is to
  198. simply escape the closing bracket using an C<E> sequence:
  199.  
  200.     C<$a E<lt>=E<gt> $b>
  201.  
  202. This will produce: "C<$a E<lt>=E<gt> $b>"
  203.  
  204. A more readable, and perhaps more "plain" way is to use an alternate set of
  205. delimiters that doesn't require a ">" to be escaped.  As of perl5.5.660,
  206. doubled angle brackets ("<<" and ">>") may be used I<if and only if there
  207. is whitespace immediately following the opening delimiter and immediately
  208. preceding the closing delimiter!> For example, the following will do the
  209. trick:
  210.  
  211.     C<< $a <=> $b >>
  212.  
  213. In fact, you can use as many repeated angle-brackets as you like so
  214. long as you have the same number of them in the opening and closing
  215. delimiters, and make sure that whitespace immediately follows the last
  216. '<' of the opening delimiter, and immediately precedes the first '>' of
  217. the closing delimiter.  So the following will also work:
  218.  
  219.     C<<< $a <=> $b >>>
  220.     C<<<< $a <=> $b >>>>
  221.  
  222. This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),
  223. and any other pod2xxx and Pod::Xxxx translator that uses Pod::Parser
  224. 1.093 or later.
  225.  
  226.  
  227. =head2 The Intent
  228.  
  229. That's it.  The intent is simplicity, not power.  I wanted paragraphs
  230. to look like paragraphs (block format), so that they stand out
  231. visually, and so that I could run them through fmt easily to reformat
  232. them (that's F7 in my version of B<vi>).  I wanted the translator (and not
  233. me) to worry about whether " or ' is a left quote or a right quote
  234. within filled text, and I wanted it to leave the quotes alone, dammit, in
  235. verbatim mode, so I could slurp in a working program, shift it over 4
  236. spaces, and have it print out, er, verbatim.  And presumably in a
  237. constant width font.
  238.  
  239. In particular, you can leave things like this verbatim in your text:
  240.  
  241.     Perl
  242.     FILEHANDLE
  243.     $variable
  244.     function()
  245.     manpage(3r)
  246.  
  247. Doubtless a few other commands or sequences will need to be added along
  248. the way, but I've gotten along surprisingly well with just these.
  249.  
  250. Note that I'm not at all claiming this to be sufficient for producing a
  251. book.  I'm just trying to make an idiot-proof common source for nroff,
  252. TeX, and other markup languages, as used for online documentation.
  253. Translators exist for B<pod2man>  (that's for nroff(1) and troff(1)),
  254. B<pod2text>, B<pod2html>, B<pod2latex>, and B<pod2fm>.
  255.  
  256. =head2 Embedding Pods in Perl Modules
  257.  
  258. You can embed pod documentation in your Perl scripts.  Start your
  259. documentation with a "=head1" command at the beginning, and end it
  260. with a "=cut" command.  Perl will ignore the pod text.  See any of the
  261. supplied library modules for examples.  If you're going to put your
  262. pods at the end of the file, and you're using an __END__ or __DATA__
  263. cut mark, make sure to put an empty line there before the first pod
  264. directive.
  265.  
  266.     __END__
  267.  
  268.     =head1 NAME
  269.  
  270.     modern - I am a modern module
  271.  
  272. If you had not had that empty line there, then the translators wouldn't
  273. have seen it.
  274.  
  275. =head2 Common Pod Pitfalls
  276.  
  277. =over 4
  278.  
  279. =item *
  280.  
  281. Pod translators usually will require paragraphs to be separated by
  282. completely empty lines.  If you have an apparently empty line with
  283. some spaces on it, this can cause odd formatting.
  284.  
  285. =item *
  286.  
  287. Translators will mostly add wording around a LE<lt>E<gt> link, so that
  288. C<LE<lt>foo(1)E<gt>> becomes "the I<foo>(1) manpage", for example (see
  289. B<pod2man> for details).  Thus, you shouldn't write things like C<the
  290. LE<lt>fooE<gt> manpage>, if you want the translated document to read
  291. sensibly.
  292.  
  293. If you need total control of the text used for a link in the output
  294. use the form LE<lt>show this text|fooE<gt> instead.
  295.  
  296. =item *
  297.  
  298. The B<podchecker> command is provided to check pod syntax
  299. for errors and warnings. For example, it checks for completely
  300. blank lines in pod segments and for unknown escape sequences.
  301. It is still advised to pass it through
  302. one or more translators and proofread the result, or print out the
  303. result and proofread that.  Some of the problems found may be bugs in
  304. the translators, which you may or may not wish to work around.
  305.  
  306. =back
  307.  
  308. =head1 SEE ALSO
  309.  
  310. L<pod2man>, L<perlsyn/"PODs: Embedded Documentation">,
  311. L<podchecker>
  312.  
  313. =head1 AUTHOR
  314.  
  315. Larry Wall
  316.  
  317.