The documentation Temporary Values via local() says

I agree. The docs are misleading. local actually does the same thing whether an assignment ("initializer") is present or not. local doesn't even know of the presence of an assignment. Similarly The assignment doesn't know local is present.

Were it not for the side effect of setting $SIG{ALRM} to undef, nobody would ever be able to tell that being set undef is apparently a step in the initialisation of the local.

Not so. I rely on that feature all the time.

sub d :lvalue {
   print("$_[0]: ", defined($_[1]) ? "[$_[1]]" : "undef", "\n");
   $_[1]
}

our $fred = 78;
d("pre local", $fred);
d("post local", local $fred);
[download]

gives

pre local: [78]
post local: undef
[download]

It can also be seen with an "initializer" present.

sub d :lvalue {
   print("$_[0]: ", defined($_[1]) ? "[$_[1]]" : "undef", "\n");
   $_[1]
}

our $fred = 78;
d("pre local", $fred);
d("post assign", d("post local", local $fred) = 90);
[download]

pre local: [78]
post local: undef
post assign: [90]
[download]

I agree. The docs are misleading.

OK, so we're agreed: either the code doesn't do what the documentation says, or vice versa -- a bug in one or the other, by any reasonable standard, IMO :-)

Not so. I rely on that feature all the time.

Now I'm fascinated. I confess, I've tried, but I cannot imagine a useful purpose for the fact that  local $foo = 76 ; fleetingly sets $foo to undef, before setting it to the required 76.

I understand that  local $fred ; sets $fred to undef. As far as I can see your code fragment:

  sub d :lvalue {
    print("$_[0]: ", defined($_[1]) ? "[$_[1]]" : "undef", "\n");
    $_[1]
  }

  our $fred = 78;
  d("post assign", d("post local", local $fred) = 90);
[download]

performs a local $fred (setting it undef) and passes that to sub d where it, eventually gets treated/returned as an lvalue. So far, so interesting. I only wish I could see how that informs the simpler case of:

  our $fred = 78 ;
  local $fred = 'ho hum' ;
[download]

where there is a straightforward initialiser and, AFAICS, no urgent need to set $fred to undef immediately before setting it to 'ho hum'.

Remembering, that the point here is that the current behaviour means that the recommended use of local for $SIG creates a very nasty hiatus in which the SIG_DFL state is set.

One can, of course, ignore the standard advice and save and restore the $SIG state by hand. Or get out POSIX and block the signal during the local. This second turns out to be essential in order to use local to automatically restore the $SIG state on forced exit (die) from an eval.

either the code doesn't do what the documentation says

It does what the docs says. The documentation just glosses over details that turn out to be relevant when magic vars are involved. (Some people think this kind of abstraction is a good thing.)

The fact that my and local are treated as directives by the docs hindered my understanding of them when I started using Perl. They truly are functions (named operators), and the "initializer" assignment is unrelated to them.

By the way, my clears its argument variables whether an "initializer" is present or not as well, but since magic is removed too, there are no side-effects.

I only wish I could see how that informs the simpler case of:

They're identical to Perl. Perl doesn't have a concept of initializers. It sees a local, and it sees an assignment. It evaluates both independently.

I cannot imagine a useful purpose for the fact that local $foo = 76 ; fleetingly sets $foo to undef, before setting it to the required 76.

There isn't. There's a useful purpose for local $foo to set $foo to undef. In your statement, local $foo is being used for its side-effects, but it's primary function still occurs.

What you ask for requires local to check the optree to see if it's evaluated as the LHS of an assignment. I normally abhore anything that peeks at the optree to determine behaviour. Such code is inherently fragile. It works most of the time, leading people to think it always works, leading to subtle bugs. That makes the situation worse.

But in this case, we're already in that situation. So maybe it is appropriate here.

[Using POSIX to block the signal during the local] turns out to be essential in order to use local to automatically restore the $SIG state on forced exit (die) from an eval.

Not so. I already provided code that doesn't use POSIX or local and restores the signal automatically on scope exit.