diff --git a/bin/doom b/bin/doom index 190003b8e..542b1de30 100755 --- a/bin/doom +++ b/bin/doom @@ -165,10 +165,10 @@ EXIT CODES: 3 Unrecognized user input error 4 Command not found, or is incorrect/deprecated 5 Invalid, missing, or extra options/arguments - 6-49 Reserved for Doom - 50-200 Reserved for custom user codes + 6-15 Reserved for Doom + 16-192 Reserved for the user's extensions 254 Successful run (but then execute `doom-cli-restart-script') - 255 Uncaught internal errors + 255 Uncaught critical errors SEE ALSO: https://doomemacs.org Homepage diff --git a/lisp/cli/sync.el b/lisp/cli/sync.el index b9877109e..5d654a0f9 100644 --- a/lisp/cli/sync.el +++ b/lisp/cli/sync.el @@ -36,14 +36,14 @@ This is the equivalent of running autoremove, install, autoloads, then recompile. Run this whenever you: 1. Modify your `doom!' block, - 2. Add or remove `package!' blocks to your config, - 3. Add or remove autoloaded functions in module autoloaded files, - 4. Update Doom outside of Doom (e.g. with git), + 2. Add, remove, or modify `package!' blocks to your config, + 3. Add, remove, or modify autoloaded functions in module autoloaded files, + 4. Update Doom manually (e.g. with git), 5. Move your Doom config (either $EMACSDIR or $DOOMDIR) to a new location. - 6. When you up (or down) grade Emacs itself. + 6. Up or downgrade Emacs itself (e.g. 29.1 -> 29.4). -It will ensure that unneeded packages are removed, all needed packages are -installed, autoloads files are up-to-date and no byte-compiled files have gone +Sync'ing ensures that unneeded packages are removed, needed packages are +installed, autoloads files are up-to-date, and no byte-compiled files have gone stale. OPTIONS: diff --git a/lisp/doom.el b/lisp/doom.el index 1ab1195bf..857df908d 100644 --- a/lisp/doom.el +++ b/lisp/doom.el @@ -194,7 +194,7 @@ ;;; Core globals (defgroup doom nil - "An Emacs framework for the stubborn martian hacker." + "A development framework for Emacs configurations and Emacs Lisp projects." :link '(url-link "https://doomemacs.org") :group 'emacs) @@ -206,7 +206,7 @@ "Current version of Doom Emacs.") (defvar doom-init-time nil - "The time it took, in seconds, for Doom Emacs to initialize.") + "The time it took, in seconds (as a float), for Doom Emacs to start up.") (defconst doom-profile (if-let (profile (getenv-internal "DOOMPROFILE")) @@ -307,11 +307,11 @@ For profile-local cache files, use `doom-profile-cache-dir' instead.") (file-name-concat doom-local-dir "state/")) "Where Doom stores its global state files. -State files contain unessential, unportable, but persistent data which, if lost -won't cause breakage, but may be inconvenient as they cannot be automatically -regenerated or restored. For example, a recently-opened file list is not -essential, but losing it means losing this record, and restoring it requires -revisiting all those files. +State files contain unessential, non-portable, but persistent data which, if +lost won't cause breakage, but may be inconvenient as they cannot be +automatically regenerated or restored. For example, a recently-opened file list +is not essential, but losing it means losing this record, and restoring it +requires revisiting all those files. Use this for: history, logs, user-saved data, autosaves/backup files, known projects, recent files, bookmarks. @@ -333,7 +333,7 @@ For profile-local state files, use `doom-profile-state-dir' instead.") (defconst doom-profile-dir (file-name-concat doom-profile-data-dir "@" (cdr doom-profile)) - "Where generated files for the active profile are kept.") + "Where generated files for the active profile (for Doom's core) are kept.") ;; DEPRECATED: Will be moved to cli/env (defconst doom-env-file @@ -536,14 +536,14 @@ empty. Each context describes what phase Doom is in, and may respond to. All valid contexts: cli -- while executing a Doom CLI - compile -- while byte-compilation is in progress - eval -- during inline evaluation of elisp + compile -- while byte-compiling packages + eval -- during interactive evaluation of elisp init -- while doom is formally starting up for the first time, after its - core libraries are loaded, but before user config is. - modules -- while loading modules and their files - sandbox -- This session was launched from Doom's sandbox. - packages -- when packagedefs are being read - reload -- while reloading doom") + core libraries are loaded, but before $DOOMDIR is + modules -- while loading modules configuration files (but not packages) + sandbox -- This session was launched from Doom's sandbox + packages -- while a module's packages.el's file is being evaluated + reload -- while reloading doom with `doom/reload'") (put 'doom-context 'valid-values '(cli compile eval init modules packages reload doctor sandbox)) (put 'doom-context 'risky-local-variable t) @@ -554,7 +554,9 @@ All valid contexts: (list context "Unrecognized context" valid))))) (defun doom-context-p (context) - "Return t if CONTEXT is active (i.e. in `doom-context')." + "Return t if CONTEXT is active, nil otherwise. + +See `doom-context' for possible values for CONTEXT." (if (memq context doom-context) t)) (defun doom-context-push (context)