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 | |
---|