FAQ
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 (rra@stanford.edu) <http://www.eyrie.org/~eagle/>

Search Discussions

  • Ricardo Signes at Dec 27, 2012 at 2:42 pm
    * Russ Allbery [2012-12-26T17:47:41]
    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.
    I have often found such lines *in other programs* useful for sorting out bugs.
    I've never tried debugging the podlators, thankfully! :) My inclination would
    be to add the flag for such packagers to use, but I'm not particularly invested
    in the problem.

    --
    rjbs
  • Nicholas Clark at Dec 28, 2012 at 4:08 pm

    On Thu, Dec 27, 2012 at 09:42:34AM -0500, Ricardo Signes wrote:
    * Russ Allbery [2012-12-26T17:47:41]
    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.
    I have often found such lines *in other programs* useful for sorting out bugs.
    I've never tried debugging the podlators, thankfully! :) My inclination would
    be to add the flag for such packagers to use, but I'm not particularly invested
    in the problem.
    "Me too". In that my experience and situation parallels Ricardo's.

    A flag for people who know what they are doing to disable the generation of
    comments feels like the best compromise, as such people likely also know how
    to debug their toolchain if they get a problem. (Rather than asking upstream,
    at which point the "generated by" comments are useful to upstream.)

    Nicholas Clark

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
grouppod-people @
categoriesperl
postedDec 26, '12 at 10:47p
activeDec 28, '12 at 4:08p
posts3
users3
websiteperl.org

People

Translate

site design / logo © 2019 Grokbase