0

I wonder: In Perl POD is recognized partially by the Perl parser, and there is the __END__ keyword to stop Perl parsing. If I want to write POD in a shell script (maybe at the end of the script), can that be done, and if so: How?

U. Windl
  • 3,480
  • 26
  • 54

1 Answers1

2

You could use in your shell a dummy here document:

: <<END_OF_POD
write your
POD description
here
END_OF_POD

Example for a complete script podtest:

: <<'__END__'
=pod

=head1 test

=cut

__END__
echo hello

Doing a sh podtest runs the script. Doing a perldoc podtest shows the doc.

user1934428
  • 19,864
  • 7
  • 42
  • 87
  • 1
    Nice suggestion. I'd also quote the heredoc to avoid any substitutions: `: << 'END_OF_POD'` – glenn jackman Mar 16 '22 at 14:53
  • I tested it, but there is a problem: The documentation would end with `END_OF_POD`. Maybe show a short real example that 1) runs correctly in the shell, 2) passes `podchecker`, and 3) produces the correct output using `perldoc`. – U. Windl Sep 08 '22 at 10:30
  • You don't use podchecker and perldoc. It's a shell script which serves the same purpose. I didn't expect that you would use perldoc for generating code. However, in this case - how is _peldoc_ behaving if you use `__END__` to terminate the _here_-string, instead of `END_OF_POD`? – user1934428 Sep 08 '22 at 10:56
  • @U.Windl : Added example. – user1934428 Sep 08 '22 at 11:03
  • OK, adding a `=cut` at the end does the trick. `perldoc` does not recognize `__END__` as special. – U. Windl Sep 08 '22 at 11:18
  • @U.Windl : Uh, my Perl days are already long time back. How about using `__DATA__` instead of `__END__`? The Perl parser is not supposed to touch thing in the __DATA__ area. – user1934428 Sep 08 '22 at 11:47
  • What I had meant to say was: `=cut` at the end does the trick (terminate POD processing), while `<<'__END__'` is not different from any other string. However with `=cut` that does not matter. – U. Windl Sep 09 '22 at 09:02