This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
VMS build tweaks (from Charles Bailey)
[perl5.git] / pod / perlpod.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
cb1a09d0 3perlpod - plain old documentation
a0d0e21e
LW
4
5=head1 DESCRIPTION
6
7A pod-to-whatever translator reads a pod file paragraph by paragraph,
8and translates it to the appropriate output format. There are
9three kinds of paragraphs:
b74bceb9
AB
10L<verbatim|/"Verbatim Paragraph">,
11L<command|/"Command Paragraph">, and
12L<ordinary text|/"Ordinary Block of Text">.
a0d0e21e 13
b74bceb9 14=head2 Verbatim Paragraph
a0d0e21e
LW
15
16A verbatim paragraph, distinguished by being indented (that is,
17it starts with space or tab). It should be reproduced exactly,
18with tabs assumed to be on 8-column boundaries. There are no
19special formatting escapes, so you can't italicize or anything
20like that. A \ means \, and nothing else.
21
b74bceb9
AB
22=head2 Command Paragraph
23
24All command paragraphs start with "=", followed by an
a0d0e21e
LW
25identifier, followed by arbitrary text that the command can
26use 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 45The "=pod" directive does nothing beyond telling the compiler to lay
116160e3
CS
46off parsing code through the next "=cut". It's useful for adding
47another 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
53Head1 and head2 produce first and second level headings, with the text in
54the 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
62Item, over, and back require a little more explanation: "=over" starts a
63section specifically for the generation of a list using "=item" commands. At
64the 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
66This should probably be a default. Note also that there are some basic rules
67to using =item: don't use them outside of an =over/=back block, use at least
68one inside an =over/=back block, you don't _have_ to include the =back if
69the list just runs off the document, and perhaps most importantly, keep the
70items consistent: either use "=item *" for all of them, to produce bullets,
71or 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
73or numbers. If you start with bullets or numbers, stick with them, as many
54310121 74formatters 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
82For, begin, and end let you include sections that are not interpreted
83as pod text, but passed directly to particular formatters. A formatter
84that can utilize that format will use the section, otherwise it will be
85completely ignored. The directive "=for" specifies that the entire next
86paragraph 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
92The paired commands "=begin" and "=end" work very similarly to "=for", but
93instead of only accepting a single paragraph, all text from "=begin" to a
54310121 94paragraph with a matching "=end" are treated as a particular format.
c7c9f956
KA
95
96Here 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
115Some format names that formatters currently are known to accept include
116"roff", "man", "latex", "tex", "text", and "html". (Some formatters will
117treat some of these as synonyms.)
118
116160e3 119And don't forget, when using any command, that the command lasts up until
cb1a09d0 120the end of the B<paragraph>, not the line. Hence in the examples below, you
3fe9a6f1 121can see the empty lines after each command to end its paragraph.
cb1a09d0
AD
122
123Some 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
153It will be filled, and maybe even
a0d0e21e
LW
154justified. Certain interior sequences are recognized both
155here 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
191Most of the time, you will only need a single set of angle brackets to
192delimit the beginning and end of interior sequences. However, sometimes
193you will want to put a right angle bracket (or greater-than sign '>')
194inside of a sequence. This is particularly common when using a sequence
195to provide a different font-type for a snippet of code. As with all
196things in Perl, there is more than one way to do it. One way is to
197simply escape the closing bracket using an C<E> sequence:
198
199 C<$a E<lt>=E<gt> $b>
200
201This will produce: "C<$a E<lt>=E<gt> $b>"
202
203A more readable, and perhaps more "plain" way is to use an alternate set of
204delimiters that doesn't require a ">" to be escaped. As of perl5.5.660,
205doubled angle brackets ("<<" and ">>") may be used I<if and only if there
206is whitespace immediately following the opening delimiter and immediately
207preceding the closing delimiter!> For example, the following will do the
208trick:
209
210 C<< $a <=> $b >>
211
212In fact, you can use as many repeated angle-brackets as you like so
213long as you have the same number of them in the opening and closing
214delimiters, and make sure that whitespace immediately follows the last
215'<' of the opening delimiter, and immediately precedes the first '>' of
216the closing delimiter. So the following will also work:
217
218 C<<< $a <=> $b >>>
219 C<<<< $a <=> $b >>>>
220
221This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),
222and any other pod2xxx and Pod::Xxxx translator that uses Pod::Parser
2231.093 or later.
224
225
b74bceb9 226=head2 The Intent
3141265f 227
a0d0e21e
LW
228That's it. The intent is simplicity, not power. I wanted paragraphs
229to look like paragraphs (block format), so that they stand out
230visually, and so that I could run them through fmt easily to reformat
231them (that's F7 in my version of B<vi>). I wanted the translator (and not
232me) to worry about whether " or ' is a left quote or a right quote
5f05dabc 233within filled text, and I wanted it to leave the quotes alone, dammit, in
a0d0e21e
LW
234verbatim mode, so I could slurp in a working program, shift it over 4
235spaces, and have it print out, er, verbatim. And presumably in a
236constant width font.
237
238In particular, you can leave things like this verbatim in your text:
239
240 Perl
241 FILEHANDLE
242 $variable
243 function()
244 manpage(3r)
245
246Doubtless a few other commands or sequences will need to be added along
247the way, but I've gotten along surprisingly well with just these.
248
249Note that I'm not at all claiming this to be sufficient for producing a
250book. I'm just trying to make an idiot-proof common source for nroff,
251TeX, and other markup languages, as used for online documentation.
cb1a09d0 252Translators exist for B<pod2man> (that's for nroff(1) and troff(1)),
b74bceb9 253B<pod2text>, B<pod2html>, B<pod2latex>, and B<pod2fm>.
a0d0e21e 254
b74bceb9 255=head2 Embedding Pods in Perl Modules
4633a7c4
LW
256
257You can embed pod documentation in your Perl scripts. Start your
116160e3
CS
258documentation with a "=head1" command at the beginning, and end it
259with a "=cut" command. Perl will ignore the pod text. See any of the
260supplied library modules for examples. If you're going to put your
261pods at the end of the file, and you're using an __END__ or __DATA__
3fe9a6f1 262cut mark, make sure to put an empty line there before the first pod
116160e3 263directive.
cb1a09d0
AD
264
265 __END__
266
267 =head1 NAME
268
269 modern - I am a modern module
270
3fe9a6f1 271If you had not had that empty line there, then the translators wouldn't
cb1a09d0
AD
272have seen it.
273
b74bceb9 274=head2 Common Pod Pitfalls
1294c5d8
JM
275
276=over 4
277
278=item *
279
280Pod translators usually will require paragraphs to be separated by
3fe9a6f1 281completely empty lines. If you have an apparently empty line with
1294c5d8
JM
282some spaces on it, this can cause odd formatting.
283
284=item *
285
286Translators will mostly add wording around a LE<lt>E<gt> link, so that
287C<LE<lt>foo(1)E<gt>> becomes "the I<foo>(1) manpage", for example (see
288B<pod2man> for details). Thus, you shouldn't write things like C<the
289LE<lt>fooE<gt> manpage>, if you want the translated document to read
290sensibly.
291
49877630
GS
292If you need total control of the text used for a link in the output
293use the form LE<lt>show this text|fooE<gt> instead.
b74bceb9 294
1294c5d8
JM
295=item *
296
297The script F<pod/checkpods.PL> in the Perl source distribution
3fe9a6f1 298provides skeletal checking for lines that look empty but aren't
1294c5d8
JM
299B<only>, but is there as a placeholder until someone writes
300Pod::Checker. The best way to check your pod is to pass it through
301one or more translators and proofread the result, or print out the
302result and proofread that. Some of the problems found may be bugs in
303the translators, which you may or may not wish to work around.
304
305=back
306
cb1a09d0
AD
307=head1 SEE ALSO
308
309L<pod2man> and L<perlsyn/"PODs: Embedded Documentation">
4633a7c4 310
cb1a09d0 311=head1 AUTHOR
a0d0e21e
LW
312
313Larry Wall
314