docs/getting_started: remove redundant section

And mark unfinished sections with TODO.
This commit is contained in:
Henrik Lissner 2019-10-29 23:43:39 -04:00
parent 63dfd298ca
commit 412674b165
No known key found for this signature in database
GPG key ID: 5F6C0EA160557395

View file

@ -63,10 +63,7 @@
- [[#a-backtrace-from-bindoom][A backtrace from `bin/doom`]] - [[#a-backtrace-from-bindoom][A backtrace from `bin/doom`]]
- [[#evaluating-elisp-on-the-fly][Evaluating Elisp on-the-fly]] - [[#evaluating-elisp-on-the-fly][Evaluating Elisp on-the-fly]]
- [[#how-to-determine-the-origin-of-a-bug][How to determine the origin of a bug]] - [[#how-to-determine-the-origin-of-a-bug][How to determine the origin of a bug]]
- [[#acquiring-a-backtrace][Acquiring a backtrace]] - [[#testing-in-dooms-sandbox][Testing in Doom's sandbox]]
- [[#enabling-debug-on-error-1][Enabling ~debug-on-error~]]
- [[#a-backtrace-from-bindoom-1][A backtrace from ~bin/doom~]]
- [[#use-the-sandbox][Use the sandbox]]
- [[#opening-the-sandbox][Opening the sandbox]] - [[#opening-the-sandbox][Opening the sandbox]]
- [[#launching-the-sandbox][Launching the sandbox]] - [[#launching-the-sandbox][Launching the sandbox]]
- [[#testing-packages-in-the-sandbox][Testing packages in the sandbox]] - [[#testing-packages-in-the-sandbox][Testing packages in the sandbox]]
@ -1122,39 +1119,7 @@ are couple things you can do:
(=gR=) to evaluate code, (=gR=) to evaluate code,
** How to determine the origin of a bug ** How to determine the origin of a bug
*** Acquiring a backtrace ** Testing in Doom's sandbox
If you encounter an error while using Doom Emacs, you're probably about to head
off and file a bug report (or request help on [[https://discord.gg/bcZ6P3y][our Discord server]]. Before you do,
please generate a backtrace to include with it.
To do so you must enable ~debug-on-error~, then recreate the error.
**** Enabling ~debug-on-error~
There are three ways to enable `debug-on-error`:
1. Start Emacs with ~emacs --debug-init~. Use this for errors that occur at
startup.
2. Evil users can press =SPC h d d= and non-evil users can press =C-h d d=.
3. If the above don't work, there's always: ~M-x toggle-debug-on-error~
Now that ~debug-on-error~ is on, recreate the error. A window should pop up with
a backtrace.
**** A backtrace from ~bin/doom~
To acquire a backtrace from an error emitted from `bin/doom`, re-run the same
command with the ~-d~ / ~--debug~ switches or the `DEBUG` environment variable:
#+BEGIN_SRC sh
doom -d refresh
doom --debug install
DEBUG=1 doom update
#+END_SRC
*Note:* switch order is important. ~-d~ / ~--debug~ /must/ come right after
~doom~.
*** Use the sandbox
"The sandbox" is one of Doom Emacs' features; it is a test bed for running elisp "The sandbox" is one of Doom Emacs' features; it is a test bed for running elisp
in a fresh instance of Emacs with varying amounts of Doom loaded (none at all, in a fresh instance of Emacs with varying amounts of Doom loaded (none at all,
all of it, or somewhere in between). This can be helpful for isolating bugs to all of it, or somewhere in between). This can be helpful for isolating bugs to
@ -1166,7 +1131,7 @@ developers of the relevant plugins or, perhaps, the Emacs devs themselves.
Otherwise, it is best to bring it up on the Doom Emacs issue list, rather than Otherwise, it is best to bring it up on the Doom Emacs issue list, rather than
confusing and inundating the Emacs community with Doom-specific issues. confusing and inundating the Emacs community with Doom-specific issues.
**** Opening the sandbox *** Opening the sandbox
There are three common ways to access the sandbox: There are three common ways to access the sandbox:
+ =SPC h E= (for evil users) + =SPC h E= (for evil users)
@ -1177,7 +1142,7 @@ Doing any of the above will pop up a ~*doom:sandbox*~ window. What you enter
into this buffer will be executed in the new instance of Emacs when you decide into this buffer will be executed in the new instance of Emacs when you decide
to launch it. to launch it.
**** Launching the sandbox *** Launching the sandbox
You have four options when it comes to launching the sandbox: You have four options when it comes to launching the sandbox:
- =C-c C-c= :: This launches "vanilla Emacs". Vanilla means nothing is loaded; - =C-c C-c= :: This launches "vanilla Emacs". Vanilla means nothing is loaded;
@ -1197,7 +1162,7 @@ You have four options when it comes to launching the sandbox:
All new instances will inherit your ~load-path~ so you can access any packages All new instances will inherit your ~load-path~ so you can access any packages
you have installed. you have installed.
#+END_QUOTE #+END_QUOTE
**** Testing packages in the sandbox *** Testing packages in the sandbox
Instances of Emacs launched from the sandbox have inherited your ~load-path~. Instances of Emacs launched from the sandbox have inherited your ~load-path~.
This means you can load packages -- even in Vanilla Emacs -- without worrying This means you can load packages -- even in Vanilla Emacs -- without worrying
about installing or setting them up. Just ~(require PACKAGE)~ and launch the about installing or setting them up. Just ~(require PACKAGE)~ and launch the
@ -1209,5 +1174,5 @@ sandbox. e.g.
(call-interactively #'magit-status) (call-interactively #'magit-status)
#+END_SRC #+END_SRC
*** Bisecting your private config ** TODO Bisecting your private config
*** Bisecting Doom Emacs ** TODO Bisecting Doom Emacs