Docs: hostname, config helpers, packages and keybinding notes

1 files changed, 49 insertions, 21 deletions

diff --git a/shoshimacs.org b/shoshimacs.org
index 25461f9..b2eaa23 100644
--- a/shoshimacs.org
+++ b/shoshimacs.org
@@ -29,7 +29,7 @@ scattered around. I'll attempt to have a system to keep them organized, but
 this is all an experiment.
 
 The following code block is the "table of contents" that determines what
-is tangled into the resulting elisp file:
+is "tangled" into the resulting elisp file:
 
 #+begin_src emacs-lisp :tangle yes :noweb no-export
   ;;; shoshimacs.el --- Beginner's Mind Config  -*- lexical-binding:t -*-
@@ -83,11 +83,39 @@ set and load a separate file to keep it clean:
       (make-empty-file my-custom-file))
     (setq custom-file my-custom-file)
     (load custom-file))
+#+end_src
+
+*** using a hostname to tweak the config for different machines
 
+I use this config on several machines. Using their individual hostnames,
+I can add conditional configuration for each of them as needed. As an
+example, I use a smaller font size on an older low-resolution laptop.
 
+#+begin_src emacs-lisp
   (defun my-hostname ()
     "Helper function to determine on which host Emacs is starting."
-    (string-trim (with-temp-buffer (shell-command "hostname" t ) (buffer-string))))
+    (string-trim (with-temp-buffer (shell-command "hostname" t) (buffer-string))))
+#+end_src
+
+*** shortcuts to this configuration document
+
+I use a special variable to hold the path to this org file in its
+project directory (under version control), then two functions to
+quickly jump to it and reload it.
+
+#+begin_src emacs-lisp
+  (defvar *my-config* "~/projects/shoshimacs/shoshimacs.org"
+    "Path to my main configuration file.")
+
+  (defun my-configuration ()
+    "Opens my configuration file in buffer."
+    (interactive)
+    (find-file *my-config*))
+
+  (defun my-reload-config ()
+    "Tangles and reloads a literate config with `org-babel-load-file'"
+    (interactive)
+    (org-babel-load-file *my-config*))
 #+end_src
 
 * Package Management
@@ -98,8 +126,11 @@ set and load a separate file to keep it clean:
 I've been using [[https://github.com/radian-software/straight.el#start-of-content][straight.el]]
 as my package manager since 2019 when I moved away from Spacemacs as my
 main configuration for day-to-day work. While I definitely recommend it
-as a flexible yet minimal package manager, it is certainly more useful
-to experienced Emacs users.
+as a flexible yet minimal package manager, it is targeted more to
+experienced Emacs users. In my opinion, the main benefit of something
+like straight is having all of the packages' source code cloned into
+local repos on your machine. This makes it easier to fix bugs and make
+contributions to the packages you're using.
 
 This configuration will stick to packages available through the built-in
 ~package.el~ system. As of Emacs 28, this is everything in the ELPA and
@@ -134,10 +165,12 @@ distributions may not yet have it as an available package.
 ~package.el~ provides the [[help:package-install][package-install]] command which can be used interactively
 or from Lisp code like this configuration. If a package is already installed,
 it won't try to install it again. When you install a package this way, Emacs will
-add its name to [[help:package-selected-packages][package-selected-packages]].
+add its name to [[help:package-selected-packages][package-selected-packages]]. Packages will also not be upgraded
+when running a configuration that calls ~package-install~.
 
-You can also use ~list-packages~ to browse, install and upgrade packages as
-well.
+~M-x list-packages~ provides an interface to browse, install and upgrade packages
+as well. Often, I will try something out by installing it through this UI, and
+then add it to my config with ~package-install~ if I intend to keep it around.
 
 I'll initialize the package functionality and refresh the contents to look for
 updates, and ensure any additional archives are fetched. this may have a startup
@@ -145,7 +178,7 @@ impact, but i'm not concerned about that.
 
 #+begin_src emacs-lisp
   (package-initialize)
-  (package-refresh-contents)
+  (package-refresh-contents)  ;; this will make internet requests on start up
 #+end_src
 
 ** Packages not in the default repos
@@ -154,6 +187,8 @@ Any elisp package that is in Emacs's [[help:load-path][load-path]] can be ~requi
 ~(add-to-list 'load-path (expand-file-name "some-package/" user-emacs-directory))~
 is an example of putting the directory ~some-package/~ into the load path.
 
+[[*minitest-emacs][The installation of minitest-emacs is an example in this config.]]
+
 *** COMMENT xah-fly-keys
 
 muscle memory has bound me to xah-fly-keys, and so i've decided to just
@@ -232,6 +267,12 @@ to go away.
 
 ** with-map-defkey
 
+This is an experiment in learning to write Elisp macros, all with the
+result of being able to have a mini "dsl" to define keybindings in my
+personal (or any given) keymap. The only thing being a macro really
+does in this case is to avoid evaluating the ~pairs~ arguments. A tiny
+bit of ergonomics essentially avoiding some parens and quotes 😂
+
 #+begin_src emacs-lisp
   (defmacro with-map-defkey (keymap leader &rest pairs)
     "Define a new KEYMAP with prefix key LEADER, and list of bindings in it."
@@ -247,18 +288,6 @@ to go away.
                  (cadr pair)))
              (quote ,(seq-partition pairs 2)))))
 
-  (defvar *my-config* "~/projects/shoshimacs/shoshimacs.org"
-    "Path to my main configuration file.")
-
-  (defun my-configuration ()
-    (interactive)
-    (find-file *my-config*))
-
-  (defun my-reload-config ()
-    "Tangles and reloads a literate config with `org-babel-load-file'"
-    (interactive)
-    (org-babel-load-file *my-config*))
-
   (with-map-defkey my-key-map "M-m"
     1 delete-other-windows
     a apropos
@@ -684,7 +713,6 @@ elpa. however, at the moment i must install from source:
   (package-install 'haml-mode)
 #+end_src
 
-
 ** Dev Docs
 #+begin_src emacs-lisp
   (package-install 'devdocs)