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