1NAME
2    basic.pod - Test of various basic POD features in translators.
3
4HEADINGS
5    Try a few different levels of headings, with embedded formatting codes
6    and other interesting bits.
7
8This "is" a "level 1" heading
9  ``Level'' "2 *heading*
10   Level 3 heading *with "weird stuff "" (double quote)"*
11   Level "4 "heading"
12    Now try again with intermixed text.
13
14This "is" a "level 1" heading
15    Text.
16
17  ``Level'' 2 *heading*
18    Text.
19
20   Level 3 heading *with "weird stuff"*
21    Text.
22
23   Level "4 "heading"
24    Text.
25
26LINKS
27    These are all taken from the Pod::Parser tests.
28
29    Try out *LOTS* of different ways of specifying references:
30
31    Reference the "section" in manpage
32
33    Reference the "section" in "manpage"
34
35    Reference the "section" in manpage
36
37    Now try it using the new "|" stuff ...
38
39    Reference the thistext|
40
41    Reference the thistext |
42
43    Reference the thistext|
44
45    Reference the thistext |
46
47    Reference the thistext|
48
49    Reference the thistext|
50
51    And then throw in a few new ones of my own.
52
53    foo
54
55    foo
56
57    "bar" in foo
58
59    "baz boo" in foo
60
61    "bar"
62
63    "baz boo"
64
65    "baz boo"
66
67    "baz boo" in foo bar
68
69    "boo var baz"
70
71    "bar baz"
72
73    "boo", "bar", and "baz"
74
75    foobar
76
77    Testing *italics*
78
79    "*Italic* text" in foo
80
81    "Section "with" *other markup*" in foo|bar
82
83OVER AND ITEMS
84    Taken from Pod::Parser tests, this is a test to ensure that multiline
85    =item paragraphs get indented appropriately.
86
87    This is a test.
88
89    There should be whitespace now before this line.
90
91    Taken from Pod::Parser tests, this is a test to ensure the nested =item
92    paragraphs get indented appropriately.
93
94    1 First section.
95
96      a this is item a
97
98      b this is item b
99
100    2 Second section.
101
102      a this is item a
103
104      b this is item b
105
106      c
107      d This is item c & d.
108
109    Now some additional weirdness of our own. Make sure that multiple tags
110    for one paragraph are properly compacted.
111
112    "foo"
113    bar
114    "baz"
115        There shouldn't be any spaces between any of these item tags; this
116        idiom is used in perlfunc.
117
118    Some longer item text
119        Just to make sure that we test paragraphs where the item text
120        doesn't fit in the margin of the paragraph (and make sure that this
121        paragraph fills a few lines).
122
123        Let's also make it multiple paragraphs to be sure that works.
124
125    Test use of =over without =item as a block "quote" or block paragraph.
126
127        This should be indented four spaces but otherwise formatted the same
128        as any other regular text paragraph. Make sure it's long enough to
129        see the results of the formatting.....
130
131    Now try the same thing nested, and make sure that the indentation is
132    reset back properly.
133
134            This paragraph should be doubly indented.
135
136        This paragraph should only be singly indented.
137
138        *   This is an item in the middle of a block-quote, which should be
139            allowed.
140
141        *   We're also testing tagless item commands.
142
143        Should be back to the single level of indentation.
144
145    Should be back to regular indentation.
146
147    Now also check the transformation of * into real bullets for man pages.
148
149    *   An item. We're also testing using =over without a number, and making
150        sure that item text wraps properly.
151
152    *   Another item.
153
154    and now test the numbering of item blocks.
155
156    1.  First item.
157
158    2.  Second item.
159
160FORMATTING CODES
161    Another test taken from Pod::Parser.
162
163    This is a test to see if I can do not only $self and "method()", but
164    also "$self->method()" and "$self->{FIELDNAME}" and "$Foo <=> $Bar"
165    without resorting to escape sequences. If I want to refer to the
166    right-shift operator I can do something like "$x >> 3" or even "$y >>
167    5".
168
169    Now for the grand finale of "$self->method()->{FIELDNAME} = {FOO=>BAR}".
170    And I also want to make sure that newlines work like this
171    "$self->{FOOBAR} >> 3 and [$b => $a]->[$a <=> $b]"
172
173    Of course I should still be able to do all this *with* escape sequences
174    too: "$self->method()" and "$self->{FIELDNAME}" and "{FOO=>BAR}".
175
176    Don't forget "$self->method()->{FIELDNAME} = {FOO=>BAR}".
177
178    And make sure that 0 works too!
179
180    Now, if I use << or >> as my delimiters, then I have to use whitespace.
181    So things like "<$self-"method()>> and "<$self-"{FIELDNAME}>> won't end
182    up doing what you might expect since the first > will still terminate
183    the first < seen.
184
185    Lets make sure these work for empty ones too, like "" and ">>" (just to
186    be obnoxious)
187
188    The statement: "This is dog kind's *finest* hour!" is a parody of a
189    quotation from Winston Churchill.
190
191    The following tests are added to those:
192
193    Make sure that a few other odd *things* still work. This should be a
194    vertical bar: |. Here's a test of a few more special escapes that have
195    to be supported:
196
197    &  An ampersand.
198
199    '  An apostrophe.
200
201    <  A less-than sign.
202
203    >  A greater-than sign.
204
205    "  A double quotation mark.
206
207    /  A forward slash.
208
209    Try to get this bit of text over towards the edge so
210    |that all of this text inside S<> won't| be wrapped. Also test the
211    |same thing with non-breaking spaces.|
212
213    There is a soft hyphen in hyphen at hy-phen.
214
215    This is a test of an index entry.
216
217VERBATIM
218    Throw in a few verbatim paragraphs.
219
220        use Term::ANSIColor;
221        print color 'bold blue';
222        print "This text is bold blue.\n";
223        print color 'reset';
224        print "This text is normal.\n";
225        print colored ("Yellow on magenta.\n", 'yellow on_magenta');
226        print "This text is normal.\n";
227        print colored ['yellow on_magenta'], "Yellow on magenta.\n";
228
229        use Term::ANSIColor qw(uncolor);
230        print uncolor '01;31', "\n";
231
232    But this isn't verbatim (make sure it wraps properly), and the next
233    paragraph is again:
234
235        use Term::ANSIColor qw(:constants);
236        print BOLD, BLUE, "This text is in bold blue.\n", RESET;
237
238        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";
239
240    (Ugh, that's obnoxiously long.) Try different spacing:
241
242            Starting with a tab.
243    Not
244    starting
245    with
246    a
247    tab.  But this should still be verbatim.
248     As should this.
249
250    This isn't.
251
252     This is.  And this:    is an internal tab.  It should be:
253                        |--| <= lined up with that.
254
255    (Tricky, but tabs should be expanded before the translator starts in on
256    the text since otherwise text with mixed tabs and spaces will get messed
257    up.)
258
259        And now we test verbatim paragraphs right before a heading.  Older
260        versions of Pod::Man generated two spaces between paragraphs like this
261        and the heading.  (In order to properly test this, one may have to
262        visually inspect the nroff output when run on the generated *roff
263        text, unfortunately.)
264
265CONCLUSION
266    That's all, folks!
267
268COPYRIGHT AND LICENSE
269    Copyright 2001, 2004, 2016, 2018 Russ Allbery <rra@cpan.org>
270
271    Copying and distribution of this file, with or without modification, are
272    permitted in any medium without royalty provided the copyright notice
273    and this notice are preserved. This file is offered as-is, without any
274    warranty.
275
276    SPDX-License-Identifier: FSFAP
277
278