pod documentation in zsh scripts (Was: Block comments ala Ray)

[Stephane Chazelas <stephane@xxxxxxxxxxxx>]

2021-02-16 16:30:49 +0100, Juergen Christoffel:
[...]
> That said, wouldn't it be possible to augment the comment parsing to use
> something like perl's "plain old documentation" (pod) meachnism, e.g.
[...]
> P.S. Even the use of the here document for block comments look less
> horrible to me, because it's easily recognized when looking at a script.
[...]

As discussed earlier in this thread, here docs can already be
(ab)used to add pod documentation to zsh scripts. An example one
could look like:

#! /bin/zsh -

for a (pod head{1..4} over item back begin end for encoding)
  aliases[=$a]=":||:<<'=cut' #"

=encoding utf8

=head1 NAME

mytool - blah

=head1 SYNOPSIS

B<mytool> [B<-f>] [B<-h>] [B<-o> I<flag>]...

=head1 DESCRIPTION

B<mytool> does cool stuff

=head1 OPTIONS

=over
=cut

flag=false
opt=()
while getopts hfo: o; do
  case $o in
    (f) flag=true

=item B<-f>

turns a flag on
=cut

  ;;(o) opt+=("$OPTARG")

=item B<-o> I<opt>

to pass some optional value
=cut

  ;;(h) LESS=${LESS}RFX exec perldoc -oterm $0:P

=item B<-h>

show this manual.

=back
=cut

  ;;(*) exit 1
  esac
done

=head1 AUTHOR

Stéphane
=cut