Guillem Jover <[email protected]> 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 ([email protected]) <http://www.eyrie.org/~eagle/> -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected]
