Without perl-doc installed snazzer --man doesn't behave well

[jamiereid]

uname -a = Linux 4.8.0-1-amd64 #1 SMP Debian 4.8.7-1 (2016-11-13) x86_64 GNU/Linux
Bash version 4.4.5(1)-release

Without perl-doc installed, when running snazzer --man, the source code for snazzer is displayed. After closing (is it less that's used?) a message is presented saying that "You need to install the perl-doc package to use this program".

Expected behaviour: I believe it would be good to, if the dependency isn't there, gracefully fail to the info message instead of opening the source code.

[florianjacob]

It seems like the perl-doc debian package only contains perl manpages, and no executables.

snazzer manpage display generation needs the pod2usage executable, that is bundled with perl in Debian as well. Could it be that you didn't have perl installed, and perl-doc pulled in perl as a dependency?

The code to display the manpage in snazzer essentially boils down to a simple pod2usage --verbose 3 ./snazzer.

Currently investigating how this could result in source code display instead of command not found…

[florianjacob]

Ok, if I replace pod2usage with a command that doesn't exist, I get an error that that command does not exist. This is strange. So I guess you a

Questions:

• Did you have perl installed before? (I guess so, but just to be sure)
• Could you remove perl-doc again, and then post what's happening on a
  pod2usage --verbose 3 $(which snazzer)

[jamiereid]

Sorry it's taken a while for me to reply @florianjacob

• I assume I had perl installed before, I don't remember it coming down as a dependency when I installed perl-doc
• Removing perl-doc and running pod2usage --verbose 3 ./snazzer yields the same behavior as in my initial post

[florianjacob]

No worries, I now have an idea what's happening there. 😄

I found out that without perl-doc installed, /usr/bin/perldoc contains only this:

#!/bin/sh
# place-holder, diverted by perl-doc
echo You need to install the perl-doc package to use this program. >&2
exit 1

which is (very probably) the thing that's causing the error message.

I guess there's some pipe in pod2usage /usr/bin/snazzer like
cat /usr/bin/snazzer | perldoc --some-options | $PAGER,
which would explain the observed behaviour.

There's nothing we can do about this in our usage of pod2usage, it seems.

Calling perldoc without arguments returns 255 on Debian 7 Wheezy, 22 using the current perl version on Arch Linux.
So we could probably work around this Debian packaging by introducing a check into the --man branch like:

…
perldoc
if [ $? -eq 1 ]
  printf "Calling perldoc returned 1. You're probably running Debian and are missing the perl-doc package for this function." >&2
  exit 1
fi
…

Of course this somewhat ugly and depends on the real perldoc never returning 1.
@csirac2 what do you think of this?

I'm a little reluctant to add this code as a permanent workaround for what seems like a downstream packaging bug, though.

It would be interesting to hear the Debian packager's stance to this.
Maybe they're not aware that pod2usage might use perldoc in this way, or at least have a better idea how one should check whether their perldoc works or not.

Note that this isn't snazzer-specific at all, you can actually reproduce this
with any text file, e.g. pod2usage --verbose 3 /usr/bin/pod2usage or even pod2usage --verbose 3 /etc/os-release. Each of those will first show the file and afterwards display the error message.

@jamiereid, in case you want to help @csirac and me out some more,
do you think you could open a Debian bug about pod2usage behaving like you described,
and post the link here?

[csirac2]

I'm aware of the perl-doc limitation. I'm not sure we want to complicate snazzer here; perhaps this would be a problem best solved by doing proper releases with pre-compiled man pages.

I think the actionable thing here for this bug is to ensure we're failing loudly during make if man pages can't be generated properly; we should create a separate issue for packaging and/or proper tarball releases.

[jamiereid]

Would implementing something like:

• if perldoc in path
  • if file -b --mime-type /usr/bin/perldoc is not text/x-shellscript
    • pod2usage -verbose 3

cover the "failing loudly during make if the man pages can't be generated properly"?

[csirac2]

AFAIK the dummy pod2usage already exits non-zero, is that the case? We just want the "build" to fail if build dependencies are missing

[jamiereid]

Strange thing is, at least on Debian Jessie, the pod2usage call for snazzer --help works, it's only when you attempt the pod2usage -verbose 3 call that it fails without the real perldoc installed.
Without perl-doc installed /usr/bin/perldoc is a simple shell script telling you to install perl-doc

That's lead me to think the problem is more around perl-doc missing and less around pod2usage.
Have I followed a red herring?

[florianjacob]

@jamiereid No, you're right. 😄 I found the same and tried to express that in #49 (comment) .

pod2usage is fully functional without perl-doc installed, except in the case of -verbose 3 where manpages are generated. In that case, the dummy perldoc is still executed, but pod2usage doesn't expect perldoc to return -1 and no output, which leads to this strange behaviour. A real perldoc called without arguments returns neither 0 or 1 but something higher, so we could use this to make the check in the Makefile.