utils/perldoc.Com vs utils/perldoc

[Nicholas Clark]

tl;dr: There's a question at the end...

So, I'm testing blead on the Itanium testdrive machine, configured with
-"des" -"Dusedevel". If I run

mmk install

things install somewhere. I failed to RTFM but figured out that it defaults
to a directory named after the build tree with _ROOT appended. If I go up
and run this:

@[.perl-58583d21ac03_ROOT]perl_setup


it seems that perl is now that perl.exe, and perldoc is now perldoc.Com in
[.perl-58583d21ac03_ROOT.utils]

This is good.

I uploaded the Pod::Perldoc tarball to the testdrive machine, unpacked it,
ran perl Makefile.PL and mmk

I see this:

$ perl Makefile.PL
Checking if your kit is complete...
Looks good
Generating a GNU-style Makefile
Writing Descrip.MMS for Pod::Perldoc
Writing MYMETA.yml and MYMETA.json
$ mmk test
cp [.lib.Pod.Perldoc]BaseTo.pm [.blib.lib.Pod.Perldoc]BaseTo.pm
cp [.lib.Pod.Perldoc]GetOptsOO.pm [.blib.lib.Pod.Perldoc]GetOptsOO.pm
cp [.lib.Pod.Perldoc]ToANSI.pm [.blib.lib.Pod.Perldoc]ToANSI.pm
cp [.lib.Pod.Perldoc]ToChecker.pm [.blib.lib.Pod.Perldoc]ToChecker.pm
cp [.lib.Pod.Perldoc]ToMan.pm [.blib.lib.Pod.Perldoc]ToMan.pm
cp [.lib.Pod.Perldoc]ToNroff.pm [.blib.lib.Pod.Perldoc]ToNroff.pm
cp [.lib.Pod.Perldoc]ToPod.pm [.blib.lib.Pod.Perldoc]ToPod.pm
cp [.lib.Pod.Perldoc]ToRtf.pm [.blib.lib.Pod.Perldoc]ToRtf.pm
cp [.lib.Pod.Perldoc]ToTerm.pm [.blib.lib.Pod.Perldoc]ToTerm.pm
cp [.lib.Pod.Perldoc]ToText.pm [.blib.lib.Pod.Perldoc]ToText.pm
cp [.lib.Pod.Perldoc]ToTk.pm [.blib.lib.Pod.Perldoc]ToTk.pm
cp [.lib.Pod.Perldoc]ToXml.pm [.blib.lib.Pod.Perldoc]ToXml.pm
cp [.lib.Pod]Perldoc.pm [.blib.lib.Pod]Perldoc.pm
cp perldoc.pod [.blib.lib.Pod]perldoc.pod
MCR PTAC$DKA0:[NCLARK.I.perl-58583d21ac03_ROOT]perl.exe.1 "-MExtUtils::Command"
-e "cp" "--" perldoc [.blib.script]perldoc
MCR PTAC$DKA0:[NCLARK.I.perl-58583d21ac03_ROOT]perl.exe.1 "-MExtUtils::MY" -e "M
Y->fixin(shift)" "--" [.blib.script]perldoc
MCR PTAC$DKA0:[NCLARK.I.perl-58583d21ac03_ROOT]perl.exe.1 "-MExtUtils::Command::
MM" "-e" "test_harness(0, '[.blib.lib]', '[.blib.arch]')" t/*.t t/*/*.t
t/load.t .............. ok
t/man/_get_columns.t .. ok
t/pod.t ............... skipped: Pod tests not required for installation.
All tests successful.
Files=3, Tests=48, 7 wallclock secs ( 0.51 usr + 0.00 sys = 0.51 CPU)
Result: PASS


using bash, I locate the perldoc that it built:

BASH-4.2$ less blib/script/perldoc
$ perl 'f$env("procedure")' "''p1'" "''p2'" "''p3'" "''p4'" "''p5'" "''p6'" "''p
7'" "''p8'"!
$ exit++ + ++$status!=0 and $exit=$status=undef; while($#ARGV != -1 and $ARGV[$#
ARGV] eq ''){pop @ARGV;}
#!perl

require 5;
BEGIN { $^W = 1 if $ENV{'PERLDOCDEBUG'} }
use Pod::Perldoc;
exit( Pod::Perldoc->run() );



quitting bash, if I install, I see this:

$ mmk install
Installing perl_root:[lib.Pod]perldoc.pod
Installing perl_root:[utils]perldoc.
Appending installation info to perl_root:[lib.VMS_IA64.5_19_4]perllocal.pod


(this sort of makes sense, as I'm installing the same version as is in blead)

the GNV tools reveal the slight expected difference in the two installed files:

--- utils/perldoc 2013-09-19 21:12:54 +0530
+++ utils/perldoc.Com 2013-09-19 20:23:10 +0530
@@ -1,6 +1,9 @@
$ perl 'f$env("procedure")' "''p1'" "''p2'" "''p3'" "''p4'" "''p5'" "''p6'" "''
p7'" "''p8'"!
$ exit++ + ++$status!=0 and $exit=$status=undef; while($#ARGV != -1 and $ARGV[$
#ARGV] eq ''){pop @ARGV;}
-#!perl
+ eval 'exec perl_root:[000000]Perl.exe -S $0 ${1+"$@"}'
+ if 0;
+
+# This "PERLDOC.com" file was generated by "[.UTILS]PERLDOC.PL"

require 5;
BEGIN { $^W = 1 if $ENV{'PERLDOCDEBUG'} }



If I delete the perldoc.com, I get this:

$ perldoc
Can't open perl script "perl_root:[utils]perldoc.com": no such file or directory
%SYSTEM-F-ABORT, abort

If I rename perldoc to perldoc.com (after tweaking its privs):

$ perldoc
Usage: perldoc.com [-hVriDtumFXlT] [-n nroffer_program]
[-d output_filename] [-o output_format] [-M FormatterModule]
[-w formatter_option:option_value] [-L translation_code]
PageName|ModuleName|ProgramName

Examples:

perldoc.com -f PerlFunc
perldoc.com -q FAQKeywords
perldoc.com -v PerlVar

The -h option prints more help. Also try "perldoc.com perldoc" to get
acquainted with the system. [Perldoc v3.20]
%SYSTEM-F-NOLOGNAM, no logical name match





So, my question is, surely that file should be installed as
"utils/perldoc.COM" not "utils/perldoc"?

And if so, where in ExtUtils::MakeMaker does it need fixing?

(Does anyone on VMS actually install modules from CPAN that have scripts?)

Nicholas Clark

[John E. Malmberg]

On 9/19/2013 1:36 PM, Nicholas Clark wrote:

> If I delete the perldoc.com, I get this:
>
> $ perldoc
> Can't open perl script "perl_root:[utils]perldoc.com": no such file or directory
> %SYSTEM-F-ABORT, abort

(mail client may wrape the line)
LION> show sym perldoc
PERLDOC == "$PERL_ROOT:[000000]PERL.EXE perl_root:[utils]perldoc.com
"-t""

The install/setup procedure creates a set of foreign commands similar to
Bash aliases.

Attempting to run perldoc.com by it self fails as it does not like its
name. It looks like it is set up to only be run as a parameter to perl.

The .com suffix was apparently added for some reason, but running the
com procedure directly just says not to run it that way in so many
words. So that is a bit confusing to me.

To make things run under GNV Bash some helper scripts can be used,
assuming that the logical name PERL_ROOT is set up.

BASH-4.2$ cat /usr/bin/perl
#! /bin/sh
/perl_root/perl $*
BASH-4.2$ cat /usr/bin/perldoc
#! /bin/sh
perl /perl_root/utils/perldoc.com -t $*
BASH-4.2$
BASH-4.2$ perldoc -t

Usage: perldoc.com [-hVriDtumFXlT] [-n nroffer_program]
[-d output_filename] [-o output_format] [-M FormatterModule]
[-w formatter_option:option_value] [-L translation_code]
PageName|ModuleName|ProgramName

Examples:

perldoc.com -f PerlFunc
perldoc.com -q FAQKeywords
perldoc.com -v PerlVar

The -h option prints more help. Also try "perldoc.com perldoc" to get

acquainted with the system. [Perldoc v3.19]

> So, my question is, surely that file should be installed as
> "utils/perldoc.COM" not "utils/perldoc"?
> And if so, where in ExtUtils::MakeMaker does it need fixing?
>
> (Does anyone on VMS actually install modules from CPAN that have scripts?)

I do not know.

Regards,
-John
malm...@encompasserve.organization
Personal Opinion Only

[Craig A. Berry]

On Sep 19, 2013, at 1:36 PM, Nicholas Clark <ni...@ccl4.org> wrote:

> So, my question is, surely that file should be installed as
> "utils/perldoc.COM" not "utils/perldoc"?

Yes.

> And if so, where in ExtUtils::MakeMaker does it need fixing?

Good question. ExtUtils::MakeMaker::MM_Unix::installbin says:

=item installbin (o)

Defines targets to make and to install EXE_FILES.

but I think it's lying. It doesn't seem to "make" anything at all but mostly copies files into place after fiddling with the shebang line. I think there is also some special handling if it finds POD in the file. I suppose the file copy line in there should append .com if it's not already present.

> (Does anyone on VMS actually install modules from CPAN that have scripts?)

Probably rarely. And installing it wouldn't let you run it automatically anyway unless you happen to put perl_root:[utils] into DCL$PATH. The reason you had it still looking for perldoc.com even after you deleted that file is because there is a foreign command for perldoc defined in perl_setup.com (more or less like an alias as John said).


________________________________________
Craig A. Berry
mailto:craig...@mac.com

"... getting out of a sonnet is much more
difficult than getting in."
Brad Leithauser

[Nicholas Clark]

On Thu, Sep 19, 2013 at 10:29:37PM -0500, Craig A. Berry wrote:
>
> On Sep 19, 2013, at 1:36 PM, Nicholas Clark <ni...@ccl4.org> wrote:
>
> > So, my question is, surely that file should be installed as
> > "utils/perldoc.COM" not "utils/perldoc"?
>
> Yes.

Would anyone notice if it wasn't installed as utils/perldoc?
(This might be related to the question below)

> > And if so, where in ExtUtils::MakeMaker does it need fixing?
>
> Good question. ExtUtils::MakeMaker::MM_Unix::installbin says:
>
> =item installbin (o)
>
> Defines targets to make and to install EXE_FILES.
>
> but I think it's lying. It doesn't seem to "make" anything at all but mostly copies files into place after fiddling with the shebang line. I think there is also some special handling if it finds POD in the file. I suppose the file copy line in there should append .com if it's not already present.

It seems to. I've just mailed perl5-porters a result of digging some more:

In that, as best I can tell, on all platforms the makefile copies the script
to the $(INST_SCRIPT) directory, and then runs the $(FIXIN) command:

$(INST_SCRIPT)/shasum : shasum $(FIRST_MAKEFILE) $(INST_SCRIPT)$(DFSEP).exists $(INST_BIN)$(DFSEP).exists
$(NOECHO) $(RM_F) $(INST_SCRIPT)/shasum
$(CP) shasum $(INST_SCRIPT)/shasum
$(FIXIN) $(INST_SCRIPT)/shasum
-$(NOECHO) $(CHMOD) $(PERM_RWX) $(INST_SCRIPT)/shasum


On *nix the FIXIN command is this

FIXIN = $(ABSPERLRUN) -MExtUtils::MY -e 'MY->fixin(shift)' --

and on VMS just the quoting differs:

FIXIN = $(ABSPERLRUN) "-MExtUtils::MY" -e "MY->fixin(shift)" "--"

MY->fixin calls the fixin() method, which uses $Config{startperl} to change
the #! line

However, the filename is unchanged.


On Win32, the FIXIN command appears to be this:

FIXIN = $(PERLRUN) ../../win32/bin/pl2bat.pl


As best I can tell, in the case pl2bat.pl would create a shasum.bat file
within $(INST_SCRIPT)

As far as the perl core goes, I believe that ./installperl will *only*
install shasum.bat

However, if one builds Digest::SHA (or Pod::Perldoc, or anything else) from
a tarball, does it end up with both shasum and shasum.bat being installed?

__END__

So it looks like the FIXIN command would be the correct place to do such a
renaming. Or duplicating.

> > (Does anyone on VMS actually install modules from CPAN that have scripts?)
>
> Probably rarely. And installing it wouldn't let you run it automatically anyway unless you happen to put perl_root:[utils] into DCL$PATH. The reason you had it still looking for perldoc.com even after you deleted that file is because there is a foreign command for perldoc defined in perl_setup.com (more or less like an alias as John said).

Yes, I'd spotted that before I mailed. (I didn't say that, sorry)


So it looks like on Win32, both foo and foo.bat are installed, but foo and
foo.bat differ.

Whereas, if I've got VMS figured out, foo and foo.com would be identical,
because $Config{startperl} is this:

$ perl 'f$env("procedure")' "''p1'" "''p2'" "''p3'" "''p4'" "''p5'" "''p6'" "''p
7'" "''p8'"!
$ exit++ + ++$status!=0 and $exit=$status=undef; while($#ARGV != -1 and $ARGV[$#
ARGV] eq ''){pop @ARGV;}
#!perl

and ALTERNATE_SHEBANG is defined as "$", resulting in toke.c skipping over
the first line. The other 2 are valid perl, as B::Deparse demonstrates:

$ perl -"MO=Deparse" [.perl-58583d21ac03_ROOT.utils]perldoc.com
$exit = $status = undef if $exit++ + ++$status != 0;
while ($#ARGV != -1 and $ARGV[$#ARGV] eq '') {
pop @ARGV;
}
require 5;
sub BEGIN {

$^W = 1 if $ENV{'PERLDOCDEBUG'};
}
use Pod::Perldoc;

exit 'Pod::Perldoc'->run;



So, I guess next VMS question is:

Is it actually necessary to install both (eg) perldoc and perldoc.com?


In that, ignoring backwards compatibility with what people expect

1) We seem to have a discrepancy between what the core installs for perldoc,
and what a CPAN update installs
2) We seem to have a discrepancy between scripts installed by the core
("foo.com") and scripts installed by non-core modules (just "bar")
3) It would make the core build process a lot easier if ExtUtils::MakeMaker
did the ".com" trick, as it's already doing the ".bat" dance for Win32,
because this would permit a lot of simplification of the utils/ directory.

Nicholas Clark

[John E. Malmberg]

The perldoc command looks weird on VMS, and I do not know the origin of
that convention.

VMS does not support shebangs.

Passing parameters on the command line to a program require that either
the DCL shell command tables be modified to know about that command, or
a foreign command to be created, or a DCL script be used.

Now with perldoc.com and friends, a hack was done so that the resulting
files are both a legal DCL command script and a legal Perl script.

That is very useful It means that all we should have to do is set a
foreign command to the perldoc.com and all should be well.

But for some strange reason it is not, in this case, and I do not know why.

When you run a script on VMS, you prefix it with a "@" sign, and if you
do not specify the ".xxx" extension, VMS adds a ".com" to the file.

But you do not need an an extension.

So to run perldoc.com on VMS you just do:
@perl_root:[utils]perldoc.com "-t"

If you do not quote the "-t" it gets uppercased by the DCL shell.

But if you do the above, it fails because it sees it's argv[0] was
"perldoc.com" and not "perldoc." and refuses to work. Now that could
not be too hard to fix.

It should also work to create a new file name perldoc. The period is
significant here in a new directory and then include the perldoc.com
contents, and then copy the resulting file into the utils directory.

[Oddity in VMS, you can not rename or copy perldoc.com to perldoc., VMS
assumes that you want to keep the .com extension and will preserve it :-(]

Then you could run it with the command below and it should just work.
Note that the period is significant.

@perl_root:[utils]perldoc. "-t"

And then the foreign command would just be:
perldoc :== "@perlroot:[utils]perldoc. "-t".

So in theory there should not be a need to have the existing more
complex foreign commands that are being set up.

After all, if you are going to always use Perl to invoke it, why add the
hack to make it work as a command file?

And even more curious, why add a hack to make look like it should work
as a command file with out actually making it work?

Regards,
-John

[Craig A. Berry]

On Sep 20, 2013, at 9:03 AM, Nicholas Clark <ni...@ccl4.org> wrote:

> On Thu, Sep 19, 2013 at 10:29:37PM -0500, Craig A. Berry wrote:
>>
>> On Sep 19, 2013, at 1:36 PM, Nicholas Clark <ni...@ccl4.org> wrote:
>>
>>> So, my question is, surely that file should be installed as
>>> "utils/perldoc.COM" not "utils/perldoc"?
>>
>> Yes.
>
> Would anyone notice if it wasn't installed as utils/perldoc?
> (This might be related to the question below)

I can imagine a plain perldoc being useful for anyone running bash on VMS, where I don't think perldoc.com would work. But in that case perldoc should not be identical to perldoc.com. The former should get an ordinary Unix-like shebang edit rather than the full monty startperl prependage.

>
> So it looks like the FIXIN command would be the correct place to do such a
> renaming. Or duplicating.

Yes, I think so.

> So it looks like on Win32, both foo and foo.bat are installed, but foo and
> foo.bat differ.
>
> Whereas, if I've got VMS figured out, foo and foo.com would be identical,

They are now by accident. I don't think they should be the same if we install both (which seems sensible).

> So, I guess next VMS question is:
>
> Is it actually necessary to install both (eg) perldoc and perldoc.com?
>
>
> In that, ignoring backwards compatibility with what people expect
>
> 1) We seem to have a discrepancy between what the core installs for perldoc,
> and what a CPAN update installs
> 2) We seem to have a discrepancy between scripts installed by the core
> ("foo.com") and scripts installed by non-core modules (just "bar")
> 3) It would make the core build process a lot easier if ExtUtils::MakeMaker
> did the ".com" trick, as it's already doing the ".bat" dance for Win32,
> because this would permit a lot of simplification of the utils/ directory.

Making it more like what Win32 does makes sense at least on the grounds that having three different ways to do the same thing is more crazy-making than necessary. Getting MakeMaker to do the work both inside and outside the core also makes sense. Thanks for peering into this mess.

[Craig A. Berry]

On Sep 20, 2013, at 6:01 PM, John E. Malmberg <malm...@Encompasserve.org> wrote:

> After all, if you are going to always use Perl to invoke it, why add the hack to make it work as a command file?

Because you may not use Perl to invoke it. You may invoke it with DCL which will then invoke Perl. You can invoke it by putting it in the command tables, or by setting up a foreign command, or by placing it in a directory listed in DCL$PATH. Any and all of which can make "perldoc" run perl_root:[utils]perldoc.com as a command procedure (which then re-runs itself using Perl). That's about as close to having a shebang line as you're going to get on VMS.

> And even more curious, why add a hack to make look like it should work as a command file with out actually making it work?

Seems to be working just fine and as designed.

[John E. Malmberg]

On 9/20/2013 8:05 PM, Craig A. Berry wrote:
>

> On Sep 20, 2013, at 6:01 PM, John E. Malmberg
<malm...@Encompasserve.org> wrote:
>
>> After all, if you are going to always use Perl to invoke it, why
>> add the hack to make it work as a command file?
>
> Because you may not use Perl to invoke it. You may invoke it with
> DCL which will then invoke Perl. You can invoke it by putting it in the
> command tables, or by setting up a foreign command, or by placing it in
> a directory listed in DCL$PATH. Any and all of which can make "perldoc"
> run perl_root:[utils]perldoc.com as a command procedure (which then
> re-runs itself using Perl). That's about as close to having a shebang
> line as you're going to get on VMS.

I would agree with all of that, except that this is what you get when
you try running it as a command procedure:

LION> @perl_root:[utils]perldoc
You called the perldoc command with a name that I didn't recognize.
This might mean that someone is tricking you into running a
program you don't intend to use, but it also might mean that you
created your own link to perldoc. I think your program name is
[perldoc.Com;1].

I'll allow this if the filename only has [a-zA-Z0-9._-].

at PERL_ROOT:[utils]perldoc.Com;1 line 11.
I think that your name for perldoc is potentially unsafe, so I'm
going to disallow it. I'd rather you be safe than sorry. If you
intended to use the name I'm disallowing, please tell the maintainers
about it. Write to:

Pod-P...@rt.cpan.org


at PERL_ROOT:[utils]perldoc.Com;1 line 11.

>> And even more curious, why add a hack to make look like it should
work as a command file with out actually making it work?
>
> Seems to be working just fine and as designed.

Just printing an error message and exiting is how it was designed?

Regards,
-John

[Craig A. Berry]

On Sep 21, 2013, at 11:02 AM, John E. Malmberg <malm...@Encompasserve.org> wrote:

> On 9/20/2013 8:05 PM, Craig A. Berry wrote:
>>
>
>> On Sep 20, 2013, at 6:01 PM, John E. Malmberg
> <malm...@Encompasserve.org> wrote:
>>
>>> After all, if you are going to always use Perl to invoke it, why
>>> add the hack to make it work as a command file?
>>
>> Because you may not use Perl to invoke it. You may invoke it with
>> DCL which will then invoke Perl. You can invoke it by putting it in the
>> command tables, or by setting up a foreign command, or by placing it in
>> a directory listed in DCL$PATH. Any and all of which can make "perldoc"
>> run perl_root:[utils]perldoc.com as a command procedure (which then
>> re-runs itself using Perl). That's about as close to having a shebang
>> line as you're going to get on VMS.
>
> I would agree with all of that, except that this is what you get when you try running it as a command procedure:
>
> LION> @perl_root:[utils]perldoc
> You called the perldoc command with a name that I didn't recognize.

Running it explicitly with "@" syntax is not one of the options I mentioned.

>>> And even more curious, why add a hack to make look like it should
> work as a command file with out actually making it work?
>>
>> Seems to be working just fine and as designed.
>
> Just printing an error message and exiting is how it was designed?

It was designed to be run as a command, not but running it with "@". When you don't use it the way it was designed to work, it in fact (unsurprisingly) doesn't work. Most likely with enough effort it could be made to work that way as well, but it was never intended to, and I don't see the value of it.

[John E. Malmberg]

On 9/21/2013 12:48 PM, Craig A. Berry wrote:
>
> On Sep 21, 2013, at 11:02 AM, John E. Malmberg <malm...@Encompasserve.org> wrote:
>
>> On 9/20/2013 8:05 PM, Craig A. Berry wrote:
>>>
>>
>>> On Sep 20, 2013, at 6:01 PM, John E. Malmberg
>> <malm...@Encompasserve.org> wrote:
>>>
>>>> After all, if you are going to always use Perl to invoke it, why
>>>> add the hack to make it work as a command file?
>>>
>>> Because you may not use Perl to invoke it. You may invoke it with
>>> DCL which will then invoke Perl. You can invoke it by putting it in the
>>> command tables, or by setting up a foreign command, or by placing it in
>>> a directory listed in DCL$PATH. Any and all of which can make "perldoc"
>>> run perl_root:[utils]perldoc.com as a command procedure (which then
>>> re-runs itself using Perl). That's about as close to having a shebang
>>> line as you're going to get on VMS.
>>
>> I would agree with all of that, except that this is what you get
>> when you try running it as a command procedure:
>>
>> LION> @perl_root:[utils]perldoc
>> You called the perldoc command with a name that I didn't recognize.
>
> Running it explicitly with "@" syntax is not one of the options I mentioned.

Using DCL$PATH gives the same result as using the "@" syntax.

Using a foreign command to run the perldoc.com is the same as using
either DCL$PATH or the "@" syntax.

I have never seen command tables run a command script or know of a way
to configure them to do so.

I can not see any way to run perldoc.com with out passing it as a script
to be run from Perl and work. And in that case, the shebang simulation
is ignored.

>>>> And even more curious, why add a hack to make look like it should
>> work as a command file with out actually making it work?
>>>
>>> Seems to be working just fine and as designed.
>>
>> Just printing an error message and exiting is how it was designed?
>
> It was designed to be run as a command, not but running it with "@".
> When you don't use it the way it was designed to work, it in fact
> (unsurprisingly) doesn't work. Most likely with enough effort it
> could be made to work that way as well, but it was never intended to,
> and I don't see the value of it.

The wrapper that simulates the shebang only runs it in a way that
produces an error message. I can not find any way to run it that takes
advantage of the wrapper and results in useful output.

All attempts to run perldoc.com as a command instead of as a perl script
that I can find just result in it emitting an error message.

The perldoc.com is not working the way that you describe because it is
testing to see what the name of the script is. I do not know if that
change happened after the shebang simulation was added.

Since it has been run as a perl script by the foreign command, it has
not been obvious that that running it standalone is not working.

If the shebang simulation worked, then a simpler foreign command could
be used.

Regards,
-John

[Craig A. Berry]

On Sep 21, 2013, at 1:33 PM, "John E. Malmberg" <malm...@Encompasserve.org> wrote:
>
> The wrapper that simulates the shebang only runs it in a way that produces an error message. I can not find any way to run it that takes advantage of the wrapper and results in useful output.
>
> All attempts to run perldoc.com as a command instead of as a perl script that I can find just result in it emitting an error message.

OK. I think I see where we are talking at cross purposes. I was talking exclusively about how the shebang emulation works in the general case by having $Config{startperl} prepended to the .com file. I assumed that perldoc.com would work just the same as any other comparable utility in this respect, but it doesn't. Bad assumption on my part. Sorry about that.

I think you might have been assuming the same thing in reverse, namely that if perldoc.com has a problem, there must be a more general problem with the shebang emulation. But I don't think there is.

The following illustrations that the shebang emulation works just fine in the general case:

$ type testshebang.com
$ perl 'f$env("procedure")' "''p1'" "''p2'" "''p3'" "''p4'" "''p5'" "''p6'" "''p7'" "''p8'"!
$ exit++ + ++$status!=0 and $exit=$status=undef; while($#ARGV != -1 and $ARGV[$#ARGV] eq ''){pop @ARGV;}

eval 'exec perl_root:[000000]Perl.exe -S $0 ${1+"$@"}'

if 0;

require 5;
print "hello\n";
$ define DCL$PATH SYS$DISK:[]
%DCL-I-SUPERSEDE, previous value of DCL$PATH has been superseded
$ testshebang
hello

But perldoc.com doesn't work that way, as you discovered, and it's because it's a pretty thin wrapper around Pod::Perldoc::run. So there is a bug in Pod::Perldoc (specifically Pod::Perldoc::program_name) which makes invalid and non-portable assumptions about the name of the file it's running. As far as I can see from a quick look, the only real problem is that it doesn't know what to do with the version number, i.e., "perldoc.com;1" is unacceptable, whereas "perldoc.com" would be ok.

I have no time for (and not much interest in) pursuing this further, but most likely replacing the line in Perldoc.pm that looks like:

(?: \. (?: bat | exe | com ) )? # possible extension

with

(?: \. (?: bat | exe | com | com;\d+ ) )? # possible extension

would do the trick. And version numbers on .exe files are also possible of course. So folks interested in this bug might want to report/fix it at <https://rt.cpan.org/Public/Dist/Display.html?Name=Pod-Perldoc>.