* keymap.c (describe_map_tree): Revert 2011-07-07 change.

* doc.c (Fsubstitute_command_keys): Doc fix.

Fixes: debbugs:1169

4 files changed, 25 insertions, 12 deletions

diff --git a/src/ChangeLog b/src/ChangeLog
index 16bd1659b34..d8d14005d1e 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,9 @@
+2012-05-30  Chong Yidong  <cyd@gnu.org>
+
+	* keymap.c (describe_map_tree): Revert 2011-07-07 change (Bug#1169).
+
+	* doc.c (Fsubstitute_command_keys): Doc fix.
+
 2012-05-29  Eli Zaretskii  <eliz@gnu.org>
 
 	* search.c (search_buffer): Remove calls to
diff --git a/src/doc.c b/src/doc.c
index 02db4dde072..a1e9b40c92a 100644
--- a/src/doc.c
+++ b/src/doc.c
@@ -698,18 +698,23 @@ the same file name is found in the `doc-directory'.  */)
 DEFUN ("substitute-command-keys", Fsubstitute_command_keys,
        Ssubstitute_command_keys, 1, 1, 0,
        doc: /* Substitute key descriptions for command names in STRING.
-Substrings of the form \\=\\[COMMAND] replaced by either: a keystroke
-sequence that will invoke COMMAND, or "M-x COMMAND" if COMMAND is not
-on any keys.
-Substrings of the form \\=\\{MAPVAR} are replaced by summaries
-\(made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
-Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
+Each substring of the form \\=\\[COMMAND] is replaced by either a
+keystroke sequence that invokes COMMAND, or "M-x COMMAND" if COMMAND
+is not on any keys.
+
+Each substring of the form \\=\\{MAPVAR} is replaced by a summary of
+the value of MAPVAR as a keymap.  This summary is similar to the one
+produced by `describe-bindings'.  The summary ends in two newlines
+\(used by the helper function `help-make-xrefs' to find the end of the
+summary).
+
+Each substring of the form \\=\\<MAPVAR> specifies the use of MAPVAR
 as the keymap for future \\=\\[COMMAND] substrings.
 \\=\\= quotes the following character and is discarded;
 thus, \\=\\=\\=\\= puts \\=\\= into the output, and \\=\\=\\=\\[ puts \\=\\[ into the output.
 
-Returns original STRING if no substitutions were made.  Otherwise,
-a new string, without any text properties, is returned.  */)
+Return the original STRING if no substitutions are made.
+Otherwise, return a new string, without any text properties.  */)
   (Lisp_Object string)
 {
   char *buf;
diff --git a/src/keymap.c b/src/keymap.c
index 9f82175edc0..73b62f9d4bb 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -2978,9 +2978,9 @@ You type        Translation\n\
    If MENTION_SHADOW is nonzero, then when something is shadowed by SHADOW,
    don't omit it; instead, mention it but say it is shadowed.
 
-   Return whether something was inserted or not.  */
+   Any inserted text ends in two newlines (used by `help-make-xrefs').  */
 
-int
+void
 describe_map_tree (Lisp_Object startmap, int partial, Lisp_Object shadow,
 		   Lisp_Object prefix, const char *title, int nomenu, int transl,
 		   int always_title, int mention_shadow)
@@ -3090,8 +3090,10 @@ key             binding\n\
     skip: ;
     }
 
+  if (something)
+    insert_string ("\n");
+
   UNGCPRO;
-  return something;
 }
 
 static int previous_description_column;
diff --git a/src/keymap.h b/src/keymap.h
index 234ffce471d..d9334cda0f4 100644
--- a/src/keymap.h
+++ b/src/keymap.h
@@ -47,7 +47,7 @@ EXFUN (Fcurrent_active_maps, 2);
 extern Lisp_Object access_keymap (Lisp_Object, Lisp_Object, int, int, int);
 extern Lisp_Object get_keymap (Lisp_Object, int, int);
 EXFUN (Fset_keymap_parent, 2);
-extern int describe_map_tree (Lisp_Object, int, Lisp_Object, Lisp_Object,
+extern void describe_map_tree (Lisp_Object, int, Lisp_Object, Lisp_Object,
 			      const char *, int, int, int, int);
 extern ptrdiff_t current_minor_maps (Lisp_Object **, Lisp_Object **);
 extern void initial_define_key (Lisp_Object, int, const char *);