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