bug#52328: 27.2; [DOC] Paragraph about quit-restore-window

[Eli Zaretskii <eliz@gnu.org>]

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 06 Dec 2021 23:15:19 -0500
> Cc: 52328@debbugs.gnu.org
> 
>   > If the third element of the ‘quit-restore’ parameter is a list of
>   > buffer, window start (*note Window Start and End), and point
>   > (*note
>   > Window Point), 
> 
> It would be clearer to present the list using Lisp syntax:
> (@var{buffer} @var{window-start} @var{new-point})
> Then it can talk about these values with their names, which
> is clearer.

That is true.  But that's far from being the single or the main
problem of that description.

>                    and that buffer is still live, the buffer will be
>   > displayed, and start and point set accordingly.
> 
> It's bad to use passive voice; that is generally less clear because
> of the missing subject, as well as more cluttered.
> 
> "Set accordingly" is hard work to interpret because it is not concrete.

I invite you to read the entire description of this function.  It is
very complex and is IMO very hard to grasp.  I think it needs to be
completely rewritten, with the method of presenting the various
options rethought to be more clear.  One possibility is to describe
the options from the opposite POV: instead of saying "if the parameter
is this-and-that, the function will do some stuff", first describe a
job that the caller would want to do, with the rationale for that, and
then how to tell the function to do that job.

Other suggestions for clarifying that part will be most welcome.