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