Skip to content

Commit 9bf7264

Browse files
authored
Improve "Learning Emacs Lisp" doc (#231)
* Improve "Learning Emacs Lisp" doc - split up into different sections, accommodate people just starting out with Emacs a bit more - add installation instructions for starter kits - add Doom Emacs starter kit for people switching from vim - reference style guide and coding conventions closes #198 works on #18 (#18 (comment)) * Minor fixes from proof reading
1 parent 62671aa commit 9bf7264

File tree

1 file changed

+67
-1
lines changed

1 file changed

+67
-1
lines changed

docs/LEARNING.md

+67-1
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,72 @@
11
# Learning
22

3+
## Starting out with Emacs
4+
35
So you've installed Emacs. Now what?
46

57
Well, you can start the tutoral by pressing `C-h t`, and that's not a bad place
6-
to start. If you're completely new to Emacs, the [Emacs Prelude](http://batsov.com/prelude/) package offers a
8+
to start. The tutorial will teach you the basics of editing, searching, and navigating in Emacs.
9+
10+
If you're completely new to Emacs, it can make sense to grab a starter kit,
11+
which comes with a set of configurations and packages already set up.
12+
13+
The [Emacs Prelude](http://batsov.com/prelude/) package offers a
714
nice set of sensible defaults and packages.
815

16+
To install Emacs Prelude run the following in a terminal:
17+
18+
```
19+
curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh
20+
```
21+
22+
and make sure to check out the [installation guide](https://prelude.emacsredux.com/en/latest/installation/) for further instructions.
23+
24+
25+
If you are familiar with vim you might be interested in the [Doom Emacs](https://github.com/doomemacs/doomemacs) starter kit, which integrates vim emulation powered by [evil-mode](https://github.com/emacs-evil/evil).
26+
27+
To install Doom Emacs run the following in a terminal:
28+
29+
```
30+
git clone --depth 1 https://github.com/doomemacs/doomemacs ~/.emacs.d
31+
~/.emacs.d/bin/doom install
32+
```
33+
34+
and make sure to check the [installation guide](https://github.com/doomemacs/doomemacs#install) for further instructions.
35+
36+
## Setting up syntax checking and linting
37+
38+
Setting up syntax checking and linting with [Flycheck](https://www.flycheck.org/en/latest/) is recommended.
39+
40+
If you don't already have added the [MELPA](https://melpa.org/) repository to your Emacs, do this by adding the following to your [init file](https://www.flycheck.org/en/latest/glossary.html#term-init-file)
41+
42+
```elisp
43+
(require 'package)
44+
45+
(add-to-list 'package-archives
46+
'("MELPA Stable" . "https://stable.melpa.org/packages/") t)
47+
(package-initialize)
48+
(package-refresh-contents)
49+
```
50+
51+
Installation and setup of Flycheck without [use-package](https://github.com/jwiegley/use-package) is done by adding the following to your [init file](https://www.flycheck.org/en/latest/glossary.html#term-init-file)
52+
53+
```elisp
54+
(package-install 'flycheck)
55+
(add-hook 'after-init-hook #'global-flycheck-mode)
56+
```
57+
58+
Installation and setup of Flycheck with [use-package](https://github.com/jwiegley/use-package) is done by adding the following to your [init file](https://www.flycheck.org/en/latest/glossary.html#term-init-file)
59+
60+
```elisp
61+
(use-package flycheck
62+
:ensure t
63+
:init (global-flycheck-mode))
64+
```
65+
66+
For further information and trouble shooting please check the [Flycheck documentation](https://www.flycheck.org/en/latest/user/troubleshooting.html).
67+
68+
## Learning Emacs Lisp
69+
970
The best documentation on Emacs Lisp is... shipped with Emacs itself!
1071
to access the
1172
[Emacs Lisp Reference](https://www.gnu.org/software/emacs/manual/elisp.html),
@@ -17,3 +78,8 @@ it [online](https://www.gnu.org/software/emacs/manual/elisp.html).
1778
If you are brand new to Elisp, you can read the
1879
[Introduction to Emacs Lisp](http://www.emacswiki.org/emacs/EmacsLispIntro),
1980
which is opened the same way.
81+
82+
## Emacs Lisp best practices and conventions
83+
84+
The Emacs Manual contains a section on Emacs Lisp [Coding Conventions](https://www.gnu.org/software/emacs/manual/html_node/elisp/Coding-Conventions.html).
85+
There is also a community driven [Style Guide](https://github.com/bbatsov/emacs-lisp-style-guide) maintained on GitHub.

0 commit comments

Comments
 (0)