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