[emacs] re-add installation instructions and explanations

2 files changed, 50 insertions, 5 deletions

diff --git a/Makefile b/Makefile
index 3b3a23f..37c1f3f 100644
--- a/Makefile
+++ b/Makefile
@@ -1,9 +1,6 @@
 EMACS           ?= emacs
 EMACS_ARGUMENTS ?= -Q
 
-.PHONY: all help clean build build-init quick bootstrap
-.FORCE:
-
 tangle-init: init.el
 init.el: init.org
 	@$(EMACS) $(EMACS_ARGUMENTS) \
@@ -11,9 +8,14 @@ init.el: init.org
 	--eval '(org-babel-tangle-file "init.org")' 2>&1
 
 build-init:
-	@rm -f init.elc
 	@$(EMACS) $(EMACS_ARGUMENTS) \
 	--batch -l init.el --eval '(a/build-init)' 2>&1
 
 ti: tangle-init
 bi: build-init
+
+clean: FORCE
+		@rm -f init.elc
+
+.PHONY: clean tangle-init build-init
+.FORCE:
diff --git a/init.org b/init.org
index 7b8e220..c203a71 100644
--- a/init.org
+++ b/init.org
@@ -32,6 +32,45 @@ 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.  Results of byte-compilation are kept in a =*compilation*=
+buffer, which will be automatically displayed when compilation fails.
+
 * Contents                                                   :toc_1:noexport:
 
 - [[#about][About]]
@@ -856,9 +895,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.")