.SECONDARY documentation is slightly misleading

[Britton Kerin]

The documentation for the special .SECONDARY: target looks like this:

  .SECONDARY
      The targets which .SECONDARY depends on are treated as
      intermediate
      files, except that they are never automatically deleted. See
      Chains of
      Implicit Rules.

      .SECONDARY with no prerequisites causes all targets to be treated
      as
      secondary (i.e., no target is removed because it is considered
      intermediate).

The problem is the parenthesize comment "i.e., no target ...".  Normally
such a
comment is expected to be an overall summary of the preceding material
being
summarized, not a summary of a partial effect.  But in this case the
summary
ignores an important effect: the fact that prerequisites of .SECONDARY
are
treated as intermediate.  As the "Chains of Implicit Rules" section
describes,
intermediatenes has other significant effects besides eventual removal
of any
file associated with a target.  Things get especially entertaining when
your
phony targets are affected by .SECONDARY:.  In that case I believe I ran
into
places where use of .PHONY on the phony targets made a difference, but
I've
had enough make for this morning to try reproducing it: perhaps it will
be
obvious to an expert that that is expected, or impossible. 

I think the .SECONDARY target might be better if it didn't twiddle the
intermediateness of its prerequisites at all, but simply prevented them
from
being automagically removed if intermediate.  Note that no new
capabilities are
added by having .SECONDARY affect intermediateness: .INTERMEDIATE: can 
intermediateize a file, and .SECONDARY: can't unintermediatize one.

Its probably too late now to change .SECONDARY: but perhaps a new target
which only prevents deletion could be added.

Britton