.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POD2README 1p"
.TH POD2README 1p "2018-11-26" "perl v5.28.0" "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"
pod2readme \- Intelligently generate a README file from POD
.SH "USAGE"
.IX Header "USAGE"
.Vb 1
\&    pod2readme [\-cfho] [long options...] input\-file [output\-file] [target]
\&
\&        Intelligently generate a README file from POD
\&
\&        \-t \-\-target     target type (default: \*(Aqreadme\*(Aq)
\&        \-f \-\-format     output format (default: \*(Aqtext\*(Aq)
\&        \-b \-\-backup     backup output file
\&        \-o \-\-output     output filename (default based on target)
\&        \-c \-\-stdout     output to stdout (console)
\&        \-F \-\-force      only update if files are changed
\&        \-h \-\-help       print usage and exit
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    pod2readme \-f markdown lib/MyApp.pm
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This utility will use Pod::Readme to extract a \fI\s-1README\s0\fR file from
a \s-1POD\s0 document.
.PP
It works by extracting and filtering the \s-1POD,\s0 and then calling the
appropriate filter program to convert the \s-1POD\s0 to another format.
.SH "OPTIONS"
.IX Header "OPTIONS"
.ie n .SS """\-\-backup"""
.el .SS "\f(CW\-\-backup\fP"
.IX Subsection "--backup"
By default, \f(CW\*(C`pod2readme\*(C'\fR will back up the output file. To disable
this, use the \f(CW\*(C`\-\-no\-backup\*(C'\fR option.
.ie n .SS """\-\-output"""
.el .SS "\f(CW\-\-output\fP"
.IX Subsection "--output"
Specifies the name of the output file. If omitted, it will use the
second command line argument, or default to the \f(CW\*(C`\-\-target\*(C'\fR plus the
corresponding extension of the \f(CW\*(C`\-\-format\*(C'\fR.
.PP
For all intents, the default is \fI\s-1README\s0\fR.
.PP
If a format other than \*(L"text\*(R" is chosen, then the appropriate
extension will be added, e.g. for \*(L"markdown\*(R", the default output file
is \fI\s-1README\s0.md\fR.
.ie n .SS """\-\-target"""
.el .SS "\f(CW\-\-target\fP"
.IX Subsection "--target"
The target of the filter, which defaults to \*(L"readme\*(R".
.ie n .SS """\-\-format"""
.el .SS "\f(CW\-\-format\fP"
.IX Subsection "--format"
The output format, which defaults to \*(L"text\*(R".
.PP
Other supposed formats are \*(L"github\*(R", \*(L"html\*(R", \*(L"latex\*(R", \*(L"man\*(R",
\&\*(L"markdown\*(R", \*(L"pod\*(R", \*(L"rtf\*(R", and \*(L"xhtml\*(R". You can also use \*(L"gfm\*(R"
instead of \*(L"github\*(R". Similary you can use \*(L"md\*(R" for \*(L"markdown\*(R".
.ie n .SS """\-\-stdout"""
.el .SS "\f(CW\-\-stdout\fP"
.IX Subsection "--stdout"
If enabled, it will output to the console instead of \f(CW\*(C`\-\-output\*(C'\fR.
.ie n .SS """\-\-force"""
.el .SS "\f(CW\-\-force\fP"
.IX Subsection "--force"
By default, the \fI\s-1README\s0\fR will be generated if the source files have
been changed.  Using \f(CW\*(C`\-\-force\*(C'\fR will force the file to be updated.
.PP
Note: \s-1POD\s0 format files will always be updated.
.ie n .SS """\-\-help"""
.el .SS "\f(CW\-\-help\fP"
.IX Subsection "--help"
Prints the usage and exits.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
pod2text, pod2markdown.