56
56
<li><a href="http://search.cpan.org">CPAN</a></li>
57
<li><a href="http://www.perl.org">Perl.org</a></li>
57
58
<li><a href="http://www.perl.com">Perl.com</a></li>
58
<li><a href="http://www.perl.org">Perl.org</a></li>
59
<li><a href="http://perlbuzz.com">Perl Buzz</a></li>
60
<li><a href="http://www.perlfoundation.org/perl5/index.cgi">Perl 5 Wiki</a></li>
61
<li><a href="http://jobs.perl.org">Perl Jobs</a></li>
59
62
<li><a href="http://www.pm.org">Perl Mongers</a></li>
60
63
<li><a href="http://www.perlmonks.org">Perl Monks</a></li>
61
64
<li><a href="http://planet.perl.org">Planet Perl</a></li>
66
69
<li>Site maintained by<br><a href="http://perl.jonallen.info">Jon Allen</a>
67
70
(<a href="http://perl.jonallen.info">JJ</a>)</li>
68
<li class="spaced">Last updated on<br>23 April 2006</li>
71
<li class="spaced">Last updated on<br>23 December 2007</li>
69
72
<li class="spaced">See the <a href="http://perl.jonallen.info/projects/perldoc">project page</a> for
76
79
<div id="centerContent">
77
80
<div id="contentHeader">
78
81
<div id="contentHeaderLeft"><a href="#" onClick="showLeft()">Show navigation</a></div>
79
<div id="contentHeaderCentre">-- Perl 5.8.8 documentation --</div>
82
<div id="contentHeaderCentre">-- Perl 5.10.0 documentation --</div>
80
83
<div id="contentHeaderRight"><a href="#" onClick="showRight()">Show toolbar</a></div>
82
85
<div id="breadCrumbs"><a href="../index.html">Home</a> > <a href="../index-modules-A.html">Core modules</a> > <a href="../index-modules-P.html">P</a> > Pod::Text</div>
83
86
<script language="JavaScript">fromSearch();</script>
84
<div id="contentBody"><div class="title_container"><div class="page_title">Pod::Text</div></div><ul><li><a href="#NAME">NAME</a><li><a href="#SYNOPSIS">SYNOPSIS</a><li><a href="#DESCRIPTION">DESCRIPTION</a><li><a href="#DIAGNOSTICS">DIAGNOSTICS</a><li><a href="#RESTRICTIONS">RESTRICTIONS</a><li><a href="#NOTES">NOTES</a><li><a href="#SEE-ALSO">SEE ALSO</a><li><a href="#AUTHOR">AUTHOR</a><li><a href="#COPYRIGHT-AND-LICENSE">COPYRIGHT AND LICENSE</a></ul><a name="NAME"></a><h1>NAME</h1>
87
<div id="contentBody"><div class="title_container"><div class="page_title">Pod::Text</div></div><ul><li><a href="#NAME">NAME</a><li><a href="#SYNOPSIS">SYNOPSIS</a><li><a href="#DESCRIPTION">DESCRIPTION</a><li><a href="#DIAGNOSTICS">DIAGNOSTICS</a><li><a href="#NOTES">NOTES</a><li><a href="#SEE-ALSO">SEE ALSO</a><li><a href="#AUTHOR">AUTHOR</a><li><a href="#COPYRIGHT-AND-LICENSE">COPYRIGHT AND LICENSE</a></ul><a name="NAME"></a><h1>NAME</h1>
85
88
<p>Pod::Text - Convert POD data to formatted ASCII text</p>
86
89
<a name="SYNOPSIS"></a><h1>SYNOPSIS</h1>
87
<pre class="verbatim"> <a class="l_k" href="../functions/use.html">use</a> <a class="l_w" href="../Pod/Text.html">Pod::Text</a><span class="sc">;</span>
88
<a class="l_k" href="../functions/my.html">my</a> <span class="i">$parser</span> = <a class="l_w" href="../Pod/Text.html">Pod::Text</a>->new <span class="s">(</span>sentence <span class="cm">=></span> <span class="n">0</span><span class="cm">,</span> width <span class="cm">=></span> <span class="n">78</span><span class="s">)</span><span class="sc">;</span></pre>
90
<pre class="verbatim"> <a class="l_k" href="../functions/use.html">use</a> <span class="w">Pod::Text</span><span class="sc">;</span>
91
<a class="l_k" href="../functions/my.html">my</a> <span class="i">$parser</span> = <span class="w">Pod::Text</span><span class="w">->new</span> <span class="s">(</span><span class="w">sentence</span> <span class="cm">=></span> <span class="n">0</span><span class="cm">,</span> <span class="w">width</span> <span class="cm">=></span> <span class="n">78</span><span class="s">)</span><span class="sc">;</span></pre>
89
92
<pre class="verbatim"> <span class="c"># Read POD from STDIN and write to STDOUT.</span>
90
93
<span class="i">$parser</span><span class="i">->parse_from_filehandle</span><span class="sc">;</span></pre>
91
94
<pre class="verbatim"> <span class="c"># Read POD from file.pod and write to file.txt.</span>
95
98
preferred language for documenting Perl) into formatted ASCII. It uses no
96
99
special formatting controls or codes whatsoever, and its output is therefore
97
100
suitable for nearly any device.</p>
98
<p>As a derived class from Pod::Parser, Pod::Text supports the same methods and
99
interfaces. See <a href="../Pod/Parser.html">Pod::Parser</a> for all the details; briefly, one creates a
100
new parser with <code class="inline"><a class="l_w" href="../Pod/Text.html">Pod::Text</a>->new<span class="s">(</span><span class="s">)</span></code>
101
and then calls either
102
parse_from_filehandle() or parse_from_file().</p>
101
<p>As a derived class from Pod::Simple, Pod::Text supports the same methods and
102
interfaces. See <a href="../Pod/Simple.html">Pod::Simple</a> for all the details; briefly, one creates a
103
new parser with <code class="inline"><span class="w">Pod::Text</span><span class="w">->new</span><span class="s">(</span><span class="s">)</span></code>
104
and then normally calls parse_file().</p>
103
105
<p>new() can take options, in the form of key/value pairs, that control the
104
106
behavior of the parser. The currently recognized options are:</p>
142
144
characters, the first character is used as the left quote and the second as
143
145
the right quoted; and if it is four characters, the first two are used as
144
146
the left quote and the second two as the right quote.</p>
145
<p>This may also be set to the special value <code class="inline">none</code>
147
<p>This may also be set to the special value <code class="inline"><span class="w">none</span></code>
146
148
, in which case no quote
147
149
marks are added around C<> text.</p>
156
158
<p>The column at which to wrap text on the right-hand side. Defaults to 76.</p>
159
<p>The standard Pod::Parser method parse_from_filehandle() takes up to two
160
arguments, the first being the file handle to read POD from and the second
161
being the file handle to write the formatted output to. The first defaults
162
to STDIN if not given, and the second defaults to STDOUT. The method
163
parse_from_file() is almost identical, except that its two arguments are the
164
input and output disk files instead. See <a href="../Pod/Parser.html">Pod::Parser</a> for the specific
161
<p>The standard Pod::Simple method parse_file() takes one argument, the file or
162
file handle to read from, and writes output to standard output unless that
163
has been changed with the output_fh() method. See <a href="../Pod/Simple.html">Pod::Simple</a> for the
164
specific details and for other alternative interfaces.</p>
166
165
<a name="DIAGNOSTICS"></a><h1>DIAGNOSTICS</h1>
168
167
<li><a name="Bizarre-space-in-item"></a><b>Bizarre space in item</b>
180
179
<p>(F) The quote specification given (the quotes option to the constructor) was
181
180
invalid. A quote specification must be one, two, or four characters long.</p>
183
<li><a name="%25s%3a%25d%3a-Unknown-command-paragraph%3a-%25s"></a><b>%s:%d: Unknown command paragraph: %s</b>
184
<p>(W) The POD source contained a non-standard command paragraph (something of
185
the form <code class="inline"><span class="pd">=command args</span></code>
186
) that Pod::Man didn't know about. It was ignored.</p>
188
<li><a name="%25s%3a%25d%3a-Unknown-escape%3a-%25s"></a><b>%s:%d: Unknown escape: %s</b>
189
<p>(W) The POD source contained an <code class="inline">E<></code>
190
escape that Pod::Text didn't
193
<li><a name="%25s%3a%25d%3a-Unknown-formatting-code%3a-%25s"></a><b>%s:%d: Unknown formatting code: %s</b>
194
<p>(W) The POD source contained a non-standard formatting code (something of
195
the form <code class="inline">X<></code>
196
) that Pod::Text didn't know about.</p>
198
<li><a name="%25s%3a%25d%3a-Unmatched-%3dback"></a><b>%s:%d: Unmatched =back</b>
199
<p>(W) Pod::Text encountered a <code class="inline"><span class="pd">=back</span></code>
200
command that didn't correspond to an
201
<code class="inline"><span class="pd">=over</span></code>
205
<a name="RESTRICTIONS"></a><h1>RESTRICTIONS</h1>
206
<p>Embedded Ctrl-As (octal 001) in the input will be mapped to spaces on
207
output, due to an internal implementation detail.</p>
208
183
<a name="NOTES"></a><h1>NOTES</h1>
209
184
<p>This is a replacement for an earlier Pod::Text module written by Tom
210
Christiansen. It has a revamped interface, since it now uses Pod::Parser,
185
Christiansen. It has a revamped interface, since it now uses Pod::Simple,
211
186
but an interface roughly compatible with the old Pod::Text::pod2text()
212
187
function is still available. Please change to the new calling convention,
216
191
get it to work at all. This rewrite doesn't even try to do that, but a
217
192
subclass of it does. Look for <a href="../Pod/Text/Termcap.html">Pod::Text::Termcap</a>.</p>
218
193
<a name="SEE-ALSO"></a><h1>SEE ALSO</h1>
219
<p><a href="../Pod/Parser.html">Pod::Parser</a>, <a href="../Pod/Text/Termcap.html">Pod::Text::Termcap</a>, <i>pod2text(1)</i></p>
194
<p><a href="../Pod/Simple.html">Pod::Simple</a>, <a href="../Pod/Text/Termcap.html">Pod::Text::Termcap</a>, <i>pod2text(1)</i></p>
220
195
<p>The current version of this module is always available from its web site at
221
196
<a href="http://www.eyrie.org/~eagle/software/podlators/">http://www.eyrie.org/~eagle/software/podlators/</a>. It is also part of the
222
197
Perl core distribution as of 5.6.0.</p>
223
198
<a name="AUTHOR"></a><h1>AUTHOR</h1>
224
199
<p>Russ Allbery <rra@stanford.edu>, based <i>very</i> heavily on the original
225
200
Pod::Text by Tom Christiansen <tchrist@mox.perl.com> and its conversion to
226
Pod::Parser by Brad Appleton <bradapp@enteract.com>.</p>
201
Pod::Parser by Brad Appleton <bradapp@enteract.com>. Sean Burke's initial
202
conversion of Pod::Man to use Pod::Simple provided much-needed guidance on
203
how to use Pod::Simple.</p>
227
204
<a name="COPYRIGHT-AND-LICENSE"></a><h1>COPYRIGHT AND LICENSE</h1>
228
<p>Copyright 1999, 2000, 2001, 2002 by Russ Allbery <rra@stanford.edu>.</p>
205
<p>Copyright 1999, 2000, 2001, 2002, 2004, 2006 Russ Allbery <rra@stanford.edu>.</p>
229
206
<p>This program is free software; you may redistribute it and/or modify it
230
207
under the same terms as Perl itself.</p>
added
removed
Pod/Text.html
