NAME

Pod::Weaver::Section::GenerateSection - add pod section from an interpolated piece of text

VERSION

version 4.019

SYNOPSIS

In your weaver.ini

  [GenerateSection]
  title = HOMEPAGE
  text  = This is the POD for distribution {{$name}}. Check out what we have
  text  = been up to at {{$homepage}}

The title value can be omited if passed as the plugin name:

  [GenerateSection / HOMEPAGE]

DESCRIPTION

This plugin allows the creation of simple text sections, with or without the use of Text::Template for templated text.

The text parameters become the lines of the template.

The values of text are concatenated and variable names with matching values on the distribution are interpolated. Specifying the heading level allows one to write down a rather long section of POD text without need for extra files. For example:

  [GenerateSection / FEEDBACK]
  head = 1
  [GenerateSection / Reporting bugs]
  head = 2
  text = Please report bugs when you find them. While we do have a mailing
  text = list, please use the bug tracker at {{$bugtracker_web}}
  text = to report bugs
  [GenerateSection / Homegape]
  head = 2
  text = Also, come check out our other projects at
  text = {{$homepage}}

PERL VERSION

This module should work on any version of perl still receiving updates from the Perl 5 Porters. This means it should work on any version of perl released in the last two to three years. (That is, if the most recently released version is v5.40, then this module should work on both v5.40 and v5.38.)

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

ATTRIBUTES

text

The text to be added to the section. Multiple values are allowed and will be concatenated. Certain sequences on the text will be replaced (see below).

This is the X to use in the =headX that's created. If it's 0 then no heading is added. It defaults to 1.

title

The title for this section. If none is given, the plugin's name is used.

main_module_only

If true, this attribute indicates that only the main module's Pod should be altered. By default, it is false.

If true, the text is treated as a Text::Template template and rendered. This attribute is true by default.

delim

If given, this must be an arrayref with two elements. These will be the opening and closing delimiters of template variable sections. By default they are {{ and }}.

TEMPLATE RENDERING

When rendering as a template, the variables $plugin, $dist, and $distmeta will be provided, set to the GenerateSection plugin, Dist::Zilla object, and the distribution metadata hash respectively. For convenience, the following variables are also set:

  • $name

  • $version

  • $homepage

  • $repository_web

  • $repository_url

  • $bugtracker_web

  • $bugtracker_email

AUTHOR

Ricardo SIGNES <cpan@semiotic.systems>

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Ricardo SIGNES.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.