This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to podlators-1.19.
[perl5.git] / lib / Pod / t / basic.man
CommitLineData
b616daaf 1.SH "NAME"
2da3dd12 2basic.pod \- Test of various basic POD features in translators.
b616daaf
JH
3.SH "HEADINGS"
4.IX Header "HEADINGS"
5Try a few different levels of headings, with embedded formatting codes and
6other interesting bits.
7.ie n .SH "This ""is"" a ""level 1"" heading"
8.el .SH "This \f(CWis\fP a ``level 1'' heading"
9.IX Header "This is a level 1 heading"
10.Sh "``Level'' ""2 \fIheading\fP"
11.IX Subsection "``Level'' ""2 heading"
12\fILevel 3 \f(BIheading \f(BIwith \f(CB\*(C`weird \f(CBstuff "" (double quote)\f(CB\*(C'\f(BI\f(BI\fI\fR
13.IX Subsection "Level 3 heading with weird stuff """" (double quote)"
14.PP
15Level "4 \f(CW\*(C`heading\*(C'\fR
16.IX Subsection "Level ""4 heading"
17.PP
18Now try again with \fBintermixed\fR \fItext\fR.
19.ie n .SH "This ""is"" a ""level 1"" heading"
20.el .SH "This \f(CWis\fP a ``level 1'' heading"
21.IX Header "This is a level 1 heading"
22Text.
23.Sh "``Level'' 2 \fIheading\fP"
24.IX Subsection "``Level'' 2 heading"
25Text.
26.PP
27\fILevel 3 \f(BIheading \f(BIwith \f(CB\*(C`weird \f(CBstuff\f(CB\*(C'\f(BI\f(BI\fI\fR
28.IX Subsection "Level 3 heading with weird stuff"
29.PP
30Text.
31.PP
32Level "4 \f(CW\*(C`heading\*(C'\fR
33.IX Subsection "Level ""4 heading"
34.PP
35Text.
36.SH "LINKS"
37.IX Header "LINKS"
38These are all taken from the Pod::Parser tests.
39.PP
40Try out \fI\s-1LOTS\s0\fR of different ways of specifying references:
41.PP
42Reference the \*(L"section\*(R" in manpage
43.PP
44Reference the \*(L"section\*(R" in manpage
45.PP
46Reference the \*(L"section\*(R" in manpage
47.PP
48Reference the \*(L"section\*(R" in manpage
49.PP
50Reference the \*(L"manpage/section\*(R"
51.PP
52Reference the \*(L"section\*(R" in \*(L"manpage\*(R"
53.PP
54Reference the \*(L"section\*(R" in manpage
55.PP
56Reference the \*(L"section\*(R" in manpage
57.PP
58Reference the \*(L"section\*(R" in manpage
59.PP
60Now try it using the new \*(L"|\*(R" stuff ...
61.PP
62Reference the thistext|
63.PP
64Reference the thistext |
65.PP
66Reference the thistext|
67.PP
68Reference the thistext |
69.PP
70Reference the thistext|
71.PP
72Reference the thistext |
73.PP
74Reference the thistext|
75.PP
76Reference the thistext|
77.PP
78Reference the thistext |
79.PP
80And then throw in a few new ones of my own.
81.PP
82foo
83.PP
84foo
85.PP
86\&\*(L"bar\*(R" in foo
87.PP
88\&\*(L"baz boo\*(R" in foo
89.PP
90\&\*(L"bar\*(R"
91.PP
92\&\*(L"baz boo\*(R"
93.PP
94\&\*(L"baz boo\*(R"
95.PP
96\&\*(L"baz boo\*(R" in foo bar
97.PP
98\&\*(L"baz boo\*(R" in foo bar
99.PP
100\&\*(L"boo\*(R" in foo bar baz
101.PP
102\&\*(L"boo var baz\*(R"
103.PP
104\&\*(L"bar baz\*(R"
105.PP
106\&\*(L"boo bar baz / baz boo\*(R"
107.PP
108\&\*(L"boo\*(R", \*(L"bar\*(R", and \*(L"baz\*(R"
109.PP
110foo\&bar
111.PP
112Testing \fIitalics\fR
113.PP
114"\fIItalic\fR text" in foo
115.PP
116"Section \f(CW\*(C`with\*(C'\fR \fI\f(BIother\fI markup\fR" in foo|bar\&
117.PP
118Nested <http://www.perl.org/>
119.SH "OVER AND ITEMS"
120.IX Header "OVER AND ITEMS"
121Taken from Pod::Parser tests, this is a test to ensure that multiline
122=item paragraphs get indented appropriately.
123.IP "This is a test." 4
124.IX Item "This is a test."
125.PP
126There should be whitespace now before this line.
127.PP
128Taken from Pod::Parser tests, this is a test to ensure the nested =item
129paragraphs get indented appropriately.
130.IP "1" 2
131.IX Item "1"
132First section.
133.RS 2
134.IP "a" 2
135.IX Item "a"
136this is item a
137.IP "b" 2
138.IX Item "b"
139this is item b
140.RE
141.RS 2
142.RE
143.IP "2" 2
144.IX Item "2"
145Second section.
146.RS 2
147.IP "a" 2
148.IX Item "a"
149this is item a
150.IP "b" 2
151.IX Item "b"
152this is item b
153.IP "c" 2
154.IX Item "c"
155.PD 0
156.IP "d" 2
157.IX Item "d"
158.PD
159This is item c & d.
160.RE
161.RS 2
162.RE
163.PP
164Now some additional weirdness of our own. Make sure that multiple tags
165for one paragraph are properly compacted.
166.ie n .IP """foo""" 4
167.el .IP "``foo''" 4
168.IX Item "foo"
169.PD 0
170.IP "\fBbar\fR" 4
171.IX Item "bar"
172.ie n .IP """baz""" 4
173.el .IP "\f(CWbaz\fR" 4
174.IX Item "baz"
175.PD
176There shouldn't be any spaces between any of these item tags; this idiom
177is used in perlfunc.
178.IP "Some longer item text" 4
179.IX Item "Some longer item text"
180Just to make sure that we test paragraphs where the item text doesn't fit
181in the margin of the paragraph (and make sure that this paragraph fills a
182few lines).
183.Sp
184Let's also make it multiple paragraphs to be sure that works.
185.PP
186Test use of =over without =item as a block \*(L"quote\*(R" or block paragraph.
187.Sp
188.RS 4
189This should be indented four spaces but otherwise formatted the same as
190any other regular text paragraph. Make sure it's long enough to see the
191results of the formatting.....
192.RE
193.PP
194Now try the same thing nested, and make sure that the indentation is reset
195back properly.
196.RS 4
197.Sp
198.RS 4
199This paragraph should be doubly indented.
200.RE
201.RE
202.RS 4
203.Sp
204This paragraph should only be singly indented.
205.IP "\(bu" 4
206This is an item in the middle of a block\-quote, which should be allowed.
207.IP "\(bu" 4
208We're also testing tagless item commands.
209.RE
210.RS 4
211.Sp
212Should be back to the single level of indentation.
213.RE
214.PP
215Should be back to regular indentation.
216.PP
217Now also check the transformation of * into real bullets for man pages.
218.IP "\(bu" 4
219An item. We're also testing using =over without a number, and making sure
220that item text wraps properly.
221.IP "\(bu" 4
222Another item.
223.PP
224and now test the numbering of item blocks.
225.IP "1." 4
226First item.
227.IP "2." 4
228Second item.
229.SH "FORMATTING CODES"
230.IX Header "FORMATTING CODES"
231Another test taken from Pod::Parser.
232.PP
233This is a test to see if I can do not only \f(CW$self\fR and \f(CW\*(C`method()\*(C'\fR, but
234also \f(CW\*(C`$self\->method()\*(C'\fR and \f(CW\*(C`$self\->{FIELDNAME}\*(C'\fR and
235\&\f(CW\*(C`$Foo <=> $Bar\*(C'\fR without resorting to escape sequences. If
236I want to refer to the right-shift operator I can do something
237like \f(CW\*(C`$x >> 3\*(C'\fR or even \f(CW\*(C`$y >> 5\*(C'\fR.
238.PP
239Now for the grand finale of \f(CW\*(C`$self\->method()\->{FIELDNAME} = {FOO=>BAR}\*(C'\fR.
240And I also want to make sure that newlines work like this
241\&\f(CW\*(C`$self\->{FOOBAR} >> 3 and [$b => $a]\->[$a <=> $b]\*(C'\fR
242.PP
243Of course I should still be able to do all this \fIwith\fR escape sequences
244too: \f(CW\*(C`$self\->method()\*(C'\fR and \f(CW\*(C`$self\->{FIELDNAME}\*(C'\fR and
245\&\f(CW\*(C`{FOO=>BAR}\*(C'\fR.
246.PP
247Dont forget \f(CW\*(C`$self\->method()\->{FIELDNAME} = {FOO=>BAR}\*(C'\fR.
248.PP
249And make sure that \f(CW0\fR works too!
250.PP
251Now, if I use << or >> as my delimiters, then I have to use whitespace.
252So things like \f(CW\*(C`<$self\-\*(C'\fR\fImethod()\fR>> and \f(CW\*(C`<$self\-\*(C'\fR{\s-1FIELDNAME\s0}>> wont end
253up doing what you might expect since the first > will still terminate
254the first < seen.
255.PP
256Lets make sure these work for empty ones too, like and \f(CW\*(C`>>\*(C'\fR
257(just to be obnoxious)
258.PP
259The statement: \f(CW\*(C`This is dog kind's \f(CIfinest\f(CW hour!\*(C'\fR is a parody of a
260quotation from Winston Churchill.
261.PP
262The following tests are added to those:
263.PP
264Make sure that a few oth\&er odd \fI\&things\fR still work. This should be
265a vertical bar: |. Here's a test of a few more special escapes
266that have to be supported:
267.IP "&" 3
268An ampersand.
269.IP "'" 3
270An apostrophe.
271.IP "<" 3
272A less-than sign.
273.IP ">" 3
274A greater-than sign.
275.IP """" 3
276A double quotation mark.
277.IP "/" 3
278A forward slash.
279.PP
280Try to get this bit of text over towards the edge so |that\ all\ of\ this\ text\ inside\ S<>\ won't| be wrapped. Also test the
281|same\ thing\ with\ non-breaking\ spaces.|
282.PP
283There is a soft hyphen in hyphen at hy\-phen.
284.PP
285This is a test of an index entry.
286.IX Xref "index entry"
287.SH "VERBATIM"
288.IX Header "VERBATIM"
289Throw in a few verbatim paragraphs.
290.PP
291.Vb 8
292\& use Term::ANSIColor;
293\& print color 'bold blue';
294\& print "This text is bold blue.\en";
295\& print color 'reset';
296\& print "This text is normal.\en";
297\& print colored ("Yellow on magenta.\en", 'yellow on_magenta');
298\& print "This text is normal.\en";
299\& print colored ['yellow on_magenta'], "Yellow on magenta.\en";
300.Ve
2da3dd12 301.PP
b616daaf
JH
302.Vb 2
303\& use Term::ANSIColor qw(uncolor);
304\& print uncolor '01;31', "\en";
305.Ve
2da3dd12 306.PP
b616daaf
JH
307But this isn't verbatim (make sure it wraps properly), and the next
308paragraph is again:
309.PP
310.Vb 2
311\& use Term::ANSIColor qw(:constants);
312\& print BOLD, BLUE, "This text is in bold blue.\en", RESET;
313.Ve
2da3dd12 314.PP
b616daaf
JH
315.Vb 1
316\& use Term::ANSIColor qw(:constants); $Term::ANSIColor::AUTORESET = 1; print BOLD BLUE "This text is in bold blue.\en"; print "This text is normal.\en";
317.Ve
2da3dd12 318.PP
b616daaf
JH
319(Ugh, that's obnoxiously long.) Try different spacing:
320.PP
321.Vb 7
322\& Starting with a tab.
323\&Not
324\&starting
325\&with
326\&a
327\&tab. But this should still be verbatim.
328\& As should this.
329.Ve
2da3dd12 330.PP
b616daaf
JH
331This isn't.
332.PP
333.Vb 2
334\& This is. And this: is an internal tab. It should be:
335\& |--| <= lined up with that.
336.Ve
2da3dd12 337.PP
b616daaf
JH
338(Tricky, but tabs should be expanded before the translator starts in on
339the text since otherwise text with mixed tabs and spaces will get messed
340up.)
2da3dd12
AMS
341.PP
342.Vb 5
343\& And now we test verbatim paragraphs right before a heading. Older
344\& versions of Pod::Man generated two spaces between paragraphs like this
345\& and the heading. (In order to properly test this, one may have to
346\& visually inspect the nroff output when run on the generated *roff
347\& text, unfortunately.)
348.Ve
349.SH "CONCLUSION"
350.IX Header "CONCLUSION"
351That's all, folks!