git.iko.soy/typeable/nixpkgs
on master help sign in
Convert Emacs documentation from XML DocBook to CommonMark
commit19973c1893837684ae228ac4f8106ad66e5ba34d authorAndersonTorres <torres.anderson.85@protonmail.com> dateSat 28 Nov 2020, 20:49 (6 years ago) parentb69c703
3 files changed+120−132
doc/builders/packages/emacs.section.md+119 doc/builders/packages/emacs.xml−131 doc/builders/packages/index.xml+1−1
doc/builders/packages/emacs.section.mdnew file+119
@@ -0,0 +1,119 @@
1+# Emacs {#sec-emacs}
2+
3+## Configuring Emacs
4+
5+The Emacs package comes with some extra helpers to make it easier to configure. `emacsWithPackages` 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:
6+
7+```nix
8+{
9+ packageOverrides = pkgs: with pkgs; {
10+ myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
11+ company
12+ counsel
13+ flycheck
14+ ivy
15+ magit
16+ projectile
17+ use-package
18+ ]));
19+ }
20+}
21+```
22+
23+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 provide a `default.el` file in `/share/emacs/site-start/`. Emacs knows to load this file automatically when it starts.
24+
25+```nix
26+{
27+ packageOverrides = pkgs: with pkgs; rec {
28+ myEmacsConfig = writeText "default.el" ''
29+ ;; initialize package
30+
31+ (require 'package)
32+ (package-initialize 'noactivate)
33+ (eval-when-compile
34+ (require 'use-package))
35+
36+ ;; load some packages
37+
38+ (use-package company
39+ :bind ("&lt;C-tab&gt;" . company-complete)
40+ :diminish company-mode
41+ :commands (company-mode global-company-mode)
42+ :defer 1
43+ :config
44+ (global-company-mode))
45+
46+ (use-package counsel
47+ :commands (counsel-descbinds)
48+ :bind (([remap execute-extended-command] . counsel-M-x)
49+ ("C-x C-f" . counsel-find-file)
50+ ("C-c g" . counsel-git)
51+ ("C-c j" . counsel-git-grep)
52+ ("C-c k" . counsel-ag)
53+ ("C-x l" . counsel-locate)
54+ ("M-y" . counsel-yank-pop)))
55+
56+ (use-package flycheck
57+ :defer 2
58+ :config (global-flycheck-mode))
59+
60+ (use-package ivy
61+ :defer 1
62+ :bind (("C-c C-r" . ivy-resume)
63+ ("C-x C-b" . ivy-switch-buffer)
64+ :map ivy-minibuffer-map
65+ ("C-j" . ivy-call))
66+ :diminish ivy-mode
67+ :commands ivy-mode
68+ :config
69+ (ivy-mode 1))
70+
71+ (use-package magit
72+ :defer
73+ :if (executable-find "git")
74+ :bind (("C-x g" . magit-status)
75+ ("C-x G" . magit-dispatch-popup))
76+ :init
77+ (setq magit-completing-read-function 'ivy-completing-read))
78+
79+ (use-package projectile
80+ :commands projectile-mode
81+ :bind-keymap ("C-c p" . projectile-command-map)
82+ :defer 5
83+ :config
84+ (projectile-global-mode))
85+ '';
86+
87+ myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
88+ (runCommand "default.el" {} ''
89+ mkdir -p $out/share/emacs/site-lisp
90+ cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
91+ '')
92+ company
93+ counsel
94+ flycheck
95+ ivy
96+ magit
97+ projectile
98+ use-package
99+ ]));
100+ };
101+}
102+```
103+
104+This provides a fairly full Emacs start file. It will load in addition to the user's presonal config. You can always disable it by passing `-q` to the Emacs command.
105+
106+Sometimes `emacsWithPackages` is not enough, as this package set has some priorities imposed on packages (with the lowest priority assigned to Melpa Unstable, and the highest for packages manually defined in `pkgs/top-level/emacs-packages.nix`). But you can't control this priorities when some package is installed as a dependency. You can override it on 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'`.
107+
108+```nix
109+overrides = self: super: rec {
110+ haskell-mode = self.melpaPackages.haskell-mode;
111+ ...
112+};
113+((emacsPackagesGen emacs).overrideScope' overrides).emacsWithPackages
114+ (p: with p; [
115+ # here both these package will use haskell-mode of our own choice
116+ ghc-mod
117+ dante
118+ ])
119+```
doc/builders/packages/emacs.xmldeleted−131
@@ -1,131 +0,0 @@
1−<section xmlns="http://docbook.org/ns/docbook"
2− xmlns:xlink="http://www.w3.org/1999/xlink"
3− xml:id="sec-emacs">
4− <title>Emacs</title>
5−
6− <section xml:id="sec-emacs-config">
7− <title>Configuring Emacs</title>
8−
9− <para>
10− The Emacs package comes with some extra helpers to make it easier to configure. <varname>emacsWithPackages</varname> 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 <literal>company</literal>, <literal>counsel</literal>, <literal>flycheck</literal>, <literal>ivy</literal>, <literal>magit</literal>, <literal>projectile</literal>, and <literal>use-package</literal> you could use this as a <filename>~/.config/nixpkgs/config.nix</filename> override:
11− </para>
12−
13−<screen>
14−{
15− packageOverrides = pkgs: with pkgs; {
16− myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
17− company
18− counsel
19− flycheck
20− ivy
21− magit
22− projectile
23− use-package
24− ]));
25− }
26−}
27−</screen>
28−
29− <para>
30− You can install it like any other packages via <command>nix-env -iA myEmacs</command>. However, this will only install those packages. It will not <literal>configure</literal> 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 provide a <filename>default.el</filename> file in <filename>/share/emacs/site-start/</filename>. Emacs knows to load this file automatically when it starts.
31− </para>
32−
33−<screen>
34−{
35− packageOverrides = pkgs: with pkgs; rec {
36− myEmacsConfig = writeText "default.el" ''
37−;; initialize package
38−
39−(require 'package)
40−(package-initialize 'noactivate)
41−(eval-when-compile
42− (require 'use-package))
43−
44−;; load some packages
45−
46−(use-package company
47− :bind ("&lt;C-tab&gt;" . company-complete)
48− :diminish company-mode
49− :commands (company-mode global-company-mode)
50− :defer 1
51− :config
52− (global-company-mode))
53−
54−(use-package counsel
55− :commands (counsel-descbinds)
56− :bind (([remap execute-extended-command] . counsel-M-x)
57− ("C-x C-f" . counsel-find-file)
58− ("C-c g" . counsel-git)
59− ("C-c j" . counsel-git-grep)
60− ("C-c k" . counsel-ag)
61− ("C-x l" . counsel-locate)
62− ("M-y" . counsel-yank-pop)))
63−
64−(use-package flycheck
65− :defer 2
66− :config (global-flycheck-mode))
67−
68−(use-package ivy
69− :defer 1
70− :bind (("C-c C-r" . ivy-resume)
71− ("C-x C-b" . ivy-switch-buffer)
72− :map ivy-minibuffer-map
73− ("C-j" . ivy-call))
74− :diminish ivy-mode
75− :commands ivy-mode
76− :config
77− (ivy-mode 1))
78−
79−(use-package magit
80− :defer
81− :if (executable-find "git")
82− :bind (("C-x g" . magit-status)
83− ("C-x G" . magit-dispatch-popup))
84− :init
85− (setq magit-completing-read-function 'ivy-completing-read))
86−
87−(use-package projectile
88− :commands projectile-mode
89− :bind-keymap ("C-c p" . projectile-command-map)
90− :defer 5
91− :config
92− (projectile-global-mode))
93− '';
94− myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
95− (runCommand "default.el" {} ''
96−mkdir -p $out/share/emacs/site-lisp
97−cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
98−'')
99− company
100− counsel
101− flycheck
102− ivy
103− magit
104− projectile
105− use-package
106− ]));
107− };
108−}
109−</screen>
110−
111− <para>
112− This provides a fairly full Emacs start file. It will load in addition to the user's presonal config. You can always disable it by passing <command>-q</command> to the Emacs command.
113− </para>
114−
115− <para>
116− Sometimes <varname>emacsWithPackages</varname> is not enough, as this package set has some priorities imposed on packages (with the lowest priority assigned to Melpa Unstable, and the highest for packages manually defined in <filename>pkgs/top-level/emacs-packages.nix</filename>). But you can't control this priorities when some package is installed as a dependency. You can override it on 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 <varname>overrideScope'</varname>.
117− </para>
118−
119−<screen>
120−overrides = self: super: rec {
121− haskell-mode = self.melpaPackages.haskell-mode;
122− ...
123−};
124−((emacsPackagesGen emacs).overrideScope' overrides).emacsWithPackages (p: with p; [
125− # here both these package will use haskell-mode of our own choice
126− ghc-mod
127− dante
128−])
129−</screen>
130− </section>
131−</section>
doc/builders/packages/index.xml+1−1
@@ -9,7 +9,7 @@
99 <xi:include href="dlib.xml" />
1010 <xi:include href="eclipse.xml" />
1111 <xi:include href="elm.xml" />
12− <xi:include href="emacs.xml" />
12+ <xi:include href="emacs.section.xml" />
1313 <xi:include href="ibus.xml" />
1414 <xi:include href="kakoune.xml" />
1515 <xi:include href="linux.xml" />