[elpa] externals/buffer-env f3781a628a 09/12: Update README

[ELPA Syncer]

branch: externals/buffer-env
commit f3781a628a15eee035e472a0a0a98f14271297bf
Author: Augusto Stoffel <arstoffel@gmail.com>
Commit: Augusto Stoffel <arstoffel@gmail.com>

    Update README
---
 README.md     | 107 ---------------------------------------------
 README.org    | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 buffer-env.el |  36 +++++++--------
 3 files changed, 152 insertions(+), 128 deletions(-)

diff --git a/README.md b/README.md
deleted file mode 100644
index 2a15c089d6..0000000000
--- a/README.md
+++ /dev/null
@@ -1,107 +0,0 @@
-buffer-env — Buffer-local process environments
-==============================================
-
-This Emacs package sets environment variables on a buffer-local basis,
-according to the output of a shell script.  The idea is that the same
-scripts used elsewhere to set up a project environment can influence
-external processes started from buffers editing the project files.
-This is important for the correct operation of tools such as linters,
-language servers and the `M-x compile` command, for instance.
-
-With the default settings, the package gathers environment variables
-from `.envrc` files, just like the popular [direnv] program.  However,
-buffer-env is entirely independent of direnv and it's not possible to
-use certain fancy direnv-specific features in the `.envrc` scripts.
-On the plus side, it's possible to configure the package to support
-other environment setup methods, such as Python virtualenvs or `.env`
-files (see below).
-
-The usual way to activate this package is by including the
-following in your init file:
-
-``` elisp
-(add-hook 'hack-local-variables-hook 'buffer-env-update)
-```
-
-This way, any buffer potentially affected by directory-local
-variables can also be affected by buffer-env.  It is nonetheless
-possible to call `buffer-env-update` interactively or add it only
-to specific major-mode hooks.
-
-Note that it is quite common for process-executing Emacs libraries not
-to heed to the fact that `process-environment` and `exec-path` may
-have a buffer-local value.  This unfortunate state of affairs can be
-remedied by the [inheritenv] package, which see.
-
-## Alternative settings
-
-This package works as follows.  First, a file named `buffer-env-file`
-is looked up in the current directory or one of its parents.  In case
-of success, `buffer-env-command` is executed in a shell, with the
-found file as argument.  This command should print a list of
-null-separated environment variables (and nothing else) to stdout.
-The buffer-local values of `process-environment` and `exec-path` are
-then set based on that.
-
-With this in sight, it should be possible to integrate with any of the
-numerous environment management tools out there.
-
-### Python virtualenvs
-
-One can always source a virtualenv activation script from an `.envrc`
-script, but this additional step can be avoided by calling
-`buffer-env-update` manually and point to the `bin/activate` file, or
-setting
-
-``` elisp
-(setq 'buffer-env-file "bin/activate")
-```
-
-or a variation thereof.  Note that it is also possible to provide an
-absolute path for `buffer-env-file`, and it is possible to specify it
-as a buffer- or directory-local variable.
-
-### .env files
-
-To gather environment variables from `.env` files in the style of
-Docker, Node.js and others, use the following settings:
-
-``` elisp
-(setq 'buffer-env-file ".env")
-(setq 'buffer-env-command "set -a && >&2 . \"$0\" && env -0")
-```
-
-Obviously, this assumes that the `.env` file is correct when
-interpreted as a shell script, which dictates, for instance, how and
-when quotes are to be used.
-
-### Direnv
-
-As mentioned above, the default settings are compatible with direnv,
-but only as long as `.envrc` is a regular shell script.  If you need
-those, you will be better served by the [envrc] library.  It is
-nonetheless possible to take some advantage of direnv by setting
-
-``` elisp
-(setq 'buffer-env-command "direnv exec . env -0")
-```
-
-## Related packages
-
-This package is essentially a knockoff of the [envrc] package by Steve
-Purcell.  The main difference is that envrc depends on and tightly
-integrates with the direnv program, while buffer-env is minimalist and
-has no extra dependencies.
-
-For a comparison of the buffer-local approach to environment variables
-with the global approach used by most of the similar packages, see
-envrc's README.
-
-There is a large number of Emacs packages interfacing with Python's
-virtualenv system.  They all seem to take the global approach and,
-therefore, the comparisons and caveats in the envrc README also apply,
-mutatis mutandis.
-
-[direnv]: https://direnv.net/
-[envrc]: https://github.com/purcell/envrc
-[inheritenv]: https://github.com/purcell/inheritenv
diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..9b7fbb1a69
--- /dev/null
+++ b/README.org
@@ -0,0 +1,137 @@
+#+title: buffer-env --- Buffer-local process environments
+
+#+html: <a href="https://melpa.org/#/buffer-env";><img alt="MELPA" 
src="https://melpa.org/packages/buffer-env-badge.svg"/></a>
+
+With this package, you can teach Emacs to call the correct version of
+external programs such as linters, compilers and language servers on a
+/per-project/ basis.  Thus you can work on several projects in
+parallel without undue interference and switching seamlessly between
+them.
+
+** Basic setup
+*** On the project side
+Your project settings should go into a shell script named =.envrc=
+which exports a suitable =PATH=, as well as any other desired
+environment variables.  Place this script at the root directory of
+your project.
+
+This follows the ansatz of the popular [[https://direnv.net/][direnv]] 
program, and is mostly
+compatible with it.  However, buffer-env is entirely independent of
+direnv so it is not possible to use direnv-specific features in the
+=.envrc= scripts --- at least not directly.
+
+Alternatively, it is possible to configure buffer-env to directly
+support other environment setup methods, such as Python virtualenvs or
+=.env= files.  See below for details.
+
+*** On the Emacs side
+The usual way to activate this package in Emacs is by including the
+following in your init file:
+
+#+begin_src emacs-lisp
+  (add-hook 'hack-local-variables-hook 'buffer-env-update)
+#+end_src
+
+This way, any buffer potentially affected by 
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html][directory-local
 variables]]
+will also be affected by buffer-env.  It is nonetheless possible to
+call =buffer-env-update= interactively or add it only to specific
+major-mode hooks.
+
+** Alternative settings
+This package works as follows.  First, a file named =buffer-env-file=
+is looked up in the current directory or one of its parents.  In case
+of success, =buffer-env-command= is executed in a shell, with the
+found file as argument.  This command should print a null-separated
+list of environment variables (and nothing else) to stdout.  The
+buffer-local values of =process-environment= and =exec-path= are then
+set based on that.
+
+With this in sight, it should be possible to integrate with any of the
+numerous environment management tools out there.
+
+*** Python virtualenvs
+One can always source a virtualenv activation script from an =.envrc=
+script, but this additional step can be avoided by calling
+=buffer-env-update= manually and pointing to the =bin/activate=
+script.  This can be automated if you create virtualenvs in a
+predictable place, say in a =.venv= directory at the root of each
+project; in this case you can say
+
+#+begin_src emacs-lisp
+  (setq buffer-env-file ".venv/bin/activate")
+#+end_src
+
+or a variation thereof.  Note that it is also possible to provide an
+absolute path for =buffer-env-file=, and it is possible to specify it
+as a buffer- or directory-local variable.
+
+*** .env files
+To gather environment variables from =.env= files in the style of
+Docker, Node.js and others, use the following settings:
+
+#+begin_src emacs-lisp
+  (setq buffer-env-file ".env")
+  (setq buffer-env-command "set -a && >&2 . \"$0\" && env -0")
+#+end_src
+
+Obviously, this assumes that the =.env= file is correct when
+interpreted as a shell script, which dictates, for instance, how and
+when quotes are to be used.
+
+*** Direnv
+As mentioned above, the default settings are compatible with direnv,
+but only as long as =.envrc= is a regular shell script.  If you need
+any direnv extensions, you will probably be better served by the 
[[https://github.com/purcell/envrc][envrc]]
+package.  It is nonetheless possible to take some advantage of direnv
+by setting
+
+#+begin_src emacs-lisp
+  (setq buffer-env-command "direnv exec . env -0")
+#+end_src
+
+*** Non-Unix-like systems
+I need to know what the appropriate value of =buffer-env-command= is
+for those.  Drop me a line if you can help.
+
+** Compatibility issues
+Most Emacs packages are not written with the possibility of a
+buffer-local process environment in mind.  This can lead to issues
+with a few commands; specifically, those which start an external
+process after switching to a different buffer or remote
+directory.  Examples include:
+
+- =shell=, =project-shell= (=C-x p s=) and other REPLs;
+- =compile= and =project-compile= (=C-x p c=) in Emacs 27 and older;
+- =async-shell-command= (=M-&=).
+
+Fortunately, the problem has an easy fix provided by the 
[[https://github.com/purcell/inheritenv][inheritenv]]
+package, which see.
+
+Alternatively, if you speak Elisp and want to keep your configuration
+lean, you can just copy the function below and apply it as an
+=:around= advice to any affected commands.
+
+#+begin_src emacs-lisp
+  (defun buffer-env-inherit (fn &rest args)
+    "Call FN with ARGS using the buffer-local process environment.
+  Intended as an advice around commands that start a process after
+  switching buffers."
+    (cl-letf (((default-value 'process-environment) process-environment)
+              ((default-value 'exec-path) exec-path))
+      (apply fn args)))
+#+end_src
+
+** Related packages
+This package is essentially a knockoff of the 
[[https://github.com/purcell/envrc][envrc]] package by Steve
+Purcell.  The main difference is that envrc depends on and tightly
+integrates with the [[https://direnv.net/][direnv]] program, while buffer-env 
is minimalist and
+has no extra dependencies.
+
+For a comparison of the buffer-local approach to environment variables
+with the global approach used by most of the similar packages, see
+envrc's README.
+
+There is a large number of Emacs packages interfacing with Python's
+virtualenv system.  They all seem to take the global approach and,
+therefore, the comparisons and caveats in the envrc README also apply,
+mutatis mutandis.
diff --git a/buffer-env.el b/buffer-env.el
index 132b01e5da..808114d1bf 100644
--- a/buffer-env.el
+++ b/buffer-env.el
@@ -23,21 +23,20 @@
 
 ;;; Commentary:
 
-;; This package adjusts the `process-environment' and `exec-path'
-;; variables buffer locally according to the output of a shell script.
-;; The idea is that the same scripts used elsewhere to set up a
-;; project environment can influence external processes started from
-;; buffers editing the project files.  This is important for the
-;; correct operation of tools such as linters, language servers and
-;; the `compile' command, for instance.
-
-;; The default settings of the package are compatible with the popular
-;; direnv program.  However, this package is entirely independent of
-;; direnv and it's not possible to use direnv-specific features in the
-;; .envrc scripts.  On the plus side, it's possible to configure the
-;; package to support other environment setup methods, such as .env
-;; files or Python virtualenvs.  The package Readme includes some
-;; examples.
+;; The purpose of this package is to adjust the `process-environment'
+;; and `exec-path' variables buffer locally according to the output of
+;; a shell script.  This allows the correct operation of tools such as
+;; linters, compilers and language servers when working on projects
+;; with special requirements which are not installed globally on the
+;; system.
+
+;; The default settings of this package are compatible with the
+;; popular direnv program.  However, the package is entirely
+;; independent of direnv and it's not possible to use direnv-specific
+;; features in the .envrc scripts.  On the plus side, it's possible to
+;; configure the package to support other environment setup methods,
+;; such as .env files or Python virtualenvs.  The README file includes
+;; some examples.
 
 ;; The usual way to activate this package is by including the
 ;; following in your init file:
@@ -45,15 +44,10 @@
 ;;     (add-hook 'hack-local-variables-hook 'buffer-env-update)
 ;;
 ;; This way, any buffer potentially affected by directory-local
-;; variables can also be affected by buffer-env.  It is nonetheless
+;; variables will also be affected by buffer-env.  It is nonetheless
 ;; possible to call `buffer-env-update' interactively or add it only
 ;; to specific major-mode hooks.
 
-;; Note that it is quite common for process-executing Emacs libraries
-;; not to heed to the fact that `process-environment' and `exec-path'
-;; may have a buffer-local value.  This unfortunate state of affairs
-;; can be remedied by the `inheritenv' package, which see.
-
 ;;; Code:
 
 (require 'seq)