unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* delete-other-frames
@ 2016-08-23  8:19 martin rudalics
  2016-08-23 14:09 ` delete-other-frames Eli Zaretskii
  0 siblings, 1 reply; 15+ messages in thread
From: martin rudalics @ 2016-08-23  8:19 UTC (permalink / raw)
  To: emacs-devel

I'd like to fix two issues with ‘delete-other-frames’ but am yet
undecided on how to do that.

(1) With emacs -Q step by step evaluate the following forms:

(setq less (make-frame '((minibuffer . nil))))
(setq normal (make-frame))
(delete-other-frames normal)

This gets me:

Debugger entered--Lisp error: (error "Attempt to delete a surrogate minibuffer frame")
   delete-frame(#<frame *scratch* 01bb1090>)
   delete-other-frames(#<frame *scratch* 050f4a30>)
   eval((delete-other-frames normal) nil)
   elisp--eval-last-sexp(nil)
   eval-last-sexp(nil)
   funcall-interactively(eval-last-sexp nil)
   call-interactively(eval-last-sexp nil nil)
   command-execute(eval-last-sexp)

The problematic code in ‘delete-other-frames’ is this:

     ;; Delete mon-minibuffer-only frames first, because `delete-frame'
     ;; signals an error when trying to delete a mini-frame that's
     ;; still in use by another frame.
     (dolist (frame frames)
       (unless (eq (frame-parameter frame 'minibuffer) 'only)
	(delete-frame frame)))

Here we try to delete all frames whose `minibuffer' parameter is not
`only'.  However, the minibuffer window of a minibuffer-less frame might
be on a _normal_ frame as in our example: The minibuffer window of the
frame ‘less’ is owned by the initial frame and ‘delete-other-frames’
tries to delete that frame before ‘less’, resulting in the error cited
above.

Should we document the current behavior in the doc-string or should we
amend the code?

(2) The doc-string says "Delete all frames on the current terminal,
except FRAME."  IIUC this doesn't make much sense when FRAME is not on
the current terminal.  In that case, ‘delete-other-frames’ will delete
all frames on the current terminal and leave the frames on FRAME's
terminal alone.  In order to delete all other frames on FRAME's terminal
one has to make that terminal current first.  If that is the desired
behavior, we should mention it in the doc-string.  Otherwise, we should
delete all other frames on FRAME's terminal.

Thanks for suggestions, martin




^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: delete-other-frames
  2016-08-23  8:19 delete-other-frames martin rudalics
@ 2016-08-23 14:09 ` Eli Zaretskii
  2016-08-23 17:56   ` delete-other-frames Richard Copley
  2016-08-24  9:06   ` delete-other-frames martin rudalics
  0 siblings, 2 replies; 15+ messages in thread
From: Eli Zaretskii @ 2016-08-23 14:09 UTC (permalink / raw)
  To: martin rudalics; +Cc: emacs-devel

> Date: Tue, 23 Aug 2016 10:19:59 +0200
> From: martin rudalics <rudalics@gmx.at>
> 
> The problematic code in ‘delete-other-frames’ is this:
> 
>      ;; Delete mon-minibuffer-only frames first, because `delete-frame'
>      ;; signals an error when trying to delete a mini-frame that's
>      ;; still in use by another frame.
>      (dolist (frame frames)
>        (unless (eq (frame-parameter frame 'minibuffer) 'only)
> 	(delete-frame frame)))
> 
> Here we try to delete all frames whose `minibuffer' parameter is not
> `only'.  However, the minibuffer window of a minibuffer-less frame might
> be on a _normal_ frame as in our example: The minibuffer window of the
> frame ‘less’ is owned by the initial frame and ‘delete-other-frames’
> tries to delete that frame before ‘less’, resulting in the error cited
> above.
> 
> Should we document the current behavior in the doc-string or should we
> amend the code?

IMO, amend the code.

> (2) The doc-string says "Delete all frames on the current terminal,
> except FRAME."  IIUC this doesn't make much sense when FRAME is not on
> the current terminal.  In that case, ‘delete-other-frames’ will delete
> all frames on the current terminal and leave the frames on FRAME's
> terminal alone.  In order to delete all other frames on FRAME's terminal
> one has to make that terminal current first.  If that is the desired
> behavior, we should mention it in the doc-string.  Otherwise, we should
> delete all other frames on FRAME's terminal.

The latter, I think.



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: delete-other-frames
  2016-08-23 14:09 ` delete-other-frames Eli Zaretskii
@ 2016-08-23 17:56   ` Richard Copley
  2016-08-23 18:31     ` delete-other-frames Eli Zaretskii
  2016-08-24  9:07     ` delete-other-frames martin rudalics
  2016-08-24  9:06   ` delete-other-frames martin rudalics
  1 sibling, 2 replies; 15+ messages in thread
From: Richard Copley @ 2016-08-23 17:56 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: martin rudalics, Emacs Development

On 23 August 2016 at 15:09, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Tue, 23 Aug 2016 10:19:59 +0200
>> From: martin rudalics <rudalics@gmx.at>
>>
>> The problematic code in ‘delete-other-frames’ is this:
>>
>>      ;; Delete mon-minibuffer-only frames first, because `delete-frame'
>>      ;; signals an error when trying to delete a mini-frame that's
>>      ;; still in use by another frame.
>>      (dolist (frame frames)
>>        (unless (eq (frame-parameter frame 'minibuffer) 'only)
>>       (delete-frame frame)))
>>
>> Here we try to delete all frames whose `minibuffer' parameter is not
>> `only'.  However, the minibuffer window of a minibuffer-less frame might
>> be on a _normal_ frame as in our example: The minibuffer window of the
>> frame ‘less’ is owned by the initial frame and ‘delete-other-frames’
>> tries to delete that frame before ‘less’, resulting in the error cited
>> above.
>>
>> Should we document the current behavior in the doc-string or should we
>> amend the code?
>
> IMO, amend the code.
>
>> (2) The doc-string says "Delete all frames on the current terminal,
>> except FRAME."  IIUC this doesn't make much sense when FRAME is not on
>> the current terminal.  In that case, ‘delete-other-frames’ will delete
>> all frames on the current terminal and leave the frames on FRAME's
>> terminal alone.  In order to delete all other frames on FRAME's terminal
>> one has to make that terminal current first.  If that is the desired
>> behavior, we should mention it in the doc-string.  Otherwise, we should
>> delete all other frames on FRAME's terminal.
>
> The latter, I think.

Possibly related: from emacs -Q,

C-x b * RET ;; create and switch to buffer "*"
M-x ediff-buffers RET RET RET ;; ediff buffers "*" and "*scratch*"
;; Now attempt to close the main Emacs frame using the window manager

This gives:

Debugger entered--Lisp error: (error "Attempt to delete a surrogate
minibuffer frame")
  delete-frame(#<frame *scratch* 00000004009c5870> t)
  handle-delete-frame((delete-frame (#<frame *scratch* 00000004009c5870>)))
  funcall-interactively(handle-delete-frame (delete-frame (#<frame
*scratch* 00000004009c5870>)))
  call-interactively(handle-delete-frame nil [(delete-frame (#<frame
*scratch* 00000004009c5870>))])
  command-execute(handle-delete-frame nil [(delete-frame (#<frame
*scratch* 00000004009c5870>))] t)
  read-event(nil t 2)
  sit-for(2)
  execute-extended-command(nil "toggle-debug-on-error" "t-d-o-e")
  funcall-interactively(execute-extended-command nil
"toggle-debug-on-error" "t-d-o-e")
  call-interactively(execute-extended-command nil nil)
  command-execute(execute-extended-command)

I've never been sure whether this deserves a bug report, or what
should be the expected behaviour. FWIW when this happens my intention
is usually to kill Emacs. In any case the error message isn't very
user friendly.



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: delete-other-frames
  2016-08-23 17:56   ` delete-other-frames Richard Copley
@ 2016-08-23 18:31     ` Eli Zaretskii
  2016-08-23 19:55       ` delete-other-frames Richard Copley
  2016-08-24  9:07     ` delete-other-frames martin rudalics
  1 sibling, 1 reply; 15+ messages in thread
From: Eli Zaretskii @ 2016-08-23 18:31 UTC (permalink / raw)
  To: Richard Copley; +Cc: rudalics, emacs-devel

> From: Richard Copley <rcopley@gmail.com>
> Date: Tue, 23 Aug 2016 18:56:52 +0100
> Cc: martin rudalics <rudalics@gmx.at>, Emacs Development <emacs-devel@gnu.org>
> 
> C-x b * RET ;; create and switch to buffer "*"
> M-x ediff-buffers RET RET RET ;; ediff buffers "*" and "*scratch*"
> ;; Now attempt to close the main Emacs frame using the window manager
> 
> This gives:
> 
> Debugger entered--Lisp error: (error "Attempt to delete a surrogate
> minibuffer frame")
>   delete-frame(#<frame *scratch* 00000004009c5870> t)
>   handle-delete-frame((delete-frame (#<frame *scratch* 00000004009c5870>)))
>   funcall-interactively(handle-delete-frame (delete-frame (#<frame
> *scratch* 00000004009c5870>)))
>   call-interactively(handle-delete-frame nil [(delete-frame (#<frame
> *scratch* 00000004009c5870>))])
>   command-execute(handle-delete-frame nil [(delete-frame (#<frame
> *scratch* 00000004009c5870>))] t)
>   read-event(nil t 2)
>   sit-for(2)
>   execute-extended-command(nil "toggle-debug-on-error" "t-d-o-e")
>   funcall-interactively(execute-extended-command nil
> "toggle-debug-on-error" "t-d-o-e")
>   call-interactively(execute-extended-command nil nil)
>   command-execute(execute-extended-command)
> 
> I've never been sure whether this deserves a bug report, or what
> should be the expected behaviour.

If we don't know what should be the correct behavior, how can we fix
this?

> FWIW when this happens my intention is usually to kill Emacs.

But there are more than one frame in this case, so closing one of them
can never kill Emacs anyway, even if the frame you want to delete will
be deleted.

As with any multi-window program, closing one window normally doesn't
exit the program.



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: delete-other-frames
  2016-08-23 18:31     ` delete-other-frames Eli Zaretskii
@ 2016-08-23 19:55       ` Richard Copley
  0 siblings, 0 replies; 15+ messages in thread
From: Richard Copley @ 2016-08-23 19:55 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: martin rudalics, Emacs Development

On 23 August 2016 at 19:31, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Richard Copley <rcopley@gmail.com>
>> Date: Tue, 23 Aug 2016 18:56:52 +0100
>> Cc: martin rudalics <rudalics@gmx.at>, Emacs Development <emacs-devel@gnu.org>
>>
>> C-x b * RET ;; create and switch to buffer "*"
>> M-x ediff-buffers RET RET RET ;; ediff buffers "*" and "*scratch*"
>> ;; Now attempt to close the main Emacs frame using the window manager
>>
>> This gives:
>>
>> Debugger entered--Lisp error: (error "Attempt to delete a surrogate
>> minibuffer frame")
>>   delete-frame(#<frame *scratch* 00000004009c5870> t)
>>   handle-delete-frame((delete-frame (#<frame *scratch* 00000004009c5870>)))
>>   funcall-interactively(handle-delete-frame (delete-frame (#<frame
>> *scratch* 00000004009c5870>)))
>>   call-interactively(handle-delete-frame nil [(delete-frame (#<frame
>> *scratch* 00000004009c5870>))])
>>   command-execute(handle-delete-frame nil [(delete-frame (#<frame
>> *scratch* 00000004009c5870>))] t)
>>   read-event(nil t 2)
>>   sit-for(2)
>>   execute-extended-command(nil "toggle-debug-on-error" "t-d-o-e")
>>   funcall-interactively(execute-extended-command nil
>> "toggle-debug-on-error" "t-d-o-e")
>>   call-interactively(execute-extended-command nil nil)
>>   command-execute(execute-extended-command)
>>
>> I've never been sure whether this deserves a bug report, or what
>> should be the expected behaviour.
>
> If we don't know what should be the correct behavior, how can we fix
> this?

Yes, we would need to decide what behaviour to implement.
Now that I come to think about it, my tentative suggestion is:
a close command to the last non-minibuffer-only frame
should have the same effect as C-x C-c.

>> FWIW when this happens my intention is usually to kill Emacs.
>
> But there are more than one frame in this case, so closing one of them
> can never kill Emacs anyway, even if the frame you want to delete will
> be deleted.

Yeah, but I wouldn't put it like that, just that it doesn't kill Emacs
the way things are now. Unless I'm misunderstanding you.

> As with any multi-window program, closing one window normally doesn't
> exit the program.

For programs with multiple top-level document windows, that's true.
On the other hand, programs with floating toolbar windows such as
Paint.NET don't make you close all the toolbars as well as the main
window. But that's not very helpful of me, because Emacs isn't the
same as either of those things.



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: delete-other-frames
  2016-08-23 14:09 ` delete-other-frames Eli Zaretskii
  2016-08-23 17:56   ` delete-other-frames Richard Copley
@ 2016-08-24  9:06   ` martin rudalics
  2016-08-25  9:16     ` delete-other-frames martin rudalics
  1 sibling, 1 reply; 15+ messages in thread
From: martin rudalics @ 2016-08-24  9:06 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

 > IMO, amend the code.
[...]
 > The latter, I think.

I have two versions to accomplish that: One based on calling
‘next-frame’ exhaustively ...

(defun delete-other-frames (&optional frame)
   "Delete all frames on FRAME's terminal, except FRAME.
If FRAME uses another frame's minibuffer, the minibuffer frame is
left untouched.  FRAME must be a live frame.  FRAME nil or
omitted means use the selected frame."
   (interactive)
   (unless frame
     (setq frame (selected-frame)))
   (let ((minibuffer-frame (window-frame (minibuffer-window frame)))
         (this (next-frame frame t))
         next)
     ;; In a first round consider minibuffer-less frames only.
     (while (not (eq this frame))
       (setq next (next-frame this t))
       (unless (eq (window-frame (minibuffer-window this)) this)
         (delete-frame this))
       (setq this next))
     ;; In a second round consider all remaining frames.
     (setq this (next-frame frame t))
     (while (not (eq this frame))
       (setq next (next-frame this t))
       (unless (eq this minibuffer-frame)
         (delete-frame this))
       (setq this next))))

... and a more conservative one using ‘frame-list’.

(defun delete-other-frames (&optional frame)
   "Delete all frames on FRAME's terminal, except FRAME.
If FRAME uses another frame's minibuffer, the minibuffer frame is
left untouched.  FRAME must be a live frame.  FRAME nil or
omitted means use the selected frame."
   (interactive)
   (unless frame
     (setq frame (selected-frame)))
   (let ((terminal (frame-terminal frame))
	(minibuffer-frame (window-frame (minibuffer-window frame)))
	(frames (frame-list)))
     ;; Clean up candidate frames.
     (dolist (this (prog1 frames (setq frames nil)))
       (when (and (eq (frame-terminal this) terminal)
		 (not (eq this frame))
		 (not (eq this minibuffer-frame)))
	(push this frames)))
     ;; In a first round consider minibuffer-less frames only.
     (dolist (this frames)
       (unless (eq (window-frame (minibuffer-window this)) this)
	(delete-frame this)))
     ;; In a second round consider all remaining frames.
     (dolist (this frames)
       (when (frame-live-p this)
	(delete-frame this)))))

If someone sees weaknesses with either of these approaches, please
tell me.

martin




^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: delete-other-frames
  2016-08-23 17:56   ` delete-other-frames Richard Copley
  2016-08-23 18:31     ` delete-other-frames Eli Zaretskii
@ 2016-08-24  9:07     ` martin rudalics
  1 sibling, 0 replies; 15+ messages in thread
From: martin rudalics @ 2016-08-24  9:07 UTC (permalink / raw)
  To: Richard Copley, Eli Zaretskii; +Cc: Emacs Development

 > Possibly related: from emacs -Q,
 >
 > C-x b * RET ;; create and switch to buffer "*"
 > M-x ediff-buffers RET RET RET ;; ediff buffers "*" and "*scratch*"
 > ;; Now attempt to close the main Emacs frame using the window manager
 >
 > This gives:
 >
 > Debugger entered--Lisp error: (error "Attempt to delete a surrogate
 > minibuffer frame")
[...]
 > I've never been sure whether this deserves a bug report, or what
 > should be the expected behaviour. FWIW when this happens my intention
 > is usually to kill Emacs. In any case the error message isn't very
 > user friendly.

The ediff Control Panel frame is an oddity.  OT1H, for navigation, it
detracts user input from the main frame and OTOH uses the main frame's
minibuffer window for echoing.  IMHO the Control Panel should appear on
the main frame by default.  But I'm afraid that many users already got
used to the current behavior.

In any case this and similar scenarios show that "surrogate minibuffer
frames" should be of the minibuffer-only type.

martin



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: delete-other-frames
  2016-08-24  9:06   ` delete-other-frames martin rudalics
@ 2016-08-25  9:16     ` martin rudalics
  2016-08-25 14:46       ` delete-other-frames Eli Zaretskii
  0 siblings, 1 reply; 15+ messages in thread
From: martin rudalics @ 2016-08-25  9:16 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

 > I have two versions to accomplish that: One based on calling
 > ‘next-frame’ exhaustively ...

I've used that, added an Elisp manual entry and tried to clarify
some related doc issues.

Thanks, martin




^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: delete-other-frames
  2016-08-25  9:16     ` delete-other-frames martin rudalics
@ 2016-08-25 14:46       ` Eli Zaretskii
  2016-08-27  1:32         ` delete-other-frames Richard Stallman
       [not found]         ` <<E1bdSUT-00059T-8W@fencepost.gnu.org>
  0 siblings, 2 replies; 15+ messages in thread
From: Eli Zaretskii @ 2016-08-25 14:46 UTC (permalink / raw)
  To: martin rudalics; +Cc: emacs-devel

> Date: Thu, 25 Aug 2016 11:16:34 +0200
> From: martin rudalics <rudalics@gmx.at>
> CC: emacs-devel@gnu.org
> 
>  > I have two versions to accomplish that: One based on calling
>  > ‘next-frame’ exhaustively ...
> 
> I've used that, added an Elisp manual entry and tried to clarify
> some related doc issues.

Thanks.

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 former reads as less awkward English and avoids using the same
word twice in a row.



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: delete-other-frames
  2016-08-25 14:46       ` delete-other-frames Eli Zaretskii
@ 2016-08-27  1:32         ` Richard Stallman
  2016-08-27  7:40           ` delete-other-frames Eli Zaretskii
       [not found]         ` <<E1bdSUT-00059T-8W@fencepost.gnu.org>
  1 sibling, 1 reply; 15+ messages in thread
From: Richard Stallman @ 2016-08-27  1:32 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > 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}.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.




^ permalink raw reply	[flat|nested] 15+ messages in thread

* RE: delete-other-frames
       [not found]         ` <<E1bdSUT-00059T-8W@fencepost.gnu.org>
@ 2016-08-27  6:31           ` Drew Adams
  2016-08-27  7:45             ` delete-other-frames Eli Zaretskii
  2016-08-27 21:45             ` delete-other-frames Richard Stallman
       [not found]           ` <<49a2a9c7-8573-4f07-897f-3eb444679d8a@default>
  1 sibling, 2 replies; 15+ messages in thread
From: Drew Adams @ 2016-08-27  6:31 UTC (permalink / raw)
  To: rms, Eli Zaretskii; +Cc: emacs-devel

>   > 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.



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: delete-other-frames
  2016-08-27  1:32         ` delete-other-frames Richard Stallman
@ 2016-08-27  7:40           ` Eli Zaretskii
  0 siblings, 0 replies; 15+ messages in thread
From: Eli Zaretskii @ 2016-08-27  7:40 UTC (permalink / raw)
  To: rms; +Cc: emacs-devel

> From: Richard Stallman <rms@gnu.org>
> cc: emacs-devel@gnu.org
> Date: Fri, 26 Aug 2016 21:32:57 -0400
> 
>   >   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.

(In Info files, the parameter is just up-cased, it isn't in italics.)

If the name of the argument is different, I don't object to the latter
form, provided that it has the comma.  But when it is the same word,
the result reads as incorrect English, especially when there's no
comma between them, as things usually stand.

> 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}.

But

  Send it to my assistant ASSISTANT.

and

  delete the frame FRAME

don't sound right to me.  The speller even highlights them as
mis-spellings, because it flags repeated adjacent words.  (It doesn't
when there's a comma between them.)

An additional advantage of my proposal is that it goes well with the
style we use in the doc strings, because the form I proposed is
shorter.

In any case, we have quite a few of instances in our documentation
that use the form I proposed, so if we really think it's incorrect (I
don't agree), we have to change them all first.



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: delete-other-frames
  2016-08-27  6:31           ` delete-other-frames Drew Adams
@ 2016-08-27  7:45             ` Eli Zaretskii
  2016-08-27 21:45             ` delete-other-frames Richard Stallman
  1 sibling, 0 replies; 15+ messages in thread
From: Eli Zaretskii @ 2016-08-27  7:45 UTC (permalink / raw)
  To: Drew Adams; +Cc: rms, emacs-devel

> Date: Fri, 26 Aug 2016 23:31:19 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: emacs-devel@gnu.org
> 
> 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.

Yes, that's what was on my mind.

> 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.

Exactly.

Thanks.



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: delete-other-frames
  2016-08-27  6:31           ` delete-other-frames Drew Adams
  2016-08-27  7:45             ` delete-other-frames Eli Zaretskii
@ 2016-08-27 21:45             ` Richard Stallman
  1 sibling, 0 replies; 15+ messages in thread
From: Richard Stallman @ 2016-08-27 21:45 UTC (permalink / raw)
  To: Drew Adams; +Cc: eliz, emacs-devel

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > 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.

You're right.  I must have been in a daze.

  > 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}".

Yes.  Exactly.  A comparable example in algebra is "Square the number x."

  > 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, 

Grammatically, it does not matter whether the argument's name is f or
frame.  In the first case, the sentence should be, "delete the frame
@var{f}", shortened to "delete frame @var{f}".  In the second case,
the sentence should be, "delete the frame @var{frame}", shortened to
"delete frame @var{frame}".

Whether the argument name is the same as the description, or not,
has no effect.

				       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.

It is grammatical to omit the description of the argument, and use
just its name.  There must be no article, in this usage.

  > Example:

  > Just "copy FILE to DIRECTORY", 

Here FILE and DIRECTORY are both names of argument values,
so they must have no articles.

   "copy F to D"

is equally grammatical, but it is clear only if the reader already
knows that F is a file and D is a directory.  Otherwise, we need to
say so.

  "copy the FILE to the DIRECTORY"

is grammatically incorrect because you can't put an article on a name.


-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.




^ permalink raw reply	[flat|nested] 15+ messages in thread

* RE: delete-other-frames
       [not found]             ` <<E1bdlPn-0005Ch-I4@fencepost.gnu.org>
@ 2016-08-28  0:41               ` Drew Adams
  0 siblings, 0 replies; 15+ messages in thread
From: Drew Adams @ 2016-08-28  0:41 UTC (permalink / raw)
  To: rms, Drew Adams; +Cc: eliz, emacs-devel

>   > 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.
> 
> You're right.  I must have been in a daze.

You're human. ;-)

>   > 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}".
> 
> Yes.  Exactly.  A comparable example in algebra is "Square the number x."
> 
>   > 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,
> 
> Grammatically, it does not matter whether the argument's name is f or
> frame.  In the first case, the sentence should be, "delete the frame
> @var{f}", shortened to "delete frame @var{f}".  In the second case,
> the sentence should be, "delete the frame @var{frame}", shortened to
> "delete frame @var{frame}".
> 
> Whether the argument name is the same as the description, or not,
> has no effect.
> 
> 				       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.
> 
> It is grammatical to omit the description of the argument, and use
> just its name.  There must be no article, in this usage.

Right.

>   > Example:
>   > Just "copy FILE to DIRECTORY",
> 
> Here FILE and DIRECTORY are both names of argument values,
> so they must have no articles.
> 
>    "copy F to D"
> 
> is equally grammatical, but it is clear only if the reader already
> knows that F is a file and D is a directory.  Otherwise, we need to
> say so.
> 
>   "copy the FILE to the DIRECTORY"
> 
> is grammatically incorrect because you can't put an article on a name.

Yes.



^ permalink raw reply	[flat|nested] 15+ messages in thread

end of thread, other threads:[~2016-08-28  0:41 UTC | newest]

Thread overview: 15+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-08-23  8:19 delete-other-frames martin rudalics
2016-08-23 14:09 ` delete-other-frames Eli Zaretskii
2016-08-23 17:56   ` delete-other-frames Richard Copley
2016-08-23 18:31     ` delete-other-frames Eli Zaretskii
2016-08-23 19:55       ` delete-other-frames Richard Copley
2016-08-24  9:07     ` delete-other-frames martin rudalics
2016-08-24  9:06   ` delete-other-frames martin rudalics
2016-08-25  9:16     ` delete-other-frames martin rudalics
2016-08-25 14:46       ` delete-other-frames Eli Zaretskii
2016-08-27  1:32         ` delete-other-frames Richard Stallman
2016-08-27  7:40           ` delete-other-frames Eli Zaretskii
     [not found]         ` <<E1bdSUT-00059T-8W@fencepost.gnu.org>
2016-08-27  6:31           ` delete-other-frames Drew Adams
2016-08-27  7:45             ` delete-other-frames Eli Zaretskii
2016-08-27 21:45             ` delete-other-frames Richard Stallman
     [not found]           ` <<49a2a9c7-8573-4f07-897f-3eb444679d8a@default>
     [not found]             ` <<E1bdlPn-0005Ch-I4@fencepost.gnu.org>
2016-08-28  0:41               ` delete-other-frames Drew Adams
     [not found] <<57BC072F.9070704@gmx.at>
     [not found] <<<57BC072F.9070704@gmx.at>

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).