; Improve documentation of 'append'

* doc/lispref/lists.texi (Building Lists):
* src/fns.c (Fappend): Improve documentation of 'append'.  (Bug#73427)

2 files changed, 30 insertions, 1 deletions

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 6f4d838042a..816af4a4ff7 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -668,6 +668,17 @@ This once was the usual way to copy a list, before the function
 @end group
 @end example
 
+@cindex list of characters of a string
+@cindex convert string to list of its characters
+  Here's how to convert a string into a list of its characters:
+
+@example
+@group
+(append "abcd" nil)
+     @result{} (97 98 99 100)
+@end group
+@end example
+
   With the help of @code{apply} (@pxref{Calling Functions}), we can append
 all the lists in a list of lists:
 
@@ -690,10 +701,12 @@ all the lists in a list of lists:
   Here are some examples where the final argument is not a list:
 
 @example
+@group
 (append '(x y) 'z)
      @result{} (x y . z)
 (append '(x y) [z])
      @result{} (x y . [z])
+@end group
 @end example
 
 @noindent
@@ -702,6 +715,17 @@ not a list, the sequence's elements do not become elements of the
 resulting list.  Instead, the sequence becomes the final @sc{cdr}, like
 any other non-list final argument.
 
+  As an exception, if all the arguments but the last are @code{nil} and
+the last argument is not a list, the return value is that last argument
+unchanged:
+
+@example
+@group
+(append nil nil "abcd")
+     @result{} "abcd"
+@end group
+@end example
+
 @defun copy-tree tree &optional vectors-and-records
 This function returns a copy of the tree @var{tree}.  If @var{tree} is a
 cons cell, this makes a new cons cell with the same @sc{car} and
diff --git a/src/fns.c b/src/fns.c
index 6133c20573a..33079cf926a 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -719,7 +719,12 @@ The result is a list whose elements are the elements of all the arguments.
 Each argument may be a list, vector or string.
 
 All arguments except the last argument are copied.  The last argument
-is just used as the tail of the new list.
+is just used as the tail of the new list.  If the last argument is not
+a list, this results in a dotted list.
+
+As an exception, if all the arguments except the last are nil, and the
+last argument is not a list, the return value is that last argument
+unaltered.
 
 usage: (append &rest SEQUENCES)  */)
   (ptrdiff_t nargs, Lisp_Object *args)