Module::Install::ReadmeFromPod(3pm)

1Module::Install::ReadmeUFsreormPCoodn(t3r)ibuted Perl DoMcoudmuelnet:a:tIinosntall::ReadmeFromPod(3)
2
3
4

NAME

6       Module::Install::ReadmeFromPod - A Module::Install extension to
7       automatically convert POD to a README
8

SYNOPSIS

10         # In Makefile.PL
11
12         use inc::Module::Install;
13         author 'Vestan Pants';
14         license 'perl';
15         readme_from 'lib/Some/Module.pm';
16         readme_from 'lib/Some/Module.pm', { clean => 1, format => 'htm', output_file => 'SomeModule.html' };
17
18       A "README" file will be generated from the POD of the indicated module
19       file.
20
21       Note that the author will need to make sure
22       "Module::Install::ReadmeFromPod" is installed before running the
23       "Makefile.PL".  (The extension will be bundled into the user-side
24       distribution).
25

DESCRIPTION

27       Module::Install::ReadmeFromPod is a Module::Install extension that
28       generates a "README" file automatically from an indicated file
29       containing POD, whenever the author runs "Makefile.PL". Several output
30       formats are supported: plain-text, HTML, PDF or manpage.
31

COMMANDS

33       This plugin adds the following Module::Install command:
34
35       "readme_from"
36           Does nothing on the user-side. On the author-side it will generate
37           a "README" file.
38
39             readme_from 'lib/Some/Module.pm';
40
41           If a second parameter is set to a true value then the "README" will
42           be removed at "make distclean".
43
44             readme_from 'lib/Some/Module.pm', 1;
45
46           A third parameter can be used to determine the format of the
47           "README" file.
48
49             readme_from 'lib/Some/Module.pm', 1, 'htm';
50
51           Valid formats for this third parameter are:
52
53           txt, text
54               Produce a plain-text "README" file using Pod::Text. The 'txt'
55               format is the default.
56
57           htm, html
58               Produce an HTML "README.htm" file using Pod::Html.
59
60           man Produce a "README.1" manpage using Pod::Man.
61
62           md  Produce a "README.md" file using Pod::Markdown.
63
64           pdf Produce a PDF "README.pdf" file with App::pod2pdf if this
65               module is installed.
66
67           A fourth parameter can be used to supply an output filename.
68
69             readme_from 'lib/Some/Module.pm', 0, 'pdf', 'SomeModule.pdf';
70
71           Finally, you can pass additional arguments to the POD formatter
72           that handles the requested format.
73
74             my @options = ( 'release' => 1.03, 'section' => 8 ); # options for Pod::Man
75             readme_from 'lib/Some/Module.pm', 1, 'man', undef, @options;
76
77           But instead of passing this long list of optional arguments to
78           readme_from, you should probably pass these arguments as a named
79           hashref for clarity.
80
81             my @options = ( 'release' => 1.03, 'section' => 8 );
82             readme_from 'lib/Some/Module.pm', {clean => 1, format => 'man', output_file => undef, options => @options};
83
84           If you use the "all_from" command, "readme_from" will default to
85           that value.
86
87             all_from 'lib/Some/Module.pm';
88             readme_from;              # Create README from lib/Some/Module.pm
89             readme_from '','clean';   # Put a empty string before 'clean'
90

AUTHOR

92       Chris "BinGOs" Williams
93

LICENSE

95       Copyright © Chris Williams
96
97       This module may be used, modified, and distributed under the same terms
98       as Perl itself. Please see the license that came with your Perl
99       distribution for details.
100

NAME

SYNOPSIS

DESCRIPTION

COMMANDS

AUTHOR

LICENSE

SEE ALSO