├── .gitignore ├── docs ├── images │ ├── apropos-which-key.png │ ├── elpa-package-list.png │ ├── emacs-start-screen.png │ └── which-key-mode-help.png ├── 04-using-documentation.md ├── 01-first-steps.md ├── 02-first-customizations.md └── 03-package-installation.md └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | *.backup 2 | -------------------------------------------------------------------------------- /docs/images/apropos-which-key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gsforza/emacs-the-adhd-way/HEAD/docs/images/apropos-which-key.png -------------------------------------------------------------------------------- /docs/images/elpa-package-list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gsforza/emacs-the-adhd-way/HEAD/docs/images/elpa-package-list.png -------------------------------------------------------------------------------- /docs/images/emacs-start-screen.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gsforza/emacs-the-adhd-way/HEAD/docs/images/emacs-start-screen.png -------------------------------------------------------------------------------- /docs/images/which-key-mode-help.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gsforza/emacs-the-adhd-way/HEAD/docs/images/which-key-mode-help.png -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Table of contents 2 | ================= 3 | 4 | - [Learn Emacs the ADHD way](#learn-emacs-the-adhd-way) 5 | - [The constraints](#the-constraints) 6 | - [Using the Pomodoro technique](#using-the-pomodoro-technique) 7 | - [The goal](#the-goal) 8 | - [Chapters](#chapters) 9 | - ![First steps](docs/01-first-steps.md) 10 | - ![First customizations](docs/02-first-customizations.md) 11 | - ![Package installation](docs/03-package-installation.md) 12 | - ![On using documentation](docs/04-using-documentation.md) 13 | - [Side note](#side-note) 14 | 15 | Learn Emacs the ADHD way 16 | ======================== 17 | 18 | As a long-time vim user I always fantasized about having one place to do 19 | all my usual computing, note taking, email and task management. So 20 | naturally I have always been intrigued by Emacs and its capabilities: 21 | Org, the possibility of configuring my editor with an actual - and sane - (programming) language - opposed to the abomination that is `Vim script` - the community, the trillions of packages, just to name a few. 22 | 23 | The things that always held me back were the completely different key 24 | bindings, the necessity of learning Lisp at some point and the time of 25 | not being productive while learning and researching all of the 26 | aforementioned things, but the biggest concern - the new keybinding - 27 | got completely blown off when I learned about `evil-mode`, which is kind 28 | of an emulation layer, giving one the possibility to use vim keybindings 29 | inside Emacs. 30 | 31 | This made the transition from Vim to Emacs a lot less daunting to me. I 32 | could just use Emacs, kind of, like the way I used Vim and could learn 33 | and customize Emacs along the way. \'Perfect\', I thought to myself, 34 | \'so now there is actually nothing holding me back anymore!\' Well, 35 | there **was** nothing, except **my ADHD kicking in**. 36 | 37 | I spent countless days reading about a million things I thought of being 38 | super nice having in my config. I over-engineered the smallest things, 39 | browsed through `init.el` after `init.el` on GitHub and always found a 40 | new package I wanted to try. Suffice to say, I never really got stuff 41 | done, being too busy configuring Emacs and planning how to be more 42 | productive with **this** package and supposedly making my workflow 43 | easier with **that** package - without ever really learning Emacs. 44 | 45 | So I had to come up with something, as always, to contain my ADHD - this 46 | is the case especially when trying to learn something new and shiny. 47 | After countless hours evaluating **this** idea and **that** procedure 48 | (you see the pattern here, right?), in the end I came up with the idea 49 | of starting this project - **Learn Emacs the ADHD way** - which is just 50 | a collection of rules I will lay onto myself to truly learn Emacs. Plus, 51 | me publicizing this hopefully makes me go through with this, regarding 52 | my never-ending love for attention. 53 | 54 | The constraints 55 | =============== 56 | 57 | - I will force myself to go step-by-step, loosely following the Emacs 58 | documentation 59 | - At first I will install no\* other package and evaluate every 60 | built-in functionality if it is enough for my use-case 61 | - I will not configure any other part of Emacs, may it be cosmetically 62 | or functionally 63 | - I will only research a part of Emacs when it is genuinely relevant 64 | to my workflow or when I am veritably encountering a problem or use 65 | case where the builtin feature is limiting me 66 | - I will time-constrain myself while researching and configuring; see 67 | below 68 | 69 | Using the Pomodoro technique 70 | ---------------------------- 71 | 72 | To hinder me of getting carried away - like so often - I will follow a 73 | strict rule: When I am researching something about Emacs, or some 74 | package I want to install, I will use the [Pomodoro 75 | technique](https://en.wikipedia.org/wiki/Pomodoro_Technique) to monitor 76 | myself. 77 | 78 | After finishing four \"pomodoros\" I will stop searching and use the 79 | best solution I have found up until the very moment the timer ends. If I 80 | still have the urge to look up **that one tiny last thing** (of course) 81 | I can do so in one of the breaks, but apart from that I will just go on 82 | with my life. 83 | 84 | The goal 85 | ======== 86 | 87 | Other than learning Emacs, I hope to learn coping with my ADHD and 88 | possibly encourage others - with or without the condition - to try this 89 | way of gradual and controlled learning. And, of course, I am hoping to 90 | spur some kind of discussion about learning, working and living with 91 | ADHD and all its aspects. 92 | 93 | Chapters 94 | ======== 95 | 96 | - ![First steps](docs/01-first-steps.md) 97 | - ![First customizations](docs/02-first-customizations.md) 98 | - ![Package installation](docs/03-package-installation.md) 99 | - ![On using documentation](docs/04-using-documentation.md) 100 | 101 | Side note 102 | ========= 103 | 104 | A small note about the format of this documentation: I will eventually 105 | write and structure all this inside an Org file, but to actually stay on 106 | track and not go down the first rabbit hole before really having started 107 | I am initially writing all this in a plain markdown file. 108 | -------------------------------------------------------------------------------- /docs/04-using-documentation.md: -------------------------------------------------------------------------------- 1 | Table of contents 2 | ================= 3 | 4 | - [On using documentation](#on-using-documentation) 5 | - [The builtin manual](#the-builtin-manual) 6 | - [Looking up variables, functions, symbols and much 7 | more](#looking-up-variables-functions-symbols-and-much-more) 8 | - [Apropos](#apropos) 9 | 10 | On using documentation 11 | ====================== 12 | 13 | Emacs calls itself an \'extensible, self-documenting\' editor. I guess 14 | at this point we figured out why it calls itself extensible but I did 15 | not talk that much about the \'self-documenting\' part. Shamefully so, 16 | because the documentation and manuals provided with, and even accessible 17 | from within, Emacs is really impressive. On top of that I think knowing 18 | how to read and use documentation is a key skill everyone should have. 19 | 20 | More that I am willing to admit I find myself looking things up via 21 | search engine and reading completely outdated information instead of 22 | just consulting the official documentation. I understand that sometimes 23 | the documentation is hard to search in but with Emacs this is not the 24 | case. 25 | 26 | The builtin manual 27 | ================== 28 | 29 | First off: All commands regarding any form of help have the prefix 30 | `C-h`. 31 | 32 | To show the builtin Emacs manual for your specific version, press 33 | `C-h r`. This is the same manual one would see when going to the [Emacs 34 | website](https://www.gnu.org/software/emacs/manual/html_mono/emacs.html). 35 | 36 | You can use normal Emacs movement key chords in here and press `RET` on 37 | a link (manual topic) to follow it. To get back to the parent topic you 38 | can press `o`. To go to the last shown page press `l`. 39 | 40 | But, of course, this is not the fancy \'self-documenting\' 41 | functionality I am talking about. There is so much more! 42 | 43 | Looking up variables, functions, symbols and much more 44 | ====================================================== 45 | 46 | When you are once again deep inside an `init.el` on GitHub and want to 47 | know what all these variables the creator of said config is using for 48 | customization, you can press `C-h v` to look up the definition of that 49 | variable, same for functions (`C-h f`) and symbols (`C-h S`). 50 | 51 | But again, there is more! Let\'s say you forgot what exactly a specific 52 | variable inside your config does, you can move to it and then press 53 | `C-h v`. Emacs will then suggest the variable under point. 54 | 55 | To see all possible things you can look up, press `C-h ?`. This will 56 | open a list of options in a new buffer. 57 | 58 | But to give you some example of what you can look up with these 59 | commands, I will provide more examples: 60 | 61 | When you know or heard about a specific command but don\'t know which 62 | key cord invokes it, you can simply use `C-h w` and Emacs will tell you. 63 | On the contrary, there is `C-h c` which shows you the command invoked by 64 | the given key sequence of which you get the full documentation of when 65 | using `C-h k`. 66 | 67 | If you want to know more about a specific package, is it builtin or 68 | external, you can search for it with `C-h i` which brings you to the 69 | documentation browser. In here you can find documentation on all the 70 | packages, Emacs basics, and much more. Also, whenever you install a 71 | package from `(M)ELPA` which brings a manual it places this manual 72 | inside a file called `dir`. The path to this file is then added to the 73 | variable `Info-directory-list`. The browser then adds all these `dir` 74 | files to the top of the info page. Sadly, it seems that only a small 75 | number of packages actually include a `dir` file. 76 | 77 | With `C-h m` you get the documentation of the current minor modes and 78 | major mode. This is really helpful, especially if you installed a 79 | package which does not provide a `dir` file like explained above. In 80 | here you can find out about all the key bindings inherent to the current 81 | major/minor mode(s). 82 | 83 | Apropos 84 | ======= 85 | 86 | But what if you don\'t actually know what you are looking for? What if 87 | you can only describe what you want? There is a command for that: 88 | `Apropos`. 89 | 90 | With `M-x apropos` you have a full-text search at your disposal to 91 | search for words, lists of words or even regular expressions. It will 92 | find any (interactive) function or variable matching your search query 93 | and will show you a list of all matches in a new buffer - which is in 94 | the `Apropos` major mode. 95 | 96 | You can use different variations of the apropos command to narrow the 97 | search. There are `apropos-command`, `apropos-documentation`, 98 | `apropos-mode`, `apropos-library` and a few others. 99 | 100 | To show off a bit what we have learned by now, let\'s assume we know 101 | there is a package that shows possible keys after typing a key chord, 102 | but we don\'t know what its name is. So we type 103 | `M-x apropos RET show key`. 104 | 105 | You will see something like that: 106 | 107 | ![Apropos buffer for which-key](images/apropos-which-key.png) 108 | 109 | Right, it\'s `which-key`! We found the package we were looking for 110 | without searching the internet and hoping to find the answer we were 111 | looking for in a 5 year old reddit thread or something (okay, in the 112 | case of `which-key` it would be not that hard, but still). 113 | 114 | Now, just out of curiosity let\'s see what we can do in the `Apropos` 115 | major mode. We learned that one can get info about the current modes by 116 | pressing `C-h m`. This will look something like that: 117 | 118 | ![Help buffer for which-key-mode](images/which-key-mode-help.png) 119 | 120 | Frankly, there is not that much we can do in here, but it also tells us 121 | that when starting the `Apropos` major mode, it runs the 122 | `apropos-mode-hook`. This makes it possible to activate specific minor 123 | modes or set a variable just in this mode. 124 | 125 | This might not be that helpful in `Apropos`, but there are also hooks 126 | for e.g. `prog-mode`, a specific mode that activates whenever Emacs 127 | opens a \'programming buffer\'. Here I for example start `hl-line-mode`, 128 | which highlights the current line and `display-line-numbers-mode`, which 129 | shows the current line number and all the other lines relatively to it. 130 | I also want Emacs to show matching parentheses when point is near it. I 131 | don\'t want these modes inside \'prose-writing buffer\', so I only 132 | activate it when I am coding. 133 | 134 | This is the code block I am using for that: 135 | 136 | (add-hook 'prog-mode-hook 137 | (lambda () 138 | (hl-line-mode t) 139 | (show-paren-mode 1) 140 | (setq display-line-numbers-type 'relative) 141 | (display-line-numbers-mode 1))) 142 | 143 | I know this derailed a bit, but I wanted to show you that when exploring 144 | something in Emacs you can find out about a totally different function 145 | or variable you did not know about before. And all this inside Emacs! 146 | You also think that\'s great, right? 147 | -------------------------------------------------------------------------------- /docs/01-first-steps.md: -------------------------------------------------------------------------------- 1 | Table of contents 2 | ================= 3 | 4 | - [Emacs tutorial](#emacs-tutorial) 5 | - [Basic movement](#basic-movement) 6 | - [Delete, kill, yank and mark](#delete-kill-yank-and-mark) 7 | - [Buffers](#buffers) 8 | - [eXtended commands](#extended-commands) 9 | - [Cancel a (running) command](#cancel-a-running-command) 10 | - [Mode line](#mode-line) 11 | - [Major modes](#major-modes) 12 | - [Minor modes](#minor-modes) 13 | - [Search](#search) 14 | - [(Multiple) windows](#multiple-windows) 15 | - [Side note](#side-note) 16 | 17 | Emacs tutorial 18 | ============== 19 | 20 | When first launching Emacs, you will be presented with this:\ 21 | ![Emacs start screen](images/emacs-start-screen.png)\ 22 | Here one can start the `Emacs Tutorial`, view the `Emacs Manual` or do 23 | various other things. All the links are clickable. But of course, we are 24 | not learning Emacs to just click on things, are we? 25 | 26 | To learn the basics of moving around in Emacs and also get some basic 27 | info about the multitude of aspects of Emacs, I will start by going 28 | through the tutorial. Whenever I started using Emacs, I always neglected 29 | the tutorial and dived head-first into using Emacs, not even learning 30 | the basics of moving around, because I always installed `evil` as soon 31 | as possible. 32 | 33 | This time, I will force myself through the whole tutorial and also, 34 | although stated differently earlier, I will not install `evil` from the 35 | get-go and stay with the built-in keybindings. 36 | 37 | Basic movement 38 | -------------- 39 | 40 | - Move one screen down: `C-v` 41 | - Move one screen up: `M-v` 42 | 43 | This is also the default \'motion\' when going down the last visible 44 | line in the current frame. This will be one setting I will change as 45 | soon as possible. I do not like the jumpiness. I want the lines to 46 | scroll smoothly. 47 | 48 | - Move text under cursor: `C-l` 49 | 50 | This will move the text to the top, bottom and center of the screen, 51 | respectively. This mainly helps \'refocusing\' the window when moving up 52 | and down with `C-v` and `M-v`. 53 | 54 | - Move cursor one character **forward**: `C-f` 55 | - Move cursor one character **backward**: `C-b` 56 | - Move cursor one line up (go to **previous** line): `C-p` 57 | - Move cursor one line down (go to **next** line): `C-n` 58 | 59 | Basic movement, indeed. 60 | 61 | - Move cursor one word **forward**: `M-f` 62 | - Move cursor one word **backward**: `M-b` 63 | 64 | This is my default way of moving around inside a file, besides 65 | \'movement by search\'. 66 | 67 | - Move cursor to beginning of line (German: **Anfang**): `C-a` 68 | - Move cursor to end of line (German: **Ende**): `C-e` 69 | 70 | I knew those from the shell. 71 | 72 | - Move cursor to beginning of sentence (**Anfang**): `M-a` 73 | - Move cursor to end of sentence (**Ende**): `M-e` 74 | 75 | The location of the cursor in the text is also called \'point\'. I\'ll 76 | try to use this term from now on. 77 | 78 | - Go to beginning of file: `M-<` 79 | - Go to end of file: `M->` 80 | 81 | Delete, kill, yank and mark 82 | --------------------------- 83 | 84 | In Emacs, there is a difference between `kill` and `delete`. The former 85 | erases the line/string/character, but makes it `yankable`, which means 86 | it can be pasted again. This is a bit confusing for vim users, because 87 | `yank` means copy here, not paste. 88 | 89 | - Delete character before cursor: `` 90 | - Delete next character after cursor: `C-d` 91 | 92 | Those will make the deleted characters not `yankable`. 93 | 94 | - Kill word before the cursor: `M-` 95 | - Kill word after the cursor: `M-d` 96 | - Kill from the cursor position to end of line: `C-k` 97 | - Kill to end of current sentence: `M-k` 98 | 99 | Those make the deleted lines/string `yankable`. 100 | 101 | - Mark lines and press `M-w` 102 | 103 | Copy/kill without actually killing. 104 | 105 | - Yank last killed characters: `C-y` 106 | - Press `C-y` and then cycle with `M-y`. 107 | 108 | To cycle through the killed characters/lines 109 | 110 | - Visually mark lines: `C-` 111 | 112 | Mark to kill. 113 | 114 | - Undo: `C-/` 115 | 116 | This is also a setting which needs configuring. 117 | 118 | Buffers 119 | ------- 120 | 121 | When opening a file inside Emacs, it creates a buffer for this file. 122 | This buffer stays open until Emacs gets closed or the buffer itself gets 123 | killed. This makes it easy to jump between different files, even when 124 | the file itself got \'closed\'. 125 | 126 | - Save current file: `C-x C-s` 127 | - Find file (open for editing): `C-x C-f` 128 | 129 | This will open the chosen file inside a new buffer. 130 | 131 | - Show all open buffers: `C-x C-b` 132 | 133 | One can select one of the buffers and press Enter to open this buffer. 134 | 135 | - Switch to buffer: `C-x b` 136 | 137 | With this one can start typing the buffer name and use for 138 | auto-completion. 139 | 140 | There are also special buffers: 141 | 142 | - `*Buffer List*`, which contains the buffer list, obviously 143 | - `*Messages*`, contains the messages that have appeared on the bottom 144 | line during your Emacs session 145 | 146 | To save the edited files inside a buffer, one can type `C-x s`, which 147 | asks you about each buffer that need saving. 148 | 149 | eXtended commands 150 | ----------------- 151 | 152 | Emacs has a lot of commands. A lot of them do not come with a keybinding 153 | out-of-the-box. So there are two ways of invoking these commands: 154 | 155 | - `C-x` **Character eXtend**: Followed by one character 156 | - `M-x` **Named command eXtend**: Followed by a long name 157 | 158 | So the first type is invoked by a chain of keybindings, the latter by 159 | pressing `M-x` and typing out the command. 160 | 161 | Cancel a (running) command 162 | -------------------------- 163 | 164 | - Cancel a running or not yet invoked command: `C-g` 165 | 166 | Mode line 167 | --------- 168 | 169 | The line immediately above the echo area is called the \"mode line\". 170 | The mode line says something like this: 171 | 172 | `-:**- TUTORIAL 63% L749 (Fundamental)` 173 | 174 | This indicates if the current file has unsaved changes `**-`; this will 175 | be all dashes if it has not. The next part is the name of the currently 176 | active file, in this case it is `TUTORIAL`. 177 | 178 | The 63% indicates the current position in the active file. It will say 179 | `Top` if the top of the file is seen in the buffer and will say `Bot` if 180 | the opposite is the case. If the buffer is so small that the whole 181 | content fits one screen, it will say `All`. 182 | 183 | The `L` indicates the current line. 184 | 185 | Major modes 186 | ----------- 187 | 188 | The part inside the parentheses indicates which major mode we are 189 | currently in. A major mode tells Emacs how to handle this specific 190 | buffer. Some examples are `Lisp mode`, `Text mode` or `Python mode`. All 191 | these just tell Emacs how to handle indentation, auto-completion and the 192 | like. 193 | 194 | Only one major mode can be active at any given time. To view 195 | documentation on the current major mode, type `C-h m`. 196 | 197 | Minor modes 198 | ----------- 199 | 200 | Minor modes are specific \'nuances\' of a major mode. There can be one, 201 | multiple or no minor modes at all at any given time. 202 | 203 | An example, which is given in the tutorial is `Auto Fill mode`. It makes 204 | Emacs break the line in between words when the maximum number of 205 | characters per line are crossed. 206 | 207 | Search 208 | ------ 209 | 210 | - Search forward: `C-s` 211 | - Search backward: `C-r` 212 | 213 | The typed word is searched and displayed on the fly. 214 | 215 | (Multiple) windows 216 | ------------------ 217 | 218 | - Split horizontally: `C-x 2` 219 | - Split vertically: `C-x 3` 220 | 221 | To scroll the other, non-active window: `C-M-v` and `C-M-S-v`, 222 | respectively. 223 | 224 | - Kill the currently active window: `C-x 0` 225 | - Kill all other windows beside the active one: `C-x 1` 226 | - Move cursor to next frame: `C-x o` 227 | 228 | Side note 229 | ========= 230 | 231 | Just for reference, I am using Emacs 26.3 on Fedora 31 Workstation. 232 | -------------------------------------------------------------------------------- /docs/02-first-customizations.md: -------------------------------------------------------------------------------- 1 | Table of contents 2 | ================= 3 | 4 | - [First customizations](#first-customizations) 5 | - [init.el](#initel) 6 | - [Intro to Lisp](#intro-to-lisp) 7 | - [Customizing Emacs](#customizing-emacs) 8 | - [Visual declutter](#visual-declutter) 9 | - [Start-up screen](#startup-screen) 10 | - [Font](#font) 11 | - [Line numbers](#line-numbers) 12 | - [Show keystrokes faster](#show-keystrokes-faster) 13 | - [Disable audio](#disable-audio) 14 | - [Show matching parentheses](#show-matching-parentheses) 15 | - [Backups and auto-saves](#backups-and-autosaves) 16 | - [Tabs are evil](#tabs-are-evil) 17 | - [y-or-n](#y-or-n) 18 | - [Auto-completion](#auto-completion) 19 | - [Side note](#side-note) 20 | - [Research](#research) 21 | 22 | First customizations 23 | ==================== 24 | 25 | As stated earlier I wanted to tone down the customizing and tweaking to 26 | a bare minimum. In addition to that, I want to research exactly what the 27 | changes do and how they change Emacs default behavior. 28 | 29 | init.el 30 | ======= 31 | 32 | When starting up, Emacs looks in specific places for its config file. 33 | These are: 34 | 35 | - `~/.emacs` 36 | - `~/.emacs.el` 37 | - `~/.emacs.d/init.el` 38 | - `~/.config/emacs/init.el` (starting with Emacs 27) 39 | 40 | Placing the config into `~/.emacs.d/init.el` is generally preferred. 41 | 42 | - First reason for that is that because of the `.el` ending Emacs 43 | automatically interprets the file as an Emacs Lisp file, and because 44 | of that, when editing the file Emacs automatically uses its Elisp 45 | major mode. 46 | - Second reason is that other than `~/.emacs.el` - which also has the 47 | `.el` ending and also has the same benefit as stated in reason 1 - 48 | `init.el` resides in a dedicated directory. So one can put all Emacs 49 | related files and directories into one place and keep everything 50 | nice and tidy. 51 | 52 | So from now on I will assume that the reader\'s config is located at 53 | `~/.emacs.d/init.el`, where my own config resides. 54 | 55 | Intro to Lisp 56 | ============= 57 | 58 | The whole init file is written in Emacs Lisp. So one is actually writing 59 | code to configure Emacs. Basically the syntax of an expression looks 60 | like this (this is the example the [official Emacs 61 | documentation](https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Syntax.html#Init-Syntax) 62 | uses, which I highly recommend): 63 | 64 | `(setq fill-column 60)` 65 | 66 | As the name `LISP`, which is an abbreviation for `LISt Processor`, 67 | indicates everything in Lisp is a list, which is indicated by the 68 | parentheses. Next, `setq` is the name of the called function, with 69 | `fill-column` being a variable and `60` being the assigned value of the 70 | variable. Constants in Emacs can be of type 71 | 72 | - number 73 | - string 74 | - `t` (True) 75 | - `nil` (False) 76 | - another Lisp object (indicated with a single `'` in front of it) 77 | 78 | With `setq` one can set variables globally, most of the time. Some 79 | variables will be set as `buffer-local` variables, so they are just 80 | available inside the current buffer. So to make these variables globally 81 | available, one has to set them via `setq-default`. Also, what confused 82 | me a bit in the beginning was the documentation speaking of `symbols` - 83 | a symbol is just an object with a name. 84 | 85 | After making everything a bit clearer, I hope, let\'s start customizing 86 | Emacs! 87 | 88 | Customizing Emacs 89 | ================= 90 | 91 | Visual declutter 92 | ---------------- 93 | 94 | First, I want to get rid of the scroll, menu and tool bar and I do not 95 | want the cursor to be blinking. Those actually are globally enabled 96 | minor modes, so we do not use `setq`, we just disable them via: 97 | 98 | (menu-bar-mode -1) 99 | (tool-bar-mode -1) 100 | (scroll-bar-mode -1) 101 | (blink-cursor-mode -1) 102 | 103 | Notice that we are using `-1` instead of `nil`, because `nil` equals to 104 | no set and this in return means the modes will be still enabled. 105 | 106 | Start-up screen 107 | -------------- 108 | 109 | I do not want to see the splash screen every time I start Emacs, I want 110 | to see an empty `scratch buffer`. The scratch buffer always 111 | automatically starts when starting Emacs. It is a buffer which is in 112 | Elisp major mode from the get-go and is meant to quickly jot down 113 | something or try out an Elisp function. 114 | 115 | To have the current buffer be the `scratch buffer` and to disable the 116 | startup message it always contains, add this to your `init.el`. 117 | 118 | (setq inhibit-startup-screen t 119 | initial-scratch-message "") 120 | 121 | Font 122 | ---- 123 | 124 | I **really** like `IBM Plex Mono`. Feel free to use any other font (you 125 | should try `IBM Plex Mono`, though). 126 | 127 | One changes the default font to use in all future frames like that: 128 | 129 | (add-to-list 'default-frame-alist 130 | '(font . "IBM Plex Mono 12")) 131 | 132 | Let\'s look a little closer at what that code block does. 133 | 134 | It calls the function `add-to-list` with the argument 135 | `'default-frame-alist` which is a symbol (object) containing multiple 136 | `alists` which is short for `Association List`, which is just a key 137 | value pair. So with this we set the key `font` to the value 138 | `"IBM Plex Mono 12"`. 139 | 140 | `add-to-list` goes through the whole list and, if the element is not yet 141 | set, will add it to the top of the list. Because of this it avoids 142 | duplicates but it also means when going through a big list the process 143 | will be expensive computation-wise. `'default-frame-alist` contains all 144 | the settings regarding the Emacs frames, e.g. height and width of the 145 | initial frame. 146 | 147 | Line numbers 148 | ------------ 149 | 150 | Next I want line numbers to be displayed, but relatively to where the 151 | cursor currently is. To do this, I put this into my config: 152 | 153 | (setq display-line-numbers-type 'relative) 154 | (global-display-line-numbers-mode 1) 155 | 156 | This sets the variable `display-line-numbers-type` to `'relative`, which 157 | `global-display-line-numbers-mode` takes as an argument. 158 | 159 | Show keystrokes faster 160 | ---------------------- 161 | 162 | I want to change the time it takes for Emacs to show which keys I 163 | pressed. The default is set to 1 second. I want it to be instantaneous. 164 | 165 | (setq echo-keystrokes 0.1) 166 | 167 | Disable audio 168 | ------------- 169 | 170 | I also want to disable the pesky ring bell, which Emacs uses to indicate 171 | an error made. 172 | 173 | (setq ring-bell-function 'ignore) 174 | 175 | This will set the variable `ring-bell-function` to use the function 176 | `'ignore` which just does nothing and return `nil`.There is also the 177 | possibility to make Emacs flash the screen, but I want none of that. 178 | 179 | Show matching parentheses 180 | ------------------------- 181 | 182 | Showing matching parentheses makes coding easier. This activates the 183 | minor mode `show-paren-mode` globally. 184 | 185 | (show-paren-mode 1) 186 | 187 | Backups and auto-saves 188 | --------------------- 189 | 190 | Emacs has the concept of backups and auto-saves, which by default are 191 | more annoying than helpful to me. 192 | 193 | Backups are being created when the currently active file is saved for 194 | the first time. Emacs then either creates a copy of the file, or it 195 | renames the file and then creates a new buffer with the new content. 196 | 197 | The problem with this functionality is that the backup itself never gets 198 | deleted. So in the end, you have those backups lying all over the place. 199 | So I want to turn that off. 200 | 201 | Also, Emacs creates auto-saves when editing a file. Again, I do not like 202 | that behavior. The last line of code hinders Emacs to create the 203 | directory `auto-save-list`. 204 | 205 | (setq make-backup-files nil) 206 | (setq auto-save-default nil) 207 | (setq auto-save-list-file-prefix nil) 208 | 209 | Tabs are evil 210 | ------------- 211 | 212 | I want Emacs to insert spaces when indenting. Notice the `setq-default` 213 | to make this setting global. 214 | 215 | (setq-default indent-tabs-mode nil) 216 | 217 | y-or-n 218 | ------ 219 | 220 | Instead of wanting me to type out yes or no, I want to just use y or n. 221 | `fset` sets a new function definition for a symbol, in this case 222 | `'yes-or-no-p` to `'y-or-n-p`. 223 | 224 | (fset 'yes-or-no-p 'y-or-n-p) 225 | 226 | Auto-completion 227 | --------------- 228 | 229 | Emacs has a builtin auto-completion mode, `ido-mode`. This shows 230 | existing files and buffers when searching for them with `C-x C-f` or 231 | `C-x b`. 232 | 233 | (ido-mode 1) 234 | 235 | Side note 236 | ========= 237 | 238 | There are other kind of init files which I will not focus in this 239 | chapter. You can read about them 240 | [here](https://www.gnu.org/software/emacs/manual/html_node/eintr/Site_002dwide-Init.html). 241 | 242 | Also, in the future I will list all topics I want to research for the 243 | chapter under the **Research** headline. 244 | 245 | Research 246 | ======== 247 | 248 | ![Difference between push and 249 | add-to-list](https://emacs.stackexchange.com/questions/7389/whats-the-difference-between-push-and-add-to-list/7392) 250 | -------------------------------------------------------------------------------- /docs/03-package-installation.md: -------------------------------------------------------------------------------- 1 | Table of contents 2 | ================= 3 | 4 | - [Package installation](#package-installation) 5 | - [What is a package?](#what-is-a-package) 6 | - [Installing a package with 7 | package.el](#installing-a-package-with-packageel) 8 | - [MELPA](#melpa) 9 | - [Using MELPA](#using-melpa) 10 | - [Installing packages 11 | programmatically](#installing-packages-programmatically) 12 | - [use-package, straight.el, Borg, Quelpa, Cask, 13 | el-get](#use-package-straightel-borg-quelpa-cask-el-get) 14 | 15 | Package installation 16 | ==================== 17 | 18 | In this chapter I want to talk about package installation and 19 | management. Since version 24 Emacs has a builtin package manager, 20 | `package.el`. There are multiple ways of installing packages, some of 21 | which I will only mention and others which I will focus a bit on. But 22 | let\'s start with the definition of a package and the default way of 23 | installing one. 24 | 25 | What is a package? 26 | ================== 27 | 28 | A package is nothing but one or multiple Elisp files which extend or 29 | change the functionality of Emacs. 30 | 31 | There are two types of packages, a `simple package` and a 32 | `multi-file package`. The first is just a single Emacs Lisp file, the 33 | latter is a conglomerate of multiple Emacs Lisp and non-Lisp files 34 | stored inside a tar archive. 35 | 36 | When installing a package, Emacs creates a sub-directory under 37 | `package-user-dir`, which by default is called `elpa`, for the newly 38 | installed package, where its name is `$packagename-$version`. This is 39 | the package\'s content directory, i.e. where Emacs stores the Elisp 40 | file(s) which form the package. 41 | 42 | Installing a package with package.el 43 | ==================================== 44 | 45 | Let\'s say we want to install the `ace-window` package, which makes it 46 | easier to navigate between multiple windows. By typing 47 | `M-x list-packages` we can see all available packages in the `ELPA`, 48 | which stands for `Emacs Lisp Package Archive`. This is the official 49 | package repository that comes with Emacs per default. 50 | 51 | So after typing said command, one will see something like that: 52 | 53 | ![Listed ELPA packages](images/elpa-package-list.png) 54 | 55 | By moving the cursor to the package one wants to install and pressing 56 | `i`, said package will be marked for installation, which can be started 57 | by pressing `x` (you can uninstall a package the same way by pressing 58 | `d` instead of `i`). 59 | 60 | This will create the following directory structure inside 61 | `~/.emacs.d/elpa/`: 62 | 63 | . 64 | ├── ace-window-0.9.0 65 | │ ├── ace-window-autoloads.el 66 | │ ├── ace-window.el 67 | │ ├── ace-window.elc 68 | │ └── ace-window-pkg.el 69 | ├── ace-window-0.9.0.signed 70 | ├── archives 71 | │ └── gnu 72 | │ ├── archive-contents 73 | │ └── archive-contents.signed 74 | ├── avy-0.5.0 75 | │ ├── avy-autoloads.el 76 | │ ├── avy.el 77 | │ ├── avy.elc 78 | │ ├── avy-pkg.el 79 | │ ├── avy-pkg.elc 80 | │ ├── avy-test.el 81 | │ ├── avy-test.elc 82 | │ ├── ChangeLog 83 | │ ├── doc 84 | │ │ └── Changelog.org 85 | │ ├── Makefile 86 | │ ├── README.md 87 | │ └── targets 88 | │ ├── avy-init.el 89 | │ ├── avy-init.elc 90 | │ ├── checkdoc.el 91 | │ └── checkdoc.elc 92 | ├── avy-0.5.0.signed 93 | └── gnupg 94 | ├── private-keys-v1.d 95 | ├── pubring.kbx 96 | ├── pubring.kbx~ 97 | └── trustdb.gpg 98 | 99 | Notice that besides me only marking `ace-window` for installation, the 100 | package tells `package.el` about its dependency on `avy` which it then 101 | installs, too. 102 | 103 | As you can see, the installed `ace-window` has its own directory named 104 | after the aforementioned syntax of `$packagename-$version`, which in 105 | this case is `ace-window-0.9.0`. Inside this directory, they are the 106 | Emacs Lisp files `.el` which Emacs then compiles into `.elc` files. 107 | 108 | The directory also contains `ace-window-autoloads.el` and 109 | `ace-window-pkg.el`. The `autoloads` feature is a really nifty thing, in 110 | my opinion. What it does is it tells Emacs about the functions (or 111 | macros) of the installed package and the file(s) where they actually 112 | reside in. This greatly enhances the start-up of Emacs because it does 113 | not load the files until they are needed to actually provide the 114 | functions they contain. 115 | 116 | Just to be clear, though: I am greatly simplifying `autoloads` and the 117 | benefits they provide, mostly because at this point I do not fully 118 | understand how they work and because of my self-imposed restrictions of 119 | not over-researching a topic I will keep myself from doing just that. 120 | 121 | The `ace-window-pkg.el` file just describes the package itself, names 122 | its author, and the like. 123 | 124 | The rest of the files and directories are the signed package hashes, the 125 | public key of the archive we are using and the corresponding database 126 | for storing those. 127 | 128 | Notice that after installing `ace-window` or any other package, there 129 | will be the following code blocks in your config file: 130 | 131 | ;; Added by Package.el. This must come before configurations of 132 | ;; installed packages. Don't delete this line. If you don't want it, 133 | ;; just comment it out by adding a semicolon to the start of the line. 134 | ;; You may delete these explanatory comments. 135 | (package-initialize) 136 | 137 | (custom-set-variables 138 | ;; custom-set-variables was added by Custom. 139 | ;; If you edit it by hand, you could mess it up, so be careful. 140 | ;; Your init file should contain only one such instance. 141 | ;; If there is more than one, they won't work right. 142 | '(package-selected-packages (quote (ace-window)))) 143 | (custom-set-faces 144 | ;; custom-set-faces was added by Custom. 145 | ;; If you edit it by hand, you could mess it up, so be careful. 146 | ;; Your init file should contain only one such instance. 147 | ;; If there is more than one, they won't work right. 148 | ) 149 | 150 | At start-up, after loading the init file, the `(package-initialize)` 151 | function initializes Emacs\' internal record of installed packages, and 152 | loads their `autoloads` - if they are in the `package-load-list` - which 153 | by default every installed package is. 154 | 155 | The second part with `custom-set-variables` are entries which will be 156 | created by the `customize` interface. This is for handling dependencies 157 | on package deletions and is also intended to make your configuration 158 | portable. I do not like Emacs to write into my config file. Because of 159 | that, I move these entries to another file `~/.emacs.d/custom.el` and 160 | tell Emacs where to find them. 161 | 162 | (setq custom-file "~/.emacs.d/custom.el") 163 | (load custom-file) 164 | 165 | MELPA 166 | ===== 167 | 168 | The `ELPA` might be the official archive, but the number of packages in 169 | it are pretty limited and, most of the time, the packages themselves are 170 | outdated. This is because of the strict regulations the `ELPA` 171 | maintainers enforce on package creators. 172 | 173 | Because of that, the `MELPA`, or 174 | `Milkypostman's Emacs Lisp Package Archive` is the de facto standard 175 | repository for Emacs. 176 | 177 | It is not officially supported by the GNU project, but it is curated and 178 | one can be sure that the packages do not contain malicious code. Still, 179 | you should still take care when installing a lesser-known package! 180 | 181 | Using MELPA 182 | ----------- 183 | 184 | In order to use `MELPA`, you need to put the following code block into 185 | your config file: 186 | 187 | (require 'package) 188 | (let* ((no-ssl (and (memq system-type '(windows-nt ms-dos)) 189 | (not (gnutls-available-p)))) 190 | (proto (if no-ssl "http" "https"))) 191 | (add-to-list 'package-archives (cons "melpa" (concat proto "://melpa.org/packages/")) t)) 192 | (package-initialize) 193 | 194 | Let\'s see what that does. 195 | 196 | The (require \'package) line tells Emacs to fully load the builtin 197 | package `'package`, but only when not already loaded. This is opposed to 198 | using `load`, which would load the files even already loaded. To let 199 | Emacs know which package provides the `'package` feature, inside the 200 | package itself there must be a line like `provide 'package`. 201 | 202 | The `'package` package provides the package installation and management 203 | system of Emacs. 204 | 205 | The next code block just makes sure that when the system is a Windows 206 | system it should not use `HTTPS` to access the repository. I am not 207 | going to fully explain what the code exactly does and - of course - this 208 | is not mandatory if you are not on a Windows system or are planning to 209 | use your config on one. 210 | 211 | The `add-to-list` part adds the `MELPA` URL to the `'package-archives` 212 | `alist`. 213 | 214 | After that, the package record will be initialized. 215 | 216 | Now, after typing `M-x package-list` you can see that there are a lot 217 | more packages available for installation. When you do not see the new 218 | entries you have to refresh the package list via 219 | `M-x package-refresh-contents`. 220 | 221 | Installing packages programmatically 222 | ==================================== 223 | 224 | Like stated before there is another option to install packages other 225 | than using `M-x list-packages`. To install e.g. `which-key`, a package 226 | which \'displays the key bindings following your currently entered 227 | incomplete command (a prefix) in a pop-up\' - [as the developer describes 228 | it](https://github.com/justbur/emacs-which-key) - I put the following 229 | code into my config: 230 | 231 | (package-install 'which-key) 232 | (which-key-mode) 233 | 234 | When Emacs starts up, it will try to install `which-key` and after 235 | either doing so or realizing that it is already installed it will 236 | activate `which-key-mode` globally. This makes your config portable so 237 | that when you are keeping it in version control you just have to copy 238 | your config onto the new system and it will install all the packages you 239 | list. 240 | 241 | Of course this is not the most sophisticated way, but it works. And 242 | after I have dug a bit more into Elisp programming I might reevaluate 243 | this approach. But for now, this should suffice. I am aware, though, 244 | that this might not scale as the number of installed packages increases. 245 | 246 | use-package, straight.el, Borg, Quelpa, Cask, el-get 247 | ==================================================== 248 | 249 | Like I initially said, there are a lot of ways to install packages in 250 | Emacs. Mostly these are \'external\' package managers or installers that 251 | one has to install first. 252 | 253 | I will only mention them here, as I want to get into the nitty-gritty 254 | and follow the \'official\' way of doing things with the builtin 255 | features. By doing so I hope, in the future, I will be able to 256 | objectively decide on which alternative package manager or installer I 257 | want to use (yes, I know: `use-package` is not a package manager). 258 | 259 | Also know that there might be a lot more than the few I mention in the 260 | heading, but those are the most known - to me at least. 261 | --------------------------------------------------------------------------------