Documentation overhaul

README.md

@@ -1,3 +1,5 @@
+| readme | [reference](./docs/reference.md)| [faq](./docs/faq.md)  |
+
 # nix-doom-emacs
 
 |     | Status |
@@ -6,8 +8,8 @@
 | Dependency updater | [![Dependency Updater Status](https://github.com/nix-community/nix-doom-emacs/workflows/Update%20Dependencies/badge.svg?branch=master)](https://github.com/nix-community/nix-doom-emacs/actions/workflows/update-dependencies.yml?query=branch%3Amaster) |
 | Matrix Chat | [![Matrix Chat](https://img.shields.io/static/v1?label=chat&message=doom-emacs&color=brightgreen&logo=matrix)](https://matrix.to/#/#doom-emacs:nixos.org) |
 
-Nix expression to install and configure
-[doom-emacs](https://github.com/doomemacs/doomemacs).
+nix-doom-emacs (abbreviated as NDE) provides a customisable Nix derivation for [Doom Emacs](https://github.com/doomemacs/doomemacs)
+The project has lots of moving pieces and hacks. Users are expected to know their way around using (and especially debugging) Nix and Emacs Lisp in order to use this project.
 
 The expression builds a `doom-emacs` distribution with dependencies
 pre-installed based on an existing `~/.doom.d` directory.
@@ -17,121 +19,20 @@ some may not be fully compatible as the version available in NixOS or
 [emacs-overlay](https://github.com/nix-community/emacs-overlay) may not be
 compatible with the `doom-emacs` requirements.
 
-## Getting started
-
-Using [home-manager](https://github.com/nix-community/home-manager):
-
-``` nix
-{ pkgs, ... }:
-
-let
-  doom-emacs = pkgs.callPackage (builtins.fetchTarball {
-    url = https://github.com/nix-community/nix-doom-emacs/archive/master.tar.gz;
-  }) {
-    doomPrivateDir = ./doom.d;  # Directory containing your config.el init.el
-                                # and packages.el files
-  };
-in {
-  home.packages = [ doom-emacs ];
-}
-```
-
-`./doom.d` should contain the following three files: `config.el`, `init.el` and
-`packages.el`. If you don't already have an existing `doom-emacs` configuration,
-you can use the contents of `test/doom.d` as a template.
-
-Using `flake.nix`:
-
-``` nix
-{
-  inputs = {
-    home-manager.url = "github:nix-community/home-manager";
-    nix-doom-emacs.url = "github:nix-community/nix-doom-emacs";
-  };
-
-  outputs = {
-    self,
-    nixpkgs,
-    lib,
-    home-manager,
-    nix-doom-emacs,
-    ...
-  }: {
-    nixosConfigurations.exampleHost = lib.nixosSystem {
-      system = "x86_64-linux";
-      modules = [
-        home-manager.nixosModules.home-manager
-        ({
-          home-manager.users.exampleUser = lib.mkMerge [
-            nix-doom-emacs.hmModule
-            { ... }: {
-              programs.doom-emacs = {
-                enable = true;
-                doomPrivateDir = ./doom.d;
-              };
-            }
-          ];
-        })
-      ];
-    };
-  };
-}
-```
-
-## Under the hood
-
-This expression leverages
-[nix-straight.el](https://github.com/nix-community/nix-straight.el) under the hood for
-installing dependencies. The restrictions of that package apply here too.
-
-## Usage
-
-instead of running emacs.d/bin/doom, once you have update your config files (packages.el, init.el, config.el), rebuild doom-emacs with nix. If you are using home-manager, simply run `home-manager switch`
-
-## Troubleshooting
-
-On macOS on a fresh install, you might run into the error `Too many files open`. running `ulimit -S -n 2048` will only work for the duration of your shell and will fix the error
-
-## Installing emacs packages
-
-In the initial packages.el instructions for how to install packages can be
-found. However some packages might require a particular software dependency to
-be installed. Trying to install those would give you an error of the type:
-`Searching for program: No such file or directory, git` (Missing git dependency)
-Here is how you would go installing
-[magit-delta](https://github.com/dandavison/magit-delta) for example (which
-requires git).
-
-Under the line:
-`doomPrivateDir = ./doom.d;`
-in your configuration, you would add the following:
+# Quick Start
 
-```Nix
-{
-  emacsPackagesOverlay = self: super: {
-     magit-delta = super.magit-delta.overrideAttrs (esuper: {
-       buildInputs = esuper.buildInputs ++ [ pkgs.git ];
-     });
-  };
-}
-```
+If you want to get a taste of nix-doom-emacs, you can run ``nix run github:nix-community/nix-doom-emacs``
+Which will run nix-doom-emacs with an example configuration. 
 
-To make the git dependency available. trying to rebuild doom-emacs with
-`home-manager switch` should work correctly now.
+Pick which setup you're using here (if you're not using NixOS or Home-Manager, then you should use standalone):
 
-## Using the daemon
+| Home-Manager | NixOS | Standalone |
+|      ---     |  ---  |    ---     |
+| [Flake + Home-Manager](./docs/reference.md#home-manager) | [NixOS](./docs/reference.md#nixos) | [Standalone](./docs/reference.md#standalone) |
 
-To use the daemon, simply enable the emacs service (with `NixOS`, `home-manager`
-or `nix-darwin`) and use the doom emacs package. `doom-emacs` will need to be
-referenced at the top of your config file.
 
-```nix
-{
-  services.emacs = {
-    enable = true;
-    package = doom-emacs; # Not needed if you're using the Home-Manager module instead
-  };
-}
-```
+# Hacking
 
-to connect to the daemon you can now run `emacsclient -c`
+This project is licensend under MIT. Only bugs should be filed in our [issue tracker](https://github.com/nix-community/nix-doom-emacs/issues).
+The `PR wanted` label is for issues that we'd appreciate PRs for the most.
+Contributions are welcome.

docs/faq.md

@@ -0,0 +1,60 @@
+| [readme](/README.md) | [reference](./reference.md)| faq |
+
+# Frequently Asked Questions
+
+## I am new to Nix. Is this the only way to use Doom Emacs with Nix/NixOS?
+
+Nope! Doom Emacs is still perfectly usable imperatively. In fact, the very author of Doom Emacs uses NixOS and install Doom Emacs with an ["imperative" setup](https://github.com/hlissner/dotfiles/blob/master/modules/editors/emacs.nix). You can follow the instructions on the [Doom Emacs GitHub repository](https://github.com/doomemacs/doomemacs) to get a working setup.
+
+
+## How do I add a non-(M)ELPA dependency to a package's build?
+
+You'd usually need to do this when a (M)ELPA pakage needs some package to exist on your system, like `git` for example.
+
+You should use the `emacsPackagesOverlay` attribute. Here's an example that installs `magit-delta`, which depends on Git:
+
+```nix
+programs.doom-emacs = {
+  # ...
+  emacsPackagesOverlay = self: super: {
+    magit-delta = super.magit-delta.overrideAttrs (esuper: {
+      buildInputs = esuper.buildInputs ++ [ pkgs.git ];
+    });
+  }
+};
+```
+
+## How do I add a package that's only on GitHub (or any Git frontend)
+
+If you try to add a package that isn't from (M)ELPA, you'd get this error: `Package not available`. This is because `nix-straight.el` assumes that packages are on emacs-overlay's packages, which only include (M)ELPA.
+This question assumes the package uses GitHub, so it uses the `fetchFromGitHub` function. To see which function you'd need to use, you should look at [the Nixpkgs manual's fetchers section](https://nixos.org/manual/nixpkgs/stable/#chap-pkgs-fetchers)
+For an example, this installs `idris2-mode` which isn't on (M)ELPA, but is hosted on GitHub:
+
+```nix
+programs.doom-emacs = {
+  # ...
+  emacsPackagesOverlay = self: super: {
+    idris2-mode = self.trivialBuild {
+      pname = "idris2-mode";
+      ename = "idris2-mode";
+      version = "unstable-2022-09-21";
+      buildInputs = [ self.prop-menu ];
+      src = pkgs.fetchFromGitHub {
+        owner = "idris-community";
+        repo = "idris2-mode";
+        rev = "4a3f9cdb1a155da59824e39f0ac78ccf72f2ca97";
+        sha256 = "sha256-TxsGaG2fBRWWP9aas59kiNnUVD4ZdNlwwaFbM4+n81c=";
+      };
+    };
+  }
+};
+```
+
+## nix-doom-emacs isn't working if I set DOOMDIR or EMACSDIR
+
+You shouldn't do that. nix-doom-emacs' home-manager module writes `~/.emacs.d` in your `$HOME`. Make sure to remove the environment variables from your configuration, then reboot after rebuilding it. If for just the session, you can just `unset` those 2 variables.
+
+## It erros with "Too many files open"!
+
+Running `ulimit -S -n 2048` will fix it for the duration of your shell session.
+For a more permanent solution, NixOS has [`security.pam.loginLimits`](https://search.nixos.org/options?channel=22.05&from=0&size=50&sort=relevance&type=packages&query=security.pam.loginLimits)