Commit | Line | Data |
---|---|---|
a0d0e21e LW |
1 | =head1 NAME |
2 | ||
cb1a09d0 | 3 | perlpod - plain old documentation |
a0d0e21e LW |
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 AB |
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 LW |
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 AB |
22 | =head2 Command Paragraph |
23 | ||
24 | All command paragraphs start with "=", followed by an | |
a0d0e21e LW |
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 | |
4633a7c4 | 33 | =cut |
cb1a09d0 | 34 | =pod |
c7c9f956 KA |
35 | =for X |
36 | =begin X | |
37 | =end X | |
cb1a09d0 | 38 | |
b74bceb9 AB |
39 | =over 4 |
40 | ||
41 | =item =pod | |
42 | ||
43 | =item =cut | |
44 | ||
cb1a09d0 | 45 | The "=pod" directive does nothing beyond telling the compiler to lay |
116160e3 CS |
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. | |
cb1a09d0 | 48 | |
b74bceb9 AB |
49 | =item =head1 |
50 | ||
51 | =item =head2 | |
52 | ||
116160e3 CS |
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. | |
cb1a09d0 | 55 | |
b74bceb9 AB |
56 | =item =over |
57 | ||
58 | =item =back | |
59 | ||
60 | =item =item | |
61 | ||
116160e3 CS |
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. | |
cb1a09d0 AD |
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 | |
54310121 | 74 | formatters use the first "=item" type to decide how to format the list. |
cb1a09d0 | 75 | |
b74bceb9 AB |
76 | =item =for |
77 | ||
78 | =item =begin | |
79 | ||
80 | =item =end | |
81 | ||
116160e3 CS |
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: | |
c7c9f956 | 88 | |
54310121 | 89 | =for html <br> |
c7c9f956 KA |
90 | <p> This is a raw HTML paragraph </p> |
91 | ||
116160e3 CS |
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 | |
54310121 | 94 | paragraph with a matching "=end" are treated as a particular format. |
c7c9f956 KA |
95 | |
96 | Here are some examples of how to use these: | |
97 | ||
98 | =begin html | |
a6006777 | 99 | |
c7c9f956 | 100 | <br>Figure 1.<IMG SRC="figure1.png"><br> |
a6006777 | 101 | |
c7c9f956 | 102 | =end html |
a6006777 | 103 | |
c7c9f956 | 104 | =begin text |
a6006777 | 105 | |
c7c9f956 KA |
106 | --------------- |
107 | | foo | | |
108 | | bar | | |
109 | --------------- | |
a6006777 | 110 | |
c7c9f956 | 111 | ^^^^ Figure 1. ^^^^ |
a6006777 | 112 | |
c7c9f956 KA |
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 | ||
116160e3 | 119 | And don't forget, when using any command, that the command lasts up until |
cb1a09d0 | 120 | the end of the B<paragraph>, not the line. Hence in the examples below, you |
3fe9a6f1 | 121 | can see the empty lines after each command to end its paragraph. |
cb1a09d0 AD |
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 | |
a0d0e21e | 148 | |
b74bceb9 AB |
149 | =back |
150 | ||
b74bceb9 AB |
151 | =head2 Ordinary Block of Text |
152 | ||
153 | It will be filled, and maybe even | |
a0d0e21e LW |
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 | |
54310121 | 160 | C<code> literal code |
a0d0e21e | 161 | L<name> A link (cross reference) to name |
5f05dabc | 162 | L<name> manual page |
163 | L<name/ident> item in manual page | |
164 | L<name/"sec"> section in other manual page | |
165 | L<"sec"> section in this manual page | |
a0d0e21e | 166 | (the quotes are optional) |
cb1a09d0 | 167 | L</"sec"> ditto |
b74bceb9 | 168 | same as above but only 'text' is used for output. |
4b6a7270 IZ |
169 | (Text can not contain the characters '/' and '|', |
170 | and should contain matched '<' or '>') | |
b74bceb9 AB |
171 | L<text|name> |
172 | L<text|name/ident> | |
173 | L<text|name/"sec"> | |
174 | L<text|"sec"> | |
175 | L<text|/"sec"> | |
c47ff5f1 | 176 | |
a0d0e21e | 177 | F<file> Used for filenames |
cb1a09d0 | 178 | X<index> An index entry |
fa859636 | 179 | Z<> A zero-width character |
c7c9f956 | 180 | E<escape> A named character (very similar to HTML escapes) |
1294c5d8 JM |
181 | E<lt> A literal < |
182 | E<gt> A literal > | |
4b6a7270 IZ |
183 | E<sol> A literal / |
184 | E<verbar> A literal | | |
1294c5d8 JM |
185 | (these are optional except in other interior |
186 | sequences and when preceded by a capital letter) | |
c7c9f956 | 187 | E<n> Character number n (probably in ASCII) |
7f3dfc00 RS |
188 | E<html> Some non-numeric HTML entity, such |
189 | as E<Agrave> | |
a0d0e21e | 190 | |
5455df32 GS |
191 | Most of the time, you will only need a single set of angle brackets to |
192 | delimit the beginning and end of interior sequences. However, sometimes | |
193 | you will want to put a right angle bracket (or greater-than sign '>') | |
194 | inside of a sequence. This is particularly common when using a sequence | |
195 | to provide a different font-type for a snippet of code. As with all | |
196 | things in Perl, there is more than one way to do it. One way is to | |
197 | simply escape the closing bracket using an C<E> sequence: | |
198 | ||
199 | C<$a E<lt>=E<gt> $b> | |
200 | ||
201 | This will produce: "C<$a E<lt>=E<gt> $b>" | |
202 | ||
203 | A more readable, and perhaps more "plain" way is to use an alternate set of | |
204 | delimiters that doesn't require a ">" to be escaped. As of perl5.5.660, | |
205 | doubled angle brackets ("<<" and ">>") may be used I<if and only if there | |
206 | is whitespace immediately following the opening delimiter and immediately | |
207 | preceding the closing delimiter!> For example, the following will do the | |
208 | trick: | |
209 | ||
210 | C<< $a <=> $b >> | |
211 | ||
212 | In fact, you can use as many repeated angle-brackets as you like so | |
213 | long as you have the same number of them in the opening and closing | |
214 | delimiters, and make sure that whitespace immediately follows the last | |
215 | '<' of the opening delimiter, and immediately precedes the first '>' of | |
216 | the closing delimiter. So the following will also work: | |
217 | ||
218 | C<<< $a <=> $b >>> | |
219 | C<<<< $a <=> $b >>>> | |
220 | ||
221 | This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man), | |
222 | and any other pod2xxx and Pod::Xxxx translator that uses Pod::Parser | |
223 | 1.093 or later. | |
224 | ||
225 | ||
b74bceb9 | 226 | =head2 The Intent |
3141265f | 227 | |
a0d0e21e LW |
228 | That's it. The intent is simplicity, not power. I wanted paragraphs |
229 | to look like paragraphs (block format), so that they stand out | |
230 | visually, and so that I could run them through fmt easily to reformat | |
231 | them (that's F7 in my version of B<vi>). I wanted the translator (and not | |
232 | me) to worry about whether " or ' is a left quote or a right quote | |
5f05dabc | 233 | within filled text, and I wanted it to leave the quotes alone, dammit, in |
a0d0e21e LW |
234 | verbatim mode, so I could slurp in a working program, shift it over 4 |
235 | spaces, and have it print out, er, verbatim. And presumably in a | |
236 | constant width font. | |
237 | ||
238 | In particular, you can leave things like this verbatim in your text: | |
239 | ||
240 | Perl | |
241 | FILEHANDLE | |
242 | $variable | |
243 | function() | |
244 | manpage(3r) | |
245 | ||
246 | Doubtless a few other commands or sequences will need to be added along | |
247 | the way, but I've gotten along surprisingly well with just these. | |
248 | ||
249 | Note that I'm not at all claiming this to be sufficient for producing a | |
250 | book. I'm just trying to make an idiot-proof common source for nroff, | |
251 | TeX, and other markup languages, as used for online documentation. | |
cb1a09d0 | 252 | Translators exist for B<pod2man> (that's for nroff(1) and troff(1)), |
b74bceb9 | 253 | B<pod2text>, B<pod2html>, B<pod2latex>, and B<pod2fm>. |
a0d0e21e | 254 | |
b74bceb9 | 255 | =head2 Embedding Pods in Perl Modules |
4633a7c4 LW |
256 | |
257 | You can embed pod documentation in your Perl scripts. Start your | |
116160e3 CS |
258 | documentation with a "=head1" command at the beginning, and end it |
259 | with a "=cut" command. Perl will ignore the pod text. See any of the | |
260 | supplied library modules for examples. If you're going to put your | |
261 | pods at the end of the file, and you're using an __END__ or __DATA__ | |
3fe9a6f1 | 262 | cut mark, make sure to put an empty line there before the first pod |
116160e3 | 263 | directive. |
cb1a09d0 AD |
264 | |
265 | __END__ | |
266 | ||
267 | =head1 NAME | |
268 | ||
269 | modern - I am a modern module | |
270 | ||
3fe9a6f1 | 271 | If you had not had that empty line there, then the translators wouldn't |
cb1a09d0 AD |
272 | have seen it. |
273 | ||
b74bceb9 | 274 | =head2 Common Pod Pitfalls |
1294c5d8 JM |
275 | |
276 | =over 4 | |
277 | ||
278 | =item * | |
279 | ||
280 | Pod translators usually will require paragraphs to be separated by | |
3fe9a6f1 | 281 | completely empty lines. If you have an apparently empty line with |
1294c5d8 JM |
282 | some spaces on it, this can cause odd formatting. |
283 | ||
284 | =item * | |
285 | ||
286 | Translators will mostly add wording around a LE<lt>E<gt> link, so that | |
287 | C<LE<lt>foo(1)E<gt>> becomes "the I<foo>(1) manpage", for example (see | |
288 | B<pod2man> for details). Thus, you shouldn't write things like C<the | |
289 | LE<lt>fooE<gt> manpage>, if you want the translated document to read | |
290 | sensibly. | |
291 | ||
49877630 GS |
292 | If you need total control of the text used for a link in the output |
293 | use the form LE<lt>show this text|fooE<gt> instead. | |
b74bceb9 | 294 | |
1294c5d8 JM |
295 | =item * |
296 | ||
88d14829 GS |
297 | The F<L<podchecker|podchecker>> command is provided to check pod syntax |
298 | for errors and warnings. For example, it checks for completely | |
299 | blank lines in pod segments and for unknown escape sequences. | |
300 | It is still advised to pass it through | |
1294c5d8 JM |
301 | one or more translators and proofread the result, or print out the |
302 | result and proofread that. Some of the problems found may be bugs in | |
303 | the translators, which you may or may not wish to work around. | |
304 | ||
305 | =back | |
306 | ||
cb1a09d0 AD |
307 | =head1 SEE ALSO |
308 | ||
88d14829 GS |
309 | L<pod2man>, L<perlsyn/"PODs: Embedded Documentation">, |
310 | L<podchecker> | |
4633a7c4 | 311 | |
cb1a09d0 | 312 | =head1 AUTHOR |
a0d0e21e LW |
313 | |
314 | Larry Wall | |
315 |