.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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 "Dist::Zilla::Plugin::TemplateCJM 3pm"
.TH Dist::Zilla::Plugin::TemplateCJM 3pm "2012-06-04" "perl v5.14.2" "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"
Dist::Zilla::Plugin::TemplateCJM \- Process templates, including version numbers & changes
.SH "VERSION"
.IX Header "VERSION"
This document describes version 4.09 of
Dist::Zilla::Plugin::TemplateCJM, released June 4, 2012
as part of Dist-Zilla-Plugins-CJM version 4.09.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In your \fIdist.ini\fR:
.PP
.Vb 5
\&  [TemplateCJM]
\&  changelog = Changes      ; this is the default
\&  changes   = 1            ; this is the default
\&  file      = README       ; this is the default
\&  report_versions = 1      ; this is the default
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This plugin is the successor to Module::Build::DistVersion.
It performs the following actions:
.IP "1." 4
It opens the \fIChanges\fR file, and finds the first version listed.  The
line must begin with the version number, and everything after the
version number is considered to be the release date.  The version
number from Changes must match Dist::Zilla's idea of the
distribution version, or the process stops here with an error.
.IP "2." 4
It processes each template file with Text::Template.  Template files
are specified with the \f(CW\*(C`file\*(C'\fR attribute.  Any number of
templates may be present.
.Sp
Each template may use the following variables:
.RS 4
.ie n .IP "$changes" 4
.el .IP "\f(CW$changes\fR" 4
.IX Item "$changes"
The changes in the current release.  This is a string containing all
lines in \fIChanges\fR following the version/release date line up to (but
not including) the next line that begins with a non-whitespace
character (or end-of-file).  The string does \fBnot\fR end with a newline
(since version 0.08).
.Sp
You can include the changes from more than one release by setting the
\&\*(L"changes\*(R" in \f(CW\*(C`changes\*(C'\fR attribute.  This is useful when you make a
major release immediately followed by a bugfix release.
.ie n .IP "$date" 4
.el .IP "\f(CW$date\fR" 4
.IX Item "$date"
The release date as it appeared in \fIChanges\fR.
.ie n .IP "$dist" 4
.el .IP "\f(CW$dist\fR" 4
.IX Item "$dist"
The name of the distribution.
.ie n .IP "%meta" 4
.el .IP "\f(CW%meta\fR" 4
.IX Item "%meta"
The hash of metadata that will be stored in \fI\s-1META\s0.yml\fR.
.ie n .IP "$t" 4
.el .IP "\f(CW$t\fR" 4
.IX Item "$t"
The TemplateCJM object that is processing the template.
.ie n .IP "$version" 4
.el .IP "\f(CW$version\fR" 4
.IX Item "$version"
The distribution's version number.  (Also available as \f(CW$dist_version\fR.)
.ie n .IP "$zilla" 4
.el .IP "\f(CW$zilla\fR" 4
.IX Item "$zilla"
The Dist::Zilla object that is creating the distribution.
.RE
.RS 4
.RE
.IP "3." 4
For each module to be installed, it processes each \s-1POD\s0 section and
each comment that starts at the beginning of a line through
Text::Template.
.Sp
Each section may use the same variables as step 2, plus the following:
.RS 4
.ie n .IP "$module" 4
.el .IP "\f(CW$module\fR" 4
.IX Item "$module"
The name of the module being processed (i.e., its package).
.ie n .IP "$pm_info" 4
.el .IP "\f(CW$pm_info\fR" 4
.IX Item "$pm_info"
A Module::Metadata object containing information about the
module.  (Note that the filename in \f(CW$pm_info\fR will not be correct.)
.ie n .IP "$version" 4
.el .IP "\f(CW$version\fR" 4
.IX Item "$version"
The module's version number.  This may be different than the
distribution's version, which is available as \f(CW$dist_version\fR.
.RE
.RS 4
.RE
.PP
It also peforms a BeforeRelease
check to ensure that the release date in the changelog is not a single
uppercase word.  (I set the date to \s-1NOT\s0 until I'm ready to release.)
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "changelog"
.IX Subsection "changelog"
This is the name of the \fIChanges\fR file.  It defaults to \fIChanges\fR.
.SS "changelog_re"
.IX Subsection "changelog_re"
This is the regex used to extract the version and release date from
the \fIChanges\fR file.  It defaults to \f(CW\*(C`(\ed[\ed._]*)\es+(.+)\*(C'\fR
(i.e. version number at beginning of the line, followed by whitespace,
and everything after that is the release date).  It it automatically
anchored at the beginning of the line.  Note: your version lines
\&\fImust not\fR begin with whitespace.  All other lines \fImust\fR begin with
whitespace.
.SS "changes"
.IX Subsection "changes"
This is the number of releases to include in the \f(CW$changes\fR variable
passed to templates.  It defaults to 1 (meaning only changes in the
current release).  This is useful when you make a major release
immediately followed by a bugfix release.
.SS "file"
.IX Subsection "file"
This is the name of a file to process with Text::Template in step 2.
The \f(CW\*(C`file\*(C'\fR attribute may be listed any number of times.  If you don't
list any \f(CW\*(C`file\*(C'\fRs, it defaults to \fI\s-1README\s0\fR.  If you do specify any
\&\f(CW\*(C`file\*(C'\fRs, then \fI\s-1README\s0\fR is not processed unless explicitly specified.
.SS "finder"
.IX Subsection "finder"
This FileFinder provides the list of files that are processed in step
3.  The default is \f(CW\*(C`:InstallModules\*(C'\fR.  The \f(CW\*(C`finder\*(C'\fR attribute may be
listed any number of times.
.SS "report_versions"
.IX Subsection "report_versions"
If true (the default), report the version of each module processed.
.SH "METHODS"
.IX Header "METHODS"
.SS "build_instructions"
.IX Subsection "build_instructions"
.Vb 1
\&  $t\->build_instructions( [$prefix] )
.Ve
.PP
A template can use this method to add build instructions for the
distribution (normally used in \s-1README\s0).  \f(CW$prefix\fR is prepended to
each line, and defaults to a single \s-1TAB\s0.
.PP
It returns either
.PP
.Vb 4
\&        perl Build.PL
\&        ./Build
\&        ./Build test
\&        ./Build install
.Ve
.PP
or
.PP
.Vb 4
\&        perl Makefile.PL
\&        make
\&        make test
\&        make install
.Ve
.PP
depending on whether your distribution includes a Build.PL.  The
string will \s-1NOT\s0 end with a newline.
.PP
It throws an error if neither Build.PL nor Makefile.PL is found.
.SS "dependency_link"
.IX Subsection "dependency_link"
.Vb 1
\&  $t\->dependency_link(\*(AqFoo::Bar\*(Aq)
.Ve
.PP
A template can use this method to add a link to the documentation of a
required module.  It returns either
.PP
.Vb 1
\&  L<Foo::Bar> (VERSION or later)
.Ve
.PP
or
.PP
.Vb 1
\&  L<Foo::Bar>
.Ve
.PP
depending on whether \s-1VERSION\s0 is non-zero.  (It determines \s-1VERSION\s0 by
checking \f(CW\*(C`requires\*(C'\fR and \f(CW\*(C`recommends\*(C'\fR in your prerequisites.)
.SS "dependency_list"
.IX Subsection "dependency_list"
.Vb 1
\&  $t\->dependency_list
.Ve
.PP
A template can use this method to add a list of required modules.
It returns a string like:
.PP
.Vb 5
\&  Package                Minimum Version
\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  perl                    5.8.0
\&  List::Util
\&  Moose                   0.90
.Ve
.PP
If \f(CW\*(C`perl\*(C'\fR is one of he dependencies, it is listed first.  All other
dependencies are listed in ASCIIbetical order.  The string will \s-1NOT\s0
end with a newline.
.PP
If there are no dependencies, the string \f(CW\*(C`None.\*(C'\fR will be returned.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
TemplateCJM requires Dist::Zilla (4.300009 or later) and
Text::Template.  I also recommend applying \fITemplate_strict.patch\fR
to Text::Template.  This will add support for the \s-1STRICT\s0 option, which
will help catch errors in your templates.
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.SH "AUTHOR"
.IX Header "AUTHOR"
Christopher J. Madsen  \f(CW\*(C`<perl\ AT\ cjmweb.net>\*(C'\fR
.PP
Please report any bugs or feature requests
to \f(CW\*(C`<bug\-Dist\-Zilla\-Plugins\-CJM\ AT\ rt.cpan.org>\*(C'\fR
or through the web interface at
http://rt.cpan.org/Public/Bug/Report.html?Queue=Dist\-Zilla\-Plugins\-CJM <http://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Zilla-Plugins-CJM>.
.PP
You can follow or contribute to Dist-Zilla-Plugins-CJM's development at
http://github.com/madsen/dist\-zilla\-plugins\-cjm <http://github.com/madsen/dist-zilla-plugins-cjm>.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 by Christopher J. Madsen.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0
\&\s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0 \s-1WHEN\s0
\&\s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0
\&\s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EITHER\s0
\&\s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0
\&\s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. \s-1THE\s0
\&\s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0
\&\s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0 \s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0
\&\s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0.
.PP
\&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0
\&\s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0
\&\s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENSE\s0, \s-1BE\s0
\&\s-1LIABLE\s0 \s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0,
\&\s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0
\&\s-1THE\s0 \s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0
\&\s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A
\&\s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0
\&\s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0
\&\s-1SUCH\s0 \s-1DAMAGES\s0.