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