Bug#764612: pod2man: Please add support for automatically injecting $VERSION

[Russ Allbery]

Guillem Jover <guillem at debian.org> writes:

> The libdpkg-perl package contains a bunch of perl modules, some public
> (with $VERSION >= 1.00), some private (with $VERSION < 1.00) to be used
> only (in theory) by the dpkg-dev perl scripts. In principle only public
> interfaces are documented (as per [API]), but even then it would be nice
> to list the current module version, which otherwise needs to be either
> inferred from the CHANGES section, or read from the source. It would
> also be nice to be able to just say, that even if documented only
> $VERSION > 1.00 modules are public, and not require people to read the
> module sources.

>   [API] /usr/share/doc/dpkg-dev/README.api

> But having to keep the $VERSION variable and a POD text in sync is a bit
> annoying and error prone, so my request would be to have something
> (anything really) that allowed to pull that value (semi-)automatically
> into the output.

> Of course that depends on the design principles of pod2man and POD in
> general I guess, and how much that might allow for full automatic
> injection or only partial, etc.

There are facilities in the module building layers for Perl that do this
already.  See, for example, Dist::Zilla and Pod::Weaver.  Something based
on Pod::Weaver would probably be the path of least resistence.

I view pod2man as a lower-level tool that converts POD source to *roff
output.  If one wants to auto-generate sections of that POD documentation,
I think it makes more sense for some higher-level tool to do that and feed
the resulting document to pod2man for the final formatting.  That also
lets that higher-level tool generate POD, which means that other
converters can also get the same functionality, rather than reinventing it
for each output format.

Note that, in order to pull $VERSION information out of the module,
pod2man would have to source the module and execute at least the module
loading code.  This isn't exactly a vulnerability given that it would be
controlled by a command-line option, but I think it's rather surprising
and unexpected for a formatting program to be doing that much magic.

-- 
Russ Allbery (rra at debian.org)               <http://www.eyrie.org/~eagle/>