example/ and contrib/ re-org

README.md

@@ -72,7 +72,7 @@ the following instructions will help you get started with lorri.
 2. **Start the daemon.** For testing, you can start the daemon in a separate
    terminal by running `lorri daemon`.
 
-   See the [`contrib`][contrib] directory for ways to start the daemon
+   See [`contrib/DAEMON.md`](contrib/DAEMON.md) for ways to start the daemon
    automatically in the background.
 
 3. **Install direnv v2.19.2 or later.** If you are using a Nixpkgs channel at

contrib/DAEMON.md

@@ -0,0 +1,79 @@
+# How to start the lorri daemon as a service
+
+This guide shows you how to run `lorri daemon` as a service.
+
+If you are using NixOS or `home-manager` on Linux with a Nixpkgs channel at
+least as recent as `nixos-19.09`, you have it easy: see [Setup on NixOS or with
+`home-manager` on Linux][setup-nixos-or-home-manager]. Otherwise, read on.
+
+The exact steps depend on your operating system and general setup. Currently,
+we have instructions for these setups:
+
+- [Run `lorri daemon` on Linux with just
+  systemd](#run-lorri-daemon-on-linux-with-just-systemd)
+- [Run `lorri daemon` on macOS with
+  Nix](#run-lorri-daemon-on-macOS-with-nix)
+
+## Run `lorri daemon` on Linux with just systemd
+
+Here we'll set up a [systemd] socket and service file manually.
+
+<details>
+<summary>What's the purpose of the systemd socket? How does systemd know when
+to start the daemon "on demand"?</summary>
+<p>lorri clients, like the `direnv` integration, talk to the daemon via a Unix
+socket at a well-known location. [`lorri.socket`] tells systemd to start the
+systemd service defined in [`lorri.service`] the first time a client attempts
+to connect to this socket.</p>
+</details>
+
+If your `lorri` binary is not in `~/.nix-profile/bin/lorri`, please change the
+`ExecStart=` setting in `lorri.service` to the correct location.
+
+Install [`lorri.socket`] and [`lorri.service`] and make systemd listen on the
+daemon socket:
+
+```console
+$ mkdir -p ~/.config/systemd/user && \
+    cp contrib/lorri.{socket,service} ~/.config/systemd/user/ && \
+    systemctl --user daemon-reload && \
+    systemctl --user enable --now lorri.socket
+```
+
+The lorri daemon will now be started on demand by systemd. See [Verify the
+setup](#verify-the-setup) to check that everything works as expected.
+
+## Run `lorri daemon` on macOS with Nix
+
+Please take a look at [@pawlowsklalaex]'s [suggested
+`darwin-configuration.nix`](https://github.com/target/lorri/issues/96#issuecomment-545152525).
+
+## Verify the setup
+
+In this section, we'll see how to check that the `lorri daemon` setup actually
+works as intended.
+
+### systemd
+
+On a systemd-based system, you should get the following:
+
+```console
+$ systemctl --user is-enabled lorri.socket
+enabled
+$ systemctl --user is-active lorri.socket
+active
+```
+
+### launchd
+
+On macOS, use this command to check the status of the lorri daemon:
+
+```console
+$ launchctl list | grep lorri
+```
+
+[`lorri.socket`]: ./lorri.socket
+[`lorri.service`]: ./lorri.service
+[@pawlowsklalaex]: https://github.com/pawlowskialex
+[setup-nixos-or-home-manager]: ../README.md#setup-on-nixos-or-with-home-manager-on-linux
+[systemd]: https://www.freedesktop.org/wiki/Software/systemd/

contrib/EMACS.md

@@ -0,0 +1,51 @@
+## Set up `direnv` in Emacs with `direnv-mode`
+
+`lorri` uses `direnv`, because `direnv` has dozens of integrations for
+editors, shells and the like . Basically everywhere you want to change
+an environment on the fly, you can use `direnv`.
+
+In particular, there is integration for the Emacs editor,
+[`emacs-direnv`](https://github.com/wbolster/emacs-direnv).
+
+Follow [the `emacs-direnv` setup
+guide](https://github.com/wbolster/emacs-direnv/blob/master/README.rst)
+now.
+
+Note: There are direnv plugins for _many_ editors. Just a few,
+[vscode](https://github.com/direnv/direnv/wiki/VSCode),
+[Sublime](https://github.com/zchee/sublime-direnv),
+[vim](https://github.com/direnv/direnv.vim),
+[Atom](https://atom.io/packages/000-project-shell-env).
+
+
+Once you have it installed, hit `M-x` and enter `direnv-mode`.
+This activates direnv integration for every buffer.
+
+Use the the Emacs file browser to navigate to `lorri/example` and open
+`shell.nix`. If everything went fine, you should see the same list
+of environment variables in your Emacs status line that you previously
+saw in your shell.
+Congratulations, you have working `direnv` integration in your editor,
+and therefore also working `lorri` integration.
+
+`direnv-mode` updates your environment every time you enter a buffer
+that is in a project with a different `.envrc` file. To manually
+apply changes, hit `M-x` and enter `direnv-update-environment`.
+
+Try playing around with the `shell.nix` file, removing and adding
+things. For example, add an environment variable:
+
+```nix
+with import ../nix/nixpkgs.nix;
+mkShell {
+  buildInputs = [];
+
+  MYVARIABLE = "hi";
+}
+```
+
+Wait until the evaluation finishes and refresh your direnv environment
+(`M-x direnv-update-environment`). Your status line shows that
+`MYVARIABLE` was added to the environment.
+Comment out `MYVARIABLE` and refresh, it is removed from the
+environment again.

contrib/README.md

@@ -1,79 +1,9 @@
-# How to start the lorri daemon as a service
+# contrib
 
-This guide shows you how to run `lorri daemon` as a service.
+This directory contains additional files and guides for integrating lorri into your environment.
 
-If you are using NixOS or `home-manager` on Linux with a Nixpkgs channel at
-least as recent as `nixos-19.09`, you have it easy: see [Setup on NixOS or with
-`home-manager` on Linux][setup-nixos-or-home-manager]. Otherwise, read on.
+## Guides
 
-The exact steps depend on your operating system and general setup. Currently,
-we have instructions for these setups:
+[**`DAEMON.md`**](DAEMON.md) shows you how to start lorri's daemon process automatically in the background.
 
-- [Run `lorri daemon` on Linux with just
-  systemd](#run-lorri-daemon-on-linux-with-just-systemd)
-- [Run `lorri daemon` on macOS with
-  Nix](#run-lorri-daemon-on-macOS-with-nix)
-
-## Run `lorri daemon` on Linux with just systemd
-
-Here we'll set up a [systemd] socket and service file manually.
-
-<details>
-<summary>What's the purpose of the systemd socket? How does systemd know when
-to start the daemon "on demand"?</summary>
-<p>lorri clients, like the `direnv` integration, talk to the daemon via a Unix
-socket at a well-known location. [`lorri.socket`] tells systemd to start the
-systemd service defined in [`lorri.service`] the first time a client attempts
-to connect to this socket.</p>
-</details>
-
-If your `lorri` binary is not in `~/.nix-profile/bin/lorri`, please change the
-`ExecStart=` setting in `lorri.service` to the correct location.
-
-Install [`lorri.socket`] and [`lorri.service`] and make systemd listen on the
-daemon socket:
-
-```console
-$ mkdir -p ~/.config/systemd/user && \
-    cp contrib/lorri.{socket,service} ~/.config/systemd/user/ && \
-    systemctl --user daemon-reload && \
-    systemctl --user enable --now lorri.socket
-```
-
-The lorri daemon will now be started on demand by systemd. See [Verify the
-setup](#verify-the-setup) to check that everything works as expected.
-
-## Run `lorri daemon` on macOS with Nix
-
-Please take a look at [@pawlowsklalaex]'s [suggested
-`darwin-configuration.nix`](https://github.com/target/lorri/issues/96#issuecomment-545152525).
-
-## Verify the setup
-
-In this section, we'll see how to check that the `lorri daemon` setup actually
-works as intended.
-
-### systemd
-
-On a systemd-based system, you should get the following:
-
-```console
-$ systemctl --user is-enabled lorri.socket
-enabled
-$ systemctl --user is-active lorri.socket
-active
-```
-
-### launchd
-
-On macOS, use this command to check the status of the lorri daemon:
-
-```console
-$ launchctl list | grep lorri
-```
-
-[`lorri.socket`]: ./lorri.socket
-[`lorri.service`]: ./lorri.service
-[@pawlowsklalaex]: https://github.com/pawlowskialex
-[setup-nixos-or-home-manager]: ../README.md#setup-on-nixos-or-with-home-manager-on-linux
-[systemd]: https://www.freedesktop.org/wiki/Software/systemd/
+[**`EMACS.md`**](EMACS.md) shows you how to use direnv to manage project-specific Emacs configuration.