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