Dist::Zilla::Plugin::ReadmeAnyFromPod(3pm)

1Dist::Zilla::Plugin::ReUasdemreACnoynFtrroimbPuotde(d3D)Piesrtl::DZoiclulmae:n:tPaltuigoinn::ReadmeAnyFromPod(3)
2
3
4

NAME

6       Dist::Zilla::Plugin::ReadmeAnyFromPod - Automatically convert POD to a
7       README in any format for Dist::Zilla
8

VERSION

10       version 0.163250
11

SYNOPSIS

13       In your dist.ini
14
15           [ReadmeAnyFromPod]
16           ; Default is plaintext README in build dir
17
18           ; Using non-default options: POD format with custom filename in
19           ; dist root, outside of build. Including this README in version
20           ; control makes Github happy.
21           [ReadmeAnyFromPod / ReadmePodInRoot]
22           type = pod
23           filename = README.pod
24           location = root
25
26           ; Using plugin name autodetection: Produces README.html in root
27           [ ReadmeAnyFromPod / HtmlInRoot ]
28

DESCRIPTION

30       Generates a README for your Dist::Zilla powered dist from its
31       "main_module" in any of several formats. The generated README can be
32       included in the build or created in the root of your dist for e.g.
33       inclusion into version control.
34
35   PLUGIN NAME AUTODETECTION
36       If you give the plugin an appropriate name (a string after the slash)
37       in your dist.ini, it will can parse the "type" and "location"
38       attributes from it. The format is "Readme[TYPE]In[LOCATION]". The words
39       "Readme" and "In" are optional, and the whole name is case-insensitive.
40       The SYNOPSIS section above gives one example.
41
42       When run with "location = dist", this plugin runs in the "FileMunger"
43       phase to create the new file. If it runs before another "FileMunger"
44       plugin does, that happens to modify the input pod (like, say,
45       "[PodWeaver]"), the README file contents will be recalculated, along
46       with a warning that you should modify your dist.ini by referencing
47       "[ReadmeAnyFromPod]" lower down in the file (the build still works, but
48       is less efficient).
49

ATTRIBUTES

51   type
52       The file format for the readme. Supported types are "text", "markdown",
53       "gfm" (Github-flavored markdown), "pod", and "html". Note that you are
54       not advised to create a .pod file in the dist itself, as
55       ExtUtils::MakeMaker will install that, both into "PERL5LIB" and
56       "MAN3DIR".
57
58   filename
59       The file name of the README file to produce. The default depends on the
60       selected format.
61
62   source_filename
63       The file from which to extract POD for the content of the README. The
64       default is the file of the main module of the dist. If the main module
65       has a companion ".pod" file with the same basename, that is used as the
66       default instead.
67
68   location
69       Where to put the generated README file. Choices are:
70
71       build
72           This puts the README in the directory where the dist is currently
73           being built, where it will be incorporated into the dist.
74
75       root
76           This puts the README in the root directory (the same directory that
77           contains dist.ini). The README will not be incorporated into the
78           built dist.
79
80       If you want to generate the same README file in both the build
81       directory and the root directory, simply generate it in the build
82       directory and use the "[CopyFilesFromBuild]" plugin to copy it to the
83       dist root.
84
85   phase
86       At what phase to generate the README file. Choices are:
87
88       build
89           (Default) This generates the README at 'after build' time. A new
90           README will be generated each time you build the dist.
91
92       release
93           This generates the README at 'after release' time. Note that this
94           is too late to get the file into the generated tarball, and is
95           therefore incompatible with "location = build". However, this is
96           ideal if you are using "location = root" and only want to update
97           the README upon each release of your module.
98

METHODS

100   gather_files
101       We create the file early, so other plugins that need to have the full
102       list of files are aware of what we will be generating.
103
104   prune_files
105       Files with "location = root" must also be pruned, so that they don't
106       sneak into the next build by virtue of already existing in the root
107       dir.  (The alternative is that the user doesn't add them to the build
108       in the first place, with an option to their "GatherDir" plugin.)
109
110   munge_files
111   munge_file
112       Edits the content into the requested README file in the dist.
113
114   after_build
115       Create the requested README file at build time, if requested.
116
117   after_release
118       Create the requested README file at release time, if requested.
119
120   get_readme_content
121       Get the content of the README in the desired format.
122

BUGS AND LIMITATIONS

124       Please report any bugs or feature requests to
125       "rct+perlbug@thompsonclan.org".
126

INSTALLATION

137       See perlmodinstall for information and options on installing Perl
138       modules.
139

AUTHORS

141       •   Ryan C. Thompson <rct@thompsonclan.org>
142
143       •   Karen Etheridge <ether@cpan.org>
144

COPYRIGHT AND LICENSE

146       This software is copyright (c) 2016 by Ryan C. Thompson.
147
148       This is free software; you can redistribute it and/or modify it under
149       the same terms as the Perl 5 programming language system itself.
150

DISCLAIMER OF WARRANTY

152       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
153       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
154       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
155       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
156       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
157       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
158       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
159       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
160       NECESSARY SERVICING, REPAIR, OR CORRECTION.
161
162       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
163       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
164       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
165       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
166       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
167       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
168       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
169       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
170       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
171       DAMAGES.
172
173
174
175perl v5.32.1                      2021-D0i1s-t2:7:Zilla::Plugin::ReadmeAnyFromPod(3)