From 2bcffc1d7cc2941145c34bd3e5f833a855300d53 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Mon, 23 Sep 2024 14:41:34 +0300
Subject: [PATCH] ; Improve documentation of 'append'

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

(cherry picked from commit c8ed48b9901790fdabcf91ef15a6ba47c96b48c8)
---
 doc/lispref/lists.texi | 24 ++++++++++++++++++++++++
 src/fns.c              |  7 ++++++-
 2 files changed, 30 insertions(+), 1 deletion(-)

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
@@ -666,6 +666,17 @@ This once was the usual way to copy a list, before the function
 (append [a b] "cd" nil)
      @result{} (a b 99 100)
 @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
@@ -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 e91797d7764..edfa66edf4c 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)
-- 
2.39.5