From e575817e8feffd3db3b4fe953e0cc8640481acd1 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 2 May 2026 12:35:48 +0300
Subject: [PATCH] ; Improve documentation of Emacs server-client protocol

* lib-src/emacsclient.c (main):
* lisp/server.el (server-process-filter): Document the protocol
requirements regarding the terminating newline.  (Bug#80807)
---
 lib-src/emacsclient.c | 14 +++++++++++---
 lisp/server.el        |  4 +++-
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/lib-src/emacsclient.c b/lib-src/emacsclient.c
index 134c2217650..0769c94a89d 100644
--- a/lib-src/emacsclient.c
+++ b/lib-src/emacsclient.c
@@ -2257,6 +2257,11 @@ main (int argc, char **argv)
       char *p = recv_buf;
       for (char *end_p = p; end_p < recv_buf + nrecv; p = end_p)
 	{
+	  /* An unquoted newline ends a server command.  Keep reading,
+             possibly growing the buffer, until a buffer with a newline
+             is received.  This handles commands with arbitrary-long
+             arguments (actually needed in 'print' and 'error' commands,
+             which are followed by strings).  */
 	  end_p = memchr (p, '\n', recv_buf + nrecv - p);
 	  if (!end_p)
 	    break;
@@ -2288,7 +2293,8 @@ main (int argc, char **argv)
             }
           else if (strprefix ("-print ", p))
             {
-              /* -print STRING: Print STRING on the terminal. */
+              /* -print STRING: Print STRING, preceeded by a newline, on
+                  the terminal. */
 	      if (!suppress_output)
 		{
 		  char *str = unquote_argument (p + strlen ("-print "));
@@ -2299,8 +2305,10 @@ main (int argc, char **argv)
 	    }
           else if (strprefix ("-print-nonl ", p))
             {
-              /* -print-nonl STRING: Print STRING on the terminal.
-                 Used to continue a preceding -print command.  */
+              /* -print-nonl STRING: Print STRING on the terminal
+                 without a preceding newlin.  Used to continue a
+                 preceding -print command.  Nowadays used only for
+                 servers in Emacs versions before 31.  */
 	      if (!suppress_output)
 		{
 		  char *str = unquote_argument (p + strlen ("-print-nonl "));
diff --git a/lisp/server.el b/lisp/server.el
index c2aa854a4bb..b912b185275 100644
--- a/lisp/server.el
+++ b/lisp/server.el
@@ -1143,7 +1143,9 @@ The following commands are accepted by the client:
 `-print-nonl STRING'
   Print STRING on stdout.  Used to continue a
   preceding -print command that would be too big to send
-  in a single message.
+  in a single message.  Unused in the server since Emacs 31;
+  mentioned here only for completeness, because the client
+  needs to support it when it connects to older Emacsen.
 
 `-error DESCRIPTION'
   Signal an error and delete process PROC.