contrib/perl5/pod/perlpod.pod

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