(Formatting Strings): Warn against arbitrary strings as first arg to `format'.

2 files changed, 16 insertions, 1 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index f3f3037e4d1..eb1fd9797c2 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2006-08-04  Eli Zaretskii  <eliz@gnu.org>
+
+        * strings.texi (Formatting Strings): Warn against arbitrary
+        strings as first arg to `format'.
+
 2006-07-31  Thien-Thi Nguyen  <ttn@gnu.org>
 
         * text.texi (Clickable Text): Mention `help-echo' text property.
diff --git a/lispref/strings.texi b/lispref/strings.texi
index 46c01982f32..12abc38ee02 100644
--- a/lispref/strings.texi
+++ b/lispref/strings.texi
@@ -701,7 +701,6 @@ arguments @var{objects} are the computed values to be formatted.
 
 The characters in @var{string}, other than the format specifications,
 are copied directly into the output; if they have text properties,
-these are copied into the output also.
 @end defun
 
 @cindex @samp{%} in format
@@ -719,6 +718,17 @@ For example:
 @end group
 @end example
 
+  Since @code{format} interprets @samp{%} characters as format
+specifications, you should @emph{never} pass an arbitrary string as
+the first argument.  This is particularly true when the string is
+generated by some Lisp code.  Unless the string is @emph{known} to
+never include any @samp{%} characters, pass @code{"%s"}, described
+below, as the first argument, and the string as the second, like this:
+
+@example
+  (format "%s" @var{arbitrary-string})
+@end example
+
   If @var{string} contains more than one format specification, the
 format specifications correspond to successive values from
 @var{objects}.  Thus, the first format specification in @var{string}