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

NAME

6       Pod::Readme - Convert POD to README file
7

SYNOPSIS

9         use Pod::Readme;
10         my $parser = Pod::Readme->new();
11
12         # Read POD from STDIN and write to STDOUT
13         $parser->parse_from_filehandle;
14
15         # Read POD from Module.pm and write to README
16         $parser->parse_from_file('Module.pm', 'README');
17

DESCRIPTION

19       This module is a subclass of Pod::PlainText which provides additional
20       POD markup for generating README files.
21
22       Why should one bother with this? One can simply use
23
24         pod2text Module.pm > README
25
26       A problem with doing that is that the default pod2text converter will
27       add text to links, so that "L<Module>" is translated to "the Module
28       manpage".
29
30       Another problem is that the README includes the entirety of the module
31       documentation!  Most people browsing the README file do not need all of
32       this information.
33
34       Likewise, including installation and requirement information in the
35       module documentation is not necessary either, since the module is
36       already installed.
37
38       This module allows authors to mark portions of the POD to be included
39       only in, or to be excluded from the README file.  It also allows you to
40       include portions of another file (such as a separate ChangeLog).
41
42       Markup
43
44       Special POD markup options are described below:
45
46       begin/end
47             =begin readme
48
49             =head1 README ONLY
50
51             This section will only show up in the README file.
52
53             =end readme
54
55           Delineates a POD section that is only available in README file. If
56           you prefer to include plain text instead, add the "text" modifier:
57
58             =begin readme text
59
60             README ONLY (PLAINTEXT)
61
62                 This section will only show up in the README file.
63
64             =end readme
65
66           Note that placing a colon before the section to indicate that it is
67           POD (e.g. "begin :readme") is not supported in this version.
68
69       stop/continue
70             =for readme stop
71
72           All POD that follows will not be included in the README, until a
73           "continue" command occurs:
74
75             =for readme continue
76
77       include
78             =for readme include file=filename type=type start=Regexp stop=Regexp
79
80             =for readme include file=Changes start=^0.09 stop=^0.081 type=text
81
82           Includes a plaintext file named filename, starting with the line
83           that contains the start "Regexp" and ending at the line that begins
84           with the stop "Regexp".  (The start and stop Regexps are optional:
85           one or both may be omitted.)
86
87           Type may be "text" or "pod". If omitted, "pod" will be assumed.
88
89           Quotes may be used when the filename or marks contains spaces:
90
91             =for readme include file="another file.pod"
92
93       One can also using maintain multiple file types (such as including
94       TODO, or COPYING) by using a modified constructor:
95
96         $parser = Pod::Readme->new( readme_type => "copying" );
97
98       In the above "Markup" commands replace "readme" with the tag specified
99       instead (such as "copying"):
100
101         =begin copying
102
103       As of version 0.03 you can specify multiple sections by separating them
104       with a comma:
105
106         =begin copying,readme
107
108       There is also no standard list of type names.  Some names might be rec‐
109       ognized by other POD processors (such as "testing" or "html").
110       Pod::Readme will reject the following "known" type names when they are
111       specified in the constructor:
112
113           testing html xhtml xml docbook rtf man nroff dsr rno latex tex code
114
115       You can also use a "debug" mode to diagnose any problems, such as
116       mistyped format names:
117
118         $parser = Pod::Readme->new( debug => 1 );
119
120       Warnings will be issued for any ignored formatting commands.
121
122       Example
123
124       For an example, see the Readme.pm file in this distribution.
125

SEE ALSO

127       See perlpod, perlpodspec and podlators.
128

AUTHOR

130       Robert Rothenberg <rrwo at cpan.org>
131
132       Suggestions and Bug Reporting
133
134       Feedback is always welcome.  Please use the CPAN Request Tracker at
135       <http://rt.cpan.org> to submit bug reports.
136

LICENSE

138       Copyright (c) 2005,2006 Robert Rothenberg. All rights reserved.  This
139       program is free software; you can redistribute it and/or modify it
140       under the same terms as Perl itself.
141
142       Some portions are based on Pod::PlainText 2.02.
143
144
145
146perl v5.8.8                       2006-12-09                    Pod::Readme(3)
Impressum