Re: Manual suggestions for quit-restore documentation

[Eric Abrahamsen <eric@ericabrahamsen.net>]

martin rudalics <rudalics@gmx.at> writes:

>> I just don't see how/where the `bury-or-kill' parameter affects the
>> handling of the frame, I think it only affects the buffer. But I may
>> have "fixed" it until it doesn't make sense :)
>
> Isn't that via
>
> (defun quit-restore-window (&optional window bury-or-kill)
>            ...
> 	   ;; Delete WINDOW if possible.
> 	   (window--delete window nil (eq bury-or-kill 'kill)))
>
> and
>
> (defun window--delete (&optional window dedicated-only kill)
>           ...
> 	  (cond
> 	   (kill
> 	    (delete-frame frame))
>
> or what am I missing?

Ah, of course -- I even looked in there, but it didn't click.

>> I added a line about 'same as the first element of `quit-restore', but
>> it might be wrong.
>>
>> I didn't add anything new about the 'other symbol. I see it getting set
>> in `display-buffer-record-window', but I don't see that it ever gets
>> used.
>
> I suppose it's used here
>
> (defun quit-restore-window (&optional window bury-or-kill)
>      ...
>      ((and (listp (setq quad (nth 1 quit-restore)))
> 	   (buffer-live-p (car quad))
>
> and it's essential when the window was used for showing an "other"
> buffer.

Now I'm missing something -- I'm talking about (car quit-restore) ->
'other. Unless I'm really turned around, I don't see that getting checked.

>> +however, if it is the only one in its frame.  If @var{window} is the
>> +only window on its frame and there are other frames on the frame's
>> +terminal, the value of the optional argument @var{bury-or-kill}
>> +determines how to proceed with the window.  If @var{bury-or-kill}
>> +equals @code{kill}, the frame is deleted unconditionally.
>
> Correct IMHO.  So what is still unclear about `bury-or-kill'?

I think it's fine, I was just confused. I might tweak the wording
slightly.

>> +possible to set it manually, using the following code when displaying
>> +``buffer'' in ``window'':
>
> Both `buffer' and `window' are arguments so I'd use var{} here.
>
>> +The final use of @code{set-window-prev-buffers} ensures that a future
>> +call to @code{quit-window} will delete the window altogether.
>> +
>
> I'd prefer something like "Setting @code{set-window-prev-buffers} _to
> nil_ ensures that a future call to @code{quit-window} _can_ delete the
> window altogether."

That's still a bit off, as it sounds like we're setting the function
name to nil. How about:

Setting the window history to nil ensures that a future call to
@code{quit-window} can delete the window altogether.

Is that clear enough, do you think?

>> +window showed another buffer before. The 'frame and 'window elements
>
> I think we use `frame' and `window' instead of 'frame and 'window.

Good, thanks for this and the @var{} tip, I don't have much experience
writing texinfo.

>> +re-uses the window to display the buffer.
>
> Would "reuses" be bad English?

No, they're both acceptable spellings, "reuses" is fine.

Let me know what you think about 'other, and I'll do a proper commit.

Eric