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 | |
a0d0e21e | 14 | |
b74bceb9 | 15 | =head2 Verbatim Paragraph |
a0d0e21e LW |
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 | ||
a0d0e21e | 23 | |
b74bceb9 AB |
24 | =head2 Command Paragraph |
25 | ||
26 | All command paragraphs start with "=", followed by an | |
a0d0e21e LW |
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 | |
4633a7c4 | 35 | =cut |
cb1a09d0 | 36 | =pod |
c7c9f956 KA |
37 | =for X |
38 | =begin X | |
39 | =end X | |
cb1a09d0 | 40 | |
b74bceb9 AB |
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 CS |
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 AB |
51 | =item =head1 |
52 | ||
53 | =item =head2 | |
54 | ||
116160e3 CS |
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. | |
cb1a09d0 | 57 | |
b74bceb9 AB |
58 | =item =over |
59 | ||
60 | =item =back | |
61 | ||
62 | =item =item | |
63 | ||
116160e3 CS |
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. | |
cb1a09d0 AD |
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 | |
54310121 | 76 | formatters use the first "=item" type to decide how to format the list. |
cb1a09d0 | 77 | |
b74bceb9 AB |
78 | |
79 | =item =for | |
80 | ||
81 | =item =begin | |
82 | ||
83 | =item =end | |
84 | ||
116160e3 CS |
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: | |
c7c9f956 | 91 | |
54310121 | 92 | =for html <br> |
c7c9f956 KA |
93 | <p> This is a raw HTML paragraph </p> |
94 | ||
116160e3 CS |
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 | |
54310121 | 97 | paragraph with a matching "=end" are treated as a particular format. |
c7c9f956 KA |
98 | |
99 | Here are some examples of how to use these: | |
100 | ||
101 | =begin html | |
a6006777 | 102 | |
c7c9f956 | 103 | <br>Figure 1.<IMG SRC="figure1.png"><br> |
a6006777 | 104 | |
c7c9f956 | 105 | =end html |
a6006777 | 106 | |
c7c9f956 | 107 | =begin text |
a6006777 | 108 | |
c7c9f956 KA |
109 | --------------- |
110 | | foo | | |
111 | | bar | | |
112 | --------------- | |
a6006777 | 113 | |
c7c9f956 | 114 | ^^^^ Figure 1. ^^^^ |
a6006777 | 115 | |
c7c9f956 KA |
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 | ||
116160e3 | 122 | And don't forget, when using any command, that the command lasts up until |
cb1a09d0 | 123 | the end of the B<paragraph>, not the line. Hence in the examples below, you |
3fe9a6f1 | 124 | can see the empty lines after each command to end its paragraph. |
cb1a09d0 AD |
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 | |
a0d0e21e | 151 | |
a0d0e21e | 152 | |
b74bceb9 AB |
153 | =back |
154 | ||
155 | ||
156 | =head2 Ordinary Block of Text | |
157 | ||
158 | It will be filled, and maybe even | |
a0d0e21e LW |
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 | |
54310121 | 165 | C<code> literal code |
a0d0e21e | 166 | L<name> A link (cross reference) to name |
5f05dabc | 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 | |
a0d0e21e | 171 | (the quotes are optional) |
cb1a09d0 | 172 | L</"sec"> ditto |
b74bceb9 | 173 | same as above but only 'text' is used for output. |
4b6a7270 IZ |
174 | (Text can not contain the characters '/' and '|', |
175 | and should contain matched '<' or '>') | |
b74bceb9 AB |
176 | L<text|name> |
177 | L<text|name/ident> | |
178 | L<text|name/"sec"> | |
179 | L<text|"sec"> | |
180 | L<text|/"sec"> | |
181 | ||
a0d0e21e | 182 | F<file> Used for filenames |
cb1a09d0 | 183 | X<index> An index entry |
fa859636 | 184 | Z<> A zero-width character |
c7c9f956 | 185 | E<escape> A named character (very similar to HTML escapes) |
1294c5d8 JM |
186 | E<lt> A literal < |
187 | E<gt> A literal > | |
4b6a7270 IZ |
188 | E<sol> A literal / |
189 | E<verbar> A literal | | |
1294c5d8 JM |
190 | (these are optional except in other interior |
191 | sequences and when preceded by a capital letter) | |
c7c9f956 | 192 | E<n> Character number n (probably in ASCII) |
7f3dfc00 RS |
193 | E<html> Some non-numeric HTML entity, such |
194 | as E<Agrave> | |
a0d0e21e | 195 | |
b74bceb9 AB |
196 | |
197 | =head2 The Intent | |
3141265f | 198 | |
a0d0e21e LW |
199 | That's it. The intent is simplicity, not power. I wanted paragraphs |
200 | to look like paragraphs (block format), so that they stand out | |
201 | visually, and so that I could run them through fmt easily to reformat | |
202 | them (that's F7 in my version of B<vi>). I wanted the translator (and not | |
203 | me) to worry about whether " or ' is a left quote or a right quote | |
5f05dabc | 204 | within filled text, and I wanted it to leave the quotes alone, dammit, in |
a0d0e21e LW |
205 | verbatim mode, so I could slurp in a working program, shift it over 4 |
206 | spaces, and have it print out, er, verbatim. And presumably in a | |
207 | constant width font. | |
208 | ||
209 | In particular, you can leave things like this verbatim in your text: | |
210 | ||
211 | Perl | |
212 | FILEHANDLE | |
213 | $variable | |
214 | function() | |
215 | manpage(3r) | |
216 | ||
217 | Doubtless a few other commands or sequences will need to be added along | |
218 | the way, but I've gotten along surprisingly well with just these. | |
219 | ||
220 | Note that I'm not at all claiming this to be sufficient for producing a | |
221 | book. I'm just trying to make an idiot-proof common source for nroff, | |
222 | TeX, and other markup languages, as used for online documentation. | |
cb1a09d0 | 223 | Translators exist for B<pod2man> (that's for nroff(1) and troff(1)), |
b74bceb9 | 224 | B<pod2text>, B<pod2html>, B<pod2latex>, and B<pod2fm>. |
a0d0e21e | 225 | |
b74bceb9 AB |
226 | |
227 | =head2 Embedding Pods in Perl Modules | |
4633a7c4 LW |
228 | |
229 | You can embed pod documentation in your Perl scripts. Start your | |
116160e3 CS |
230 | documentation with a "=head1" command at the beginning, and end it |
231 | with a "=cut" command. Perl will ignore the pod text. See any of the | |
232 | supplied library modules for examples. If you're going to put your | |
233 | pods at the end of the file, and you're using an __END__ or __DATA__ | |
3fe9a6f1 | 234 | cut mark, make sure to put an empty line there before the first pod |
116160e3 | 235 | directive. |
cb1a09d0 AD |
236 | |
237 | __END__ | |
238 | ||
116160e3 | 239 | |
cb1a09d0 AD |
240 | =head1 NAME |
241 | ||
242 | modern - I am a modern module | |
243 | ||
3fe9a6f1 | 244 | If you had not had that empty line there, then the translators wouldn't |
cb1a09d0 AD |
245 | have seen it. |
246 | ||
b74bceb9 AB |
247 | |
248 | =head2 Common Pod Pitfalls | |
1294c5d8 JM |
249 | |
250 | =over 4 | |
251 | ||
252 | =item * | |
253 | ||
254 | Pod translators usually will require paragraphs to be separated by | |
3fe9a6f1 | 255 | completely empty lines. If you have an apparently empty line with |
1294c5d8 JM |
256 | some spaces on it, this can cause odd formatting. |
257 | ||
258 | =item * | |
259 | ||
260 | Translators will mostly add wording around a LE<lt>E<gt> link, so that | |
261 | C<LE<lt>foo(1)E<gt>> becomes "the I<foo>(1) manpage", for example (see | |
262 | B<pod2man> for details). Thus, you shouldn't write things like C<the | |
263 | LE<lt>fooE<gt> manpage>, if you want the translated document to read | |
264 | sensibly. | |
265 | ||
b74bceb9 AB |
266 | If you don need or want total control of the text used for a |
267 | link in the output use the form LE<lt>show this text|fooE<gt> | |
268 | instead. | |
269 | ||
1294c5d8 JM |
270 | =item * |
271 | ||
272 | The script F<pod/checkpods.PL> in the Perl source distribution | |
3fe9a6f1 | 273 | provides skeletal checking for lines that look empty but aren't |
1294c5d8 JM |
274 | B<only>, but is there as a placeholder until someone writes |
275 | Pod::Checker. The best way to check your pod is to pass it through | |
276 | one or more translators and proofread the result, or print out the | |
277 | result and proofread that. Some of the problems found may be bugs in | |
278 | the translators, which you may or may not wish to work around. | |
279 | ||
280 | =back | |
281 | ||
cb1a09d0 AD |
282 | =head1 SEE ALSO |
283 | ||
284 | L<pod2man> and L<perlsyn/"PODs: Embedded Documentation"> | |
4633a7c4 | 285 | |
cb1a09d0 | 286 | =head1 AUTHOR |
a0d0e21e LW |
287 | |
288 | Larry Wall | |
289 |