Update & revise docs
+ Getting Started + Add "Using/loading local packages" section + Add "Pinning packages to specific commits" section + Clarify prereqs & revise install docs + Revise package-management section + FAQ + Add package management section
This commit is contained in:
Henrik Lissner
parent
32e42a5608
commit
665b627b7c
5 changed files with 610 additions and 482 deletions
|
|
@ -32,19 +32,20 @@ to contribute to our fine corner of the interwebs.
|
|||
- [[#contributing-documentation][Contributing documentation]]
|
||||
- [[#contributing-to-dooms-manual][Contributing to Doom's manual]]
|
||||
- [[#contributing-module-documentation][Contributing module documentation]]
|
||||
- [[#help-keep-packages-up-to-date][Help keep packages up-to-date!]]
|
||||
- [[#other-ways-to-support-doom-emacs][Other ways to support Doom Emacs]]
|
||||
- [[#special-thanks][Special thanks]]
|
||||
|
||||
* Where can I help?
|
||||
+ Our [[https://github.com/hlissner/doom-emacs/issues][issue tracker]] has many issues. If you find one that you have an answer to,
|
||||
please don't hold back!
|
||||
it would be a huge help!
|
||||
+ Look for issues tagged [[https://github.com/hlissner/doom-emacs/labels/good%20first%20issue][good first issue]]. These were judged to have a low
|
||||
barrier of entry.
|
||||
+ Look for issues tagged [[https://github.com/hlissner/doom-emacs/labels/help%20wanted][help wanted]]. These tend to be a little (or a lot)
|
||||
harder, and are issues outside my own expertise.
|
||||
+ If you've encountered a bug, [[https://github.com/hlissner/doom-emacs/issues/new/choose][file a bug report]].
|
||||
+ The [[https://github.com/hlissner/doom-emacs/projects/3][development roadmap board]] is a rough timeline of what is being worked on
|
||||
and when. It will give you some idea of what will change and where you can
|
||||
and when. It will give you an idea of what will change and where you can
|
||||
redirect your efforts.
|
||||
+ The [[https://github.com/hlissner/doom-emacs/projects/2][plugins under review board]] lists third party plugins being considered (or
|
||||
rejected) for inclusion in Doom Emacs. Approved and unclaimed packages are
|
||||
|
|
@ -54,30 +55,21 @@ to contribute to our fine corner of the interwebs.
|
|||
cause) perhaps you can address them at the source.
|
||||
|
||||
* TODO Reporting issues
|
||||
So you've found a problem. Before you fire off that bug report, there are a few
|
||||
things you should try first:
|
||||
You've found a problem and you're ready to fire off that bug report. Hold up!
|
||||
Before you do that, [[file:getting_started.org::*Troubleshoot][have a look at our Troubleshooting guide]]. If none of these
|
||||
suggestions pan out, /then/ it is time to file a bug report.
|
||||
|
||||
+ Make sure your configuration (or Doom Emacs) is *not* byte-compiled. Run ~doom
|
||||
clean~ to ensure it isn't. *Byte-compilation interferes with debugging!*
|
||||
+ Run ~bin/doom refresh~ to ensure all plugins are installed and autoload files
|
||||
generated.
|
||||
+ Run ~bin/doom doctor~ to diagnose common issues with your system.
|
||||
+ Check [[file:faq.org::*Common%20Issues][Common Issues]] in the FAQ to see if yours is a known issue.
|
||||
+ If you happen to know what module(s) are relevant to your issue, check their
|
||||
documentation (press =<leader> h m= to jump to a module's documentation). Your
|
||||
issue may be documented.
|
||||
+ If possible, check if the issue can be reproduced in vanilla Emacs (Emacs
|
||||
without Doom) and/or vanilla Doom (Doom without your private config). To test
|
||||
this, use ~M-x doom/sandbox~ (bound to =<leader> h E=). [[file:getting_started.org::*Use the sandbox][A guide for using the
|
||||
sandbox can be found in the manual]].
|
||||
+ Make sure your issue hasn't already been reported by searching the [[https://github.com/hlissner/doom-emacs/issues][issue
|
||||
tracker]].
|
||||
+ Make sure your issue hasn't been resolved on the =develop= branch of Doom.
|
||||
An effective bug report is informative. Please try to provide:
|
||||
|
||||
If these suggestions haven't worked for you, it's time [[https://github.com/hlissner/doom-emacs/issues/new/choose][to write a bug report]].
|
||||
Please make sure of the following before you submit:
|
||||
+ A backtrace of all mentioned errors.
|
||||
+ A step-by-step reproduction of the issue.
|
||||
+ Information about your Doom config and system environment.
|
||||
+ Screenshots/casts of the issue (if possible).
|
||||
|
||||
** TODO Collect backtraces of any error messages
|
||||
This section will show you how to collect this information.
|
||||
|
||||
** Acquire a backtrace from errors
|
||||
See "[[file:getting_started.org::*How to extract a backtrace from an error][How to extract a backtrace from an error]]" in the [[file:getting_started.org][Getting Started]] guide.
|
||||
|
||||
** TODO Create a step-by-step reproduction guide
|
||||
|
||||
|
|
@ -165,6 +157,11 @@ contact via our [[https://discord.gg/bcZ6P3y][Discord server]] or [[mailto:henri
|
|||
|
||||
** TODO Contributing module documentation
|
||||
|
||||
* TODO Help keep packages up-to-date!
|
||||
Doom pins all its packages to reduce the likelihood of upstream breakage leaking
|
||||
into Doom Emacs. However, we may miss when a package releases hotfixes for
|
||||
critical issues. Let us know or PR a bump to our pinned packages.
|
||||
|
||||
* TODO Other ways to support Doom Emacs
|
||||
|
||||
* TODO Special thanks
|
||||
|
|
|
|||
82
docs/faq.org
82
docs/faq.org
|
|
@ -20,11 +20,6 @@
|
|||
- [[#should-i-fork-doom-to-customize-it][Should I fork Doom to customize it?]]
|
||||
- [[#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-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?]]
|
||||
- [[#how-do-i-change-where-an-existing-package-is-installed-from][How do I change where an existing package is installed from?]]
|
||||
- [[#how-do-i-disable-a-package-completely][How do I disable a package completely?]]
|
||||
- [[#how-do-i-reconfigure-a-package-included-in-doom][How do I reconfigure a package included in Doom?]]
|
||||
- [[#how-do-i-change-the-theme][How do I change the theme?]]
|
||||
- [[#how-do-i-change-the-fonts][How do I change the fonts?]]
|
||||
- [[#how-do-i-bind-my-own-keys-or-change-existing-ones][How do I bind my own keys (or change existing ones)?]]
|
||||
|
|
@ -39,6 +34,13 @@
|
|||
- [[#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]]
|
||||
- [[#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?]]
|
||||
- [[#how-do-i-change-where-an-existing-package-is-installed-from][How do I change where an existing package is installed from?]]
|
||||
- [[#how-do-i-disable-a-package-completely][How do I disable a package completely?]]
|
||||
- [[#how-do-i-reconfigure-a-package-included-in-doom][How do I reconfigure a package included in Doom?]]
|
||||
- [[#where-does-straight-clonebuild-packages-to][Where does straight clone/build packages to?]]
|
||||
- [[#defaults][Defaults]]
|
||||
- [[#why-ivy-over-helm][Why Ivy over Helm?]]
|
||||
- [[#why-are-there-no-default-keybinds-for-smartparens-for-evil-users][Why are there no default keybinds for Smartparens (for evil users)?]]
|
||||
|
|
@ -437,53 +439,6 @@ module list with Doom.
|
|||
See the "[[file:getting_started.org::*Configuration modules][Configuration modules]]" section of the [[file:getting_started.org][Getting Started]] guide for more
|
||||
information.
|
||||
|
||||
** How do I install a package from ELPA?
|
||||
See the "[[file:getting_started.org::*Installing%20packages][Installing packages]]" section of the [[file:getting_started.org][Getting Started]] guide.
|
||||
|
||||
** How do I install a package from github/another source?
|
||||
See the "[[file:getting_started.org::*Installing%20packages%20from%20external%20sources][Installing packages from external sources]]" section of the [[file:getting_started.org][Getting
|
||||
Started]] guide.
|
||||
|
||||
** How do I change where an existing package is installed from?
|
||||
See the "[[file:getting_started.org::*Changing%20a%20built-in%20recipe%20for%20a%20package][Changing a built-in recipe for a package]]" section of the [[file:getting_started.org][Getting
|
||||
Started]] guide.
|
||||
|
||||
** How do I disable a package completely?
|
||||
See 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?
|
||||
~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
|
||||
;; Takes a feature symbol or a library name (string)
|
||||
(after! evil
|
||||
(setq evil-magic nil))
|
||||
|
||||
;; Takes a major-mode, a quoted hook function or a list of either
|
||||
(add-hook! python-mode
|
||||
(setq python-shell-interpreter "bpython"))
|
||||
|
||||
(use-package! hl-todo
|
||||
;; if you omit :defer, :hook, :commands, or :after, then the package is loaded
|
||||
;; immediately. By using :hook here, the `hl-todo` package won't be loaded
|
||||
;; until prog-mode-hook is triggered (by activating a major mode derived from
|
||||
;; it, e.g. python-mode)
|
||||
:hook (prog-mode . hl-todo-mode)
|
||||
:init
|
||||
;; code here will run immediately
|
||||
:config
|
||||
;; code here will run after the package is loaded
|
||||
(setq hl-todo-highlight-punctuation ":"))
|
||||
|
||||
;; There's also `setq-hook!' for setting variables buffer-locally
|
||||
(setq-hook! python-mode python-indent-offset 2)
|
||||
#+END_SRC
|
||||
|
||||
See the "[[file:getting_started.org::*Configuring%20Doom][Configuring Doom]]" section of the [[file:getting_started.org][Getting Started]] guide for more
|
||||
explanation and examples.
|
||||
|
||||
** How do I change the theme?
|
||||
There are two ways to load a theme. Both assume the theme is installed and
|
||||
available. You can either set ~doom-theme~ or manually load a theme with the
|
||||
|
|
@ -755,6 +710,29 @@ doom --yes update
|
|||
YES=1 doom update
|
||||
#+END_SRC
|
||||
|
||||
* Package Management
|
||||
** How do I install a package from ELPA?
|
||||
See the "[[file:getting_started.org::*Installing%20packages][Installing packages]]" section of the [[file:getting_started.org][Getting Started]] guide.
|
||||
|
||||
** How do I install a package from github/another source?
|
||||
See the "[[file:getting_started.org::*Installing%20packages%20from%20external%20sources][Installing packages from external sources]]" section of the [[file:getting_started.org][Getting
|
||||
Started]] guide.
|
||||
|
||||
** How do I change where an existing package is installed from?
|
||||
See the "[[file:getting_started.org::*Changing a recipe for a included package][Changing a recipe for a included package]]" section of the [[file:getting_started.org][Getting
|
||||
Started]] guide.
|
||||
|
||||
** How do I disable a package completely?
|
||||
See 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?
|
||||
See the "[[file:getting_started.org::*Configuring packages][configuring packages]]" section of the Getting Started guide.
|
||||
|
||||
** Where does straight clone/build packages to?
|
||||
Straight clones packages to =~/.emacs.d/.local/straight/repos/REPO-NAME=, then
|
||||
later symlinks and byte-compiles them to
|
||||
=~/.emacs.d/.local/straight/build/PACKAGE-NAME= when they are "built".
|
||||
|
||||
* Defaults
|
||||
** Why Ivy over Helm?
|
||||
Short answer: ivy is simpler to maintain.
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
|
|
@ -45,6 +45,7 @@ s= (or =C-h d s=).
|
|||
** [[file:faq.org][Frequently Asked Questions]]
|
||||
- [[file:faq.org::*General][General]]
|
||||
- [[file:faq.org::*Configuration][Configuration]]
|
||||
- [[file:faq.org::*Package Management][Package Management]]
|
||||
- [[file:faq.org::*Defaults][Defaults]]
|
||||
- [[file:faq.org::Common Issues][Common Issues]]
|
||||
- [[file:faq.org::Contributing][Contributing]]
|
||||
|
|
|
|||
|
|
@ -1,7 +1,15 @@
|
|||
#+TITLE: Workflow tips, tricks & tutorials
|
||||
#+TITLE: Getting to know Doom Emacs
|
||||
#+STARTUP: nofold
|
||||
|
||||
This page is a WIP.
|
||||
Once you've installed Doom and launched it, the next step of your masochistic
|
||||
journey is to master it. This guide will walk you through many Doom-centric
|
||||
workflows you'll commonly find in a text editor (and beyond). It isn't
|
||||
exhaustive because I don't have enough lives to make it so.
|
||||
|
||||
#+begin_quote
|
||||
If you feel like we've missed something, don't hesitate to let us know! You're
|
||||
welcome to [[https://discord.gg/qvGgnVx][join us on our Discord server]].
|
||||
#+end_quote
|
||||
|
||||
* Table of Contents :TOC:
|
||||
- [[#day-1-in-doom-emacs][Day 1 in Doom Emacs]]
|
||||
|
|
@ -14,6 +22,7 @@ This page is a WIP.
|
|||
- [[#pipe-text-through-ex-commands-and-programs][Pipe text through ex commands and programs]]
|
||||
- [[#transposingswapping-text][Transposing/swapping text]]
|
||||
- [[#managing-your-projects][Managing your projects]]
|
||||
- [[#reconfiguring-emacs-on-a-per-project-basis][Reconfiguring Emacs on a per-project basis]]
|
||||
- [[#search--replace][Search & replace]]
|
||||
- [[#project-wide-text-search][Project-wide text search]]
|
||||
- [[#search--replace-1][Search & replace]]
|
||||
|
|
@ -32,6 +41,8 @@ This page is a WIP.
|
|||
- [[#using-emacs-for][Using Emacs for...]]
|
||||
- [[#writing-fiction][Writing fiction]]
|
||||
- [[#writing-papers][Writing papers]]
|
||||
- [[#note-keeping][Note-keeping]]
|
||||
- [[#a-personal-organizer][A Personal Organizer]]
|
||||
- [[#composing-music][Composing music]]
|
||||
- [[#game-development][Game development]]
|
||||
- [[#web-development][Web development]]
|
||||
|
|
@ -48,6 +59,9 @@ This page is a WIP.
|
|||
** TODO Pipe text through ex commands and programs
|
||||
** TODO Transposing/swapping text
|
||||
* TODO Managing your projects
|
||||
** TODO Reconfiguring Emacs on a per-project basis
|
||||
*** TODO .dir-locals.el
|
||||
*** TODO editorconfig
|
||||
* TODO Search & replace
|
||||
** TODO Project-wide text search
|
||||
** TODO Search & replace
|
||||
|
|
@ -66,6 +80,8 @@ This page is a WIP.
|
|||
* TODO Using Emacs for...
|
||||
** TODO Writing fiction
|
||||
** TODO Writing papers
|
||||
** TODO Note-keeping
|
||||
** TODO A Personal Organizer
|
||||
** TODO Composing music
|
||||
** TODO Game development
|
||||
** TODO Web development
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue