Your message dated Fri, 10 Oct 2014 04:38:13 +0200
with message-id <[email protected]>
and subject line Re: Bug#764612: pod2man: Please add support for automatically
injecting $VERSION
has caused the Debian Bug report #764612,
regarding pod2man: Please add support for automatically injecting $VERSION
to be marked as done.
This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.
(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact [email protected]
immediately.)
--
764612: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=764612
Debian Bug Tracking System
Contact [email protected] with problems
--- Begin Message ---
Package: perl
Version: 5.20.1-1
Severity: wishlist
X-Debbugs-Cc: Russ Allbery <[email protected]>
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
--- End Message ---
--- Begin Message ---
Hi!
On Thu, 2014-10-09 at 09:39:20 -0700, Russ Allbery wrote:
> Guillem Jover <[email protected]> writes:
> > 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.
Ah! Thanks for the tip, but unfortunately while these seem nice, they
look too dependency heavy for something that is build-essential.
> 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.
Sure, makes sense, and I was kind of expecting such an answer. I guess
the request was more of a probe in case any such option might be
acceptable.
> 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.
Right.
Ok, given the above, and that I can actually control the format of the
$VERSION variable, it's actually been very easy to extract it with some
sed, and replace @@VERSION@@ on the fly in the build system, which even
if not pretty, can get the job done. I'll be probably merging something
like that in the future in dpkg.
(The only slight annoyance is that if I do the sed on the output pipe I
might get the pattern mangled by the formatting, but if I do on the input
pipe it cannot extract information from the file itself, and I'd need a
temp file.)
In any case, I think it's best to close this request now.
Thanks,
Guillem
--- End Message ---
