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:

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
[download]

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.