Pod::Weaver::Plugin::Include - Support for including sections of Pod from other files
pod_path = lib:bin:docs/pod
insert_errors = 0
This is a Pod::Weaver plugin for making it possible to include segments of Pod documentation being included from one file into another. This is useful when one has a piece of documentation which is nice to have included into a couple of documentations. So, instead of telling a user to 'go see this info in that file' one could simply have this info included from that file into this file.
For example, let's say we have a script useful_tool which is handling its command line processing to a module Core. In turn, the module gathers information about standard command line options from modules Core::Mod1, Core::Mod2, etc. So far, so good until one writes another script noless_useful, which is based upon the module Core too. Yet, even worse – it adds its own command lines the list gathered by Core! With standard Pod documentation for the common set of options would have to be copy-pasted into each script documentation. For the latter one it's own options must be included. And then if any documentation would be changed in the original modules we would have not forget update both scripts' docs too!
Pod::Weaver::Plugin::Include solves the issue by defining a concept of template (borrowed from archaic Pod::Template) and allowing a template to be included by a third-party pod:
# File lib/Core/Mod1.pm
# Template options won't be included into resulting Pod.
Here we define command line options for later use by calling module.
# File lib/Core/Mod2.pm
Here is the options we declare in this module:
Whatever it means.
... we'll document it. Some day...
You will find these in your script documentation too.
# File lib/Core.pm
=srcAlias mod2opts Core/Mod2.pm
Display this help
Now, after processing this code by Include plugin, resulting lib/Core.pm documentation will contain options from both Core::Mod1 and Core::Mod2. Yet, the noless_useful script would has the following section in its documentation:
# File: noless_useful
This is added by the script code
and this section will have all the options defined by the modules plus what is been added by the script itself.
Three Pod commands are added by this plugin:
=srcAlias alias source
Declares a template if tmplName is defined. Prefixing the name with a dash tells the plugin that template body is 'hidden' and must not be included into enclosing documentation and will only be visible as a result of =include command.
Template's name must start with either a alpha char or underscore (_) and continued with alpha-numeric or underscore.
A template body is terminated by another =tmpl command. If =tmpl doesn't have the name parameter then it acts as a terminating command only. For example:
Some more docs
The above code declares three templates of which tmpl2 and tmpl3 are hidden and tmpl1 is included into the resulting Pod. The "Some more docs" paragraph is not a part of any template.
Defines an alias for a source. The source could be either a file name or a module name.
=srcAlias mod1 Some::Very::Long::Module::Name1
=srcAlias aPodFile pod/templates/some.pod
This command tries to locate a template defined by name tmplName in a source defined by either a file name, a module name, or by an alias and include it into the output.
Missing template is an "Error Case" (see below).
Plugin does its best as to not abort the building process. Errors are ignored and only error messages are logged. But some error reports could be included into generated pod if insert_errors option is set to true in weaver.ini. In this case the error message is also inserted into the resulting Pod with Pod INCLUDE ERROR: prefix.
Semicolon-separated list of directories to search for template sources.
Insert some error message into the resulting Pod.
List of directories to look for pods in.
Set to true if some errors are to be included into the output.
See "IMPLEMENTING" in Pod::Weaver::Role::Preparer.
See "IMPLEMENTING" in Pod::Weaver::Role::Dialect.
Initializer for pod_path attribute.
Initializer for insert_errors attribute.
Vadim Belman <email@example.com>
This software is copyright (c) 2017 by Vadim Belman.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Pod::Weaver::Plugin::Include, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.