Re^3: Mysterious crash of perldoc

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

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

Comment on Re^3: Mysterious crash of perldoc Select or Download Code

Replies are listed 'Best First'.
Re^4: Mysterious crash of perldoc by pryrt (Abbot) on Mar 15, 2019 at 16:10 UTC
hippo, I don't think it's mentioning "foo.pl" which solved the problem when in a .pl extension: cmd.exe>type foo.pl && perldoc foo.pl #!/usr/bin/perl -w use strict; =item foo.pl My Documentation =cut No documentation found for "foo.pl". cmd.exe>type foo.pl && perldoc foo.pl #!/usr/bin/perl -w use strict; =head1 foo.pl My Documentation =cut foo.pl My Documentation cmd.exe>type foo.pl && perldoc foo.pl #!/usr/bin/perl -w use strict; =begin foo.pl My Documentation =cut No documentation found for "foo.pl". cmd.exe>type foo.pl && perldoc foo.pl #!/usr/bin/perl -w use strict; =head1 SomethingElse My Documentation =cut SomethingElse My Documentation cmd.exe>type foo.pl && perldoc foo.pl #!/usr/bin/perl -w use strict; =head4 SomethingElse My Documentation =cut SomethingElse My Documentation cmd.exe>type foo.pod && perldoc foo.pod #!/usr/bin/perl -w use strict; =pod My Documentation =cut My Documentation [download] Per that experiment: inside a .pl, it's solely a matter of whether there was a `=head`: it doesn't matter whether it's a `=head1` or `=head4`; if a .pl has a head, then perldoc is fine, whether or not it mentions the name of the .pl. Meanwhile, the .pod is fine with just `=pod`, and doesn't need a mention of `=head` to be properly parsed/rendered by perldoc.	[reply] [d/l] [select]

Replies are listed 'Best First'.

Re^4: Mysterious crash of perldoc
by pryrt (Abbot) on Mar 15, 2019 at 16:10 UTC

hippo, I don't think it's mentioning "foo.pl" which solved the problem when in a .pl extension:

cmd.exe>type foo.pl && perldoc foo.pl
#!/usr/bin/perl -w
use strict;

=item foo.pl

My Documentation

=cut

No documentation found for "foo.pl".

cmd.exe>type foo.pl && perldoc foo.pl
#!/usr/bin/perl -w
use strict;

=head1 foo.pl

My Documentation

=cut

foo.pl
    My Documentation


cmd.exe>type foo.pl && perldoc foo.pl
#!/usr/bin/perl -w
use strict;

=begin foo.pl

My Documentation

=cut

No documentation found for "foo.pl".

cmd.exe>type foo.pl && perldoc foo.pl
#!/usr/bin/perl -w
use strict;

=head1 SomethingElse

My Documentation

=cut

SomethingElse
    My Documentation

cmd.exe>type foo.pl && perldoc foo.pl
#!/usr/bin/perl -w
use strict;

=head4 SomethingElse

My Documentation

=cut

   SomethingElse
    My Documentation

cmd.exe>type foo.pod && perldoc foo.pod
#!/usr/bin/perl -w
use strict;

=pod

My Documentation

=cut

    My Documentation
[download]

Per that experiment: inside a .pl, it's solely a matter of whether there was a =head: it doesn't matter whether it's a =head1 or =head4; if a .pl has a head, then perldoc is fine, whether or not it mentions the name of the .pl. Meanwhile, the .pod is fine with just =pod, and doesn't need a mention of =head to be properly parsed/rendered by perldoc.

[reply]
[d/l]
[select]