.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" 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" '' . ds C` . ds C' '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 >0, 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. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Pod::Readme 3pm" .TH Pod::Readme 3pm "2018-11-26" "perl v5.28.0" "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" Pod::Readme \- Intelligently generate a README file from POD .SH "SYNOPSIS" .IX Header "SYNOPSIS" In a module's \s-1POD:\s0 .PP .Vb 1 \& =head1 NAME \& \& MyApp \- my nifty app \& \& =for readme plugin version \& \& =head1 DESCRIPTION \& \& This is a nifty app. \& \& =begin :readme \& \& =for readme plugin requires \& \& =head1 INSTALLATION \& \& ... \& \& =end :readme \& \& =for readme stop \& \& =head1 METHODS \& \& ... .Ve .PP Then from the command-line: .PP .Vb 1 \& pod2readme lib/MyModule.pm README .Ve .PP From within Perl: .PP .Vb 1 \& use Pod::Readme; \& \& my $prf = Pod::Readme\->new( \& input_file => \*(Aqlib/MyModule.pm\*(Aq, \& translate_to_file => $dest, \& translation_class => \*(AqPod::Simple::Text\*(Aq, \& ); \& \& $prf\->run(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module filters \s-1POD\s0 to generate a \fI\s-1README\s0\fR file, by using \s-1POD\s0 commands to specify which parts are included or excluded from the \&\fI\s-1README\s0\fR file. .SH "POD COMMANDS" .IX Header "POD COMMANDS" .ie n .SS """=for readme stop""" .el .SS "\f(CW=for readme stop\fP" .IX Subsection "=for readme stop" Stop including the \s-1POD\s0 that follows in the \fI\s-1README\s0\fR. .ie n .SS """=for readme start""" .el .SS "\f(CW=for readme start\fP" .IX Subsection "=for readme start" .ie n .SS """=for readme continue""" .el .SS "\f(CW=for readme continue\fP" .IX Subsection "=for readme continue" Start (or continue to) include the \s-1POD\s0 that follows in the \fI\s-1README\s0\fR. .PP Note that the \f(CW\*(C`start\*(C'\fR command was added as a synonym in version 1.0.0. .ie n .SS """=for readme include""" .el .SS "\f(CW=for readme include\fP" .IX Subsection "=for readme include" .Vb 1 \& =for readme include file="INSTALL" type="text" .Ve .PP Include a text or \s-1POD\s0 file in the \fI\s-1README\s0\fR. It accepts the following options: .ie n .IP """file""" 4 .el .IP "\f(CWfile\fR" 4 .IX Item "file" Required. This is the file name to include. .ie n .IP """type""" 4 .el .IP "\f(CWtype\fR" 4 .IX Item "type" Can be \*(L"text\*(R" or \*(L"pod\*(R" (default). .ie n .IP """start""" 4 .el .IP "\f(CWstart\fR" 4 .IX Item "start" An optional regex of where to start including the file. .ie n .IP """stop""" 4 .el .IP "\f(CWstop\fR" 4 .IX Item "stop" An optional regex of where to stop including the file. .ie n .SS """=for readme plugin""" .el .SS "\f(CW=for readme plugin\fP" .IX Subsection "=for readme plugin" Loads a plugin, e.g. .PP .Vb 1 \& =for readme plugin version .Ve .PP Note that specific plugins may add options, e.g. .PP .Vb 1 \& =for readme plugin changes title=\*(AqCHANGES\*(Aq .Ve .PP See Pod::Readme::Plugin for more information. .PP Note that the \f(CW\*(C`plugin\*(C'\fR command was added in version 1.0.0. .ie n .SS """=begin :readme""" .el .SS "\f(CW=begin :readme\fP" .IX Subsection "=begin :readme" .ie n .SS """=end :readme""" .el .SS "\f(CW=end :readme\fP" .IX Subsection "=end :readme" Specify a block of \s-1POD\s0 to include only in the \fI\s-1README\s0\fR. .PP You can also specify a block in another format: .PP .Vb 1 \& =begin readme text \& \& ... \& \& =end readme text .Ve .PP This will be translated into .PP .Vb 1 \& =begin text \& \& ... \& \& =end text .Ve .PP and will only be included in \fI\s-1README\s0\fR files of that format. .PP Note: earlier versions of this module suggested using .PP .Vb 1 \& =begin readme \& \& ... \& \& =end readme .Ve .PP While this version supports that syntax for backwards compatibility, it is not standard \s-1POD.\s0 .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" This module extends Pod::Readme::Filter with the following attributes: .ie n .SS """translation_class""" .el .SS "\f(CWtranslation_class\fP" .IX Subsection "translation_class" The class used to translate the filtered \s-1POD\s0 into another format, e.g. Pod::Simple::Text. .PP If it is \f(CW\*(C`undef\*(C'\fR, then there is no translation. .PP Only subclasses of Pod::Simple are supported. .ie n .SS """translate_to_fh""" .el .SS "\f(CWtranslate_to_fh\fP" .IX Subsection "translate_to_fh" The IO::Handle to save the translated file to. .ie n .SS """translate_to_file""" .el .SS "\f(CWtranslate_to_file\fP" .IX Subsection "translate_to_file" The Path::Tiny filename to save the translated file to. If omitted, then it will be saved to \f(CW\*(C`STDOUT\*(C'\fR. .ie n .SS """output_file""" .el .SS "\f(CWoutput_file\fP" .IX Subsection "output_file" The Pod::Readme::Filter \f(CW\*(C`output_file\*(C'\fR will default to a temporary file. .ie n .SS """force""" .el .SS "\f(CWforce\fP" .IX Subsection "force" For a new \fI\s-1README\s0\fR to be generated, even if the dependencies have not been updated. .PP See \*(L"dependencies_updated\*(R". .ie n .SS """zilla""" .el .SS "\f(CWzilla\fP" .IX Subsection "zilla" For use with Dist::Zilla plugins. .PP This allows plugins which normally depend on files in the distribution to use metadata from here instead. .SH "METHODS" .IX Header "METHODS" This module extends Pod::Readme::Filter with the following methods: .ie n .SS """default_readme_file""" .el .SS "\f(CWdefault_readme_file\fP" .IX Subsection "default_readme_file" The default name of the \fI\s-1README\s0\fR file, which depends on the \&\*(L"translation_class\*(R". .ie n .SS """translate_file""" .el .SS "\f(CWtranslate_file\fP" .IX Subsection "translate_file" This method runs translates the resulting \s-1POD\s0 from \f(CW\*(C`filter_file\*(C'\fR. .ie n .SS """dependencies_updated""" .el .SS "\f(CWdependencies_updated\fP" .IX Subsection "dependencies_updated" Used to determine when the dependencies have been updated, and a translation can be run. .PP Note that this only returns a meaningful value after the \s-1POD\s0 has been processed, since plugins may add to the dependencies. A side-effect of this is that when generating a \s-1POD\s0 formatted \fI\s-1README\s0\fR is that it will always be updated, even when \*(L"force\*(R" is false. .ie n .SS """run""" .el .SS "\f(CWrun\fP" .IX Subsection "run" This method runs \f(CW\*(C`filter_file\*(C'\fR and then \*(L"translate_file\*(R". .ie n .SS """parse_from_file""" .el .SS "\f(CWparse_from_file\fP" .IX Subsection "parse_from_file" .Vb 2 \& my $parser = Pod::Readme\->new(); \& $parser\->parse_from_file( \*(AqREADME.pod\*(Aq, \*(AqREADME\*(Aq ); \& \& Pod::Readme\->parse_from_file( \*(AqREADME.pod\*(Aq, \*(AqREADME\*(Aq ); .Ve .PP This is a class method that acts as a Pod::Select compatibility shim for software that is designed for versions of Pod::Readme prior to v1.0. .PP Its use is deprecated, and will be deleted in later versions. .ie n .SS """parse_from_filehandle""" .el .SS "\f(CWparse_from_filehandle\fP" .IX Subsection "parse_from_filehandle" Like \*(L"parse_from_file\*(R", this exists as a compatibility shim. .PP Its use is deprecated, and will be deleted in later versions. .SH "CAVEATS" .IX Header "CAVEATS" This module is intended to be used by module authors for their own modules. It is not recommended for generating \fI\s-1README\s0\fR files from arbitrary Perl modules from untrusted sources. .SH "SEE ALSO" .IX Header "SEE ALSO" See perlpod, perlpodspec and podlators. .SH "AUTHORS" .IX Header "AUTHORS" The original version was by Robert Rothenberg until 2010, when maintenance was taken over by David Precious . .PP In 2014, Robert Rothenberg rewrote the module to use filtering instead of subclassing a \s-1POD\s0 parser. .SS "Acknowledgements" .IX Subsection "Acknowledgements" Thanks to people who gave feedback and suggestions to posts about the rewrite of this module on . .SS "Suggestions, Bug Reporting and Contributing" .IX Subsection "Suggestions, Bug Reporting and Contributing" This module is developed on GitHub at .SH "LICENSE" .IX Header "LICENSE" Copyright (c) 2005\-2014 Robert Rothenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.