This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to podlators-1.19.
[perl5.git] / lib / Pod / t / basic.pod
1 =head1 NAME
2
3 basic.pod - Test of various basic POD features in translators.
4
5 =head1 HEADINGS
6
7 Try a few different levels of headings, with embedded formatting codes and
8 other interesting bits.
9
10 =head1 This C<is> a "level 1" heading
11
12 =head2 ``Level'' "2 I<heading>
13
14 =head3 Level 3 B<heading I<with C<weird F<stuff "" (double quote)>>>>
15
16 =head4 Level "4 C<heading>
17
18 Now try again with B<intermixed> F<text>.
19
20 =head1 This C<is> a "level 1" heading
21
22 Text.
23
24 =head2 ``Level'' 2 I<heading>
25
26 Text.
27
28 =head3 Level 3 B<heading I<with C<weird F<stuff>>>>
29
30 Text.
31
32 =head4 Level "4 C<heading>
33
34 Text.
35
36 =head1 LINKS
37
38 These are all taken from the Pod::Parser tests.
39
40 Try out I<LOTS> of different ways of specifying references:
41
42 Reference the L<manpage/section>
43
44 Reference the L<manpage / section>
45
46 Reference the L<manpage/ section>
47
48 Reference the L<manpage /section>
49
50 Reference the L<"manpage/section">
51
52 Reference the L<"manpage"/section>
53
54 Reference the L<manpage/"section">
55
56 Reference the L<manpage/
57 section>
58
59 Reference the L<manpage
60 /section>
61
62 Now try it using the new "|" stuff ...
63
64 Reference the L<thistext|manpage/section>|
65
66 Reference the L<thistext | manpage / section>|
67
68 Reference the L<thistext| manpage/ section>|
69
70 Reference the L<thistext |manpage /section>|
71
72 Reference the L<thistext|
73 "manpage/section">|
74
75 Reference the L<thistext
76 |"manpage"/section>|
77
78 Reference the L<thistext|manpage/"section">|
79
80 Reference the L<thistext|
81 manpage/
82 section>|
83
84 Reference the L<thistext
85 |manpage
86 /section>|
87
88 And then throw in a few new ones of my own.
89
90 L<foo>
91
92 L<foo|bar>
93
94 L<foo/bar>
95
96 L<foo/"baz boo">
97
98 L</bar>
99
100 L</"baz boo">
101
102 L</baz boo>
103
104 L<foo bar/baz boo>
105
106 L<foo bar  /  baz boo>
107
108 L<foo
109 bar
110 baz
111 /
112 boo>
113
114 L<"boo var baz">
115
116 L<bar baz>
117
118 L<"boo bar baz / baz boo">
119
120 L</boo>, L</bar>, and L</baz>
121
122 L<fooZ<>bar>
123
124 L<Testing I<italics>|foo/bar>
125
126 L<foo/I<Italic> text>
127
128 L<fooE<verbar>barZ<>/Section C<with> I<B<other> markup>>
129
130 L<Nested L<http://www.perl.org/>|fooE<sol>bar>
131
132 =head1 OVER AND ITEMS
133
134 Taken from Pod::Parser tests, this is a test to ensure that multiline
135 =item paragraphs get indented appropriately.
136
137 =over 4 
138
139 =item This 
140 is
141 a
142 test.
143
144 =back
145
146 There should be whitespace now before this line.
147
148 Taken from Pod::Parser tests, this is a test to ensure the nested =item
149 paragraphs get indented appropriately.
150
151 =over 2
152
153 =item 1
154
155 First section.
156
157 =over 2
158
159 =item a
160
161 this is item a
162
163 =item b
164
165 this is item b
166
167 =back
168
169 =item 2
170
171 Second section.
172
173 =over 2
174
175 =item a
176
177 this is item a
178
179 =item b
180
181 this is item b
182
183 =item c
184
185 =item d
186
187 This is item c & d.
188
189 =back
190
191 =back
192
193 Now some additional weirdness of our own.  Make sure that multiple tags
194 for one paragraph are properly compacted.
195
196 =over 4
197
198 =item "foo"
199
200 =item B<bar>
201
202 =item C<baz>
203
204 There shouldn't be any spaces between any of these item tags; this idiom
205 is used in perlfunc.
206
207 =item Some longer item text
208
209 Just to make sure that we test paragraphs where the item text doesn't fit
210 in the margin of the paragraph (and make sure that this paragraph fills a
211 few lines).
212
213 Let's also make it multiple paragraphs to be sure that works.
214
215 =back
216
217 Test use of =over without =item as a block "quote" or block paragraph.
218
219 =over 4
220
221 This should be indented four spaces but otherwise formatted the same as
222 any other regular text paragraph.  Make sure it's long enough to see the
223 results of the formatting.....
224
225 =back
226
227 Now try the same thing nested, and make sure that the indentation is reset
228 back properly.
229
230 =over 4
231
232 =over 4
233
234 This paragraph should be doubly indented.
235
236 =back
237
238 This paragraph should only be singly indented.
239
240 =over 4
241
242 =item
243
244 This is an item in the middle of a block-quote, which should be allowed.
245
246 =item
247
248 We're also testing tagless item commands.
249
250 =back
251
252 Should be back to the single level of indentation.
253
254 =back
255
256 Should be back to regular indentation.
257
258 Now also check the transformation of * into real bullets for man pages.
259
260 =over
261
262 =item *
263
264 An item.  We're also testing using =over without a number, and making sure
265 that item text wraps properly.
266
267 =item *
268
269 Another item.
270
271 =back
272
273 and now test the numbering of item blocks.
274
275 =over 4
276
277 =item 1.
278
279 First item.
280
281 =item 2.
282
283 Second item.
284
285 =back
286
287 =head1 FORMATTING CODES
288
289 Another test taken from Pod::Parser.
290
291 This is a test to see if I can do not only C<$self> and C<method()>, but
292 also C<< $self->method() >> and C<< $self->{FIELDNAME} >> and
293 C<< $Foo <=> $Bar >> without resorting to escape sequences. If 
294 I want to refer to the right-shift operator I can do something
295 like C<<< $x >> 3 >>> or even C<<<< $y >> 5 >>>>.
296
297 Now for the grand finale of C<< $self->method()->{FIELDNAME} = {FOO=>BAR} >>.
298 And I also want to make sure that newlines work like this
299 C<<<
300 $self->{FOOBAR} >> 3 and [$b => $a]->[$a <=> $b]
301 >>>
302
303 Of course I should still be able to do all this I<with> escape sequences
304 too: C<$self-E<gt>method()> and C<$self-E<gt>{FIELDNAME}> and
305 C<{FOO=E<gt>BAR}>.
306
307 Dont forget C<$self-E<gt>method()-E<gt>{FIELDNAME} = {FOO=E<gt>BAR}>.
308
309 And make sure that C<0> works too!
310
311 Now, if I use << or >> as my delimiters, then I have to use whitespace.
312 So things like C<<$self->method()>> and C<<$self->{FIELDNAME}>> wont end
313 up doing what you might expect since the first > will still terminate
314 the first < seen.
315
316 Lets make sure these work for empty ones too, like C<<  >> and C<< >> >>
317 (just to be obnoxious)
318
319 The statement: C<This is dog kind's I<finest> hour!> is a parody of a
320 quotation from Winston Churchill.
321
322 The following tests are added to those:
323
324 Make sure that a few othZ<>er odd I<Z<>things> still work.  This should be
325 a vertical bar:  E<verbar>.  Here's a test of a few more special escapes
326 that have to be supported:
327
328 =over 3
329
330 =item E<amp>
331
332 An ampersand.
333
334 =item E<apos>
335
336 An apostrophe.
337
338 =item E<lt>
339
340 A less-than sign.
341
342 =item E<gt>
343
344 A greater-than sign.
345
346 =item E<quot>
347
348 A double quotation mark.
349
350 =item E<sol>
351
352 A forward slash.
353
354 =back
355
356 Try to get this bit of text over towards the edge so S<|that all of this
357 text inside SE<lt>E<gt> won't|> be wrapped.  Also test the
358 |sameE<nbsp>thingE<nbsp>withE<nbsp>non-breakingS< spaces>.|
359
360 There is a soft hyE<shy>phen in hyphen at hy-phen.
361
362 This is a test of an X<index entry>index entry.
363
364 =head1 VERBATIM
365
366 Throw in a few verbatim paragraphs.
367
368     use Term::ANSIColor;
369     print color 'bold blue';
370     print "This text is bold blue.\n";
371     print color 'reset';
372     print "This text is normal.\n";
373     print colored ("Yellow on magenta.\n", 'yellow on_magenta');
374     print "This text is normal.\n";
375     print colored ['yellow on_magenta'], "Yellow on magenta.\n";
376
377     use Term::ANSIColor qw(uncolor);
378     print uncolor '01;31', "\n";
379
380 But this isn't verbatim (make sure it wraps properly), and the next
381 paragraph is again:
382
383     use Term::ANSIColor qw(:constants);
384     print BOLD, BLUE, "This text is in bold blue.\n", RESET;
385
386     use Term::ANSIColor qw(:constants); $Term::ANSIColor::AUTORESET = 1; print BOLD BLUE "This text is in bold blue.\n"; print "This text is normal.\n";
387
388 (Ugh, that's obnoxiously long.)  Try different spacing:
389
390         Starting with a tab.
391 Not
392 starting
393 with
394 a
395 tab.  But this should still be verbatim.
396  As should this.
397
398 This isn't.
399
400  This is.  And this:    is an internal tab.  It should be:
401                     |--| <= lined up with that.
402
403 (Tricky, but tabs should be expanded before the translator starts in on
404 the text since otherwise text with mixed tabs and spaces will get messed
405 up.)
406
407     And now we test verbatim paragraphs right before a heading.  Older
408     versions of Pod::Man generated two spaces between paragraphs like this
409     and the heading.  (In order to properly test this, one may have to
410     visually inspect the nroff output when run on the generated *roff
411     text, unfortunately.)
412
413 =head1 CONCLUSION
414
415 That's all, folks!
416
417 =cut