Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Pod::Readme(3)	      User Contributed Perl Documentation	Pod::Readme(3)

NAME
       Pod::Readme - Intelligently generate a README file from POD

SYNOPSIS
       In a module's POD:

	 =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

	 ...

       Then from the command-line:

	 pod2readme lib/MyModule.pm README

       From within Perl:

	 use Pod::Readme;

	 my $prf = Pod::Readme->new(
	   input_file	       => 'lib/MyModule.pm',
	   translate_to_file   => $dest,
	   translation_class   => 'Pod::Simple::Text',
	 );

	 $prf->run();

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

POD COMMANDS
   "=for readme	stop"
       Stop including the POD that follows in the README.

   "=for readme	start"
   "=for readme	continue"
       Start (or continue to) include the POD that follows in the README.

       Note that the "start" command was added as a synonym in version 1.0.0.

   "=for readme	include"
	 =for readme include file="INSTALL" type="text"

       Include a text or POD file in the README.  It accepts the following
       options:

       "file"
	   Required. This is the file name to include.

       "type"
	   Can be "text" or "pod" (default).

       "start"
	   An optional regex of	where to start including the file.

       "stop"
	   An optional regex of	where to stop including	the file.

   "=for readme	plugin"
       Loads a plugin, e.g.

	 =for readme plugin version

       Note that specific plugins may add options, e.g.

	 =for readme plugin changes title='CHANGES'

       See Pod::Readme::Plugin for more	information.

       Note that the "plugin" command was added	in version 1.0.0.

   "=begin :readme"
   "=end :readme"
       Specify a block of POD to include only in the README.

       You can also specify a block in another format:

	 =begin	readme text

	 ...

	 =end readme text

       This will be translated into

	 =begin	text

	 ...

	 =end text

       and will	only be	included in README files of that format.

       Note: earlier versions of this module suggested using

	 =begin	readme

	 ...

	 =end readme

       While this version supports that	syntax for backwards compatibility, it
       is not standard POD.

ATTRIBUTES
       This module extends Pod::Readme::Filter with the	following attributes:

   "translation_class"
       The class used to translate the filtered	POD into another format, e.g.
       Pod::Simple::Text.

       If it is	"undef", then there is no translation.

       Only subclasses of Pod::Simple are supported.

   "translate_to_fh"
       The IO::Handle to save the translated file to.

   "translate_to_file"
       The Path::Tiny filename to save the translated file to. If omitted,
       then it will be saved to	"STDOUT".

   "output_file"
       The Pod::Readme::Filter "output_file" will default to a temporary file.

   "force"
       For a new README	to be generated, even if the dependencies have not
       been updated.

       See "dependencies_updated".

   "zilla"
       For use with Dist::Zilla	plugins.

       This allows plugins which normally depend on files in the distribution
       to use metadata from here instead.

METHODS
       This module extends Pod::Readme::Filter with the	following methods:

   "default_readme_file"
       The default name	of the README file, which depends on the
       "translation_class".

   "translate_file"
       This method runs	translates the resulting POD from "filter_file".

   "dependencies_updated"
       Used to determine when the dependencies have been updated, and a
       translation can be run.

       Note that this only returns a meaningful	value after the	POD has	been
       processed, since	plugins	may add	to the dependencies.  A	side-effect of
       this is that when generating a POD formatted README is that it will
       always be updated, even when "force" is false.

   "run"
       This method runs	"filter_file" and then "translate_file".

   "parse_from_file"
	 my $parser = Pod::Readme->new();
	 $parser->parse_from_file( 'README.pod', 'README' );

	 Pod::Readme->parse_from_file( 'README.pod', 'README' );

       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.

       Its use is deprecated, and will be deleted in later versions.

   "parse_from_filehandle"
       Like "parse_from_file", this exists as a	compatibility shim.

       Its use is deprecated, and will be deleted in later versions.

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

SEE ALSO
       See perlpod, perlpodspec	and podlators.

AUTHORS
       The original version was	by Robert Rothenberg <rrwo@cpan.org> until
       2010, when maintenance was taken	over by	David Precious
       <davidp@preshweb.co.uk>.

       In 2014,	Robert Rothenberg rewrote the module to	use filtering instead
       of subclassing a	POD parser.

   Acknowledgements
       Thanks to people	who gave feedback and suggestions to posts about the
       rewrite of this module on <http://blogs.perl.org>.

   Suggestions,	Bug Reporting and Contributing
       This module is developed	on GitHub at
       <http://github.com/bigpresh/Pod-Readme>

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.

perl v5.32.0			  2018-10-31			Pod::Readme(3)

NAME | SYNOPSIS | DESCRIPTION | POD COMMANDS | ATTRIBUTES | METHODS | CAVEATS | SEE ALSO | AUTHORS | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Pod::Readme&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help