Escript doc mismatch?

[Michael Richter]

Quoting from http://www.erlang.org/doc/man/escript.html:

The header of an Erlang script differs from a normal Erlang module. The
> first line is intended to be the interpreter line, which invokes escript.
> However if you invoke escript like this
>
> $ *escript factorial 5*
>
> *the contents of the first line does not matter, but it cannot contain
> Erlang code as it will be ignored. *
>

(*Emphasis* mine. *Bold* in original.)

The reality:

michael@REDACTED:~/junk$ cat factorial
> This line should be ignored, no?
> %% -*- erlang -*-
> %%! -smp enable -sname factorial -mnesia debug verbose
> main([String]) ->
>     try
>         N = list_to_integer(String),
>         F = fac(N),
>         io:format("factorial ~w = ~w\n", [N,F])
>     catch
>         _:_ ->
>             usage()
>     end;
> main(_) ->
>     usage().
>
> usage() ->
>     io:format("usage: factorial integer\n"),
>     halt(1).
>
> fac(0) -> 1;
> fac(N) -> N * fac(N-1).
> michael@REDACTED:~/junk$ escript factorial 10
> factorial:4: undefined macro 'main'
> escript: There were compilation errors.
>

A further test:

michael@REDACTED:~/junk$ cat factorial
> main([String]) ->
>     try
>         N = list_to_integer(String),
>         F = fac(N),
>         io:format("factorial ~w = ~w\n", [N,F])
>     catch
>         _:_ ->
>             usage()
>     end;
> main(_) ->
>     usage().
>
> usage() ->
>     io:format("usage: factorial integer\n"),
>     halt(1).
>
> fac(0) -> 1;
> fac(N) -> N * fac(N-1).
> michael@REDACTED:~/junk$ escript factorial 10
> factorial 10 = 3628800
>

By my reading of the manual that first script should have worked (first line
ignored thus passing over invalid Erlang) and the second should have failed
(first line ignored, taking with it an important chunk of Erlang code).  The
reason I want this to work properly is because I'd like to have escript
working under Windows.  For that to happen the first line has to be
something like "@escript %0 %* & exit/b" which is obviously not valid
Erlang.

I've already got escript (mostly) working under Windows using some hacks.
The first hack works under the TCC/LE CMD.EXE drop-in.  For this I create an
alias called "#!" that is quietly replaced with "cmd/c".  I also make use of
a special variable in that shell--"%_batchname"--that gives me the full name
of the batch file being executed.  Together these give me a batch header
that works for escript: "#! escript.exe %_batchname %* & exit/b".  Not
everybody uses TCC/LE, however (although they really should if they're stuck
in the Windows ghetto!), so that is only a useful tool for my machines.  An
attempt to get this working for CMD.EXE itself involving a batch file called
"#!.bat" was successful (sorta) except for the fact that to stop the command
from being echoed to the screen I have to put an "@" character in front of
things which goes back to breaking as per the above tests.

Is there any chance that we could get the documented behaviour instead of
trying to make workarounds for it?