Revise docs/faq

docs/faq.org

@@ -64,32 +64,29 @@
   - [[#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
 ** Why is it called Doom?
-It's an homage to idsoftware's classic game, whose open sourced code was
+It's an homage to idsoftware's classic game, whose source code was Henrik's
-Henrik's (Doom's maintainer) first exposure to programming.
+(Doom's maintainer) first exposure to programming, back in the Cretaceous period
+(1999).
 
 And if you're obsessed enough with a text editor that you write a community
 config for it, you're doomed from the start.
 
 ** Does Doom work on Windows?
-Windows support is weak and generally lags behind Linux/MacOS support, so your
+Windows support is weaker and will lag behind Linux/MacOS support, but your
-mileage will vary. However, some have reported success using Doom Emacs on
+mileage will vary. Many have reported success using Doom Emacs on Windows (using
-Windows (using WSL, WSL2 or scoop/chocolatey). You'll find install instructions
+WSL, WSL2 or scoop/chocolatey). You'll find install instructions in the [[file:getting_started.org::On Windows][Getting
-in the [[file:getting_started.org::On Windows][Getting Starting guide]].
+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, because its maintainer is a
+No, but its maintainer /is/ a dyed-in-the-wool vimmer with almost two decades of
-dyed-in-the-wool vimmer with almost two decades of vim muscle memory, and he
+vim muscle memory, so the non-vim experience will be less polished. Still, Doom
-adopted Emacs in search of a better vim.
+has a growing user base of non-vim users, who continue to improve the situation,
-
+and we welcome suggestions and contributions!
-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
-accommodate a non-evil workflow.
 
 If you'd still like a go at it, see the [[file:../modules/editor/evil/README.org::Removing evil-mode][removing evil-mode]] section in the
 [[file:../modules/editor/evil/README.org][:editor evil]] module's documentation.
@@ -144,15 +141,17 @@ Doom had +four+ *five* goals for its package management system:
    superior fork, or aren't available in ELPA repos.
 3. *Performance:* lazy-loading the package management system is a tremendous
    boon to start up speed. Initializing package.el and straight (and/or checking
-   that your packages are installed) each time you start up is expensive.
+   that your packages are installed) or loading package autoloads files each
+   time you start up is expensive.
 4. *Organization:* an Emacs configuration grows so quickly, in complexity and
    size. A clear separation of concerns (configuration of packages from their
-   installation) is more organized.
+   installation) is easier to manage.
-5. *Reproducibility:* /This goal hasn't been implemented yet/, but all our work
+5. *Reproducibility:* Emacs is a tumultuous ecosystem; packages break left and
-   up until now is aimed at this goal. Emacs is a tumultuous ecosystem; packages
+   right, and we rely on hundreds of them. By pinning our packages we achieve a
-   break left and right, and we rely on hundreds of them. Eventually, we want
+   degree of config reproducibility and significantly limit the damage upstream
-   package versions to be locked to Doom's releases so that Doom installs are
+   changes can do. Better yet, we stave off having to deal with those issues
-   reproducible.
+   until we are ready to. Although technical limitations prevent us from
+   achieving true reproducibility, this is better than nothing.
 
 ** How does Doom start up so quickly?
 Doom employs a number of techniques to cut down startup time. Here are its most
@@ -199,50 +198,25 @@ helm and ivy). Here is how Doom does it:
 (add-hook 'minibuffer-exit-hook #'doom-restore-garbage-collection-h)
 #+END_SRC
 
-Another alternative (which is [[https://github.com/hlissner/doom-emacs/blob/develop/core/core.el#L269-L274][what Doom uses]]) is to use the [[https://gitlab.com/koral/gcmh/][gcmh]] package to
+Another alternative (which is [[https://github.com/hlissner/doom-emacs/blob/develop/core/core.el#L269-L274][what Doom uses]]) is the [[https://gitlab.com/koral/gcmh/][gcmh]] package; which staves
-stave off the GC until you are idle or unfocus the Emacs frame.
+off the GC until you are idle. Doom also triggers GC when you unfocus the Emacs
-
+frame.
-*** 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.
 
 *** Concatenate package autoloads
 When you install a package, a PACKAGE-autoloads.el file is generated. This file
-contains a map of autoloaded functions and snippets declared by the package.
+maps autoloaded functions and snippets to their containing package so Emacs will
-They tell Emacs where to find them when they are eventually called. In your
+know where to find them when they are used. In your conventional Emacs config,
-conventional Emacs config, every one of these autoloads files are loaded
+every one of these autoloads files are loaded immediately at startup (when
-immediately at startup (when ~package-initialize~ is called).
+~package-initialize~ is called).
 
 Since you'll commonly have hundreds of packages, loading hundreds of autoloads
 file can hurt startup times, especially without an SSD. We get around this by
 concatenating these files into one giant one when you run ~doom sync~.
 
-Emacs 27+ introduces a ~package-quickstart~ command does this for you, and
+Emacs 27+ introduces a ~package-quickstart~ command that does this for you, and
-=straight=, our package manager, does this for you too, but [[https://github.com/hlissner/doom-emacs/tree/develop/core/cli/autoloads.el][Doom Emacs has its
+=straight= (which powers our package manager) does this for you too, but [[https://github.com/hlissner/doom-emacs/tree/develop/core/cli/autoloads.el][Doom
-own specialized mechanism]] for this, topped off with a few Doom-specific
+Emacs has its own specialized mechanism]] for this, topped off with a few
-optimizations.
+Doom-specific optimizations.
 
 *** Lazy load package management system(s)
 Initializing package.el or straight.el at startup is expensive. We can save some
@@ -437,8 +411,8 @@ summons to fight for custody of your kids.
   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
+  scene. Don't let upstream issues surprise you. Roll back or re-pin packages
-  you don't have the time to deal with them.
+  when you don't have the time to deal with issues.
 + It facilitates integration with the command line, which makes it easy to
   integrate external tools with Emacs via the =bin/doom= script.
 
@@ -453,16 +427,12 @@ can also be retrieved using ~M-x doom/version~ (bound to =SPC h d v= or =C-h d
 v= by default) or ~bin/doom version~ 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
+Yes. Discord is already woven into my social and work life, and was selected to
-community to any other platform (like Matrix, IRC or Slack), or add bridges for
+maximize my availability to the community. I have no plans to extend it to other
-them. I already have my hands full managing the one.
+platforms (like Matrix, IRC or Slack), or add bridges for them, even if they are
+better suited to the task. 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
+Email is a possible alternative, but is constantly swamped; expect a long
-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
@@ -470,7 +440,7 @@ turn-around time.
 Yes. Your private config (normally in =~/.doom.d=) can be moved to
 =~/.config/doom=.
 
-And as of Emacs 27, Emacs will recognize =~/.config/emacs=.
+And as of Emacs 27, you can move =~/.emacs.d= to =~/.config/emacs=.
 
 ** How do I configure Doom Emacs?
 Canonically, your private config is kept in =~/.doom.d/= (or =~/.config/doom/=).
@@ -840,14 +810,13 @@ Long answer: Features and performance appear to be the main talking points when
 comparing the two, but as far as I'm concerned they are equal in both respects
 (not all across the board, but on average).
 
-Instead, what is important to me is maintainability. As someone who frequently
+Instead, maintainability is most important for someone that frequently tinkers
-extends and debugs his editor (and maintains a community config), I frequently
+with their editor. When I have an issue, I spend a disproportionately more time
-run up against issues with ivy and helm, but spend disproportionally more time
+dealing helm than I do ivy, for little or no gain. Though both frameworks are
-doing so with helm than I do ivy, for little or no gain. Though both frameworks
+excellent, the difference in complexity is reflected in their plugin ecosystems;
-are excellent, the difference in complexity is also reflected in their plugin
+ivy plugins tend to be lighter, simpler, more consistent and significantly
-ecosystems; ivy plugins tend to be lighter, simpler, more consistent and
+easier to hack if I want to change something. Unless you like helm /just/ the
-significantly easier to hack if I want to change something. Unless you like helm
+way it is out of the box, ivy is just the simpler choice.
-/just/ the way it is out of the box, ivy is just the simpler choice.
 
 And since I dogfood it, Ivy's integration into Doom will always be a step or
 three ahead of helm's.
@@ -941,12 +910,13 @@ you have rambunctious colleagues peppering trailing whitespace into your
 project, you need to have a talk (with wiffle bats, preferably) rather than play
 a passive-aggressive game of whack-a-mole.
 
-Here at Doom Inc we believe that operations that mutate entire files should not
+Here at Doom Inc we believe that operations that mutate entire files (or worse,
-be automated. Rather, they should be invoked deliberately, when and where it is
+projects) should not be automated. Rather, they should be invoked deliberately,
-needed, by someone that is aware of the potential consequences. This is where
+only when and where it is needed, by someone that is aware of the consequences.
-=ws-butler= comes in. It only cleans up whitespace /on the lines you've touched/
+This is where =ws-butler= comes in. It only cleans up whitespace /on the lines
-*and* it leaves behind virtual whitespace (which is never written to the file)
+you've touched/ *and* it leaves behind virtual whitespace (which is never
-so your cursor doesn't get thrown around in all that cleanup work.
+written to the file) so your cursor doesn't get thrown around in all that
+cleanup work.
 
 In any case, if you had used =ws-butler= from the beginning, trailing whitespace
 and newlines would never be a problem!
@@ -1082,6 +1052,8 @@ Here are a few common causes for random crashes:
   #+END_SRC
 
   Or disable the =:ui doom-dashboard= & =:tools magit= modules (see [[https://github.com/hlissner/doom-emacs/issues/1170][#1170]]).
++ Ligatures and some fonts can cause Emacs to crash. You may want to try a
+  different font, or disable the =:ui pretty-code= module.
 
 ** Can't load my theme; ~unable to find theme file for X~ errors
 This means Emacs can't find the X-theme.el file for the theme you want to load.
@@ -1163,5 +1135,3 @@ There are a couple ways to address this:
 ** "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