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