; 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)

1 files changed, 11 insertions, 3 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 "));