Hello all,
The current perlpodspec contains the following requirement:
ยท When rendering Pod to a format that allows comments (i.e., to
nearly any format other than plaintext), a Pod formatter must
insert comment text identifying its name and version number, and
the name and version numbers of any modules it might be using to
process the Pod. Minimal examples:
%% POD::Pod2PS v3.14159, using POD::Parser v1.92
<!-- Pod::HTML v3.14159, using POD::Parser v1.92 -->
{\doccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08}
.\" Pod::Man version 3.14159, using POD::Parser version 1.92
Formatters may also insert additional comments, including: the
release date of the Pod formatter program, the contact address for
the author(s) of the formatter, the current time, the name of input
file, the formatting options in effect, version of Perl used, etc.
Pod::Man satisfies that requirement, inserting a comment at the start of
generated *roff output like:
.\" Automatically generated by Pod::Man 2.18 (Pod::Simple 3.05)
However, this means that the output of Pod::Man won't be stable across
different versions of Perl. That may be the case anyway, if bug fixes or
other changes to Pod::Man have caused the output to change, but it results
in more changes in the output than would otherwise be necessary.
Normally, this is not particularly important. But both Debian and Ubuntu
now support installing the same package for multiple architectures on the
same system so that, for example, one can easily use both 32-bit and
64-bit programs on a system with a 64-bit kernel. Part of that support
allows files to collide between packages of different architectures iff
those files are byte-for-byte identical.
One of the types of packages that benefit greatly from being
co-installable is development packages for libraries. Those include the
*.so symlinks, header files, and (most importantly for this discussion)
man pages for libraries that have man pages. A lot of libraries use POD
to generate man pages.
I'm concerned that this header will, in some (unnecessary) cases, break
co-installability of development packages for multiple architectures if
the build host for one architecture has, for one reason or another, a
newer point release of Perl installed. The resulting man pages would be
generated with different version numbers, the files would no longer be
byte-for-byte identical, and they could no longer be installed together.
Do people feel this comment line provides much real utility in Pod::Man
output? I could add a flag to suppress it, but I'm tempted to just drop
it entirely, since I'm not sure that it's really doing anyone any good.
--
Russ Allbery (r...@stanford.edu) <http://www.eyrie.org/~eagle/>
