Ensure REPLs per back end; document direnv; closes #706

Improve racket-repl-buffer-name-project to be per back end as well as
per project. In other words, if a project subdir happens to use an
envrc with a distinct back end, that has to be a distinct REPL.

Document how to ensure distinct back ends for people using direnv and
envrc-mode.

doc/racket-mode.texi

@@ -3092,6 +3092,9 @@ The following values will @emph{not} work:
 
 Function to call to browse a URL@.
 
+Defaults to @ref{racket-browse-url-using-temporary-file} on macOS and
+@code{browse-url} on other platforms.
+
 @node racket-xp-after-change-refresh-delay
 @subsection racket-xp-after-change-refresh-delay
 
@@ -3713,7 +3716,7 @@ A value for the variable @ref{racket-show-functions}.
 @code{(racket-repl-buffer-name-shared)}
 
 
-All @ref{racket-mode} edit buffers share one @ref{racket-repl-mode} buffer per back end.
+Share one @ref{racket-repl-mode} buffer per back end.
 
 A value for the variable @ref{racket-repl-buffer-name-function}.
 
@@ -3733,7 +3736,7 @@ A value for the variable @ref{racket-repl-buffer-name-function}.
 @code{(racket-repl-buffer-name-project)}
 
 
-All @ref{racket-mode} buffers in a project share a @ref{racket-repl-mode} buffer.
+Share a @ref{racket-repl-mode} buffer per back end and per project.
 
 A value for the variable @ref{racket-repl-buffer-name-function}.
 
@@ -3932,6 +3935,17 @@ are a few examples.
                          :racket-program "xvfb-run racket")
 @end lisp
 
+If you use various versions of Racket by setting PATH values via
+direnv, .envrc files and @code{envrc-global-mode}, then you need a
+distinct back end for each such project subdirectory. One
+approach is to use @ref{racket-add-back-end} for each project in your
+Emacs init file. Another way to is to have a .dir-locals.el file
+alongside each .envrc file:
+
+@lisp
+    ((nil . ((eval . (racket-add-back-end default-directory)))))
+@end lisp
+
 @node Running racket and raco commands in a shell or terminal (1)
 @section Running racket and raco commands in a shell or terminal
 

racket-back-end.el

@@ -200,6 +200,17 @@ are a few examples.
     (racket-add-back-end \"/ssh:headless:~/gui-project/\"
                          :racket-program \"xvfb-run racket\")
 #+END_SRC
+
+If you use various versions of Racket by setting PATH values via
+direnv, .envrc files and `envrc-global-mode', then you need a
+distinct back end for each such project subdirectory. One
+approach is to use `racket-add-back-end' for each project in your
+Emacs init file. Another way to is to have a .dir-locals.el file
+alongside each .envrc file:
+
+#+BEGIN_SRC lisp
+    ((nil . ((eval . (racket-add-back-end default-directory)))))
+#+END_SRC
 "
   (unless (and (stringp directory) (file-name-absolute-p directory))
     (error "racket-add-back-end: directory must be file-name-absolute-p"))
@@ -443,13 +454,13 @@ a possibly slow remote connection."
 (defun racket--back-end-args->command (back-end racket-command-args)
   "Given RACKET-COMMAND-ARGS, prepend path to racket for BACK-END."
   (if (racket--back-end-local-p back-end)
-      `(,(or (plist-get back-end :racket-program)
-             (executable-find racket-program)
-             (user-error
-              "Cannot find Racket executable\nracket-program: %S\nexec-path: %S"
-              racket-program
-              exec-path))
-        ,@racket-command-args)
+      (cons (or (executable-find (or (plist-get back-end :racket-program)
+                                     racket-program))
+                (error
+                 "Cannot executable-find Racket:\n  racket-program: %S\n  exec-path: %S"
+                 racket-program
+                 exec-path))
+            racket-command-args)
     (pcase-let ((`(,host ,user ,port ,_name)
                  (racket--file-name->host+user+port+name
                   (plist-get back-end :directory))))

racket-repl-buffer-name.el

@@ -26,7 +26,7 @@ customization."
 
 ;;;###autoload
 (defun racket-repl-buffer-name-shared ()
-  "All `racket-mode' edit buffers share one `racket-repl-mode' buffer per back end.
+  "Share one `racket-repl-mode' buffer per back end.
 
 A value for the variable `racket-repl-buffer-name-function'."
   (interactive)
@@ -45,14 +45,15 @@ A value for the variable `racket-repl-buffer-name-function'."
 
 ;;;###autoload
 (defun racket-repl-buffer-name-project ()
-  "All `racket-mode' buffers in a project share a `racket-repl-mode' buffer.
+  "Share a `racket-repl-mode' buffer per back end and per project.
 
 A value for the variable `racket-repl-buffer-name-function'.
 
 The \"project\" is determined by `racket-project-root'."
   (interactive)
   (setq-local racket-repl-buffer-name
-              (format "*Racket REPL <%s>*"
+              (format "*Racket REPL <%s %s>*"
+                      (racket-back-end-name)
                       (racket--file-name-sans-remote-method
                        (racket-project-root (racket--buffer-file-name))))))