perlpodspec currently contains the following note on POD processor
implementations:
• 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.
Formatters may also choose to note errors/warnings as comments, besides
or instead of emitting them otherwise (as in messages to STDERR, or
"die"ing).
We received a request to optionally remove those versions in Pod::Man
output from someone working on reproducible builds, since they can cause
spurious changes to man page output from build systems even if the text of
the man page hasn't changed, due to minor version changes in Pod::Simple
or Pod::Man. Discussion was at:
https://github.com/perl-pod/pod-simple/issues/148
https://github.com/rra/podlators/issues/18
In that discussion, Graham Knop noted that most formatters already don't
follow this requirement, and it's not clear that this is a good idea. I'm
also having a hard time justifying it (and I would certainly recommend
against including the current time, the input file, or the version of Perl
used, all things that previous versions of Pod::Man did and that I dropped
because they caused various other annoyances).
Does anyone want to make an argument for keeping this in the spec? If
not, I'm going to submit a PR to Perl to remove this whole bullet point.
(The note about including errors as comments is not wrong, but I don't
think it needs to be said in the specification document and it's mostly
covered by the next bullet point anyway.)
--
#!/usr/bin/perl -- Russ Allbery, Just Another Perl Hacker
$^=q;@!>~|{>krw>yn{u<$$<[~||<Juukn{=,<S~|}<Jwx}qn{<Yn{u<Qjltn{ > 0gFzD gD,
00Fz, 0,,( 0hF 0g)F/=, 0> "L$/GEIFewe{,$/ 0C$~> "@=,m,|,(e 0.), 01,pnn,y{
rw} >;,$0=q,$,,($_=$^)=~y,$/ C-~><@=\n\r,-~$:-u/ #y,d,s,(\$.),$1,gee,print
