Mysterious crash of perldoc

[Textorix]

Brethren and sistren (if that’s a word),

First post here. Seeking wisdom on the use of perldoc to look at new POD content that I’ve been trying to write, as for me it’s exiting with error status.
Has anyone had this happen and discovered a solution?

I’ve inherited some Perl code that is fairly devoid of documentation and contains no POD at all. Being fairly new to Perl and new to this project, I figured hey why not try to start writing some POD, at least for the things that I’m changing significantly.

The trouble is that, when I run perldoc -F or perldoc -t -F on my file, it doesn’t produce any output, and exits with a status code of 1.
This is happening to me on two machines, one with CentOS 6 and the other with Mac OS X Mojave. Perl versions are 5.10.1 and 5.18.2, respectively.

I ran perl -cw and podchecker on my file and it was blessed by both commands, so my impression is that the problem is not with my file content. Also, I’m not running as root or using sudo.

I tried setting PERLDOCDEBUG, up to as high as 100 (not sure if higher would accomplish anything), and the last thing reported in the debug output is that it’s looking for my file. Then nothing.
I have set PERLDOC_PAGER to less -+C -E; this didn’t appear to change anything.

The less and man commands work fine on both machines, and perldoc does OK on an installed module (e.g. perldoc CGI).

At the suggestion of choroba in the chatterbox (thank you), I tried using strace on the command. In the strace output, I can see that my file is getting read (all contents) and closed. After the file is closed, this appears next:

rt_sigaction(SIG_0, NULL, {0x9f0ed807, [], SA_RESTORER|SA_RESTART|SA_INTERRUPT|SA_NOCLDWAIT|0x2577268, (nil)}, 8) = -1 EINVAL (Invalid argument)

Following that are 66 other rt_sigaction calls for other signals (SIGHUP, SIGINT, etc.) and those others all return 0 (success). Then exit_group(1), and that’s the end. The process exits with status 1.

I’m guessing that the EINVAL return from that first rt_sigaction call may be because the system considers SIG_0 to be an invalid signal, and that this EINVAL return may be related somehow to perldoc’s decision to exit_group(1). But these are mere guesses.

Does anyone have other suggestions or insights? This situation is rather disappointing, as not having perldoc working will significantly reduce the motivation to write any more POD.

Here’s a super-simple example script (not the actual code I was documenting) for which perldoc -F is exhibiting the same problem.

#!/usr/bin/perl -w
use strict;

=pod

My documentation.

=cut

Thank you...

UPDATE!

The situation has been resolved (thank you to all for replies to this post). Quoting here from further down (Re^4) in the discussion with pryrt...

There appear two have been two issues contributing to my situation. One was the lack of a heading starter, as you pointed out. That appears to be the cause of the status=1 error exit. The other is that, on both of my systems, I was seeing no output because of the PERLDOC_PAGER=“less -+C -E” value that I was using. Because my POD text is so short... less than one page... the “-E” option was causing less to exit immediately (normal exit) after displaying the text. So there still appeared to be no output -- although looking more closely, the screen sometimes flickers slightly while the output appears and then disappears. In this case the exit status was normal 0 instead of 1.

...

That said, I’m a bit surprised that this heading element is required. In the perlpod web page, when I read “You can simply type in your text without any markup whatsoever, and with just a blank line before and after,” apparently I took that too literally, or perhaps out of context. Looking at the page again, it still doesn’t look obvious to me that a heading paragraph is required to be present, from the description in that page. It’s also a bit odd that the podchecker indicated all was OK in my original file, despite lack of that element whose absence caused an error in perldoc.

[pryrt]

Nice SSCCE*. You also need a paragraph starter other than =pod in your POD, like:

#!/usr/bin/perl -w
use strict;

=pod

=head1 TITLE

My Documentation

=cut

this renders fine for me

edit: *: that looked sarcastic on re-read. I meant literally: it's hard to get a shorter, more simple evidence of your problem than that, so great job!

edit 2: thinking about it more... that's not likely to be your culprit, because you said you had more POD than that. If I try something as simple as this,

#!/usr/bin/perl -w
use strict;

=pod

My Documentation

=head1 TITLE

here

=cut

... then it also renders. So you can have a plain paragraph at the start, as long as there's one defined paragraph below... I assume you had more POD than that, so, not sure anymore. :-(

edit 3: fix missing semicolons in example code

[Textorix]

Hi, thanks for the reply! I tried adding a =head TITLE element as in your first example (with blank line before and after), and I'm still getting the same behavior. Crashola. The podchecker also said this modified file is OK, as with the original file.

It seems like this problem is likely something environment or system related. It's odd, though, that the same problem is occurring on two rather different systems (CentOS 6 and OSX Mojave).
About the Mac, BTW, I didn't run strace on that machine, only on the CentOS machine. The Mac doesn't have strace on it; it does have dtrace but that requires elevated privilege to run, which I don't think I have.

[pryrt]

I tried adding a =head TITLE element as in your first example (with blank line before and after)

Did you use =head1 TITLE, like I showed, or =head TITLE like you showed?

and I'm still getting the same behavior. Crashola

The exact same error message, or a different error message? If different, please quote it here.

Using this exact text, perldoc blah.pl processes just fine for me on Windows Strawberry Perl 5.26.2 and on an ancient CentOS 4.6 with Perl 5.8.5:

#!/usr/bin/perl -w
use strict;

=pod

=head1 TITLE

My Documentation

=cut

[hippo]

This is happening to me on two machines, one with CentOS 6

I have a couple of CentOS6 boxes and am unable to reproduce your findings.

$ cat foo.pod
#!/usr/bin/perl -w
use strict;

=pod

My documentation.

=cut

$ perldoc -T foo.pod   
FOO(1)                User Contributed Perl Documentation             
+  FOO(1)



My documentation.



perl v5.10.1                      2019-03-14                          
+  FOO(1)
$

This suggests that either this isn't the POD you are really using or that your perl (or O/S) installation has become badly broken in some way. The fact that you're seeing it on 2 completely different operating systems does rather lean towards the former. Is this the entirety of the POD you are using?

[Textorix]

That's interesting that you're getting different results on another CentOS 6 system using the same POD input. Although my situation seems to have a resolution from the discussion with pryrt, I don't know how to explain why you're getting different results. Yes, that posted POD was literally one of the cases in which I was getting an error 1 status exit from the "perldoc -F" command. When I added a =head1 element to the file, that was the main thing that resolved the error. The file processes OK with or without the =pod element, but the lack of a =head1 or something similar seems to trigger the error. I also had to fix the options to my PERLDOC_PAGER in order to see the output without the pager exiting immediately.

Edit 1

Oh... one possibility might be that you're saving the text as a .pod file, whereas I had it in a .pl file. Trying it out over here... yes, if I rename my file from .pl to .pod, then perldoc runs OK on it, without the =head1 element. Very interesting.

[hippo]

Good catch - the name is indeed significant. If I rename the file to have a .pl extension then I see this:

$ mv foo.pod foo.pl
$ perldoc -T foo.pl 
No documentation found for "foo.pl".
$ echo $? 
1
$

because the contents are now expected to be a perl script and there's nothing in the POD there which refers to "foo.pl". Adding a header with that text for reference satisfies this requirement.

$ cat foo.pl
#!/usr/bin/perl -w
use strict;

=pod

=head1 foo.pl

My documentation.

=cut

$ perldoc -T foo.pl
FOO(1)                User Contributed Perl Documentation             
+  FOO(1)



foo.pl
       My documentation.



perl v5.10.1                      2019-03-15                          
+  FOO(1)
$ echo $?
0
$

[Laurent_R]

Hi Textorix,

perhaps you could try to run some other POD renderers on your source file, such as pod2html, pod2latex, or pod2text, etc. I think they are bundled with most or all of Perl installations. This might help you to figure out whether your POD is correct or not, or whether there is perhaps something wrong in your environment.

Or you could even try an on-line POD to HTML renderer: https://metacpan.org/pod2html.

[Textorix]

Hi Laurent_R,

Thanks for your reply... especially about the online renderer... that looks useful!

A resolution to the problem has been found--see update in the original post. It seems that perldoc will error out on a .pl or .pm file if some sort of paragraph starter other than =pod is not present, although podchecker does not flag this as invalid POD and no error occurs in perldoc if the file is a .pod file.

[davido]

I looked at the source code for Pod::Perldoc yesterday and was also surprised to see =head being treated special explicitly in the code. In particular, subroutine containspod opens a file and looks for m/^=head/. It feels to me like that ought to allow for any of the POD commands, but certainly =pod. Perhaps that would violate some aspect of the spec, though I haven't been able to find anything suggesting that POD has to contain a =head1 command.

I don't know if this qualifies as a bug, or if it's intended behavior. It is a little surprising though.

[karlgoethebier]

It may be that the doc you refer to is a bit misleading. Did you notice that it has a head: „Ordinary Paragraph“? Regards, Karl

[pryrt]

Did you notice that it has a head: „Ordinary Paragraph“?

So far as I can notice, the doc doesn't say anywhere that your POD cannot consist solely of "ordinary paragraphs". As davido pointed out, it seems odd that it would require a =head# paragraph.

[karlgoethebier]

Yes, sure. You are right. But please don‘t be so jesuitically correct 😎. Best regards, Karl