Docs: mostly about completion

1 files changed, 51 insertions, 5 deletions

diff --git a/shoshin-config.org b/shoshin-config.org
index 286bf5b..e8fb9b6 100644
--- a/shoshin-config.org
+++ b/shoshin-config.org
@@ -109,6 +109,8 @@ well.
 ** Packages not in the default repos
 
 Any elisp package that is in Emacs's [[help:load-path][load-path]] can be ~require~'d and used.
+~(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.
 
 *** COMMENT xah-fly-keys
 
@@ -132,6 +134,12 @@ however, it is now in non-gnu elpa! so i don't need this anymore.
 
 [[info:elisp#Native Compilation][elisp#Native Compilation]]
 
+This is a new feature in Emacs 28 that will compile all of the Elisp as native
+machine code, rather than byte-code, which can result in major performance boosts.
+Compilation will happen in the background and is logged to the
+=*Async-native-compile-log*= buffer if you are curious. Mostly you shouldn't
+have to worry about it, though you may see some compilation warnings at times.
+
 #+begin_src emacs-lisp
   (when (and (functionp #'native-comp-available-p) (native-comp-available-p))
     (setq native-comp-always-compile t
@@ -140,18 +148,18 @@ however, it is now in non-gnu elpa! so i don't need this anymore.
 
 * Keybinding
 
-keybindings are the key to playing Emacs like an instrument. no matter
+Keybindings are the key to playing Emacs like an instrument. no matter
 what you choose, keep in mind that you can always bind keys to your
 most commonly used commands to make things convienient.
 
-i highly recommend creating a personal key map bound to a "leader key".
-you initiate it with the leader, and then bind following key sequences
+I highly recommend creating a personal key map bound to a "leader key".
+You initiate it with the leader, and then bind following key sequences
 to commands you use. creating your own will make it easier to remember
 and keep organized.
 
 ** xah-fly-keys
 
-this is what i adopted to combat rsi. my muscle memory is tied into it
+This is what I adopted to combat RSI. my muscle memory is tied into it
 tightly right now. you may have other opinions about keybindings
 
 #+name: keybinding
@@ -181,9 +189,35 @@ that tie into Emacs's native completion API. This is a more modular approach
 that allows a sort of composition of extensions to completion behavior and
 its appearance in the user interface.
 
+** Two kinds of completion
+
+I want to point out that there are two distinct but similar features
+both grouped under the concept of "completion". The first is *Minibuffer*
+completion. Any time you use the minibuffer to enter commands or arguments,
+there is a completion system available to help you enter text there.
+The second is *Buffer* completion, offering candidates for text you are
+typing in any buffer. Code completion provided by a language server
+is one example. In vanilla Emacs, you get [[info:emacs#Symbol Completion][Symbol Completion]]
+for free, since Emacs itself is a running Lisp process with knowledge of
+all the defined symbols in the system.
+
+I've been confused by this in the past, because the features are so similar.
+However, completing text in an arbitrary buffer really depends on context,
+and it is much more complex than completing commands and arguments that are
+appropriate to a specific situation.
+
 ** Emacs completion styles
 
-[[info:emacs#Completion Styles][emacs#Completion Styles]]
+Emacs has a quite sophisticated way of selecting candidates for completion.
+You can read about them here: [[info:emacs#Completion Styles][emacs#Completion Styles]]
+
+I've grown used to the =flex= style of completion where typing
+=pr/s/sho.o= at the find file prompt expands to
+=projects/shoshimacs/shoshin-config.org=. There are other alternatives
+and you can even write your own. The ~completion-styles~ is a list of
+all the styles you'd like to use. It starts at the front, and if no matches
+are found, moves to the next style of completion. In this config, I just
+added =flex= to the front of the default completion styles.
 
 #+begin_src emacs-lisp
   (setq completion-styles '(flex basic partial-completion emacs22)
@@ -191,6 +225,18 @@ its appearance in the user interface.
 	tab-always-indent 'complete)
 #+end_src
 
+~completion-cycle-threshold~ defines when you want to just cycle through
+alternatives on each <TAB> (or whatever key you use) rather than presenting
+options. Setting it to 3 means if my options are "FOO, FOP, FOR" or less,
+hitting complete will change FOO->FOP, FOP->FOR, FOR->FOO.
+
+~tab-always-indent~ changes the behavior of the TAB key:
+
+#+begin_quote
+  If ‘complete’, TAB first tries to indent the current line, and if the line
+  was already indented, then try to complete the thing at point.
+#+end_quote
+
 ** [[info:consult#Top][consult]] - Consulting [[info:elisp#Minibuffer Completion][completing-read]]
 
 consult offers enhanced completion similar to ivy and helm, but with the