docs/faq: general revision & reformatting

docs/faq.org

@@ -1,5 +1,4 @@
 #+TITLE: Frequently Asked Questions
-#+STARTUP: nofold
 
 * Table of Contents :TOC:
 - [[#general][General]]
@@ -19,8 +18,8 @@
   - [[#is-discord-the-only-option-for-interacting-with-your-community][Is Discord the only option for interacting with your community?]]
   - [[#why-is-emacsdoom-slow][Why is Emacs/Doom slow?]]
 - [[#configuration][Configuration]]
-  - [[#does-doom-respect-xdg-conventions][Does Doom respect XDG conventions]]
   - [[#how-do-i-configure-doom-emacs][How do I configure Doom Emacs?]]
+  - [[#does-doom-respect-xdg-directory-conventions][Does Doom respect XDG directory conventions]]
   - [[#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?]]
   - [[#how-do-i-change-the-fonts][How do I change the fonts?]]
@@ -73,9 +72,11 @@
 
 * General
 ** Why is it called Doom?
-It's an homage to idsoftware's classic game, whose source code was Henrik's
+It's an homage to idsoftware's classic game, whose [[https://github.com/id-Software/DOOM][source code]] was my first
-(Doom's maintainer) first exposure to programming, back in the Cretaceous period
+exposure to programming, back in the Cretaceous period (1999).
-(1999).
+
+Also, Emacs is an all consuming black hole. Its users doom themselves,
+eternally.
 
 ** Is Doom a fork of Spacemacs/Prelude/etc?
 No. I started it from scratch in mid-2014. I hadn't heard of other distros until
@@ -90,33 +91,40 @@ and layers were adopted from Spacemacs or PRed from migrating users.
 As our userbase grows, more similarities (and differences) will no doubt emerge.
 
 ** Does Doom work on Windows?
-Windows support is weaker and will lag behind Linux/MacOS support, but your
+It does, /but/ there are caveats:
-mileage will vary. Many have reported success using Doom Emacs on Windows (using
-WSL, WSL2 or scoop/chocolatey). You'll find install instructions in the [[file:getting_started.org::On Windows][Getting
-Starting guide]].
 
-If you're a Windows user, help us improve our documentation!
++ Emacs is inherently slower on Windows.
++ There are more steps to setting up Emacs (and Doom) on Windows.
++ Windows support will always lag behind macOS/Linux support, because I (and
+  many of Doom's users) don't use Windows. That means fewer guinea p--I mean,
+  pioneers, willing to test Doom on Windows.
+
+That said, Doom does have Windows users who have reported success using Doom
+Emacs on Windows (using WSL or scoop/chocolatey). The [[file:getting_started.org::On Windows][Getting Starting guide]] will walk you through what we know.
+
+Help us improve our documentation if you managed to get Doom running on Windows!
 
 ** Is Doom only for vimmers?
-No, but its maintainer /is/ a dyed-in-the-wool vimmer with almost two decades of
+No, *vim/evil emulation is optional*. However, but its maintainer /is/ a
-vim muscle memory, so the non-vim experience will be less polished. Still, Doom
+dyed-in-the-wool vimmer with almost two decades of vim muscle memory, so the
-has a growing user base of non-vim users, who continue to improve the situation,
+non-vim experience will be less polished. Still, our growing user base of
-and we welcome suggestions and contributions!
+non-vim users continue to improve the situation, and we welcome suggestions and
+contributions!
 
-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
+If you'd 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]]
-[[file:../modules/editor/evil/README.org][:editor evil]] module's documentation.
+module's documentation.
 
 ** I am a beginner. Can I use Doom?
-This isn't a choice I can make for you. Generally, if you're new to the
+This isn't a choice I can make for you. How new is "new"? Are you new to the
-terminal, to programming, or Emacs and/or vim, then Doom (and Emacs, for that
+shell? To programming in general? Or just Emacs/vim?
-matter) will be a rough place to start. Neither Doom nor Emacs are particularly
-beginner friendly. Emacs' main draw is its unparalleled extensibility, but
-anything so extensible has a learning curve.
 
-That's not to say it's impossible, or that we won't help you if you ask, but
+If all of the above is true then Emacs is a rough place to start! Doom or not.
-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
+Emacs' main draw is its unparalleled extensibility, but anything so extensible
-to external resources created by our community.
+has a learning curve. Not to suggest it's impossible, and we'll try to help you
+[[https://discord.gg/qvGgnVx][if you ask]], but expect a hefty commitment and a bumpy journey. Don't pass up on
+the [[file:index.org][Documentation]]. It'll work you through setting Doom up and includes links to
+external resources created by myself or the 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]]:
@@ -142,8 +150,8 @@ To paraphrase (and expand upon) a [[https://www.reddit.com/r/emacs/comments/6pa0
   functionality externally, like org tangling or batch processing.
 + *Doom's package manager is declarative and rolling release is opt-in.* Doom
   takes a little after nix, striving for as much config reproducibility as Emacs
-  (and git) will permit. Spacemacs uses package.el, which is rolling release
+  (and git) will permit. Spacemacs uses package.el, which is only rolling
-  only.
+  release.
 
 ** Why such a complicated package management system?
 Doom had +four+ *five* goals for its package management system:
@@ -163,10 +171,10 @@ Doom had +four+ *five* goals for its package management system:
    installation) is easier to manage.
 5. *Reproducibility:* Emacs is a tumultuous ecosystem; packages break left and
    right, and we rely on hundreds of them. By pinning our packages we achieve a
-   degree of config reproducibility and significantly limit the damage upstream
+   degree of (optional) config reproducibility and significantly limit the
-   changes can do. Better yet, we stave off having to deal with those issues
+   damage upstream changes can do. Better yet, we stave off having to deal with
-   until we are ready to. Although technical limitations prevent us from
+   those issues until we are ready to. Although technical limitations prevent us
-   achieving true reproducibility, this is better than nothing.
+   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
@@ -361,12 +369,15 @@ find more about it in:
 + [[http://nullprogram.com/blog/2016/12/22/]["Some Performance Advantages of Lexical Scope."]]
 
 ** Why is startup time important? Why not use the daemon?
-The central motivation for a config that starts up fast (aside from the learning
+It /isn't/ terribly important, but I believe a) faster software is a better user
-experience) was to have a viable alternative to vim for quick, one-shot editing
+experience, b) Emacs doesn't have to be slower than it needs to be, and c) we
-in the terminal (without ~-Q~).
+shouldn't have to manage yet-another-tool simply to get sane startup times out
+of Emacs.
 
-Besides that, it happens to facilitate:
+A fast startup time also facilitates:
 
+- Emacs as a viable alternative to vim for quick, one-shot editing in the
+  terminal (without ~-Q~).
 - Running multiple, independent instances of Emacs (e.g. on a per-project basis,
   or for nix-shell users, or to isolate one instance for IRC from an instance
   for writing code, etc).
@@ -375,16 +386,16 @@ Besides that, it happens to facilitate:
 - Faster integration with "edit in Emacs" solutions (like [[https://github.com/alpha22jp/atomic-chrome][atomic-chrome]]), and
   without a daemon.
 
-What's more, I believe a daemon shouldn't be necessary to get a sane startup
+It's up to you to decide if these are good enough reasons not to use a daemon,
-time out of Emacs.
+but it's nice to have more options, isn't it?
 
 ** How do I use Doom alongside other Emacs configs?
 I recommend [[https://github.com/plexus/chemacs][Chemacs]]. You can think of it as a bootloader for Emacs. You'll [[file:getting_started.org::*Alongside other Emacs configs (with Chemacs)][find
 instructions on how to use it with Doom in the user manual]].
 
-You'll still need a separate folder for personal configuration (=~/.doom.d= or
+You will need a separate folder for personal configuration (=~/.doom.d= or
-=~/.config/doom= by default), but the =--doomdir PATH= switch (or ~DOOMDIR~
+=~/.config/doom= by default). Use the ~DOOMDIR~ environment variable to use
-environment variable) will allow you to use a different location:
+another location:
 
 #+BEGIN_SRC bash
 # First install Doom somewhere
@@ -404,8 +415,8 @@ bin/doom run
 
 #+begin_quote
 Warning: the way ~bin/doom run~ starts Doom bypasses many of its startup
-optimizations. Treat it as a convenience for testing Doom, rather than a
+optimizations. Treat it as a convenience for testing rather than a permanent
-permanent entry point.
+entry point.
 #+end_quote
 
 ** Why should I use Doom instead of rolling my own config?
@@ -419,11 +430,13 @@ 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.
 
+Also:
 + 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's fast yo. Faster than most hand-rolled configs of similar complexity.
-  Doom invests a lot of effort to improve runtime performance as well.
+  Startup is one thing, but Doom invests just as much mind share into 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. Don't let upstream issues surprise you. Roll back or re-pin packages
@@ -431,22 +444,22 @@ summons to fight for custody of your kids.
 + 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 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]].
 
 ** What version of Doom am I running?
-You'll find the current version displayed in the modeline on the dashboard. It
+The current version of Doom is displayed in the modeline on the dashboard. It
 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. Discord is already woven into my social and work life, and was selected to
-maximize my availability to the community. I have no plans to extend it to other
+maximize my availability to the community. I don't want to juggle multiple
 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.
 
+I /am/ considering a [[https://www.discourse.org][discourse]], so we have a public knowledge base of workflows and inter-user support (since Discord isn't a great archive), but it will be some time until this is set up.
+
 Email is a possible alternative, but is constantly swamped; expect a long
 turn-around time.
 
@@ -503,12 +516,6 @@ What can you do about it?
    (=C-s=) or evil-search (=/=).
 
 * Configuration
-** Does Doom respect XDG conventions
-Yes. Your private config (normally in =~/.doom.d=) can be moved to
-=~/.config/doom=.
-
-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/=).
 This directory is referred to as your ~$DOOMDIR~.
@@ -524,6 +531,12 @@ 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.
 
+** Does Doom respect XDG directory conventions
+Yes. Your private config (normally in =~/.doom.d=) can be moved to
+=~/.config/doom=.
+
+And as of Emacs 27, =~/.emacs.d= can be moved to =~/.config/emacs=.
+
 ** How do I enable or disable a Doom module?
 Comment or uncomment the module in your ~doom!~ block, found in
 =~/.doom.d/init.el=.
@@ -576,7 +589,8 @@ Doom exposes five (optional) variables for controlling fonts in Doom, they are:
 + ~doom-font~
 + ~doom-variable-pitch-font~
 + ~doom-serif-font~
-+ ~doom-unicode-font~
++ ~doom-unicode-font~ (the fallback font for unicode symbols that your default
+  font doesn't support)
 + ~doom-big-font~ (used for ~doom-big-font-mode~)
 
 They all accept either a =font-spec=, font string (="Input Mono-12"=), or [[https://wiki.archlinux.org/index.php/X_Logical_Font_Description][xlfd
@@ -592,15 +606,19 @@ e.g.
 #+END_SRC
 
 ** How do I bind my own keys (or change existing ones)?
-The ~map!~ macro is recommended; it is a convenience macro that wraps around
+There are many options. Emacs provides a number of keybind functions:
-Emacs' (and evil's) keybinding API, i.e. ~define-key~, ~global-set-key~,
-~local-set-key~ and ~evil-define-key~.
 
-You'll find comprehensive examples of ~map!~'s usage in its documentation (via
++ ~define-key KEYMAP KEY DEF~
-=SPC h f map!= or =C-h f map!= -- also found [[file:api.org][in docs/api]]).
++ ~global-set-key KEY DEF~
++ ~local-set-key KEY DEF~
++ ~evil-define-key STATES KEYMAP KEY DEF &rest ...~
 
-You'll find a more comprehensive example of ~map!~'s usage in
+However, Doom provides a ~map!~ macro, which conveniently wraps up the above
-[[file:../modules/config/default/+evil-bindings.el][config/default/+evil-bindings.el]].
+four into a more succinct syntax. Comprehensive examples of ~map!~'s usage can
+be found in its documentation (via =SPC h f map\!= or =C-h f map\!= -- or [[file:api.org][in
+docs/api]]).
+
+There are also live examples ~map!~'s usage in [[file:../modules/config/default/+evil-bindings.el][config/default/+evil-bindings.el]].
 
 ** How do I get motions to treat underscores as word delimiters?
 (This explanation comes from [[https://github.com/emacs-evil/evil#underscore-_-is-not-a-word-character][emacs-evil/evil]]'s readme)
@@ -900,7 +918,7 @@ 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, maintainability is most important for someone that frequently tinkers
-with their editor. When I have an issue, I spend a disproportionately more time
+with their editor. When I have an issue, I spend disproportionately more time
 dealing helm than I do ivy, for little or no gain. Though both frameworks are
 excellent, the difference in complexity is reflected in their plugin ecosystems;
 ivy plugins tend to be lighter, simpler, more consistent and significantly
@@ -1136,6 +1154,7 @@ known fix for this. To work around it, you must either:
    support it),
 
 3. Install Emacs via the =emacs-mac= homebrew formula.
+
 ** Doom crashes when...
 Here are a few common causes for random crashes: