From bf66ff89aa8fa77a8ec3d8511a5e3460a3d6ca6a Mon Sep 17 00:00:00 2001 From: Anderson Torres Date: Thu, 24 Oct 2024 21:40:41 -0300 Subject: [PATCH] doc/packages/emacs.section.md: reword --- doc/packages/emacs.section.md | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/doc/packages/emacs.section.md b/doc/packages/emacs.section.md index 2ced251f3e46a..6e9412eb6cf8a 100644 --- a/doc/packages/emacs.section.md +++ b/doc/packages/emacs.section.md @@ -1,8 +1,16 @@ # Emacs {#sec-emacs} +[Emacs](https://www.gnu.org/software/emacs/) is the advanced, extensible, customizable, self-documenting editor. + +At its core is an interpreter for Emacs Lisp (shortly, Elisp), a dialect of the Lisp programming language with extensions to support text editing. + ## Configuring Emacs {#sec-emacs-config} -The Emacs package comes with some extra helpers to make it easier to configure. `emacs.pkgs.withPackages` allows you to manage packages from ELPA. This means that you will not have to install that packages from within Emacs. For instance, if you wanted to use `company` `counsel`, `flycheck`, `ivy`, `magit`, `projectile`, and `use-package` you could use this as a `~/.config/nixpkgs/config.nix` override: +Nixpkgs provides a framework that leverages Emacs via Nix. + +`emacs.pkgs.withPackages` allows managing packages from various Elisp package repositories (ELPA, MELPA etc.) and even third-party stand-alone packages from Nix, without relying on Emacs to download and install them. + +For instance, by writing the code below at `~/.config/nixpkgs/config.nix`, the Elisp packages `company` `counsel`, `flycheck`, `ivy`,`magit`, `projectile`, and `use-package` are installed: ```nix { @@ -20,7 +28,16 @@ The Emacs package comes with some extra helpers to make it easier to configure. } ``` -You can install it like any other packages via `nix-env -iA myEmacs`. However, this will only install those packages. It will not `configure` them for us. To do this, we need to provide a configuration file. Luckily, it is possible to do this from within Nix! By modifying the above example, we can make Emacs load a custom config file. The key is to create a package that provides a `default.el` file in `/share/emacs/site-start/`. Emacs knows to load this file automatically when it starts. +This package can be installed like any other, via `nix-env -iA myEmacs`. + +However, this expression merely installs the package. It will not _configure_ them. +To do this, we need to provide a configuration file. + +Luckily, it is possible to do this from within Nix! + +By modifying the above example, we can make Emacs load a custom config file. +The key is to create a package that provides a `default.el` file in `/share/emacs/site-start/`. +Emacs loads this file automatically when it starts. ```nix { @@ -97,9 +114,14 @@ You can install it like any other packages via `nix-env -iA myEmacs`. However, t } ``` -This provides a fairly full Emacs start file. It will load in addition to the user's personal config. You can always disable it by passing `-q` to the Emacs command. +This provides a fairly full Emacs start file. It will be loaded in addition to the user's personal config. It is always possible to disable it, by passing `-q` as a command line argument to Emacs. + +Sometimes `emacs.pkgs.withPackages` is not enough, as this package set imposes some priorities over their packages (with the lowest priority assigned to GNU-devel ELPA, and the highest for packages manually defined in `pkgs/applications/editors/emacs/elisp-packages/manual-packages`). + +But it is not possible to control these priorities when some package is installed as a dependency. The overrides can be done on a per-package-basis, providing all the required dependencies manually. However this procedure is tedious and there is always a possibility that an unwanted dependency sneaks in through some other package. + +A complete and pervasive override for such a package can be done via `overrideScope`. -Sometimes `emacs.pkgs.withPackages` is not enough, as this package set has some priorities imposed on packages (with the lowest priority assigned to GNU-devel ELPA, and the highest for packages manually defined in `pkgs/applications/editors/emacs/elisp-packages/manual-packages`). But you can't control these priorities when some package is installed as a dependency. You can override it on a per-package-basis, providing all the required dependencies manually, but it's tedious and there is always a possibility that an unwanted dependency will sneak in through some other package. To completely override such a package, you can use `overrideScope`. ```nix let