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

[Guillem Jover]

Package: perl
Version: 5.20.1-1
Severity: wishlist
X-Debbugs-Cc: Russ Allbery <rra at debian.org>

Hi!

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. Things that come to mind:

  * Explicit request (through a command-line argument, or module option)
    to inject an automatic VERSION section around the top of the page,
    maybe after a specified section, if there's a $VERSION variable
    (maybe only for modules, but that might be difficult to detect in
    a general way).

  * Explicit request (through a command-line argument, or module option)
    to just inject the $VERSION variable into a replaceable chunk of text,
    say:

    ,---
    =head1 VERSION

    @VERSION@
    `---

    But this is pretty non-generic.

  * Implicit injection of a VERSION section for modules if none exist.
    This probably would have unintended consequences.

  * Something else entirely.


Personally I think the first would be preferable, but I would not mind
something along the lines of the second, because it's work done just
once. Anything that allows not having to sync the ever changing version
number would be very nice.

Thanks,
Guillem