Pod::Readme(3pm)

1Pod::Readme(3)        User Contributed Perl Documentation       Pod::Readme(3)
2
3
4

NAME

6       Pod::Readme - Intelligently generate a README file from POD
7

SYNOPSIS

9       In a module's POD:
10
11         =head1 NAME
12
13         MyApp - my nifty app
14
15         =for readme plugin version
16
17         =head1 DESCRIPTION
18
19         This is a nifty app.
20
21         =begin :readme
22
23         =for readme plugin requires
24
25         =head1 INSTALLATION
26
27         ...
28
29         =end :readme
30
31         =for readme stop
32
33         =head1 METHODS
34
35         ...
36
37       Then from the command-line:
38
39         pod2readme lib/MyModule.pm README
40
41       From within Perl:
42
43         use Pod::Readme;
44
45         my $prf = Pod::Readme->new(
46           input_file          => 'lib/MyModule.pm',
47           translate_to_file   => $dest,
48           translation_class   => 'Pod::Simple::Text',
49         );
50
51         $prf->run();
52

DESCRIPTION

54       This module filters POD to generate a README file, by using POD
55       commands to specify which parts are included or excluded from the
56       README file.
57

POD COMMANDS

59   "=for readme stop"
60       Stop including the POD that follows in the README.
61
62   "=for readme start"
63   "=for readme continue"
64       Start (or continue to) include the POD that follows in the README.
65
66       Note that the "start" command was added as a synonym in version 1.0.0.
67
68   "=for readme include"
69         =for readme include file="INSTALL" type="text"
70
71       Include a text or POD file in the README.  It accepts the following
72       options:
73
74       "file"
75           Required. This is the file name to include.
76
77       "type"
78           Can be "text" or "pod" (default).
79
80       "start"
81           An optional regex of where to start including the file.
82
83       "stop"
84           An optional regex of where to stop including the file.
85
86   "=for readme plugin"
87       Loads a plugin, e.g.
88
89         =for readme plugin version
90
91       Note that specific plugins may add options, e.g.
92
93         =for readme plugin changes title='CHANGES'
94
95       See Pod::Readme::Plugin for more information.
96
97       Note that the "plugin" command was added in version 1.0.0.
98
99   "=begin :readme"
100   "=end :readme"
101       Specify a block of POD to include only in the README.
102
103       You can also specify a block in another format:
104
105         =begin readme text
106
107         ...
108
109         =end readme text
110
111       This will be translated into
112
113         =begin text
114
115         ...
116
117         =end text
118
119       and will only be included in README files of that format.
120
121       Note: earlier versions of this module suggested using
122
123         =begin readme
124
125         ...
126
127         =end readme
128
129       While this version supports that syntax for backwards compatibility, it
130       is not standard POD.
131

ATTRIBUTES

133       This module extends Pod::Readme::Filter with the following attributes:
134
135   "translation_class"
136       The class used to translate the filtered POD into another format, e.g.
137       Pod::Simple::Text.
138
139       If it is "undef", then there is no translation.
140
141       Only subclasses of Pod::Simple are supported.
142
143   "translate_to_fh"
144       The IO::Handle to save the translated file to.
145
146   "translate_to_file"
147       The Path::Tiny filename to save the translated file to. If omitted,
148       then it will be saved to "STDOUT".
149
150   "output_file"
151       The Pod::Readme::Filter "output_file" will default to a temporary file.
152
153   "force"
154       For a new README to be generated, even if the dependencies have not
155       been updated.
156
157       See "dependencies_updated".
158
159   "zilla"
160       For use with Dist::Zilla plugins.
161
162       This allows plugins which normally depend on files in the distribution
163       to use metadata from here instead.
164

METHODS

166       This module extends Pod::Readme::Filter with the following methods:
167
168   "default_readme_file"
169       The default name of the README file, which depends on the
170       "translation_class".
171
172   "translate_file"
173       This method runs translates the resulting POD from "filter_file".
174
175   "dependencies_updated"
176       Used to determine when the dependencies have been updated, and a
177       translation can be run.
178
179       Note that this only returns a meaningful value after the POD has been
180       processed, since plugins may add to the dependencies.  A side-effect of
181       this is that when generating a POD formatted README is that it will
182       always be updated, even when "force" is false.
183
184   "run"
185       This method runs "filter_file" and then "translate_file".
186
187   "parse_from_file"
188         my $parser = Pod::Readme->new();
189         $parser->parse_from_file( 'README.pod', 'README' );
190
191         Pod::Readme->parse_from_file( 'README.pod', 'README' );
192
193       This is a class method that acts as a Pod::Select compatibility shim
194       for software that is designed for versions of Pod::Readme prior to
195       v1.0.
196
197       Its use is deprecated, and will be deleted in later versions.
198
199   "parse_from_filehandle"
200       Like "parse_from_file", this exists as a compatibility shim.
201
202       Its use is deprecated, and will be deleted in later versions.
203

CAVEATS

205       This module is intended to be used by module authors for their own
206       modules.  It is not recommended for generating README files from
207       arbitrary Perl modules from untrusted sources.
208

AUTHORS

213       The original version was by Robert Rothenberg <rrwo@cpan.org> until
214       2010, when maintenance was taken over by David Precious
215       <davidp@preshweb.co.uk>.
216
217       In 2014, Robert Rothenberg rewrote the module to use filtering instead
218       of subclassing a POD parser.
219
220   Acknowledgements
221       Thanks to people who gave feedback and suggestions to posts about the
222       rewrite of this module on <http://blogs.perl.org>.
223
224   Suggestions, Bug Reporting and Contributing
225       This module is developed on GitHub at
226       <http://github.com/bigpresh/Pod-Readme>
227

LICENSE

229       Copyright (c) 2005-2014 Robert Rothenberg. All rights reserved.  This
230       program is free software; you can redistribute it and/or modify it
231       under the same terms as Perl itself.
232
233
234
235perl v5.36.0                      2023-01-20                    Pod::Readme(3)