Update FAQ

Add a few questions, remove obsolete ones, and revise the rest.

docs/faq.org

@@ -13,11 +13,11 @@
   - [[#why-is-startup-time-important-why-not-use-the-daemon][Why is startup time important? Why not use the daemon?]]
   - [[#how-do-i-use-doom-alongside-other-emacs-configs][How do I use Doom alongside other Emacs configs?]]
   - [[#why-should-i-use-doom-instead-of-rolling-my-own-config][Why should I use Doom instead of rolling my own config?]]
-  - [[#what-is-the-meaning-behind-dooms-naming-conventions][What is the meaning behind Doom's naming conventions?]]
+  - [[#what-is-the-meaning-behind-dooms-naming-convention-in-its-source-code][What is the meaning behind Doom's naming convention in its source code?]]
-  - [[#how-can-i-contribute-tosupport-doom][How can I contribute to/support Doom?]]
   - [[#what-version-of-doom-am-i-running][What version of Doom am I running?]]
+  - [[#is-discord-the-only-option-for-interacting-with-your-community][Is Discord the only option for interacting with your community?]]
 - [[#configuration][Configuration]]
-  - [[#should-i-fork-doom-to-customize-it][Should I fork Doom to customize it?]]
+  - [[#does-doom-respect-xdg-conventions][Does Doom respect XDG conventions]]
   - [[#how-do-i-configure-doom-emacs][How do I configure Doom Emacs?]]
   - [[#how-do-i-enable-or-disable-a-doom-module][How do I enable or disable a Doom module?]]
   - [[#how-do-i-change-the-theme][How do I change the theme?]]
@@ -30,10 +30,10 @@
   - [[#how-do-i-change-the-appearance-of-a-face-or-faces][How do I change the appearance of a face (or faces)?]]
   - [[#can-doom-be-customized-without-restarting-emacs][Can Doom be customized without restarting Emacs?]]
   - [[#can-vimevil-be-removed-for-a-more-vanilla-emacs-experience][Can Vim/Evil be removed for a more vanilla Emacs experience?]]
-  - [[#should-i-use-make-or-bindoom][Should I use ~make~ or ~bin/doom~?]]
   - [[#when-should-and-shouldnt-i-use-bindoom][When should and shouldn't I use ~bin/doom~?]]
   - [[#when-to-run-doom-sync][When to run ~doom sync~]]
   - [[#how-to-suppress-confirmation-prompts-while-bindoom-is-running][How to suppress confirmation prompts while ~bin/doom~ is running]]
+  - [[#how-do-i-enable-lsp-support-for-insert-language-here][How do I enable LSP support for <insert language here>?]]
 - [[#package-management][Package Management]]
   - [[#how-do-i-install-a-package-from-elpa][How do I install a package from ELPA?]]
   - [[#how-do-i-install-a-package-from-githubanother-source][How do I install a package from github/another source?]]
@@ -62,6 +62,7 @@
   - [[#tramp-connections-hang-forever-when-connecting][TRAMP connections hang forever when connecting]]
   - [[#an-upstream-package-was-broken-and-i-cant-update-it][An upstream package was broken and I can't update it]]
   - [[#why-do-i-see-ugly-indentation-highlights-for-tabs][Why do I see ugly indentation highlights for tabs?]]
+  - [[#clipetty--emit-opening-output-file-permission-denied-devpts29-error]["clipetty--emit: Opening output file: Permission denied, /dev/pts/29" error]]
 - [[#contributing][Contributing]]
 
 * General
@@ -81,9 +82,9 @@ in the [[file:getting_started.org::On Windows][Getting Starting guide]].
 If you're a Windows user, help us improve our documentation!
 
 ** Is Doom only for vimmers?
-No, but it is Doom's primary audience. Its maintainer is a dyed-in-the-wool
+No, but it is Doom's primary audience, because its maintainer is a
-vimmer with almost two decades of vim muscle memory, and he came to Emacs to
+dyed-in-the-wool vimmer with almost two decades of vim muscle memory, and he
-find a better vim.
+adopted Emacs in search of a better vim.
 
 Although Doom is less polished without evil, its growing non-evil user base is
 slowly improving the situation. We welcome suggestions and PRs to help
@@ -93,12 +94,16 @@ If you'd still like a go at it, see the [[file:../modules/editor/evil/README.org
 [[file:../modules/editor/evil/README.org][:editor evil]] module's documentation.
 
 ** I am a beginner. Can I use Doom?
-If you're new to the terminal, to programming, or Emacs and/or vim, Doom (or
+This isn't a choice I can make for you. Generally, if you're new to the
-Emacs, for that matter) is a rough place to start. Neither Doom nor Emacs are
+terminal, to programming, or Emacs and/or vim, then Doom (and Emacs, for that
-particularly beginner friendly. That's not to say it's impossible, or that we
+matter) will be a rough place to start. Neither Doom nor Emacs are particularly
-won't help you if you ask, but expect a hefty commitment and a bumpy journey.
+beginner friendly. Emacs' main draw is its unparalleled extensibility, but
+anything so extensible has a learning curve.
 
-Remember to check out the [[file:index.org][Documentation]] for a guide to getting started.
+That's not to say it's impossible, or that we won't help you if you ask, but
+expect a hefty commitment and a bumpy journey. And don't pass up on the
+[[file:index.org][Documentation]], which will walk you through setting up Doom, and includes links
+to external resources created by our community.
 
 ** How does Doom compare to Spacemacs?
 To paraphrase (and expand upon) a [[https://www.reddit.com/r/emacs/comments/6pa0oq/quickstart_tutorial_for_emacs_newbies_with_doom/dkp1bhd/][reddit answer]] to this question by [[https://github.com/gilbertw1][@gilbertw1]]:
@@ -113,18 +118,19 @@ To paraphrase (and expand upon) a [[https://www.reddit.com/r/emacs/comments/6pa0
   consensus. It is [mostly] the work of one developer and caters to his
   vim-slanted tastes. Doom's defaults enforce very particular (albeit optional)
   workflows.
-+ *Doom lacks manpower.* Bugs stick around longer, documentation is light and
++ *Doom lacks manpower.* Bugs stick around longer, documentation is lighter and
-  development is at the mercy of its single maintainer's schedule, health and
+  development is at the mercy of it's maintainer's schedule, health and whims.
-  whims.
++ *Doom is not beginner friendly.* Doom lacks a large community to constantly
-+ *Doom is not beginner friendly.* Spacemacs works out of the box. Your mileage
+  improve and produce tutorials/guides for it. Spacemacs is more likely to work
-  may vary with Doom; assembly is required! Familiarity with Emacs Lisp (or
+  right out of the box. Doom also holds your hand less. A little elisp, shell
-  programming in general), git and the command line will go a long way to ease
+  and git-fu will go a long way to ease you into Doom.
-  you into Doom.
++ *Doom is managed through it's command line interface.* The ~bin/doom~ script
-+ *Doom manages its packages outside of Emacs.* Spacemacs installs (and checks
+  allows you to script package management, manage your config, or utilize elisp
-  for packages) on startup or on demand. Doom leaves package management to be
+  functionality externally, like org tangling or batch processing.
-  done externally, through the ~bin/doom~ script. This allows for package
++ *Doom's package manager is declarative and rolling release is opt-in.* Doom
-  management to be scripted on the command line and enables a number of startup
+  takes a little after nix, striving for as much config reproducibility as Emacs
-  optimizations we wouldn't have otherwise.
+  (and git) will permit. Spacemacs uses package.el, which is rolling release
+  only.
 
 ** Why such a complicated package management system?
 Doom had +four+ *five* goals for its package management system:
@@ -293,34 +299,65 @@ Note: package.el is sneaky, and will initialize itself if you're not careful.
 
 *** Lazy load more than everything
 ~use-package~ can defer your packages. Using it is a no-brainer, but Doom goes a
-little further with lazy loading. There are some massive plugins out there. For
+step further. There are some massive plugins out there for which ordinary lazy
-some of them, ordinary lazy loading techniques don't work. To name a few:
+loading techniques don't work. To name a few:
 
 + The =lang/org= module defers loading babel packages until their src blocks are
   executed or read. You no longer need ~org-babel-do-load-languages~ in your
   config -- in fact, you shouldn't use it at all!
++ =org-protocol= needs to be loaded to intercept requests for org-protocol://
+  URLs. Since org-protocol depends on org, this can be expensive to load
+  yourself, so Doom loads as soon as a org-protocol:// request is received, just
+  before it is processed.
 + Company and yasnippet are loaded as late as possible (waiting until the user
   opens a non-read-only, file-visiting buffer (that isn't in fundamental-mode)).
 + The =evil-easymotion= package binds many keys, none of which are available
   until you load the package. Instead of loading it at startup, =gs= is bound to
   a command that loads the package, populates =gs=, then simulates the =gs= key
   press as though those new keys had always been there.
-+ Doom loads some packages "incrementally". i.e. after a few seconds of idle
-  time post-startup, Doom loads packages piecemeal (one dependency at a time)
-  while Emacs. It aborts if it detects input, as to make the process as subtle
-  as possible.
 
-  For example, instead of loading =org= (a giant package), it will load these
+In addition, Doom loads some packages "incrementally". i.e. after a few seconds
-  dependencies, one at a time, before finally loading =org=:
+of idle time post-startup, Doom loads packages piecemeal (one dependency at a
+time) while Emacs. It aborts if it detects input, as to make the process as
+subtle as possible.
 
-  #+BEGIN_SRC elisp
+For example, instead of loading =org= (a giant package), it will load these
-  (calendar find-func format-spec org-macs org-compat org-faces org-entities
+dependencies, one at a time, before finally loading =org=:
-   org-list org-pcomplete org-src org-footnote org-macro ob org org-agenda
-   org-capture)
-  #+END_SRC
 
-  This ensures packages load as quickly as possible when you first load an org
+#+BEGIN_SRC elisp
-  file.
+(calendar find-func format-spec org-macs org-compat org-faces
+ org-entities org-list org-pcomplete org-src org-footnote
+ org-macro ob org org-agenda org-capture)
+#+END_SRC
+
+This ensures packages load as quickly as possible when you first load an org
+file.
+
+*** Unset ~file-name-handler-alist~ temporarily
+Emacs consults this variable every time a file is read or library loaded, or
+when certain functions in the file API are used (like ~expand-file-name~ or
+~file-truename~).
+
+Emacs does to check if a special handler is needed to read that file, but none
+of them are (typically) necessary at startup, so we disable them (temporarily!):
+
+#+BEGIN_SRC emacs-lisp
+(defvar doom--file-name-handler-alist file-name-handler-alist)
+(setq file-name-handler-alist nil)
+
+;; ... your whole emacs config here ...
+
+;; Then restore it later:
+(setq file-name-handler-alist doom--file-name-handler-alist)
+
+;; Alternatively, restore it even later:
+(add-hook 'emacs-startup-hook
+  (lambda ()
+    (setq file-name-handler-alist doom--file-name-handler-alist)))
+#+END_SRC
+
+Don't forget to restore ~file-name-handler-alist~, otherwise TRAMP won't work
+and compressed/encrypted files won't open.
 
 *** Use [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html][lexical-binding]] everywhere
 Add ~;; -*- lexical-binding: t; -*-~ to the top of your elisp files. This can
@@ -382,44 +419,61 @@ permanent entry point.
 #+end_quote
 
 ** Why should I use Doom instead of rolling my own config?
-If you care about personalizing the software you use on a daily basis, even half
+Time. If you care about personalizing the software you use on a daily basis,
-as much as I do, then you probably need professional help, but you also know it
+even half as much as I do, then you probably need professional help, but you
-is time consuming. Emacs out-of-the-box is a barren wasteland with archaic
+also know it is time consuming. Emacs out-of-the-box is a barren wasteland with
-defaults. Building anything out here and getting a feel for it will take /a lot/
+archaic defaults. Building anything out here and getting a feel for it will take
-of time. Time that I've already wasted and can never get back.
+/a lot/ of time. Time that I've already wasted and can never get back.
 
 Time you could otherwise spend attending your daughter's dance recitals, that
 baseball game your son's team almost won last Thursday, or answering the court
 summons to fight for custody of your kids.
 
++ Doom has solved many problems big and small you'll likely run into at some
+  point in your Emacs career. And the problems don't end there! Let someone else
+  worry about the menial things.
++ Doom will be faster than most hand-rolled configs. Startup is one thing, but
+  Doom invests a lot of effort to improve runtime performance as well.
++ Doom's package manager (powered by straight.el) is declarative, non-rolling
+  release and (nominally) reproducible; which is unique on the Emacs distro
+  scene. Upstream issues won't surprise you as much, and you can roll back when
+  you don't have the time to deal with them.
++ It facilitates integration with the command line, which makes it easy to
+  integrate external tools with Emacs via the =bin/doom= script.
+
 Also, Doom's fast yo.
 
-** What is the meaning behind Doom's naming conventions?
+** What is the meaning behind Doom's naming convention in its source code?
 You'll find [[file:contributing.org::*Conventions][an overview of Doom's code conventions]] in the [[file:contributing.org][contributing guide]].
 
-** How can I contribute to/support Doom?
-Take a look at the [[file:contributing.org][Contributing guide]].
-
 ** What version of Doom am I running?
 You'll find the current version displayed in the modeline on the dashboard. It
 can also be retrieved using ~M-x doom/version~ (bound to =SPC h d v= by default)
 or ~doom info~ on the command line.
 
+** Is Discord the only option for interacting with your community?
+Yes. I selected it for my personal convenience and have no plans to extend our
+community to any other platform (like Matrix, IRC or Slack), or add bridges for
+them. I already have my hands full managing the one.
+
+My being so active on our Discord is owed to that fact that my friends, family
+and other communities were on Discord to begin with. My availability was the
+most important factor in choosing a platform, even if there are other platforms
+better suited to the task.
+
+Email is a possible alternative, but it is constantly swamped; expect a long
+turn-around time.
+
 * Configuration
-** Should I fork Doom to customize it?
+** Does Doom respect XDG conventions
-No. Not unless you have a good reason for doing so (and you're comfortable with
+Yes. Your private config (normally in =~/.doom.d=) can be moved to
-the git-rebase workflow). Your customization can be relegated to =~/.doom.d/=
+=~/.config/doom=.
-(or =~/.config/doom/=) entirely.
 
-If you /must/ modify Doom proper to get something done, it's a code smell.
+And as of Emacs 27, Emacs will recognize =~/.config/emacs=.
-
-Visit the [[file:getting_started.org::*Customize][Customize section]] of [[file:getting_started.org][the Getting Started guide]] for details on how to
-do this.
 
 ** How do I configure Doom Emacs?
-Canonically, your private config is kept in =~/.doom.d/= or =~/.config/doom/=.
+Canonically, your private config is kept in =~/.doom.d/= (or =~/.config/doom/=).
-Doom will prioritize =~/.config/doom=, if it exists. This directory is referred
+This directory is referred to as your ~$DOOMDIR~.
-to as your ~$DOOMDIR~.
 
 Your private config is typically comprised of an =init.el=, =config.el= and
 =packages.el= file. Put all your config in =config.el=, install packages by
@@ -427,11 +481,14 @@ adding ~package!~ declarations to =packages.el=, and enable/disable modules in
 you ~doom!~ block, which should have been created in your =init.el= when you
 first ran ~doom install~.
 
+You shouldn't need to fork Doom or modify =~/.emacs.d=. If you have to do this
+to achieve something, it can be considered a bug.
+
 Check out the [[file:getting_started.org::Customize][Customize section]] in the [[file:getting_started.org][Getting Started]] guide for details.
 
 ** How do I enable or disable a Doom module?
 Comment or uncomment the module in your ~doom!~ block, found in
-=$DOOMDIR/init.el=.
+=~/.doom.d/init.el=.
 
 Remember to run ~bin/doom sync~ afterwards, on the command line, to sync your
 module list with Doom.
@@ -653,10 +710,6 @@ tools for experienced Emacs users to skirt around it (most of the time):
 ** Can Vim/Evil be removed for a more vanilla Emacs experience?
 Yes! See the [[file:../modules/editor/evil/README.org::Removing evil-mode][Removing evil-mode]] section in [[file:../modules/editor/evil/README.org][:editor evil]]'s documentation.
 
-** Should I use ~make~ or ~bin/doom~?
-~bin/doom~ is recommended. Doom's Makefile (to manage your config, at least) is
-deprecated. It forwards to ~bin/doom~ anyway.
-
 ** When should and shouldn't I use ~bin/doom~?
 ~bin/doom~ is your best friend. It'll keep all your secrets (mostly because it's
 a shell script incapable of sentience and thus incapable of retaining, much less
@@ -710,6 +763,16 @@ doom --yes update
 YES=1 doom update
 #+END_SRC
 
+** How do I enable LSP support for <insert language here>?
+Doom supports LSP, but it is not enabled by default. To enable it, you must:
+
+1. Enable the =:tools lsp= module,
+2. Enable the =+lsp= flag for the appropriate modules you want LSP support for
+   (e.g. =:lang (python +lsp)= or =:lang (rust +lsp)=),
+3. Install the prerequisite LSP servers through your package manager or other
+   means. You can find a list of supported servers on [[https://github.com/emacs-lsp/lsp-mode#supported-languages][the lsp-mode project page]].
+4. Run ~doom sync~ on the command line and restart Emacs.
+
 * Package Management
 ** How do I install a package from ELPA?
 See the "[[file:getting_started.org::*Installing packages][Installing packages]]" section of the [[file:getting_started.org][Getting Started]] guide.
@@ -1061,5 +1124,8 @@ There are a couple ways to address this:
    when you open a file (that isn't in a project with an editorconfig file).
    This isn't foolproof, and won't work for files that have no content in them,
    but it can help in one-off scenarios.
+** "clipetty--emit: Opening output file: Permission denied, /dev/pts/29" error
+This applies to tmux users, in particular. See
+https://github.com/spudlyo/clipetty/issues/15 for a solution.
 
 * TODO Contributing