- COPYRIGHT AND LICENSE
Pod::Weaver::Plugin::Include - Support for including sections of Pod from other files
# weaver.ini [-Include] 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::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 package Core::Mod1; ... # Template options won't be included into resulting Pod. =pod Here we define command line options for later use by calling module. =tmpl -options =item B<--option1> document it =item B<--option2> repeat =tmpl =cut 1; __END__ # File lib/Core/Mod2.pm package Core::Mod2 =head1 Options Here is the options we declare in this module: =over 4 =tmpl options =item B<--file=>I<source_file> Whatever it means. =item B<--ignore-something> ... we'll document it. Some day... =tmpl =back You will find these in your script documentation too. =cut 1; __END__ # File lib/Core.pm package Core; =pod =srcAlias mod2opts Core/Mod2.pm =tmpl coreOpts =over 4 =item B<--help> Display this help =include options@Core::Mod1 =include options@mod2opts =tmpl =cut 1; __END__
Now, after processing this code by
Include plugin, resulting lib/Core.pm documentation will contain options from both
Core::Mod2. Yet, the
noless_useful script would has the following section in its documentation:
# File: noless_useful =head1 OPTIONS =over 4 include coreOpts@Core =item B<--script-opt> This is added by the script code =back =cut
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:
=tmpl [[-]tmplName] =srcAlias alias source =include tmplName@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
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
=tmpldoesn't have the name parameter then it acts as a terminating command only. For example:
=head1 SECTION Section docs... =tmpl tmpl1 Template 1 =tmpl -tmpl2 Template 2 =tmpl Some more docs =tmpl -tmpl3 Template 3 =tmpl =cut
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.
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.