.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Pod::Readme 3pm"
.TH Pod::Readme 3pm "2010-12-09" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Pod::Readme \- Convert POD to README file
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Pod::Readme;
\&  my $parser = Pod::Readme\->new();
\&
\&  # Read POD from STDIN and write to STDOUT
\&  $parser\->parse_from_filehandle;
\&
\&  # Read POD from Module.pm and write to README
\&  $parser\->parse_from_file(\*(AqModule.pm\*(Aq, \*(AqREADME\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a subclass of Pod::PlainText which provides additional
\&\s-1POD\s0 markup for generating \fI\s-1README\s0\fR files.
.PP
Why should one bother with this? One can simply use
.PP
.Vb 1
\&  pod2text Module.pm > README
.Ve
.PP
A problem with doing that is that the default pod2text converter will
add text to links, so that \*(L"L<Module>\*(R" is translated to
\&\*(L"the Module manpage\*(R".
.PP
Another problem is that the \fI\s-1README\s0\fR includes the entirety of
the module documentation!  Most people browsing the \fI\s-1README\s0\fR file do not
need all of this information.
.PP
Likewise, including installation and requirement information in the 
module documentation is not necessary either, since the module is already
installed.
.PP
This module allows authors to mark portions of the \s-1POD\s0 to be included only
in, or to be excluded from the \fI\s-1README\s0\fR file.  It also allows you to
include portions of another file (such as a separate \fIChangeLog\fR).
.SS "Markup"
.IX Subsection "Markup"
Special \s-1POD\s0 markup options are described below:
.IP "begin/end" 4
.IX Item "begin/end"
.Vb 1
\&  =begin readme
\&
\&  =head1 README ONLY
\&
\&  This section will only show up in the README file.
\&
\&  =end readme
.Ve
.Sp
Delineates a \s-1POD\s0 section that is only available in \s-1README\s0 file. If
you prefer to include plain text instead, add the \f(CW\*(C`text\*(C'\fR modifier:
.Sp
.Vb 1
\&  =begin readme text
\&
\&  README ONLY (PLAINTEXT)
\&
\&      This section will only show up in the README file.
\&
\&  =end readme
.Ve
.Sp
Note that placing a colon before the section to indicate that it is
\&\s-1POD\s0 (e.g. \f(CW\*(C`begin :readme\*(C'\fR) is not supported in this version.
.IP "stop/continue" 4
.IX Item "stop/continue"
.Vb 1
\&  =for readme stop
.Ve
.Sp
All \s-1POD\s0 that follows will not be included in the \s-1README\s0, until
a \f(CW\*(C`continue\*(C'\fR command occurs:
.Sp
.Vb 1
\&  =for readme continue
.Ve
.IP "include" 4
.IX Item "include"
.Vb 1
\&  =for readme include file=filename type=type start=Regexp stop=Regexp
\&
\&  =for readme include file=Changes start=^0.09 stop=^0.081 type=text
.Ve
.Sp
Includes a plaintext file named \fIfilename\fR, starting with the line
that contains the start \f(CW\*(C`Regexp\*(C'\fR and ending at the line that begins
with the stop \f(CW\*(C`Regexp\*(C'\fR.  (The start and stop Regexps are optional: one
or both may be omitted.)
.Sp
Type may be \f(CW\*(C`text\*(C'\fR or \f(CW\*(C`pod\*(C'\fR. If omitted, \f(CW\*(C`pod\*(C'\fR will be assumed.
.Sp
Quotes may be used when the filename or marks contains spaces:
.Sp
.Vb 1
\&  =for readme include file="another file.pod"
.Ve
.PP
One can also using maintain multiple file types (such as including \fI\s-1TODO\s0\fR,
or \fI\s-1COPYING\s0\fR) by using a modified constructor:
.PP
.Vb 1
\&  $parser = Pod::Readme\->new( readme_type => "copying" );
.Ve
.PP
In the above \*(L"Markup\*(R" commands replace \*(L"readme\*(R" with the tag specified
instead (such as \*(L"copying\*(R"):
.PP
.Vb 1
\&  =begin copying
.Ve
.PP
As of version 0.03 you can specify multiple sections by separating them
with a comma:
.PP
.Vb 1
\&  =begin copying,readme
.Ve
.PP
There is also no standard list of type names.  Some names might be recognized
by other \s-1POD\s0 processors (such as \*(L"testing\*(R" or \*(L"html\*(R").  Pod::Readme will
reject the following \*(L"known\*(R" type names when they are specified in the
constructor:
.PP
.Vb 1
\&    testing html xhtml xml docbook rtf man nroff dsr rno latex tex code
.Ve
.PP
You can also use a \*(L"debug\*(R" mode to diagnose any problems, such as mistyped
format names:
.PP
.Vb 1
\&  $parser = Pod::Readme\->new( debug => 1 );
.Ve
.PP
Warnings will be issued for any ignored formatting commands.
.SS "Example"
.IX Subsection "Example"
For an example, see the \fIReadme.pm\fR file in this distribution.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See perlpod, perlpodspec and podlators.
.SH "AUTHOR"
.IX Header "AUTHOR"
Originally by Robert Rothenberg <rrwo at cpan.org>
.PP
Now maintained by David Precious <davidp@preshweb.co.uk>
.SS "Suggestions, Bug Reporting and Contributing"
.IX Subsection "Suggestions, Bug Reporting and Contributing"
This module is developed on GitHub at:
.PP
http://github.com/bigpresh/Pod\-Readme
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (c) 2005,2006 Robert Rothenberg. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.PP
Some portions are based on Pod::PlainText 2.02.