diff --git a/docs/faq.org b/docs/faq.org index 0cc06d59a..f9275b15c 100644 --- a/docs/faq.org +++ b/docs/faq.org @@ -566,16 +566,19 @@ The ~package!~ macro has a ~:disable~ property: (package! irony :disable t) #+END_SRC +Remember to run ~doom refresh~ afterwards to ensure that the package is +uninstalled and disabled. + You'll find more information in the "[[file:getting_started.org::*Disabling%20packages][Disabling packages]]" section of the [[file:getting_started.org][Getting Started]] guide. ** How do I reconfigure a package included in Doom? -~def-package!~ and ~after!~ (wrappers around ~use-package~ and -~with-eval-after-load~, respectively) are your bread and butter for configuring +~use-package!~ and ~after!~ (wrappers around ~use-package~ and +~eval-after-load~, respectively) are your bread and butter for configuring packages in Doom. #+BEGIN_SRC elisp -(def-package! doom-themes +(use-package! doom-themes :defer t :init (unless doom-theme @@ -600,7 +603,6 @@ available. They are: #+BEGIN_SRC emacs-lisp ;;; in ~/.doom.d/config.el - (setq doom-theme 'doom-tomorrow-night) ;; or (load-theme 'doom-tomorrow-night t) @@ -609,9 +611,9 @@ available. They are: At the moment, the only difference between the two is that ~doom-theme~ is loaded when Emacs has finished initializing at startup and ~load-theme~ loads the theme immediately. Which you choose depends on your needs, but I recommend -~doom-theme~ because, if I ever discover a better way to load themes, I can -easily change how Doom uses ~doom-theme~, but I can't control how you use the -~load-theme~ function. +setting ~doom-theme~ because, if I later discover a better way to load themes, I +can easily change how Doom uses ~doom-theme~, but I can't control how you use +the ~load-theme~ function. *** Installing a third party theme To install a theme from a third party plugin, say, [[https://github.com/bbatsov/solarized-emacs][solarized]], you need only @@ -659,11 +661,6 @@ wrapper around ~define-key~, ~global-set-key~, ~local-set-key~ and (global-set-key (kbd "C-x y") #'do-something) (map! "C-x y" #'do-something) -;; bind multiple keys -(map! "C-x x" #'do-something - "C-x y" #'do-something-else - "C-x z" #'do-another-thing) - ;; bind a key on a keymap (define-key emacs-lisp-mode (kbd "C-c p") #'do-something) (map! :map emacs-lisp-mode "C-c p" #'do-something) @@ -671,6 +668,11 @@ wrapper around ~define-key~, ~global-set-key~, ~local-set-key~ and ;; unbind a key defined elsewhere (define-key lua-mode-map (kbd "SPC m b") nil) (map! :map lua-mode-map "SPC m b" nil) + +;; bind multiple keys +(map! "C-x x" #'do-something + "C-x y" #'do-something-else + "C-x z" #'do-another-thing) #+END_SRC Evil users can also define keys in particular evil states: @@ -702,7 +704,8 @@ Evil users can also define keys in particular evil states: #+END_SRC ~map!~ supports other properties, like ~:after~, ~:when~, ~:prefix~ and ~:desc~. -Look at ~map!~'s documentation for more information. +Look at ~map!~'s documentation for more information (=SPC h f map!= for evil +users, =C-h f map!= otherwise). You'll find a more comprehensive example of ~map!~'s usage in [[file:/mnt/projects/conf/doom-emacs-docs/modules/config/default/+evil-bindings.el][config/default/+evil-bindings.el]]. @@ -757,6 +760,7 @@ These variables control what key to use for leader and localleader keys: e.g. #+BEGIN_SRC emacs-lisp +;; in ~/.doom.d/config.el (setq doom-leader-key "," doom-localleader-key "\\") #+END_SRC @@ -775,7 +779,7 @@ You'll find more precise documentation on the variable through =SPC h v display-line-numbers-type= or =C-h v display-line-numbers-type=. #+begin_quote -The ~'visual~ option is unavailable to Emacs 25 users. +The ~'visual~ option is unavailable in Emacs 25. #+end_quote There is also ~M-x doom/toggle-line-numbers~ (bound to =SPC t l= by default) for @@ -799,22 +803,24 @@ Short answer: You can, but you shouldn't. Long answer: Restarting Emacs is always your safest bet, but Doom provides a few tools for experienced Emacs users to skirt around it (most of the time): -- Generally, you can evaluate your changes on-the-fly with ~+eval/region~ (bound - to the =gr= operator for evil users) or ~eval-last-sexp~ (bound to =C-x C-e=). - Changes take effect immediately. +- Evaluate your changes on-the-fly with ~+eval/region~ (bound to the =gr= + operator for evil users) or ~eval-last-sexp~ (bound to =C-x C-e=). Changes + take effect immediately. - On-the-fly evaluation won't work for all changes. For instance, changing your - ~doom!~ block (i.e. the list of modules for Doom to enable) will almost always + ~doom!~ block (i.e. the list of modules for Doom to enable) will always require a restart (and ~bin/doom refresh~). - Doom /does/ provide ~M-x doom/reload~ for your convenience, which will run - ~doom refresh~, restart the Doom initialization process, and re-evaluate your - personal config, but this won't clear pre-existing state. That won't usually - be a problem, but Doom cannot anticipate any complications arising from your - private config. If you intend to use ~doom/reload~, try to design your config - to be idempotent. + Doom provides ~M-x doom/reload~ for your convenience, which will run ~doom + refresh~, restart the Doom initialization process, and re-evaluate your + personal config, but this won't clear pre-existing state. That may or may not + be a problem, this hasn't be thoroughly tested, and Doom cannot anticipate + complications arising from your private config. + + If you intend to use ~doom/reload~, try to design your config to be + idempotent. - Many ~bin/doom~ commands are available as elisp commands with the ~doom//*~ prefix. e.g. ~doom//refresh~, ~doom//update~, etc. Feel free to use them, but - consider them highly experimental and subject to change. + consider them highly experimental and subject to change without notice. - You can quickly restart Emacs and restore the last session with ~doom/restart-and-restore~ (bound to =SPC q r=). @@ -833,7 +839,17 @@ divulging, your secrets to others). You can run ~bin/doom help~ to see what it's capable of, but here are the highlights: ++ ~doom doctor~ :: Diagnose common issues in your environment and list missing + external dependencies for your enabled modules. ++ ~doom install~ :: Install any missing packages. + ~doom update~ :: Update all packages that Doom's (enabled) modules use. ++ ~doom refresh~ :: Ensures that all missing packages are installed, orphaned + packages are removed, and metadata properly generated. ++ ~doom env~ :: Regenerates your envvar file, which contains a snapshot of your + shell environment for Doom Emacs to load on startup. You need to run this for + changes to your shell environment to take effect. ++ ~doom purge~ :: Purge orphaned packages (i.e. ones that aren't needed anymore) + and regraft your repos. + ~doom upgrade~ :: Upgrade Doom to the latest version (then update your packages). This is equivalent to: @@ -842,19 +858,6 @@ highlights: doom refresh doom update #+END_SRC -+ ~doom doctor~ :: Diagnose common issues in your environment and list missing - external dependencies for your enabled modules. -+ ~doom install~ :: Install any missing packages. -+ ~doom purge~ :: Purge orphaned packages (i.e. ones that aren't needed anymore) - and regraft your repos. -+ ~doom autoloads~ :: Regenerates autoloads files, which tell Emacs where to - find lazy-loaded functions and packages. Necessary if you change autoload - files in modules. -+ ~doom refresh~ :: Equivalent to ~doom autoloads && doom autoremove && doom - install~. -+ ~doom env~ :: Regenerates your envvar file, which contains a snapshot of your - shell environment for Doom Emacs to load on startup. You need to run this for - changes to your shell environment to take effect. ** When to run ~doom refresh~ As a rule of thumb you should run ~doom refresh~ whenever you: @@ -1008,10 +1011,10 @@ of common issues and may give you some clues as to what is wrong. ** I see a blank scratch buffer at startup This commonly means that Emacs can't find your private doom config (in -=~/.doom.d= or =~/.config/doom=). Make sure *one of these two* folders exist, -and that it has an init.el file with a ~doom!~ block. Running ~doom install~ -will populate your private doom directory with the bare minimum you need to get -going. +=~/.doom.d= or =~/.config/doom=). Make sure *only one of these two* folders +exist, and that it has an init.el file with a ~doom!~ block. Running ~doom +install~ will populate your private doom directory with the bare minimum you +need to get going. If nothing else works, try running ~bin/doom doctor~. It can detect a variety of common issues and may give you some clues as to what is wrong. @@ -1044,7 +1047,7 @@ The most common culprit for these types of errors are: newer (or older) version of Emacs, you'll need to either reinstall or recompile your installed plugins. This can be done by: - + Running ~doom rebuild -f~, + + Running ~doom build~, + Or deleting =~/.emacs.d/.local/straight= then running ~doom install~ (this will take a while).