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 '|' or '>')
 175                     L<text|name>
 176                     L<text|name/ident>
 177                     L<text|name/"sec">
 178                     L<text|"sec">
 179                     L<text|/"sec">
 180
 181     F<file>     Used for filenames
 182     X<index>    An index entry
 183     Z<>         A zero-width character
 184     E<escape>   A named character (very similar to HTML escapes)
 185                     E<lt>               A literal <
 186                     E<gt>               A literal >
 187                     (these are optional except in other interior
 188                      sequences and when preceded by a capital letter)
 189                     E<n>                Character number n (probably in ASCII)
 190                     E<html>             Some non-numeric HTML entity, such
 191                                         as E<Agrave>
 192
 193
 194 =head2 The Intent
 195
 196 That's it.  The intent is simplicity, not power.  I wanted paragraphs
 197 to look like paragraphs (block format), so that they stand out
 198 visually, and so that I could run them through fmt easily to reformat
 199 them (that's F7 in my version of B<vi>).  I wanted the translator (and not
 200 me) to worry about whether " or ' is a left quote or a right quote
 201 within filled text, and I wanted it to leave the quotes alone, dammit, in
 202 verbatim mode, so I could slurp in a working program, shift it over 4
 203 spaces, and have it print out, er, verbatim.  And presumably in a
 204 constant width font.
 205
 206 In particular, you can leave things like this verbatim in your text:
 207
 208     Perl
 209     FILEHANDLE
 210     $variable
 211     function()
 212     manpage(3r)
 213
 214 Doubtless a few other commands or sequences will need to be added along
 215 the way, but I've gotten along surprisingly well with just these.
 216
 217 Note that I'm not at all claiming this to be sufficient for producing a
 218 book.  I'm just trying to make an idiot-proof common source for nroff,
 219 TeX, and other markup languages, as used for online documentation.
 220 Translators exist for B<pod2man>  (that's for nroff(1) and troff(1)),
 221 B<pod2text>, B<pod2html>, B<pod2latex>, and B<pod2fm>.
 222
 223
 224 =head2 Embedding Pods in Perl Modules
 225
 226 You can embed pod documentation in your Perl scripts.  Start your
 227 documentation with a "=head1" command at the beginning, and end it
 228 with a "=cut" command.  Perl will ignore the pod text.  See any of the
 229 supplied library modules for examples.  If you're going to put your
 230 pods at the end of the file, and you're using an __END__ or __DATA__
 231 cut mark, make sure to put an empty line there before the first pod
 232 directive.
 233
 234     __END__
 235
 236
 237     =head1 NAME
 238
 239     modern - I am a modern module
 240
 241 If you had not had that empty line there, then the translators wouldn't
 242 have seen it.
 243
 244
 245 =head2 Common Pod Pitfalls
 246
 247 =over 4
 248
 249 =item *
 250
 251 Pod translators usually will require paragraphs to be separated by
 252 completely empty lines.  If you have an apparently empty line with
 253 some spaces on it, this can cause odd formatting.
 254
 255 =item *
 256
 257 Translators will mostly add wording around a LE<lt>E<gt> link, so that
 258 C<LE<lt>foo(1)E<gt>> becomes "the I<foo>(1) manpage", for example (see
 259 B<pod2man> for details).  Thus, you shouldn't write things like C<the
 260 LE<lt>fooE<gt> manpage>, if you want the translated document to read
 261 sensibly.
 262
 263 If you don need or want total control of the text used for a
 264 link in the output use the form LE<lt>show this text|fooE<gt>
 265 instead.
 266
 267 =item *
 268
 269 The script F<pod/checkpods.PL> in the Perl source distribution
 270 provides skeletal checking for lines that look empty but aren't
 271 B<only>, but is there as a placeholder until someone writes
 272 Pod::Checker.  The best way to check your pod is to pass it through
 273 one or more translators and proofread the result, or print out the
 274 result and proofread that.  Some of the problems found may be bugs in
 275 the translators, which you may or may not wish to work around.
 276
 277 =back
 278
 279 =head1 SEE ALSO
 280
 281 L<pod2man> and L<perlsyn/"PODs: Embedded Documentation">
 282
 283 =head1 AUTHOR
 284
 285 Larry Wall
 286