RE: delete-other-frames

[Drew Adams]

>   > For the future, please adopt the following style:
>   >   This function deletes the specified @var{frame}.
>   > rather than using this:
>   >   This function deletes the frame @var{frame}.
> 
> The latter is the grammatically correct way.  A parameter name in
> italics, such as "@var{frame}", acts as a _name_ that refers to the
> actual value of the argument.  Just as we would write
> 
>   Send it to my assistant, Jeanne.
> 
> we should write,
>   delete the frame, @var{f}.
> or
>   delete the frame, @var{frame}.

Yes, and no.

1. If there is only one frame in the discussion, and @var{f}
is a name for it, then "delete the frame, @var{f}" is correct.
This is _non-restrictive apposition_: the frame and @var{f} are
two ways of designating the same thing: THE frame in the scope
of discussion.

The name @var{f} does not restrict the choice of frames here;
it is understood that there is only one, and it is called
@var{f}.  You could drop either "the frame" or "@var{f}"
without loss of meaning: neither qualifies the other.

But if there might be more than one frame in the discussion,
and @var{f} is the one we are concerned with at present, then
this is correct: "delete the frame @var{f}".  (Note: no comma.)
And so is this: "delete frame @var{f}".

Here, @var{f} is the name of the particular frame we care
about at the moment, but we do not assume that it is the only
one in the general discussion.  This is _restrictive apposition_:
"@var{f}" restricts "frame", identifying the one frame out of
possibly many that we are concerned with now.

It is the difference between "my sister, Sue" and "my sister
Sue".  In the first case I have only one sister.  In the
second I likely have more than one.  In both cases the nominal
appositive "Sue" applies to the descriptive appositive "sister".
In the first case "Sue" is non-restrictive; in the second case
it is restrictive.

Clearly, it is easy to not notice a comma, or to mistakenly
add or forget a comma, so it is important for clarity that the
rest of the text reinforces the meaning.

The form of restrictive apposition where "the" is dropped can
make reading easier, especially when there are multiple things
that we are juggling, as is often the case for technical writing.

For example, if we've introduced things clearly enough then it
can be simpler to speak of "querying columns JCOL and KCOL of
table TAB", instead of bothering readers with "querying the
columns JCOL and KCOL of the table TAB".

When "the" is omitted the apposition is partial: Only the
descriptive appositive (the type: columns or tables) could
be omitted; the nominal appositive (the name: JCOL or TAB)
is needed (and sufficient).

This dropping of the type and using only the name brings us
to the next point.

2. I think Eli was talking about something different, but
related: the fact that in Emacs doc the name of a parameter
is often chosen to be a type name, and a convention is to
omit the type noun to which the restrictive appositive
applies and let the parameter name stand alone.

IOW, if the name of the individual echoes the name of the
type then we can get by with just the individual name.

Example:

Just "copy FILE to DIRECTORY", instead of "copy file FILE
to directory DIRECTORY" (or the even heavier "copy the
file FILE to the directory DIRECTORY).

And if there are multiple individuals of the same type
then we can use different names for them that each echo
the type name: "copy FILE1 and FILE2 to DIRECTORY".

This is a kind of abbreviation, and it is fine too.