NAME Pod::Weaver::Plugin::Include - Support for including sections of Pod from other files VERSION version v0.1.6 SYNOPSIS # weaver.ini [-Include] pod_path = lib:bin:docs/pod insert_errors = 0 DESCRIPTION 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! Phew... "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 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::Mod1" and "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. Syntax Three Pod commands are added by this plugin: =tmpl [[-]tmplName] =srcAlias alias source =include tmplName@source =tmpl 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: =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. =srcAlias 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 =include 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). Error Cases 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. Configuration variables pod_path Semicolon-separated list of directories to search for template sources. Default: *lib* insert_errors Insert some error message into the resulting Pod. AUTHOR Vadim Belman COPYRIGHT AND LICENSE This software is Copyright (c) 2017 by Vadim Belman. This is free software, licensed under: The Apache License, Version 2.0, January 2004