Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve "Learning Emacs Lisp" doc #231

Merged
merged 2 commits into from
Oct 26, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 67 additions & 1 deletion docs/LEARNING.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,72 @@
# Learning

## Starting out with Emacs

So you've installed Emacs. Now what?

Well, you can start the tutoral by pressing `C-h t`, and that's not a bad place
to start. If you're completely new to Emacs, the [Emacs Prelude](http://batsov.com/prelude/) package offers a
to start. The tutorial will teach you the basics of editing, searching, and navigating in Emacs.

If you're completely new to Emacs, it can make sense to grab a starter kit,
which comes with a set of configurations and packages already set up.

The [Emacs Prelude](http://batsov.com/prelude/) package offers a
nice set of sensible defaults and packages.

To install Emacs Prelude run the following in a terminal:

```
curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh
```

and make sure to check out the [installation guide](https://prelude.emacsredux.com/en/latest/installation/) for further instructions.


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).

To install Doom Emacs run the following in a terminal:

```
git clone --depth 1 https://github.com/doomemacs/doomemacs ~/.emacs.d
~/.emacs.d/bin/doom install
```

and make sure to check the [installation guide](https://github.com/doomemacs/doomemacs#install) for further instructions.

## Setting up syntax checking and linting

Setting up syntax checking and linting with [Flycheck](https://www.flycheck.org/en/latest/) is recommended.

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)

```elisp
(require 'package)

(add-to-list 'package-archives
'("MELPA Stable" . "https://stable.melpa.org/packages/") t)
(package-initialize)
(package-refresh-contents)
```

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)

```elisp
(package-install 'flycheck)
(add-hook 'after-init-hook #'global-flycheck-mode)
```

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)

```elisp
(use-package flycheck
:ensure t
:init (global-flycheck-mode))
```

For further information and trouble shooting please check the [Flycheck documentation](https://www.flycheck.org/en/latest/user/troubleshooting.html).

## Learning Emacs Lisp

The best documentation on Emacs Lisp is... shipped with Emacs itself!
to access the
[Emacs Lisp Reference](https://www.gnu.org/software/emacs/manual/elisp.html),
Expand All @@ -17,3 +78,8 @@ it [online](https://www.gnu.org/software/emacs/manual/elisp.html).
If you are brand new to Elisp, you can read the
[Introduction to Emacs Lisp](http://www.emacswiki.org/emacs/EmacsLispIntro),
which is opened the same way.

## Emacs Lisp best practices and conventions

The Emacs Manual contains a section on Emacs Lisp [Coding Conventions](https://www.gnu.org/software/emacs/manual/html_node/elisp/Coding-Conventions.html).
There is also a community driven [Style Guide](https://github.com/bbatsov/emacs-lisp-style-guide) maintained on GitHub.