substitute-command-keys now marks escaped charsscratch/quote-escaping

* doc/lispref/help.texi (Keys in Documentation), etc/NEWS:
Document this.
* src/doc.c (Fsubstitute_command_keys):
Give escaped characters the 'escaped' text property.

3 files changed, 75 insertions, 79 deletions

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 868d2843569..be4a6f7bc19 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -333,6 +333,11 @@ replaces them by what they stand for, returning the result as a string.
 This permits display of documentation that refers accurately to the
 user's own customized key bindings.
 
+In the returned string, replacement characters that should not be
+further transformed have the text property @code{escaped}.  For
+example, when @samp{\=`} is replaced by @samp{`} in the output, the
+replacement character has the text property @code{escaped}.
+
 @cindex advertised binding
 If a command has multiple bindings, this function normally uses the
 first one it finds.  You can specify one particular key binding by
diff --git a/etc/NEWS b/etc/NEWS
index c4c9d774b5f..a298c76e333 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -781,6 +781,12 @@ when signaling a file error.  For example, it now reports "Permission
 denied" instead of "permission denied".  The old behavior was problematic
 in languages like German where downcasing rules depend on grammar.
 
+** substitute-command-keys now indicates which characters are data.
+The string returned by substitute-command-keys now has the text
+property 'escaped' for characters that are part of data and should
+not be further transformed.  For example, the character ` might be
+escaped to indicate that it is a grave accent and not an open quote.
+
 +++
 ** The character classes [:alpha:] and [:alnum:] in regular expressions
 now match multibyte characters using Unicode character properties.
diff --git a/src/doc.c b/src/doc.c
index dc159e1cac9..ed3b0b01d62 100644
--- a/src/doc.c
+++ b/src/doc.c
@@ -696,6 +696,10 @@ as the keymap for future \\=\\[COMMAND] substrings.
 \\=\\= quotes the following character and is discarded;
 thus, \\=\\=\\=\\= puts \\=\\= into the output, and \\=\\=\\=\\[ puts \\=\\[ into the output.
 
+Replacement characters that should not be further transformed have the
+text property `escaped'.  For example, when \\=\\=\\=` is replaced by \\=` in
+the output, the replacement character has the text property `escaped'.
+
 Return the original STRING if no substitutions are made.
 Otherwise, return a new string.  */)
   (Lisp_Object string)
@@ -704,7 +708,6 @@ Otherwise, return a new string.  */)
     return Qnil;
   CHECK_STRING (string);
 
-  ptrdiff_t bsize = SBYTES (string);
   bool changed = false;
   Lisp_Object tem = Qnil;
   Lisp_Object name = Qnil;
@@ -721,40 +724,52 @@ Otherwise, return a new string.  */)
   bool multibyte = STRING_MULTIBYTE (string);
   ptrdiff_t nchars = 0;
 
-  char *buf = xmalloc (bsize);
-  char *bufp = buf;
+  ptrdiff_t count = SPECPDL_INDEX ();
+
+  /* Switch to a temp buffer.  */
+  struct buffer *oldbuf = current_buffer;
+  set_buffer_internal (XBUFFER (Vprin1_to_string_buffer));
+  /* This is for an unusual case where some after-change
+     function uses 'format' or 'prin1' or something else that
+     will thrash Vprin1_to_string_buffer we are using.  */
+  specbind (Qinhibit_modification_hooks, Qt);
 
   unsigned char *strp = SDATA (string);
   while (strp < SDATA (string) + SBYTES (string))
     {
-      bool m_x_prefix = false;
-      ptrdiff_t idx;
-      unsigned char *start;
-      ptrdiff_t length, length_byte;
+      ptrdiff_t opoint = PT;
 
       if (strp[0] == '\\' && strp[1] == '=')
         {
           /* \= quotes the next character;
              thus, to put in \[ without its special meaning, use \=\[.  */
           strp += 2;
+          int len = 1;
+          if (multibyte)
+            STRING_CHAR_AND_LENGTH (strp, len);
+          insert_1_both ((char *) strp, 1, len, false, false, false);
+          strp += len;
+          nchars++;
+          Fput_text_property (make_number (opoint), make_number (opoint + 1),
+                              Qescaped, Qt, Qnil);
           changed = true;
         }
       else if (strp[0] == '\\' && strp[1] == '[')
         {
           strp += 2;            /* skip \[ */
-          start = strp;
+          unsigned char *start = strp;
           ptrdiff_t start_idx = start - SDATA (string);
 
           while ((strp - SDATA (string)
                   < SBYTES (string))
                  && *strp != ']')
             strp++;
-          length_byte = strp - start;
+          ptrdiff_t length_byte = strp - start;
 
           strp++;               /* skip ] */
 
           /* Save STRP in IDX.  */
-          idx = strp - SDATA (string);
+          ptrdiff_t idx = strp - SDATA (string);
           name = Fintern (make_string ((char *) start, length_byte), Qnil);
 
           tem = Fwhere_is_internal (name, keymap, Qt, Qnil, Qnil);
@@ -763,27 +778,34 @@ Otherwise, return a new string.  */)
             {
               name = AREF (tem, 1);
               tem = Fwhere_is_internal (name, keymap, Qt, Qnil, Qnil);
+              /* Fwhere_is_internal can GC, so we have to take
+                 relocation of string contents into account.  */
             }
 
-          /* Note the Fwhere_is_internal can GC, so we have to take
-             relocation of string contents into account.  */
-          strp = SDATA (string) + idx;
-          start = SDATA (string) + start_idx;
-
+          ptrdiff_t length;
           if (NILP (tem))       /* but not on any keys */
             {
+              insert_1_both ("M-x ", 4, 4, false, false, false);
+              strp = SDATA (string) + start_idx;
               if (multibyte)
-                length = multibyte_chars_in_text (start, length_byte);
+                length = multibyte_chars_in_text (strp, length_byte);
               else
                 length = length_byte;
-              m_x_prefix = true;
-              goto subst;
+              insert_1_both ((char *) strp, length, length_byte,
+                             false, false, false);
+              Fput_text_property (make_number (opoint), make_number (PT),
+                                  Qescaped, Qt, Qnil);
             }
           else
-            {                   /* function is on a key */
+            {
+              /* FIXME: Fkey_description doesn't properly mark quote
+                 characters that should be escaped.  */
               tem = Fkey_description (tem, Qnil);
-              goto subst_string;
+              insert_from_string (tem, 0, 0, SCHARS (tem), SBYTES (tem), true);
             }
+
+          strp = SDATA (string) + idx;
+          changed = true;
         }
       /* \{foo} is replaced with a summary of the keymap (symbol-value foo).
          \<foo> just sets the keymap used for \[cmd].  */
@@ -791,21 +813,20 @@ Otherwise, return a new string.  */)
         {
           /* This is for computing the SHADOWS arg for describe_map_tree.  */
           Lisp_Object active_maps = Fcurrent_active_maps (Qnil, Qnil);
-          ptrdiff_t count = SPECPDL_INDEX ();
 
           strp += 2;            /* skip \{ or \< */
-          start = strp;
+          unsigned char *start = strp;
           ptrdiff_t start_idx = start - SDATA (string);
 
           while ((strp - SDATA (string) < SBYTES (string))
                  && *strp != '}' && *strp != '>')
             strp++;
 
-          length_byte = strp - start;
+          ptrdiff_t length_byte = strp - start;
           strp++;                       /* skip } or > */
 
           /* Save STRP in IDX.  */
-          idx = strp - SDATA (string);
+          ptrdiff_t idx = strp - SDATA (string);
 
           /* Get the value of the keymap in TEM, or nil if undefined.
              Do this while still in the user's current buffer
@@ -824,21 +845,16 @@ Otherwise, return a new string.  */)
                 }
             }
 
-          /* Now switch to a temp buffer.  */
-          struct buffer *oldbuf = current_buffer;
-          set_buffer_internal (XBUFFER (Vprin1_to_string_buffer));
-          /* This is for an unusual case where some after-change
-             function uses 'format' or 'prin1' or something else that
-             will thrash Vprin1_to_string_buffer we are using.  */
-          specbind (Qinhibit_modification_hooks, Qt);
-
           if (NILP (tem))
             {
               name = Fsymbol_name (name);
               insert_string ("\nUses keymap `");
+              ptrdiff_t opoint = PT;
               insert_from_string (name, 0, 0,
                                   SCHARS (name),
                                   SBYTES (name), 1);
+              Fput_text_property (make_number (opoint), make_number (PT),
+                                  Qescaped, Qt, Qnil);
               insert_string ("', which is not currently defined.\n");
               if (start[-1] == '<') keymap = Qnil;
             }
@@ -853,66 +869,35 @@ Otherwise, return a new string.  */)
               describe_map_tree (tem, 1, Fnreverse (earlier_maps),
                                  Qnil, 0, 1, 0, 0, 1);
             }
-          tem = Fbuffer_string ();
-          Ferase_buffer ();
-          set_buffer_internal (oldbuf);
-          unbind_to (count, Qnil);
-
-        subst_string:
-          start = SDATA (tem);
-          length = SCHARS (tem);
-          length_byte = SBYTES (tem);
-        subst:;
-          ptrdiff_t stringtail_len = SBYTES (string) - idx;
-          ptrdiff_t offset = bufp - buf;
-          ptrdiff_t old_bufroom = bsize - offset;
-          ptrdiff_t new_bufroom = old_bufroom - 4 * m_x_prefix - length_byte;
-          if (new_bufroom < stringtail_len)
-            {
-              if (INT_SUBTRACT_OVERFLOW (stringtail_len, new_bufroom))
-                string_overflow ();
-              ptrdiff_t growth = max (bsize, stringtail_len - new_bufroom);
-              if (STRING_BYTES_BOUND - bsize < growth)
-                string_overflow ();
-              buf = xrealloc (buf, bsize += growth);
-              bufp = buf + offset;
-            }
-          if (m_x_prefix)
-            {
-              memcpy (bufp, "M-x ", 4);
-              bufp += 4;
-              nchars += 4;
-            }
-          memcpy (bufp, start, length_byte);
-          bufp += length_byte;
-          nchars += length;
-          /* Check STRING again in case gc relocated it.  */
-          strp = SDATA (string) + idx;
           changed = true;
-          continue;
         }
-
-      /* Just copy one char.  */
-      int len = 1;
-      if (multibyte)
-        STRING_CHAR_AND_LENGTH (strp, len);
-      memcpy (bufp, strp, len);
-      strp += len;
-      bufp += len;
-      nchars++;
+      else
+        {
+          /* Just copy one char.  */
+          int len = 1;
+          if (multibyte)
+            STRING_CHAR_AND_LENGTH (strp, len);
+          insert_1_both ((char *) strp, 1, len, false, false, false);
+          strp += len;
+          nchars++;
+        }
     }
 
   if (changed)                  /* don't bother if nothing substituted */
-    tem = make_string_from_bytes (buf, nchars, bufp - buf);
+    tem = Fbuffer_string ();
   else
     tem = string;
-  xfree (buf);
+
+  Ferase_buffer ();
+  set_buffer_internal (oldbuf);
+  unbind_to (count, Qnil);
   RETURN_UNGCPRO (tem);
 }
 
 void
 syms_of_doc (void)
 {
+  DEFSYM (Qescaped, "escaped");
   DEFSYM (Qfunction_documentation, "function-documentation");
 
   DEFVAR_LISP ("internal-doc-file-name", Vdoc_file_name,