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