; Improve documentation of 'append'

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

1 files changed, 24 insertions, 0 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