[BK-2020-03.git] / config-shared / emacs / INSTRUCTIONS.md

<!DOCTYPE html>
<meta charset="utf-8">

# Setup Instructions for `emacs`

Created by [Steven Baltakatei Sandoval][bktei_2020_homepage] on 2020-04-16T23:13Z under a [CC BY-SA 4.0][cc_20131125_bysa] license and last updated on 2020-04-17T02:58Z.

## 1. Summary

Emacs is a command line editor. This document contains instructions and files required to install and customize Emacs on GNU/Linux Debian 10 machines.

### 1.1. File list

    ./config-shared/emacs/INSTRUCTIONS.md    # These setup instructions
	./config-shared/emacs/home/.emacs.d/init.el    # enables MELPA repository
	./config-shared/emacs/home/.config/systemd/user/emacs.service    # required for automatic daemon startup
	./config-shared/emacs/home/.bash_aliases.appendme    # contains alias for use with emacs daemon
	
## 2. Instructions

### 2.1. Install `emacs` package

#### 2.1.a. Typical Debian install

Use `$ sudo apt-get install emacs` to install `emacs`.

#### 2.1.b. Headless Debian install (no GUI)

Use `$ sudo apt-get install emacs-nox` to install `emacs` without an X window manager. This may be useful if emacs is to be used via command-line only such as a machine without a monitor to which a use connects via `ssh`.

### 2.2. Enable MELPA package repository

MELPA is a package repository for packages that add functionality to `emacs`. Detailed instructions for installing it may be found at melpa.org.<sup>[[1]](#melpa_2019_setupinst)</sup>

#### 2.2.a. Typical install

Create and/or edit the `~/.emacs.d/init.el` file to include the following text elisp code:

	(require 'package)
	(let* ((no-ssl (and (memq system-type '(windows-nt ms-dos))
						(not (gnutls-available-p))))
		   (proto (if no-ssl "http" "https")))
	  (when no-ssl (warn "\
	Your version of Emacs does not support SSL connections,
	which is unsafe because it allows man-in-the-middle attacks.
	There are two things you can do about this warning:
	1. Install an Emacs version that does support SSL and be safe.
	2. Remove this warning from your init file so you won't see it again."))
	  (add-to-list 'package-archives (cons "melpa" (concat proto "://melpa.org/packages/")) t)
	  ;; Comment/uncomment this line to enable MELPA Stable if desired.  See `package-archive-priorities`
	  ;; and `package-pinned-packages`. Most users will not need or want to do this.
	  ;;(add-to-list 'package-archives (cons "melpa-stable" (concat proto "://stable.melpa.org/packages/")) t)
	  )
	(package-initialize)

A copy of this text is contained within the `./config-shared/emacs/home/.emacs.d/init.el` file in this repository. A command to copy this code to a completely new system is below.

    $ mkdir ~/.emacs.d
    $ cp ./config-shared/emacs/home/.emacs.d/init.el ~/.emacs.d/init.el

Run `M-x package-refresh-contents` (can be run from bash via `$ emacs -nw --eval '(progn (package-refresh-contents) (kill-emacs))'`) to download MELPA package list.<sup>[[2]](#se_20161221_emacsclimultieval)</sup>

### 2.3. Configure `emacs` daemon and `emacsclient`

A convenient way to share buffers between different shells (ex: across guake and Terminal) is to edit files using multiple instances of `emacsclient`<sup>[[4]](#emacswiki_20200325_emacsclient)</sup> which each communicate with a single instance of `emacs --daemon`<sup>[[3]](#emacswiki_20200408_emacsdaemon)</sup>. An instance of `emacsclient` running in `guake` may crash due to a problem with `guake` but the text buffer being edited by the user will not be lost since it is maintained by `emacs --daemon`. To regain access to the buffer, one must only start another instance of `emacsclient` and switch to the buffer (ex: via `C-x b`).

#### 2.3.a. Create `emacs` daemon as a user service.

Create the `~/.config/systemd/user/emacs.service` file to be the following text:

	[Unit]
	Description=Emacs text editor
	Documentation=info:emacs man:emacs(1) https://gnu.org/software/emacs/

	[Service]
	Type=forking
	ExecStart=/usr/bin/emacs --daemon
	ExecStop=/usr/bin/emacsclient --eval "(kill-emacs)"
	Encopy itvironment=SSH_AUTH_SOCK=%t/keyring/ssh
	Restart=on-failure

	[Install]
	WantedBy=default.target

This text is contained in this repository directory as `./config-shared/emacs/home/.config/systemd/user/emacs.service`. This file may be installed using the following command.

    $ cp ./config-shared/emacs/home/.config/systemd/user/emacs.service ~/.config/systemd/user/emacs.service

Enable and start this service by running the following commands.

    systemctl enable --user emacs
	systemctl start --user emacs
	
Successful running of this command should produce something like the following messages:

    Created symlink /home/baltakatei/.config/systemd/user/default.target.wants/emacs.service → /home/baltakatei/.config/systemd/user/emacs.service.
	
A new process named `/usr/bin/emacs --daemon` should appear in `$ ps -aux | grep emacs` output. This process should appear automatically upon login.

In order to use the daemon to edit a text file in the command line, the following command should be used.

    $ emacsclient -nw 

#### 2.3.b. Create `emacsclient` alias.

Typing `emacsclient` instead of just `emacs` is inconvenient. Therefore, it's recommended to make an alias.

##### 2.3.b.i. `bash` alias

If `bash` is your primary shell, then the alias can be included in the `~/.bash_aliases` file. The alias can be included by appending the `./config-shared/emacs/home/.bash_aliases.appendme` text file in this repository directory to the `~/.bash_aliases` file in the home directory. The following command may be used to to perform this append operation.

    $ cat ./config-shared/emacs/home/.bash_aliases.appendme >> ~/.bash_aliases

The relevant portion of the `./config-shared/emacs/home/.bash_aliases.appendme` file is below.

    alias emacs='emacsclient -create-frame --alternate-editor=""'

In order to see the alias changes, either logout and restart your shell or run `$ source ~/.bash_aliases`.

## 3. Conclusion.

Emacs should now be configured to run automatically in the background as a daemon upon login.

## 4. References

- <a name="melpa_2019_setupinst">1.</a> ["Getting started"][1]. https://melpa.org . Access date: 2020-04-17. [Archive link](https://web.archive.org/web/20200325114522/https://melpa.org/#/getting-started). Archive date: 2020-03-25.
- <a name="se_20161221_emacsclimultieval">2.</a> ["emacs --eval of multiple functions on command line"][2]. Stack Exchange. Access date: 2020-04-17. [Archive link](https://web.archive.org/web/20200417002001/https://emacs.stackexchange.com/questions/29465/emacs-eval-of-multiple-functions-on-command-line/29467)
- <a name="emacswiki_20200408_emacsdaemon">3.</a> ["Emacs As Daemon"][3]. EmacsWiki. Access date: 2020-04-17. License: GPLv2. [Archive link](https://web.archive.org/web/20200303223315/https://www.emacswiki.org/emacs/EmacsAsDaemon). Archive date: 2020-03-03.
- <a name="emacswiki_20200325_emacsclient">4.</a> ["Emacs Client"][4]. EmacsWiki. Access date: 2020-04-17. License: GPLv2. [Archive link](https://web.archive.org/web/20190804144010/https://www.emacswiki.org/emacs/EmacsClient). Archive date: 2019-08-04.


[1]: https://melpa.org/#/getting-started
[2]: https://emacs.stackexchange.com/a/29467
[3]: https://www.emacswiki.org/emacs/EmacsAsDaemon
[4]: https://www.emacswiki.org/emacs/EmacsClient
[bktei_2020_homepage]: http://baltakatei.com
[cc_20131125_bysa]: http://creativecommons.org/licenses/by-sa/4.0/


<hr>
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:cc="http://creativecommons.org/ns#">This work by <a rel="cc:attributionURL"  href="http://baltakatei.com"><span rel="cc:attributionName">Steven Baltakatei Sandoval</span></a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=ccchooser" target="_blank" rel="license noopener noreferrer" style="display: inline-block;">CC BY-SA 4.0</a><a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=ccchooser"><img style="height:22px!important;margin-left: 3px;vertical-align:text-bottom;opacity:0.7;" src="https://search.creativecommons.org/static/img/cc_icon.svg" /><img  style="height:22px!important;margin-left: 3px;vertical-align:text-bottom;opacity:0.7;" src="https://search.creativecommons.org/static/img/cc-by_icon.svg" /><img  style="height:22px!important;margin-left: 3px;vertical-align:text-bottom;opacity:0.7;" src="https://search.creativecommons.org/static/img/cc-sa_icon.svg" /></a></p>
Commit	Line	Data
1556783e SBS	1	<!DOCTYPE html>
	2	<meta charset="utf-8">
	3
	4	# Setup Instructions for `emacs`
	5
87473383	6	Created by [Steven Baltakatei Sandoval][bktei_2020_homepage] on 2020-04-16T23:13Z under a [CC BY-SA 4.0][cc_20131125_bysa] license and last updated on 2020-04-17T02:58Z.
1556783e SBS	7
	8	## 1. Summary
	9
	10	Emacs is a command line editor. This document contains instructions and files required to install and customize Emacs on GNU/Linux Debian 10 machines.
	11
	12	### 1.1. File list
	13
3a6c0037	14	./config-shared/emacs/INSTRUCTIONS.md # These setup instructions
1556783e SBS	15	./config-shared/emacs/home/.emacs.d/init.el # enables MELPA repository
	16	./config-shared/emacs/home/.config/systemd/user/emacs.service # required for automatic daemon startup
	17	./config-shared/emacs/home/.bash_aliases.appendme # contains alias for use with emacs daemon
	18
	19	## 2. Instructions
	20
	21	### 2.1. Install `emacs` package
	22
	23	#### 2.1.a. Typical Debian install
	24
	25	Use `$ sudo apt-get install emacs` to install `emacs`.
	26
	27	#### 2.1.b. Headless Debian install (no GUI)
	28
	29	Use `$ sudo apt-get install emacs-nox` to install `emacs` without an X window manager. This may be useful if emacs is to be used via command-line only such as a machine without a monitor to which a use connects via `ssh`.
	30
	31	### 2.2. Enable MELPA package repository
	32
	33	MELPA is a package repository for packages that add functionality to `emacs`. Detailed instructions for installing it may be found at melpa.org.<sup>[[1]](#melpa_2019_setupinst)</sup>
	34
	35	#### 2.2.a. Typical install
	36
	37	Create and/or edit the `~/.emacs.d/init.el` file to include the following text elisp code:
	38
	39	(require 'package)
	40	(let* ((no-ssl (and (memq system-type '(windows-nt ms-dos))
	41	(not (gnutls-available-p))))
	42	(proto (if no-ssl "http" "https")))
	43	(when no-ssl (warn "\
	44	Your version of Emacs does not support SSL connections,
	45	which is unsafe because it allows man-in-the-middle attacks.
	46	There are two things you can do about this warning:
	47	1. Install an Emacs version that does support SSL and be safe.
	48	2. Remove this warning from your init file so you won't see it again."))
	49	(add-to-list 'package-archives (cons "melpa" (concat proto "://melpa.org/packages/")) t)
	50	;; Comment/uncomment this line to enable MELPA Stable if desired. See `package-archive-priorities`
	51	;; and `package-pinned-packages`. Most users will not need or want to do this.
	52	;;(add-to-list 'package-archives (cons "melpa-stable" (concat proto "://stable.melpa.org/packages/")) t)
	53	)
	54	(package-initialize)
	55
	56	A copy of this text is contained within the `./config-shared/emacs/home/.emacs.d/init.el` file in this repository. A command to copy this code to a completely new system is below.
	57
	58	$ mkdir ~/.emacs.d
	59	$ cp ./config-shared/emacs/home/.emacs.d/init.el ~/.emacs.d/init.el
	60
	61	Run `M-x package-refresh-contents` (can be run from bash via `$ emacs -nw --eval '(progn (package-refresh-contents) (kill-emacs))'`) to download MELPA package list.<sup>[[2]](#se_20161221_emacsclimultieval)</sup>
	62
	63	### 2.3. Configure `emacs` daemon and `emacsclient`
	64
	65	A convenient way to share buffers between different shells (ex: across guake and Terminal) is to edit files using multiple instances of `emacsclient`<sup>[[4]](#emacswiki_20200325_emacsclient)</sup> which each communicate with a single instance of `emacs --daemon`<sup>[[3]](#emacswiki_20200408_emacsdaemon)</sup>. An instance of `emacsclient` running in `guake` may crash due to a problem with `guake` but the text buffer being edited by the user will not be lost since it is maintained by `emacs --daemon`. To regain access to the buffer, one must only start another instance of `emacsclient` and switch to the buffer (ex: via `C-x b`).
	66
	67	#### 2.3.a. Create `emacs` daemon as a user service.
	68
	69	Create the `~/.config/systemd/user/emacs.service` file to be the following text:
	70
	71	[Unit]
	72	Description=Emacs text editor
	73	Documentation=info:emacs man:emacs(1) https://gnu.org/software/emacs/
	74
	75	[Service]
	76	Type=forking
	77	ExecStart=/usr/bin/emacs --daemon
	78	ExecStop=/usr/bin/emacsclient --eval "(kill-emacs)"
79	Encopy itvironment=SSH_AUTH_SOCK=%t/keyring/ssh
80	Restart=on-failure
81
82	[Install]
83	WantedBy=default.target
84
85	This text is contained in this repository directory as `./config-shared/emacs/home/.config/systemd/user/emacs.service`. This file may be installed using the following command.
86
87	$ cp ./config-shared/emacs/home/.config/systemd/user/emacs.service ~/.config/systemd/user/emacs.service
88
89	Enable and start this service by running the following commands.
90
91	systemctl enable --user emacs
92	systemctl start --user emacs
93
94	Successful running of this command should produce something like the following messages:
95
96	Created symlink /home/baltakatei/.config/systemd/user/default.target.wants/emacs.service → /home/baltakatei/.config/systemd/user/emacs.service.
97
98	A new process named `/usr/bin/emacs --daemon` should appear in `$ ps -aux \| grep emacs` output. This process should appear automatically upon login.
99
100	In order to use the daemon to edit a text file in the command line, the following command should be used.
101
102	$ emacsclient -nw
103
104	#### 2.3.b. Create `emacsclient` alias.
105
106	Typing `emacsclient` instead of just `emacs` is inconvenient. Therefore, it's recommended to make an alias.
107
108	##### 2.3.b.i. `bash` alias
109
110	If `bash` is your primary shell, then the alias can be included in the `~/.bash_aliases` file. The alias can be included by appending the `./config-shared/emacs/home/.bash_aliases.appendme` text file in this repository directory to the `~/.bash_aliases` file in the home directory. The following command may be used to to perform this append operation.
111
112	$ cat ./config-shared/emacs/home/.bash_aliases.appendme >> ~/.bash_aliases
113
114	The relevant portion of the `./config-shared/emacs/home/.bash_aliases.appendme` file is below.
115
116	alias emacs='emacsclient -create-frame --alternate-editor=""'
117
87473383 SBS	118	In order to see the alias changes, either logout and restart your shell or run `$ source ~/.bash_aliases`.
87473383 SBS	119
1556783e SBS	120	## 3. Conclusion.
	121
	122	Emacs should now be configured to run automatically in the background as a daemon upon login.
	123
	124	## 4. References
	125
	126	- <a name="melpa_2019_setupinst">1.</a> ["Getting started"][1]. https://melpa.org . Access date: 2020-04-17. [Archive link](https://web.archive.org/web/20200325114522/https://melpa.org/#/getting-started). Archive date: 2020-03-25.
	127	- <a name="se_20161221_emacsclimultieval">2.</a> ["emacs --eval of multiple functions on command line"][2]. Stack Exchange. Access date: 2020-04-17. [Archive link](https://web.archive.org/web/20200417002001/https://emacs.stackexchange.com/questions/29465/emacs-eval-of-multiple-functions-on-command-line/29467)
	128	- <a name="emacswiki_20200408_emacsdaemon">3.</a> ["Emacs As Daemon"][3]. EmacsWiki. Access date: 2020-04-17. License: GPLv2. [Archive link](https://web.archive.org/web/20200303223315/https://www.emacswiki.org/emacs/EmacsAsDaemon). Archive date: 2020-03-03.
	129	- <a name="emacswiki_20200325_emacsclient">4.</a> ["Emacs Client"][4]. EmacsWiki. Access date: 2020-04-17. License: GPLv2. [Archive link](https://web.archive.org/web/20190804144010/https://www.emacswiki.org/emacs/EmacsClient). Archive date: 2019-08-04.
	130
	131
	132	[1]: https://melpa.org/#/getting-started
	133	[2]: https://emacs.stackexchange.com/a/29467
	134	[3]: https://www.emacswiki.org/emacs/EmacsAsDaemon
	135	[4]: https://www.emacswiki.org/emacs/EmacsClient
	136	[bktei_2020_homepage]: http://baltakatei.com
	137	[cc_20131125_bysa]: http://creativecommons.org/licenses/by-sa/4.0/
	138
	139
	140	<hr>
	141	<p xmlns:dct="http://purl.org/dc/terms/" xmlns:cc="http://creativecommons.org/ns#">This work by <a rel="cc:attributionURL" href="http://baltakatei.com"><span rel="cc:attributionName">Steven Baltakatei Sandoval</span></a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=ccchooser" target="_blank" rel="license noopener noreferrer" style="display: inline-block;">CC BY-SA 4.0</a><a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=ccchooser"><img style="height:22px!important;margin-left: 3px;vertical-align:text-bottom;opacity:0.7;" src="https://search.creativecommons.org/static/img/cc_icon.svg" /><img style="height:22px!important;margin-left: 3px;vertical-align:text-bottom;opacity:0.7;" src="https://search.creativecommons.org/static/img/cc-by_icon.svg" /><img style="height:22px!important;margin-left: 3px;vertical-align:text-bottom;opacity:0.7;" src="https://search.creativecommons.org/static/img/cc-sa_icon.svg" /></a></p>