Subject: bug#28814: [BUMP, PATCH] (26.0.90; When *xref* window is needed, original window-switching intent is lost )

From: [email-masked] (João Távora)
Date: Fri, 27 Oct 2017 00:59:28 +0100

Eli Zaretskii <[email-masked]> writes:

> A few comments to the documentation:
>
>  . Please proofread the text for UK English spellings (e.g., "honour")
>    and only one space between sentences.

Done.

>  . I don't understand the reason for such extensive changes in the
>    manual.  Most of them look purely stylistic, and I see no problems
>    with the original text to justify that.

Here are the (minor) problems I detected:

- In node "Looking up identifiers" there are is a repeated explanation
of what motivates a *xref* buffer (lines 1831 and 1863). I think its
clearer if this only happens once, so I merged the two.

- When the text in the same node talks about RET, I took that
opportunity to mention existing C-o binding and the proposed TAB
binding. This adds information.

- Finally, I changed "To go back to places @emph{from where} you found
the definition" to "Once you are at the definition, you may want to go
back to places @{from where}". This is indeed purely stylistic, but I
thought it was a less abrupt transition from the preceding paragraph
that talks about going to definitions. The change looks larger than it
really is because of the paragraph filling, but I did only change the
first sentence.

- A real problem is that the description for RET in the node "Xref
Commands" incorrectly states that RET buries the *xref* buffer, which we
know it doesn't.

> What did I miss?

Nothing, I just thought this improved the manual slightly. Tell me which
parts, maybe all, you think I should scrap. (though I do believe updates
to the "Xref Commands" node are in order)

> I don't see a need for a NEWS entry.  If this is a
> bugfix, then it doesn't belong there, as we don't describe bugfixes in
> NEWS (there are too many to describe).

I didn't know that, sorry. Apart from the bugfix there is also the new
quit-and-jump behaviour, but maybe also not worth it. Your call.