Docs: Clarification of Package Change Behavior (`<Leader>e` vs `<Leader>g`)

[sebastiancarlos]

Hey there,

There's a potentially confusing difference in behavior between changing the Lisp package with the evaluation command <Leader>e from a source buffer and using the <Leader>g (Set Package) command.

Evaluating (in-package ...) using <Leader>e successfully runs the in-package function, but it does not persistently change the *package* variable in the REPL, and the REPL prompt doesn't update.

Using <Leader>g and providing the package name does work.

To Reproduce:

1. Create a file a.lisp:

   (defpackage #:a (:use #:cl))
   (in-package #:a)
   
   (defun hello () "Hello from A")

2. Evaluate the buffer using <Leader>b. (The REPL prompt changes to A> as expected).
3. Add to the end of a.lisp:

   (in-package #:cl-user)

4. Evaluate it using <Leader>e. (The REPL prompt remains A>, typing *package* in the REPL and evaluating shows A> too.
5. In contrast, <Leader>g and #:cl-user (or just cl-user) changes the REPL prompt to CL-USER> (as expected)

I understand that this is a minor issue, and likely comes from:

• The documented behavior of searching backwards in the buffer for the previous in-package, and passing that to SWANK to let it handle it.
• The arguably weird case I'm describing, in which I'm using the current buffer as a a draft to send commands to the REPL.

I'm suggesting, if you agree it's a good idea, to document this difference in behavior somewhere in the docs.

Thanks for your time!