diff options
Diffstat (limited to 'nixos/modules/services/editors/emacs.xml')
| -rw-r--r-- | nixos/modules/services/editors/emacs.xml | 221 |
1 files changed, 51 insertions, 170 deletions
diff --git a/nixos/modules/services/editors/emacs.xml b/nixos/modules/services/editors/emacs.xml index 03483f69fa2..0213b8971c2 100644 --- a/nixos/modules/services/editors/emacs.xml +++ b/nixos/modules/services/editors/emacs.xml @@ -12,41 +12,26 @@ Adam Hoese @adisbladis --> <para> - <link xlink:href="https://www.gnu.org/software/emacs/">Emacs</link> is an - extensible, customizable, self-documenting real-time display editor — and - more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp - programming language with extensions to support text editing. + <link xlink:href="https://www.gnu.org/software/emacs/">Emacs</link> is an extensible, customizable, self-documenting real-time display editor — and more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp programming language with extensions to support text editing. </para> <para> - Emacs runs within a graphical desktop environment using the X Window System, - but works equally well on a text terminal. Under - <productname>macOS</productname>, a "Mac port" edition is available, which - uses Apple's native GUI frameworks. + Emacs runs within a graphical desktop environment using the X Window System, but works equally well on a text terminal. Under <productname>macOS</productname>, a "Mac port" edition is available, which uses Apple's native GUI frameworks. </para> <para> - <productname>Nixpkgs</productname> provides a superior environment for - running <application>Emacs</application>. It's simple to create custom builds - by overriding the default packages. Chaotic collections of Emacs Lisp code - and extensions can be brought under control using declarative package - management. <productname>NixOS</productname> even provides a - <command>systemd</command> user service for automatically starting the Emacs - daemon. + <productname>Nixpkgs</productname> provides a superior environment for running <application>Emacs</application>. It's simple to create custom builds by overriding the default packages. Chaotic collections of Emacs Lisp code and extensions can be brought under control using declarative package management. <productname>NixOS</productname> even provides a <command>systemd</command> user service for automatically starting the Emacs daemon. </para> <section xml:id="module-services-emacs-installing"> <title>Installing <application>Emacs</application></title> <para> - Emacs can be installed in the normal way for Nix (see - <xref linkend="sec-package-management" />). In addition, a NixOS - <emphasis>service</emphasis> can be enabled. + Emacs can be installed in the normal way for Nix (see <xref linkend="sec-package-management" />). In addition, a NixOS <emphasis>service</emphasis> can be enabled. </para> <section xml:id="module-services-emacs-releases"> <title>The Different Releases of Emacs</title> <para> - <productname>Nixpkgs</productname> defines several basic Emacs packages. - The following are attributes belonging to the <varname>pkgs</varname> set: + <productname>Nixpkgs</productname> defines several basic Emacs packages. The following are attributes belonging to the <varname>pkgs</varname> set: <variablelist> <varlistentry> <term> @@ -57,10 +42,8 @@ </term> <listitem> <para> - The latest stable version of Emacs 25 using the - <link - xlink:href="http://www.gtk.org">GTK 2</link> - widget toolkit. + The latest stable version of Emacs 25 using the <link + xlink:href="http://www.gtk.org">GTK 2</link> widget toolkit. </para> </listitem> </varlistentry> @@ -83,8 +66,7 @@ </term> <listitem> <para> - Emacs 25 with the "Mac port" patches, providing a more native look and - feel under macOS. + Emacs 25 with the "Mac port" patches, providing a more native look and feel under macOS. </para> </listitem> </varlistentry> @@ -92,12 +74,7 @@ </para> <para> - If those aren't suitable, then the following imitation Emacs editors are - also available in Nixpkgs: - <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>, - <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>, - <link xlink:href="http://yi-editor.github.io/">Yi</link>, - <link xlink:href="https://joe-editor.sourceforge.io/">jmacs</link>. + If those aren't suitable, then the following imitation Emacs editors are also available in Nixpkgs: <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>, <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>, <link xlink:href="http://yi-editor.github.io/">Yi</link>, <link xlink:href="https://joe-editor.sourceforge.io/">jmacs</link>. </para> </section> @@ -105,36 +82,20 @@ <title>Adding Packages to Emacs</title> <para> - Emacs includes an entire ecosystem of functionality beyond text editing, - including a project planner, mail and news reader, debugger interface, - calendar, and more. + Emacs includes an entire ecosystem of functionality beyond text editing, including a project planner, mail and news reader, debugger interface, calendar, and more. </para> <para> - Most extensions are gotten with the Emacs packaging system - (<filename>package.el</filename>) from - <link - xlink:href="https://elpa.gnu.org/">Emacs Lisp Package Archive - (<acronym>ELPA</acronym>)</link>, - <link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></link>, - <link xlink:href="https://stable.melpa.org/">MELPA Stable</link>, and - <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>. Nixpkgs is - regularly updated to mirror all these archives. + Most extensions are gotten with the Emacs packaging system (<filename>package.el</filename>) from <link + xlink:href="https://elpa.gnu.org/">Emacs Lisp Package Archive (<acronym>ELPA</acronym>)</link>, <link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></link>, <link xlink:href="https://stable.melpa.org/">MELPA Stable</link>, and <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>. Nixpkgs is regularly updated to mirror all these archives. </para> <para> - Under NixOS, you can continue to use - <function>package-list-packages</function> and - <function>package-install</function> to install packages. You can also - declare the set of Emacs packages you need using the derivations from - Nixpkgs. The rest of this section discusses declarative installation of - Emacs packages through nixpkgs. + Under NixOS, you can continue to use <function>package-list-packages</function> and <function>package-install</function> to install packages. You can also declare the set of Emacs packages you need using the derivations from Nixpkgs. The rest of this section discusses declarative installation of Emacs packages through nixpkgs. </para> <para> - The first step to declare the list of packages you want in your Emacs - installation is to create a dedicated derivation. This can be done in a - dedicated <filename>emacs.nix</filename> file such as: + The first step to declare the list of packages you want in your Emacs installation is to create a dedicated derivation. This can be done in a dedicated <filename>emacs.nix</filename> file such as: <example xml:id="ex-emacsNix"> <title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title> <programlisting language="nix"> @@ -176,36 +137,27 @@ in <calloutlist> <callout arearefs="ex-emacsNix-1"> <para> - The first non-comment line in this file (<literal>{ pkgs ? ... - }</literal>) indicates that the whole file represents a function. + The first non-comment line in this file (<literal>{ pkgs ? ... }</literal>) indicates that the whole file represents a function. </para> </callout> <callout arearefs="ex-emacsNix-2"> <para> - The <varname>let</varname> expression below defines a - <varname>myEmacs</varname> binding pointing to the current stable - version of Emacs. This binding is here to separate the choice of the - Emacs binary from the specification of the required packages. + The <varname>let</varname> expression below defines a <varname>myEmacs</varname> binding pointing to the current stable version of Emacs. This binding is here to separate the choice of the Emacs binary from the specification of the required packages. </para> </callout> <callout arearefs="ex-emacsNix-3"> <para> - This generates an <varname>emacsWithPackages</varname> function. It - takes a single argument: a function from a package set to a list of - packages (the packages that will be available in Emacs). + This generates an <varname>emacsWithPackages</varname> function. It takes a single argument: a function from a package set to a list of packages (the packages that will be available in Emacs). </para> </callout> <callout arearefs="ex-emacsNix-4"> <para> - The rest of the file specifies the list of packages to install. In the - example, two packages (<varname>magit</varname> and - <varname>zerodark-theme</varname>) are taken from MELPA stable. + The rest of the file specifies the list of packages to install. In the example, two packages (<varname>magit</varname> and <varname>zerodark-theme</varname>) are taken from MELPA stable. </para> </callout> <callout arearefs="ex-emacsNix-5"> <para> - Two packages (<varname>undo-tree</varname> and - <varname>zoom-frm</varname>) are taken from MELPA. + Two packages (<varname>undo-tree</varname> and <varname>zoom-frm</varname>) are taken from MELPA. </para> </callout> <callout arearefs="ex-emacsNix-6"> @@ -215,17 +167,14 @@ in </callout> <callout arearefs="ex-emacsNix-7"> <para> - <varname>notmuch</varname> is taken from a nixpkgs derivation which - contains an Emacs mode. + <varname>notmuch</varname> is taken from a nixpkgs derivation which contains an Emacs mode. </para> </callout> </calloutlist> </para> <para> - The result of this configuration will be an <command>emacs</command> - command which launches Emacs with all of your chosen packages in the - <varname>load-path</varname>. + The result of this configuration will be an <command>emacs</command> command which launches Emacs with all of your chosen packages in the <varname>load-path</varname>. </para> <para> @@ -234,23 +183,17 @@ in <prompt>$ </prompt>nix-build emacs.nix <prompt>$ </prompt>./result/bin/emacs -q </screen> - and then typing <literal>M-x package-initialize</literal>. Check that you - can use all the packages you want in this Emacs instance. For example, try - switching to the zerodark theme through <literal>M-x load-theme <RET> - zerodark <RET> y</literal>. + and then typing <literal>M-x package-initialize</literal>. Check that you can use all the packages you want in this Emacs instance. For example, try switching to the zerodark theme through <literal>M-x load-theme <RET> zerodark <RET> y</literal>. </para> <tip> <para> - A few popular extensions worth checking out are: auctex, company, - edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile, - and yasnippet. + A few popular extensions worth checking out are: auctex, company, edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile, and yasnippet. </para> </tip> <para> - The list of available packages in the various ELPA repositories can be seen - with the following commands: + The list of available packages in the various ELPA repositories can be seen with the following commands: <example xml:id="module-services-emacs-querying-packages"> <title>Querying Emacs packages</title> <programlisting><![CDATA[ @@ -263,10 +206,7 @@ nix-env -f "<nixpkgs>" -qaP -A emacsPackages.orgPackages </para> <para> - If you are on NixOS, you can install this particular Emacs for all users by - adding it to the list of system packages (see - <xref linkend="sec-declarative-package-mgmt" />). Simply modify your file - <filename>configuration.nix</filename> to make it contain: + If you are on NixOS, you can install this particular Emacs for all users by adding it to the list of system packages (see <xref linkend="sec-declarative-package-mgmt" />). Simply modify your file <filename>configuration.nix</filename> to make it contain: <example xml:id="module-services-emacs-configuration-nix"> <title>Custom Emacs in <filename>configuration.nix</filename></title> <programlisting><![CDATA[ @@ -281,9 +221,7 @@ nix-env -f "<nixpkgs>" -qaP -A emacsPackages.orgPackages </para> <para> - In this case, the next <command>nixos-rebuild switch</command> will take - care of adding your <command>emacs</command> to the <varname>PATH</varname> - environment variable (see <xref linkend="sec-changing-config" />). + In this case, the next <command>nixos-rebuild switch</command> will take care of adding your <command>emacs</command> to the <varname>PATH</varname> environment variable (see <xref linkend="sec-changing-config" />). </para> <!-- fixme: i think the following is better done with config.nix @@ -291,11 +229,7 @@ https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides --> <para> - If you are not on NixOS or want to install this particular Emacs only for - yourself, you can do so by adding it to your - <filename>~/.config/nixpkgs/config.nix</filename> (see - <link xlink:href="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs - manual</link>): + If you are not on NixOS or want to install this particular Emacs only for yourself, you can do so by adding it to your <filename>~/.config/nixpkgs/config.nix</filename> (see <link xlink:href="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs manual</link>): <example xml:id="module-services-emacs-config-nix"> <title>Custom Emacs in <filename>~/.config/nixpkgs/config.nix</filename></title> <programlisting><![CDATA[ @@ -309,9 +243,7 @@ https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides </para> <para> - In this case, the next <literal>nix-env -f '<nixpkgs>' -iA - myemacs</literal> will take care of adding your emacs to the - <varname>PATH</varname> environment variable. + In this case, the next <literal>nix-env -f '<nixpkgs>' -iA myemacs</literal> will take care of adding your emacs to the <varname>PATH</varname> environment variable. </para> </section> @@ -319,12 +251,7 @@ https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides <title>Advanced Emacs Configuration</title> <para> - If you want, you can tweak the Emacs package itself from your - <filename>emacs.nix</filename>. For example, if you want to have a - GTK 3-based Emacs instead of the default GTK 2-based binary and remove the - automatically generated <filename>emacs.desktop</filename> (useful is you - only use <command>emacsclient</command>), you can change your file - <filename>emacs.nix</filename> in this way: + If you want, you can tweak the Emacs package itself from your <filename>emacs.nix</filename>. For example, if you want to have a GTK 3-based Emacs instead of the default GTK 2-based binary and remove the automatically generated <filename>emacs.desktop</filename> (useful is you only use <command>emacsclient</command>), you can change your file <filename>emacs.nix</filename> in this way: </para> <example xml:id="ex-emacsGtk3Nix"> @@ -348,8 +275,7 @@ in [...] </example> <para> - After building this file as shown in <xref linkend="ex-emacsNix" />, you - will get an GTK 3-based Emacs binary pre-loaded with your favorite packages. + After building this file as shown in <xref linkend="ex-emacsNix" />, you will get an GTK 3-based Emacs binary pre-loaded with your favorite packages. </para> </section> </section> @@ -357,23 +283,18 @@ in [...] <title>Running Emacs as a Service</title> <para> - <productname>NixOS</productname> provides an optional - <command>systemd</command> service which launches - <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html"> - Emacs daemon </link> with the user's login session. + <productname>NixOS</productname> provides an optional <command>systemd</command> service which launches <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html"> Emacs daemon </link> with the user's login session. </para> <para> - <emphasis>Source:</emphasis> - <filename>modules/services/editors/emacs.nix</filename> + <emphasis>Source:</emphasis> <filename>modules/services/editors/emacs.nix</filename> </para> <section xml:id="module-services-emacs-enabling"> <title>Enabling the Service</title> <para> - To install and enable the <command>systemd</command> user service for Emacs - daemon, add the following to your <filename>configuration.nix</filename>: + To install and enable the <command>systemd</command> user service for Emacs daemon, add the following to your <filename>configuration.nix</filename>: <programlisting> <xref linkend="opt-services.emacs.enable"/> = true; <xref linkend="opt-services.emacs.package"/> = import /home/cassou/.emacs.d { pkgs = pkgs; }; @@ -381,16 +302,11 @@ in [...] </para> <para> - The <varname>services.emacs.package</varname> option allows a custom - derivation to be used, for example, one created by - <function>emacsWithPackages</function>. + The <varname>services.emacs.package</varname> option allows a custom derivation to be used, for example, one created by <function>emacsWithPackages</function>. </para> <para> - Ensure that the Emacs server is enabled for your user's Emacs - configuration, either by customizing the <varname>server-mode</varname> - variable, or by adding <literal>(server-start)</literal> to - <filename>~/.emacs.d/init.el</filename>. + Ensure that the Emacs server is enabled for your user's Emacs configuration, either by customizing the <varname>server-mode</varname> variable, or by adding <literal>(server-start)</literal> to <filename>~/.emacs.d/init.el</filename>. </para> <para> @@ -408,9 +324,7 @@ in [...] <title>Starting the client</title> <para> - Ensure that the emacs server is enabled, either by customizing the - <varname>server-mode</varname> variable, or by adding - <literal>(server-start)</literal> to <filename>~/.emacs</filename>. + Ensure that the emacs server is enabled, either by customizing the <varname>server-mode</varname> variable, or by adding <literal>(server-start)</literal> to <filename>~/.emacs</filename>. </para> <para> @@ -429,23 +343,15 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <!--<title><command>emacsclient</command> as the Default Editor</title>--> <para> - If <xref linkend="opt-services.emacs.defaultEditor"/> is - <literal>true</literal>, the <varname>EDITOR</varname> variable will be set - to a wrapper script which launches <command>emacsclient</command>. + If <xref linkend="opt-services.emacs.defaultEditor"/> is <literal>true</literal>, the <varname>EDITOR</varname> variable will be set to a wrapper script which launches <command>emacsclient</command>. </para> <para> - Any setting of <varname>EDITOR</varname> in the shell config files will - override <varname>services.emacs.defaultEditor</varname>. To make sure - <varname>EDITOR</varname> refers to the Emacs wrapper script, remove any - existing <varname>EDITOR</varname> assignment from - <filename>.profile</filename>, <filename>.bashrc</filename>, - <filename>.zshenv</filename> or any other shell config file. + Any setting of <varname>EDITOR</varname> in the shell config files will override <varname>services.emacs.defaultEditor</varname>. To make sure <varname>EDITOR</varname> refers to the Emacs wrapper script, remove any existing <varname>EDITOR</varname> assignment from <filename>.profile</filename>, <filename>.bashrc</filename>, <filename>.zshenv</filename> or any other shell config file. </para> <para> - If you have formed certain bad habits when editing files, these can be - corrected with a shell alias to the wrapper script: + If you have formed certain bad habits when editing files, these can be corrected with a shell alias to the wrapper script: <programlisting>alias vi=$EDITOR</programlisting> </para> </section> @@ -454,10 +360,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <title>Per-User Enabling of the Service</title> <para> - In general, <command>systemd</command> user services are globally enabled - by symlinks in <filename>/etc/systemd/user</filename>. In the case where - Emacs daemon is not wanted for all users, it is possible to install the - service but not globally enable it: + In general, <command>systemd</command> user services are globally enabled by symlinks in <filename>/etc/systemd/user</filename>. In the case where Emacs daemon is not wanted for all users, it is possible to install the service but not globally enable it: <programlisting> <xref linkend="opt-services.emacs.enable"/> = false; <xref linkend="opt-services.emacs.install"/> = true; @@ -465,11 +368,9 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal </para> <para> - To enable the <command>systemd</command> user service for just the - currently logged in user, run: + To enable the <command>systemd</command> user service for just the currently logged in user, run: <programlisting>systemctl --user enable emacs</programlisting> - This will add the symlink - <filename>~/.config/systemd/user/emacs.service</filename>. + This will add the symlink <filename>~/.config/systemd/user/emacs.service</filename>. </para> </section> </section> @@ -477,8 +378,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <title>Configuring Emacs</title> <para> - The Emacs init file should be changed to load the extension packages at - startup: + The Emacs init file should be changed to load the extension packages at startup: <example xml:id="module-services-emacs-package-initialisation"> <title>Package initialization in <filename>.emacs</filename></title> <programlisting><![CDATA[ @@ -494,10 +394,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal </para> <para> - After the declarative emacs package configuration has been tested, - previously downloaded packages can be cleaned up by removing - <filename>~/.emacs.d/elpa</filename> (do make a backup first, in case you - forgot a package). + After the declarative emacs package configuration has been tested, previously downloaded packages can be cleaned up by removing <filename>~/.emacs.d/elpa</filename> (do make a backup first, in case you forgot a package). </para> <!-- @@ -509,9 +406,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <title>A Major Mode for Nix Expressions</title> <para> - Of interest may be <varname>melpaPackages.nix-mode</varname>, which - provides syntax highlighting for the Nix language. This is particularly - convenient if you regularly edit Nix files. + Of interest may be <varname>melpaPackages.nix-mode</varname>, which provides syntax highlighting for the Nix language. This is particularly convenient if you regularly edit Nix files. </para> </section> @@ -519,9 +414,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <title>Accessing man pages</title> <para> - You can use <function>woman</function> to get completion of all available - man pages. For example, type <literal>M-x woman <RET> nixos-rebuild - <RET>.</literal> + You can use <function>woman</function> to get completion of all available man pages. For example, type <literal>M-x woman <RET> nixos-rebuild <RET>.</literal> </para> </section> @@ -529,29 +422,17 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal <title>Editing DocBook 5 XML Documents</title> <para> - Emacs includes - <link - xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>, - a major-mode for validating and editing XML documents. When editing DocBook - 5.0 documents, such as <link linkend="book-nixos-manual">this one</link>, - nXML needs to be configured with the relevant schema, which is not - included. + Emacs includes <link + xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>, a major-mode for validating and editing XML documents. When editing DocBook 5.0 documents, such as <link linkend="book-nixos-manual">this one</link>, nXML needs to be configured with the relevant schema, which is not included. </para> <para> - To install the DocBook 5.0 schemas, either add - <varname>pkgs.docbook5</varname> to - <xref linkend="opt-environment.systemPackages"/> - (<link - linkend="sec-declarative-package-mgmt">NixOS</link>), or run - <literal>nix-env -f '<nixpkgs>' -iA docbook5</literal> - (<link linkend="sec-ad-hoc-packages">Nix</link>). + To install the DocBook 5.0 schemas, either add <varname>pkgs.docbook5</varname> to <xref linkend="opt-environment.systemPackages"/> (<link + linkend="sec-declarative-package-mgmt">NixOS</link>), or run <literal>nix-env -f '<nixpkgs>' -iA docbook5</literal> (<link linkend="sec-ad-hoc-packages">Nix</link>). </para> <para> - Then customize the variable <varname>rng-schema-locating-files</varname> to - include <filename>~/.emacs.d/schemas.xml</filename> and put the following - text into that file: + Then customize the variable <varname>rng-schema-locating-files</varname> to include <filename>~/.emacs.d/schemas.xml</filename> and put the following text into that file: <example xml:id="ex-emacs-docbook-xml"> <title>nXML Schema Configuration (<filename>~/.emacs.d/schemas.xml</filename>)</title> <programlisting language="xml"><![CDATA[ |