bug#1169: 23.0.60; (substitute-command-keys "\\{...}") adds extra newline

[Drew Adams]

> >> I've now made the change,
> >
> > This change breaks the highlighting code in `help-make-xrefs' which
> > assumes that a list of key bindings produced by 
> > substitute-command-keys (in `documentation') ends with an extra blank line
> 
> Thanks.  I've reverted the change in the emacs-24 branch, and added a
> note to the docstring of substitute-command-keys that the two newlines
> are needed by `help-make-xrefs'.

Huh?  Two newlines is the wrong thing.  It is the point of this bug report.

If some other fix is needed than the one that you made, fine.  Just DTRT.
Sounds like `help-make-xrefs' needs to be fixed - dunno.

In any case, the extra newline still needs to be removed.  It is simply wrong -
doesn't belong in `substitute-command-keys' - is not part of its mission.

And you added your note to the _doc string_?  Of `substitute-command-keys'?  If
you need to make a note that this bug still needs to be fixed then that should
be done elsewhere than a doc string.

There is absolutely nothing in the purpose of `substitute-command-keys' that
constrains it or invites it to add an extra newline.  Quite the contrary.

`substitute-command-keys' is a very general utility function.  It is not some
helper routine for `help-make-xrefs'.  Bending it to fix inadequate code in
`help-make-xrefs' is _way_ wrong.  And putting that kind of note into its doc
string is doubly wrong.

To repeat, from the bug report:

> If text is added after the returned string, then it should be up
> to *that* text to start with a \n if it wants a blank separator line.
> If, for example, it starts instead with ^L, then the current code
> includes an extra blank line before the form feed.
> 
> It should be up to the *calling* function to decide whether it wants
> a blank line at the end -  *only* the calling function knows the
> context and whether such a line is appropriate.