| 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 | |
| 11 | =over 4 |
| 12 | |
| 13 | =item * |
| 14 | |
| 15 | A verbatim paragraph, distinguished by being indented (that is, |
| 16 | it starts with space or tab). It should be reproduced exactly, |
| 17 | with tabs assumed to be on 8-column boundaries. There are no |
| 18 | special formatting escapes, so you can't italicize or anything |
| 19 | like that. A \ means \, and nothing else. |
| 20 | |
| 21 | =item * |
| 22 | |
| 23 | A command. All command paragraphs start with "=", followed by an |
| 24 | identifier, followed by arbitrary text that the command can |
| 25 | use however it pleases. Currently recognized commands are |
| 26 | |
| 27 | =head1 heading |
| 28 | =head2 heading |
| 29 | =item text |
| 30 | =over N |
| 31 | =back |
| 32 | =cut |
| 33 | =pod |
| 34 | |
| 35 | The "=pod" directive does nothing beyond telling the compiler to lay |
| 36 | off of through the next "=cut". It's useful for adding another |
| 37 | paragraph to the doc if you're mixing up code and pod a lot. |
| 38 | |
| 39 | Head1 and head2 produce first and second level headings, with the text on |
| 40 | the same paragraph as "=headn" forming the heading description. |
| 41 | |
| 42 | Item, over, and back require a little more explanation: Over starts a |
| 43 | section specifically for the generation of a list using =item commands. At |
| 44 | the end of your list, use =back to end it. You will probably want to give |
| 45 | "4" as the number to =over, as some formatters will use this for indentation. |
| 46 | This should probably be a default. Note also that there are some basic rules |
| 47 | to using =item: don't use them outside of an =over/=back block, use at least |
| 48 | one inside an =over/=back block, you don't _have_ to include the =back if |
| 49 | the list just runs off the document, and perhaps most importantly, keep the |
| 50 | items consistent: either use "=item *" for all of them, to produce bullets, |
| 51 | or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use |
| 52 | "=item foo", "=item bar", etc., i.e., things that looks nothing like bullets |
| 53 | or numbers. If you start with bullets or numbers, stick with them, as many |
| 54 | formatters use the first =item type to decide how to format the list. |
| 55 | |
| 56 | And don't forget, when using any command, that that command lasts up until |
| 57 | the end of the B<paragraph>, not the line. Hence in the examples below, you |
| 58 | can see the blank lines after each command to end its paragraph. |
| 59 | |
| 60 | Some examples of lists include: |
| 61 | |
| 62 | =over 4 |
| 63 | |
| 64 | =item * |
| 65 | |
| 66 | First item |
| 67 | |
| 68 | =item * |
| 69 | |
| 70 | Second item |
| 71 | |
| 72 | =back |
| 73 | |
| 74 | =over 4 |
| 75 | |
| 76 | =item Foo() |
| 77 | |
| 78 | Description of Foo function |
| 79 | |
| 80 | =item Bar() |
| 81 | |
| 82 | Description of Bar function |
| 83 | |
| 84 | =back |
| 85 | |
| 86 | =item * |
| 87 | |
| 88 | An ordinary block of text. It will be filled, and maybe even |
| 89 | justified. Certain interior sequences are recognized both |
| 90 | here and in commands: |
| 91 | |
| 92 | I<text> italicize text, used for emphasis or variables |
| 93 | B<text> embolden text, used for switches and programs |
| 94 | S<text> text contains non-breaking spaces |
| 95 | C<code> literal code |
| 96 | L<name> A link (cross reference) to name |
| 97 | L<name> manpage |
| 98 | L<name/ident> item in manpage |
| 99 | L<name/"sec"> section in other manpage |
| 100 | L<"sec"> section in this manpage |
| 101 | (the quotes are optional) |
| 102 | L</"sec"> ditto |
| 103 | F<file> Used for filenames |
| 104 | X<index> An index entry |
| 105 | Z<> A zero-width character |
| 106 | E<escape> An HTML escape |
| 107 | E<lt> A literal < |
| 108 | E<gt> A literal > |
| 109 | (these are optional except in other interior |
| 110 | sequences and when preceded by a capital letter) |
| 111 | E<nnn> Character number nnn. |
| 112 | |
| 113 | =back |
| 114 | |
| 115 | That's it. The intent is simplicity, not power. I wanted paragraphs |
| 116 | to look like paragraphs (block format), so that they stand out |
| 117 | visually, and so that I could run them through fmt easily to reformat |
| 118 | them (that's F7 in my version of B<vi>). I wanted the translator (and not |
| 119 | me) to worry about whether " or ' is a left quote or a right quote |
| 120 | within filled text, and I wanted it to leave the quotes alone dammit in |
| 121 | verbatim mode, so I could slurp in a working program, shift it over 4 |
| 122 | spaces, and have it print out, er, verbatim. And presumably in a |
| 123 | constant width font. |
| 124 | |
| 125 | In particular, you can leave things like this verbatim in your text: |
| 126 | |
| 127 | Perl |
| 128 | FILEHANDLE |
| 129 | $variable |
| 130 | function() |
| 131 | manpage(3r) |
| 132 | |
| 133 | Doubtless a few other commands or sequences will need to be added along |
| 134 | the way, but I've gotten along surprisingly well with just these. |
| 135 | |
| 136 | Note that I'm not at all claiming this to be sufficient for producing a |
| 137 | book. I'm just trying to make an idiot-proof common source for nroff, |
| 138 | TeX, and other markup languages, as used for online documentation. |
| 139 | Translators exist for B<pod2man> (that's for nroff(1) and troff(1)), |
| 140 | B<pod2html>, B<pod2latex>, and B<pod2fm>. |
| 141 | |
| 142 | =head1 Embedding Pods in Perl Modules |
| 143 | |
| 144 | You can embed pod documentation in your Perl scripts. Start your |
| 145 | documentation with a =head1 command at the beg, and end it with |
| 146 | an =cut command. Perl will ignore the pod text. See any of the |
| 147 | supplied library modules for examples. If you're going to put |
| 148 | your pods at the end of the file, and you're using an __END__ |
| 149 | or __DATA__ cut mark, make sure to put a blank line there before |
| 150 | the first pod directive. |
| 151 | |
| 152 | __END__ |
| 153 | |
| 154 | =head1 NAME |
| 155 | |
| 156 | modern - I am a modern module |
| 157 | |
| 158 | If you had not had that blank line there, then the translators wouldn't |
| 159 | have seen it. |
| 160 | |
| 161 | =head1 Common Pod Pitfalls |
| 162 | |
| 163 | =over 4 |
| 164 | |
| 165 | =item * |
| 166 | |
| 167 | Pod translators usually will require paragraphs to be separated by |
| 168 | completely empty lines. If you have an apparently blank line with |
| 169 | some spaces on it, this can cause odd formatting. |
| 170 | |
| 171 | =item * |
| 172 | |
| 173 | Translators will mostly add wording around a LE<lt>E<gt> link, so that |
| 174 | C<LE<lt>foo(1)E<gt>> becomes "the I<foo>(1) manpage", for example (see |
| 175 | B<pod2man> for details). Thus, you shouldn't write things like C<the |
| 176 | LE<lt>fooE<gt> manpage>, if you want the translated document to read |
| 177 | sensibly. |
| 178 | |
| 179 | =item * |
| 180 | |
| 181 | The script F<pod/checkpods.PL> in the Perl source distribution |
| 182 | provides skeletal checking for lines that look blank but aren't |
| 183 | B<only>, but is there as a placeholder until someone writes |
| 184 | Pod::Checker. The best way to check your pod is to pass it through |
| 185 | one or more translators and proofread the result, or print out the |
| 186 | result and proofread that. Some of the problems found may be bugs in |
| 187 | the translators, which you may or may not wish to work around. |
| 188 | |
| 189 | =back |
| 190 | |
| 191 | =head1 SEE ALSO |
| 192 | |
| 193 | L<pod2man> and L<perlsyn/"PODs: Embedded Documentation"> |
| 194 | |
| 195 | =head1 AUTHOR |
| 196 | |
| 197 | Larry Wall |
| 198 | |