Streamline setup instructions

[curiousleo]

Closes #225, #226, #227, #231.

Motivation

We currently have the top-level README.md and example/README.md and contrib/README.md. My proposal is this:

• have one short set of instructions that should work for most lorri users, with explicit requirements, in the top-level README.md
• provide help for setting up lorri on other systems, with additional files to help the process along, in contrib.

To actually use lorri, the following are required:

• direnv must be installed and enabled
• lorri must be installed and the daemon must be running
• the user must have a project with an .envrc that invokes lorri direnv

The idea here is that for people using either NixOS or home-manager and a Nix channel that is at least as recent as nixos-19.09, this is really easy. I believe that a lot of lorri users meet these requirements, so I think that it would make sense to optimise the "README experience" for those users.

Changes

• rewrite sections "Install" and "Usage" of the top-level README.md in a way that guides users who meet the requirements above through the fast path
• point users who don't meet the requirements to additional resources (e.g. the direnv help pages or the systemd contrib files in contrib) in the "Install" and "Usage" sections of the top-level README.md
• take the Emacs section of example/README.md, put it into contrib/ and link to it from the top-level README.md, then remove the remainder of the example/ directory

At this point, the example/README.md will no longer be necessary since all the information in here should now be contained in the top-level README.me in a streamlined form.

Previews

• README.md
• contrib/README.md
• contrib/daemon.md
• contrib/emacs.md

[curiousleo]

PTAL

[curiousleo]

One thing that is currently missing is a link from the top-level README.md to contrib/EMACS.md. @Profpatsch, where do you think would be the best place to mention the Emacs integration? Perhaps the "Usage" section in the top-level README.md?

[Profpatsch]

Good that we can simplify the setup so much with the new modules!

If we delete the tutorial, there is no “hand holding”-style section anymore that the user can follow step-by-step. I think demonstrating the basic features in a tutorial is still a good thing, and even though we integrate the setup part into the readme, the demo itself is missing after. With the simplfied setup, we should have even more space to demonstrate the cool capabilities lorri has, so maybe that should be a followup quest, make another tutorial.

[Profpatsch]

In the tutorial I had this paragraph:

This gives you `nix` editor integration for free. Whenever you open
a file, as long as there is a `direnv`/`lorri` setup in the project,
your editor automatically loads all tools, environment variables,
library dependencies, etc. from your nix files. In short: Everything
you need to be productive on your project and everything to make sure
your codevelopers have the same, reproducible setup.
Even further, if you change something in your nix files, `lorri`
immediately picks it up, and your editor does as well.

Can we salvage some of that?

[curiousleo]

I use a pretty vanilla Vim setup for most of my coding.

your editor automatically loads all tools, environment variables,
library dependencies, etc. from your nix files.

This just isn't really true for example for my development experience. Whether I'm inside or outside a direnv directory has no impact on my editor at all, except that other command line tools are available via :! <tool>.

However, I do think that users (including me) can probably benefit from learning about how to integrate their editor(s) with direnv for a better development experience. This is why I wanted to keep the "How to integrate with Emacs" tutorial (tentatively in contrib/EMACS.md), and I think there should be a prominent link to it from the top-level README (see #233 (comment)).

[curiousleo]

There's a chance that because I haven't made an effort to customise my development experience based on per-project direnv / lorri things, I'm underestimating the importance of the customisation possibilities that come with the direnv / lorri duo.

If you would like the messaging to go more in this direction, I'm happy to oblige - in that case, there should be at least a teaser about editor customisation directly in the top-level README.

[Profpatsch]

This just isn't really true for example for my development experience. Whether I'm inside or outside a direnv directory has no impact on my editor at all, except that other command line tools are available via :! <tool>.

You are missing out very much. Good editor tooling support is a base premise of lorri and improves productivity significantly in my experience.

The paragraph was from back when it was Emacs-specific, but we should strongly recommend users to set up editor tooling, because lorri makes it often possible in the first place.

I'm underestimating the importance of the customisation possibilities that come with the direnv / lorri duo.

yeah! try it out :)

[Profpatsch]

I can show you some of the stuff I use if you want.

[curiousleo]

I added a stub "Editor integration" section with a link to contrib/emacs.md and #244 as a follow-up to flesh this out more.

[Profpatsch]

Okay, a few more comments, then we are ready to merge.

[Profpatsch]

LGTM