docs/faq: general revision

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