diff options
Diffstat (limited to 'nixos/modules/services/editors/emacs.xml')
| -rw-r--r-- | nixos/modules/services/editors/emacs.xml | 912 |
1 files changed, 411 insertions, 501 deletions
diff --git a/nixos/modules/services/editors/emacs.xml b/nixos/modules/services/editors/emacs.xml index fd99ee9442c9..37d7a93a12b3 100644 --- a/nixos/modules/services/editors/emacs.xml +++ b/nixos/modules/services/editors/emacs.xml @@ -1,143 +1,121 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="module-services-emacs"> - <title>Emacs</title> -<!-- - Documentation contributors: - Damien Cassou @DamienCassou - Thomas Tuegel @ttuegel - Rodney Lorrimar @rvl - 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. - </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. - </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. - </para> - <section xml:id="module-services-emacs-installing"> - <title>Installing <application>Emacs</application></title> - +<!-- Do not edit this file directly, edit its companion .md instead + and regenerate this file using nixos/doc/manual/md-to-db.sh --> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-emacs"> + <title>Emacs</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. + <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> - - <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: - <variablelist> - <varlistentry> - <term> - <varname>emacs</varname> - </term> - <term> - <varname>emacs</varname> - </term> - <listitem> - <para> - The latest stable version of Emacs using the - <link - xlink:href="http://www.gtk.org">GTK 2</link> - widget toolkit. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <varname>emacs-nox</varname> - </term> - <listitem> - <para> - Emacs built without any dependency on X11 libraries. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <varname>emacsMacport</varname> - </term> - <term> - <varname>emacsMacport</varname> - </term> - <listitem> - <para> - Emacs with the "Mac port" patches, providing a more native look and - feel under macOS. - </para> - </listitem> - </varlistentry> - </variablelist> - </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>. - </para> - </section> - - <section xml:id="module-services-emacs-adding-packages"> - <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. - </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. - </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. - </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: - <example xml:id="ex-emacsNix"> - <title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title> -<programlisting language="nix"> + <para> + Emacs runs within a graphical desktop environment using the X Window + System, but works equally well on a text terminal. Under macOS, a + <quote>Mac port</quote> edition is available, which uses Apple’s + native GUI frameworks. + </para> + <para> + Nixpkgs provides a superior environment for running Emacs. 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. NixOS even + provides a <command>systemd</command> user service for automatically + starting the Emacs daemon. + </para> + <section xml:id="module-services-emacs-installing"> + <title>Installing Emacs</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. + </para> + <section xml:id="module-services-emacs-releases"> + <title>The Different Releases of Emacs</title> + <para> + Nixpkgs defines several basic Emacs packages. The following are + attributes belonging to the <varname>pkgs</varname> set: + </para> + <variablelist spacing="compact"> + <varlistentry> + <term> + <varname>emacs</varname> + </term> + <listitem> + <para> + The latest stable version of Emacs using the + <link xlink:href="http://www.gtk.org">GTK 2</link> widget + toolkit. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>emacs-nox</varname> + </term> + <listitem> + <para> + Emacs built without any dependency on X11 libraries. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>emacsMacport</varname> + </term> + <listitem> + <para> + Emacs with the <quote>Mac port</quote> patches, providing + a more native look and feel under macOS. + </para> + </listitem> + </varlistentry> + </variablelist> + <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>. + </para> + </section> + <section xml:id="module-services-emacs-adding-packages"> + <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. + </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 (ELPA)</link>, + <link xlink:href="https://melpa.org/">MELPA</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 + <literal>package-list-packages</literal> and + <literal>package-install</literal> 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: + </para> + <para> + <anchor xml:id="ex-emacsNix" /> + </para> + <programlisting language="nix"> /* This is a nix expression to build Emacs and some Emacs packages I like from source on any distribution where Nix is installed. This will install @@ -152,185 +130,142 @@ To run the newly compiled executable: $ ./result/bin/emacs */ -{ pkgs ? import <nixpkgs> {} }: <co xml:id="ex-emacsNix-1" /> + +# The first non-comment line in this file indicates that +# the whole file represents a function. +{ pkgs ? import <nixpkgs> {} }: let - myEmacs = pkgs.emacs; <co xml:id="ex-emacsNix-2" /> - emacsWithPackages = (pkgs.emacsPackagesFor myEmacs).emacsWithPackages; <co xml:id="ex-emacsNix-3" /> + # The let expression below defines a myEmacs 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. + myEmacs = pkgs.emacs; + # This generates an emacsWithPackages 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). + emacsWithPackages = (pkgs.emacsPackagesFor myEmacs).emacsWithPackages; in - emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ <co xml:id="ex-emacsNix-4" /> + # The rest of the file specifies the list of packages to install. In the + # example, two packages (magit and zerodark-theme) are taken from + # MELPA stable. + emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ magit # ; Integrate git <C-x g> zerodark-theme # ; Nicolas' theme - ]) ++ (with epkgs.melpaPackages; [ <co xml:id="ex-emacsNix-5" /> + ]) + # Two packages (undo-tree and zoom-frm) are taken from MELPA. + ++ (with epkgs.melpaPackages; [ undo-tree # ; <C-x u> to show the undo tree zoom-frm # ; increase/decrease font size for all buffers %lt;C-x C-+> - ]) ++ (with epkgs.elpaPackages; [ <co xml:id="ex-emacsNix-6" /> + ]) + # Three packages are taken from GNU ELPA. + ++ (with epkgs.elpaPackages; [ auctex # ; LaTeX mode beacon # ; highlight my cursor when scrolling nameless # ; hide current package name everywhere in elisp code - ]) ++ [ - pkgs.notmuch # From main packages set <co xml:id="ex-emacsNix-7" /> + ]) + # notmuch is taken from a nixpkgs derivation which contains an Emacs mode. + ++ [ + pkgs.notmuch # From main packages set ]) </programlisting> - </example> - <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. - </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 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> - </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). + You can check that it works by executing this in a terminal: </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. - </para> - </callout> - <callout arearefs="ex-emacsNix-5"> + <programlisting> +$ nix-build emacs.nix +$ ./result/bin/emacs -q +</programlisting> <para> - Two packages (<varname>undo-tree</varname> and - <varname>zoom-frm</varname>) are taken from MELPA. + 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> - </callout> - <callout arearefs="ex-emacsNix-6"> + <tip> + <para> + A few popular extensions worth checking out are: auctex, + company, edit-server, flycheck, helm, iedit, magit, + multiple-cursors, projectile, and yasnippet. + </para> + </tip> <para> - Three packages are taken from GNU ELPA. + The list of available packages in the various ELPA repositories + can be seen with the following commands: + <anchor xml:id="module-services-emacs-querying-packages" /> </para> - </callout> - <callout arearefs="ex-emacsNix-7"> + <programlisting> +nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.elpaPackages +nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaPackages +nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaStablePackages +nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.orgPackages +</programlisting> <para> - <varname>notmuch</varname> is taken from a nixpkgs derivation which - contains an Emacs mode. + 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: + <anchor xml:id="module-services-emacs-configuration-nix" /> </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>. - </para> - - <para> - You can check that it works by executing this in a terminal: -<screen> -<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>. - </para> - - <tip> - <para> - 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: - <example xml:id="module-services-emacs-querying-packages"> - <title>Querying Emacs packages</title> -<programlisting><![CDATA[ -nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.elpaPackages -nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaPackages -nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaStablePackages -nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.orgPackages -]]></programlisting> - </example> - </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: - <example xml:id="module-services-emacs-configuration-nix"> - <title>Custom Emacs in <filename>configuration.nix</filename></title> -<programlisting><![CDATA[ + <programlisting> { environment.systemPackages = [ # [...] (import /path/to/emacs.nix { inherit pkgs; }) ]; } -]]></programlisting> - </example> - </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" />). - </para> - -<!-- fixme: i think the following is better done with config.nix -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="https://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[ +</programlisting> + <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" />). + </para> + <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="https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs + manual</link>): + <anchor xml:id="module-services-emacs-config-nix" /> + </para> + <programlisting> { packageOverrides = super: let self = super.pkgs; in { myemacs = import /path/to/emacs.nix { pkgs = self; }; }; } -]]></programlisting> - </example> - </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. - </para> - </section> - - <section xml:id="module-services-emacs-advanced"> - <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 if you - only use <command>emacsclient</command>), you can change your file - <filename>emacs.nix</filename> in this way: - </para> - - <example xml:id="ex-emacsGtk3Nix"> - <title>Custom Emacs build</title> -<programlisting><![CDATA[ -{ pkgs ? import <nixpkgs> {} }: +</programlisting> + <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. + </para> + </section> + <section xml:id="module-services-emacs-advanced"> + <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 if you only use + <command>emacsclient</command>), you can change your file + <filename>emacs.nix</filename> in this way: + </para> + <para> + <anchor xml:id="ex-emacsGtk3Nix" /> + </para> + <programlisting> +{ pkgs ? import <nixpkgs> {} }: let myEmacs = (pkgs.emacs.override { # Use gtk3 instead of the default gtk2 @@ -339,149 +274,143 @@ let }).overrideAttrs (attrs: { # I don't want emacs.desktop file because I only use # emacsclient. - postInstall = (attrs.postInstall or "") + '' + postInstall = (attrs.postInstall or "") + '' rm $out/share/applications/emacs.desktop ''; }); in [...] -]]></programlisting> - </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. - </para> - </section> - </section> - <section xml:id="module-services-emacs-running"> - <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. - </para> - - <para> - <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>: -<programlisting> -<xref linkend="opt-services.emacs.enable"/> = true; -<xref linkend="opt-services.emacs.package"/> = import /home/cassou/.emacs.d { pkgs = pkgs; }; </programlisting> - </para> - - <para> - 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>. - </para> - - <para> - To start the daemon, execute the following: -<screen> -<prompt>$ </prompt>nixos-rebuild switch # to activate the new configuration.nix -<prompt>$ </prompt>systemctl --user daemon-reload # to force systemd reload -<prompt>$ </prompt>systemctl --user start emacs.service # to start the Emacs daemon -</screen> - The server should now be ready to serve Emacs clients. - </para> + <para> + After building this file as shown in + <link linkend="ex-emacsNix">the example above</link>, you will + get an GTK 3-based Emacs binary pre-loaded with your favorite + packages. + </para> + </section> </section> - - <section xml:id="module-services-emacs-starting-client"> - <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>. - </para> - - <para> - To connect to the emacs daemon, run one of the following: -<programlisting><![CDATA[ + <section xml:id="module-services-emacs-running"> + <title>Running Emacs as a Service</title> + <para> + NixOS 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> + </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>: + </para> + <programlisting> +services.emacs.enable = true; +services.emacs.package = import /home/cassou/.emacs.d { pkgs = pkgs; }; +</programlisting> + <para> + The <varname>services.emacs.package</varname> option allows a + custom derivation to be used, for example, one created by + <literal>emacsWithPackages</literal>. + </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>. + </para> + <para> + To start the daemon, execute the following: + </para> + <programlisting> +$ nixos-rebuild switch # to activate the new configuration.nix +$ systemctl --user daemon-reload # to force systemd reload +$ systemctl --user start emacs.service # to start the Emacs daemon +</programlisting> + <para> + The server should now be ready to serve Emacs clients. + </para> + </section> + <section xml:id="module-services-emacs-starting-client"> + <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>. + </para> + <para> + To connect to the emacs daemon, run one of the following: + </para> + <programlisting> emacsclient FILENAME emacsclient --create-frame # opens a new frame (window) emacsclient --create-frame --tty # opens a new frame on the current terminal -]]></programlisting> - </para> - </section> - - <section xml:id="module-services-emacs-editor-variable"> - <title>Configuring the <varname>EDITOR</varname> variable</title> - -<!--<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>. - </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. - </para> - - <para> - 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> - - <section xml:id="module-services-emacs-per-user"> - <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: -<programlisting> -<xref linkend="opt-services.emacs.enable"/> = false; -<xref linkend="opt-services.emacs.install"/> = true; </programlisting> - </para> - - <para> - 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>. - </para> + </section> + <section xml:id="module-services-emacs-editor-variable"> + <title>Configuring the <varname>EDITOR</varname> variable</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>. + </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. + </para> + <para> + If you have formed certain bad habits when editing files, these + can be corrected with a shell alias to the wrapper script: + </para> + <programlisting> +alias vi=$EDITOR +</programlisting> + </section> + <section xml:id="module-services-emacs-per-user"> + <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: + </para> + <programlisting> +services.emacs.enable = false; +services.emacs.install = true; +</programlisting> + <para> + To enable the <command>systemd</command> user service for just + the currently logged in user, run: + </para> + <programlisting> +systemctl --user enable emacs +</programlisting> + <para> + This will add the symlink + <filename>~/.config/systemd/user/emacs.service</filename>. + </para> + </section> </section> - </section> - <section xml:id="module-services-emacs-configuring"> - <title>Configuring Emacs</title> - - <para> - 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[ + <section xml:id="module-services-emacs-configuring"> + <title>Configuring Emacs</title> + <para> + The Emacs init file should be changed to load the extension + packages at startup: + <anchor xml:id="module-services-emacs-package-initialisation" /> + </para> + <programlisting> (require 'package) ;; optional. makes unpure packages archives unavailable @@ -489,92 +418,73 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal (setq package-enable-at-startup nil) (package-initialize) -]]></programlisting> - </example> - </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). - </para> - -<!-- - todo: is it worth documenting customizations for |