Penguin
Recent Changes
Annotated edit history of perlpod(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 PERLPOD
2 !!!PERLPOD
3 NAME
4 DESCRIPTION
5 SEE ALSO
6 AUTHOR
7 ----
8 !!NAME
9
10
11 perlpod - plain old documentation
12 !!DESCRIPTION
13
14
15 A pod-to-whatever translator reads a pod file paragraph by
16 paragraph, and translates it to the appropriate output
17 format. There are three kinds of paragraphs: verbatim,
18 command, and ordinary text.
19
20
21 __Verbatim Paragraph__
22
23
24 A verbatim paragraph, distinguished by being indented (that
25 is, it starts with space or tab). It should be reproduced
26 exactly, with tabs assumed to be on 8-column boundaries.
27 There are no special formatting escapes, so you can't
28 italicize or anything like that. A \ means , and nothing
29 else.
30
31
32 __Command Paragraph__
33
34
35 All command paragraphs start with ``='', followed by an
36 identifier, followed by arbitrary text that the command can
37 use however it pleases. Currently recognized commands
38 are
39
40
41 =head1 heading
42 =head2 heading
43 =item text
44 =over N
45 =back
46 =cut
47 =pod
48 =for X
49 =begin X
50 =end X
51 =pod
52
53
54 =cut
55
56
57 The ``=pod'' directive does nothing beyond telling the
58 compiler to lay off parsing code through the next ``=cut''.
59 It's useful for adding another paragraph to the doc if
60 you're mixing up code and pod a lot.
61
62
63 =head1
64
65
66 =head2
67
68
69 Head1 and head2 produce first and second level headings,
70 with the text in the same paragraph as the ``=headn''
71 directive forming the heading description.
72
73
74 =over
75
76
77 =back
78
79
80 =item
81
82
83 Item, over, and back require a little more explanation:
84 ``=over'' starts a section specifically for the generation
85 of a list using ``=item'' commands. At the end of your list,
86 use ``=back'' to end it. You will probably want to give
87 ``4'' as the number to ``=over'', as some formatters will
88 use this for indentation. The unit of indentation is
89 optional. If the unit is not given the natural indentation
90 of the formatting system applied will be used. Note also
91 that there are some basic rules to using =item: don't use
92 them outside of an =over/=back block, use at least one
93 inside an =over/=back block, you don't _have_ to include the
94 =back if the list just runs off the document, and perhaps
95 most importantly, keep the items consistent: either use
96 ``=item *'' for all of them, to produce bullets, or use
97 ``=item 1.'', ``=item 2.'', etc., to produce numbered lists,
98 or use ``=item foo'', ``=item bar'', etc., i.e., things that
99 looks nothing like bullets or numbers. If you start with
100 bullets or numbers, stick with them, as many formatters use
101 the first ``=item'' type to decide how to format the
102 list.
103
104
105 =for
106
107
108 =begin
109
110
111 =end
112
113
114 For, begin, and end let you include sections that are not
115 interpreted as pod text, but passed directly to particular
116 formatters. A formatter that can utilize that format will
117 use the section, otherwise it will be completely ignored.
118 The directive ``=for'' specifies that the entire next
119 paragraph is in the format indicated by the first word after
120 ``=for'', like this:
121
122
123 =for html
124 The paired commands ``=begin'' and ``=end'' work very similarly to ``=for'', but instead of only accepting a single paragraph, all text from ``=begin'' to a paragraph with a matching ``=end'' are treated as a particular format.
125
126
127 Here are some examples of how to use these:
128
129
130 =begin html
131
132 =end html
133 =begin text
134 ---------------
135 foo
136 bar
137 ---------------
138 ^^^^ Figure 1. ^^^^
139 =end text
140 Some format names that formatters currently are known to accept include ``roff'', ``man'', ``latex'', ``tex'', ``text'', and ``html''. (Some formatters will treat some of these as synonyms.)
141
142
143 And don't forget, when using any command, that the command
144 lasts up until the end of the __paragraph__, not the
145 line. Hence in the examples below, you can see the empty
146 lines after each command to end its paragraph.
147
148
149 Some examples of lists include:
150
151
152 =over 4
153 =item *
154 First item
155 =item *
156 Second item
157 =back
158 =over 4
159 =item Foo()
160 Description of Foo function
161 =item Bar()
162 Description of Bar function
163 =back
164
165
166 __Ordinary Block of Text__
167
168
169 It will be filled, and maybe even justified. Certain
170 interior sequences are recognized both here and in
171 commands:
172
173
174 I
175 F
176 Most of the time, you will only need a single set of angle brackets to delimit the beginning and end of interior sequences. However, sometimes you will want to put a right angle bracket (or greater-than sign 'E sequence:
177
178
179 C
180 This will produce: $a
181
182
183 A more readable, and perhaps more ``plain'' way is to use an
184 alternate set of delimiters that doesn't require a ``
185 if and only
186 if there is whitespace immediately following the opening
187 delimiter and immediately preceding the closing
188 delimiter!'' For example, the following will do the
189 trick:
190
191
192 C
193 In fact, you can use as many repeated angle-brackets as you like so long as you have the same number of them in the opening and closing delimiters, and make sure that whitespace immediately follows the last '
194
195
196 C
197 This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man), and any other pod2xxx and Pod::Xxxx translator that uses Pod::Parser 1.093 or later.
198
199
200 __The Intent__
201
202
203 That's it. The intent is simplicity, not power. I wanted
204 paragraphs to look like paragraphs (block format), so that
205 they stand out visually, and so that I could run them
206 through fmt easily to reformat them (that's F7 in my version
207 of __vi__). I wanted the translator (and not me) to worry
208 about whether
209 __
210
211
212 In particular, you can leave things like this verbatim in
213 your text:
214
215
216 Perl
217 FILEHANDLE
218 $variable
219 function()
220 manpage(3r)
221 Doubtless a few other commands or sequences will need to be added along the way, but I've gotten along surprisingly well with just these.
222
223
224 Note that I'm not at all claiming this to be sufficient for
225 producing a book. I'm just trying to make an idiot-proof
226 common source for nroff, TeX, and other markup languages, as
227 used for online documentation. Translators exist for
228 __pod2man__ (that's for nroff(1) and
229 troff(1)), __pod2text__, __pod2html__,
230 __pod2latex__, and __pod2fm__.
231
232
233 __Embedding Pods in Perl Modules__
234
235
236 You can embed pod documentation in your Perl scripts. Start
237 your documentation with a ``=head1'' command at the
238 beginning, and end it with a ``=cut'' command. Perl will
239 ignore the pod text. See any of the supplied library modules
240 for examples. If you're going to put your pods at the end of
241 the file, and you're using an __END__ or __DATA__ cut mark,
242 make sure to put an empty line there before the first pod
243 directive.
244
245
246 __END__
247 =head1 NAME
248 modern - I am a modern module
249 If you had not had that empty line there, then the translators wouldn't have seen it.
250
251
252 __Common Pod Pitfalls__
253
254
255 Pod translators usually will require paragraphs to be
256 separated by completely empty lines. If you have an
257 apparently empty line with some spaces on it, this can cause
258 odd formatting.
259
260
261 Translators will mostly add wording around a L
262 L becomes
263 foo''(1) manpage''pod2man__
264 for details). Thus, you shouldn't write things like the
265 L, if you want the translated
266 document to read sensibly.
267
268
269 If you need total control of the text used for a link in the
270 output use the form L
271
272
273 The __podchecker__ command is provided to check pod
274 syntax for errors and warnings. For example, it checks for
275 completely blank lines in pod segments and for unknown
276 escape sequences. It is still advised to pass it through one
277 or more translators and proofread the result, or print out
278 the result and proofread that. Some of the problems found
279 may be bugs in the translators, which you may or may not
280 wish to work around.
281 !!SEE ALSO
282
283
284 pod2man, ``PODs: Embedded Documentation'' in perlsyn,
285 podchecker
286 !!AUTHOR
287
288
289 Larry Wall
290 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.