[emacs] slight rewording

[~bandali/configs] / init.org

diff --git a/init.org b/init.org
index 684bbf1..7e82b73 100644 (file)
--- a/init.org
+++ b/init.org
@@ -32,6 +32,46 @@ anyway.  So, I've opted to use =straight.el=.  I also used Borg for a
 few months, but decided to try =straight.el= which allows direct use
 of the various package archives.
 
+** Installation
+
+To use this config for your Emacs, first you need to clone this repo,
+then tangle =init.org= into =init.el=, and optionally byte-compile
+=init.el=.
+
+First, clone the repository and =cd= into it:
+
+#+begin_src sh :tangle no
+git clone https://git.sr.ht/~bandali/dotfiles ~/.emacs.d
+cd ~/.emacs.d
+#+end_src
+
+Then, decide if you would like to use a byte-compiled init file, and
+set the following variable accordingly:
+
+#+begin_src emacs-lisp
+(defvar a/byte-compiled-init t
+  "If non-nil, byte-(re)compile init.el on successful tangles.")
+#+end_src
+
+Now, first tangle =init.org=, and only if you chose to have a
+byte-compiled init, build init as well:
+
+#+begin_src sh :tangle no
+make tangle-init
+make build-init
+#+end_src
+
+If you'd like to use a byte-compiled init, it's important that it be
+recompiled whenever =init.el= is generated from an updated =init.org=.
+Not only does my setup automatically and asynchronously tangle
+=init.org= to =init.el= every time you edit and save =init.org= in GNU
+Emacs, it will also invoke =make build-init= if you set
+=a/byte-compiled-init= to =t= above, so you wouldn't have to worry
+about manually tangling and compiling your init file whenever you
+change it.  The output of the last byte-compilation in the current
+session is kept in a =*compilation*= buffer, which will automatically
+be displayed if compilation fails.
+
 * Contents                                                   :toc_1:noexport:
 
 - [[#about][About]]
@@ -256,11 +296,13 @@ and without compromising on performance.
 
 #+begin_src emacs-lisp
 (straight-use-package 'use-package)
-(if nil  ; set to t when need to debug init
-    (setq use-package-verbose t
-          use-package-expand-minimally nil
-          use-package-compute-statistics t
-          debug-on-error t)
+(if nil                             ; set to t when need to debug init
+    (progn
+      (setq use-package-verbose t
+            use-package-expand-minimally nil
+            use-package-compute-statistics t
+            debug-on-error t)
+      (require 'use-package))
   (setq use-package-verbose nil
         use-package-expand-minimally t))
 
@@ -347,7 +389,8 @@ in my shell.
 (use-package exec-path-from-shell
   :defer 1
   :init
-  (setq exec-path-from-shell-check-startup-files nil)
+  (setq exec-path-from-shell-arguments           nil
+        exec-path-from-shell-check-startup-files nil)
   :config
   (exec-path-from-shell-initialize)
   ;; while we're at it, let's fix access to our running ssh-agent
@@ -853,9 +896,13 @@ file.
   (defvar a/show-async-tangle-time nil
     "Show the time spent tangling the file.")
 
-  (defvar a/async-tangle-post-compile "make bi"
+  (defvar a/async-tangle-post-compile
+    (when a/byte-compiled-init "make build-init")
     "If non-nil, pass to `compile' after successful tangle.")
 
+  ;; TODO: look into why directly byte-compiling init.el causes a
+  ;; number of problems, including magit-status not loading (busy
+  ;; waiting).
   (defvar a/async-tangle-byte-recompile nil
     "If non-nil, byte-recompile the file on successful tangle.")
 
@@ -990,7 +1037,6 @@ There's no way I could top that, so I won't attempt to.
 
 #+begin_src emacs-lisp
 (use-package counsel
-  :defer 0.6
   :after ivy
   :bind (([remap execute-extended-command] . counsel-M-x)
          ([remap find-file]                . counsel-find-file)
@@ -1237,6 +1283,7 @@ Highlight matching parens.
 
 #+begin_src emacs-lisp
 (use-feature paren
+  :demand
   :config (show-paren-mode))
 #+end_src