#+STARTUP: overview
#+PROPERTY: header-args:emacs-lisp :lexical t

* ANUSTART

To welcome in Emacs 28 I intend to re-aquaint myself with the application
and its ecosystem. I've been perusing the packages available through the
default ELPA and non-gnu ELPA repos and trying to put together the various
things that I've grown accustomed to.

However, with a beginner's mind, I've been trying to avoid going down the
same old idiosyncratic paths. Courting a bit of discomfort in order to learn
what newcomers might experience coming to Emacs in this current version.

** Overview

This document is a journal, manual, and a program at once. I'm no expert at
writing a document like this. If you happen to be reading it, the journal
nature may be confusing. Over time, the journal will be incorporated into the
bits that are a manual, solidified knowledge gained through the experience.

The program bits will be tangled into [[file:shoshin-config.el]]. As a program, it
requires a certain structure from top to bottom. Here, the snippets may be
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:

#+begin_src emacs-lisp :tangle yes :noweb yes
  ;;; shoshimacs.el --- Beginner's Mind Config  -*- lexical-binding:t -*-

  ;;; Package Management
  <<package-management>>

  ;;; Completion
  <<completion>>

  ;;; Editing
  <<editing>>

  ;;; Programming
  <<programming>>

  ;;; Projects
  <<projects>>

  ;;; External Services
  <<external-services>>

  ;;; User Interface
  <<user-interface>>
#+end_src

* Package Management
:PROPERTIES:
:header-args:emacs-lisp+: :noweb-ref package-management :noweb-sep "\n\n" :results silent
:END:

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.

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
non-gnu ELPA package repositories. 

** ELPA and Non-GNU ELPA

ELPA packages have their copyright assigned to the FSF, which is a requirement
for any code to be included into Emacs itself. ELPA packages are thus the
most likely to be merged into Emacs as a new feature. Some, like EMMS, are
likely to continue as "add-on" optional features only some users may choose.

Non-gnu ELPA is relatively new, and does not require copyright assignment
to the FSF. Packages are added to both repositories through the emacs-devel
mailing list and the maintainers there. It intends to extend the packages
available to the base Emacs installation while providing a bridge to inclusion
in ELPA or Emacs proper at some time in the future.

*** Add non-gnu ELPA to Emacs < 28

Emacs 28 is the first version to include non-gnu ELPA by default. Some
distributions may not yet have it as an available package.

#+name: add-nongnu-elpa
#+begin_src emacs-lisp
  (when (string< "28.1" emacs-version)
    (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/")))
#+end_src

** Installing Packages

~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]].

You can also use ~list-packages~ to browse, install and upgrade packages as
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.

*** COMMENT xah-fly-keys

muscle memory has bound me to xah-fly-keys, and so i've decided to just
manually install it by cloning the repo and adding it to the

#+begin_src shell :var dir=(expand-file-name "xah-fly-keys" user-emacs-directory) :tangle no
  git clone https://github.com/xahlee/xah-fly-keys $dir
#+end_src

#+begin_src emacs-lisp
  (add-to-list 'load-path (expand-file-name "xah-fly-keys/" user-emacs-directory))
  (require 'xah-fly-keys)
  (xah-fly-keys-set-layout "qwerty")
  (xah-fly-keys t)
#+end_src

however, it is now in non-gnu elpa! so i don't need this anymore.

* Keybindings
** xah-fly-keys

this is what i adopted to combat rsi and have trained my muscle memory to.

#+begin_src emacs-lisp
  (package-install 'xah-fly-keys)
  (xah-fly-keys-set-layout "qwerty")
  (setq xah-fly-use-control-key nil
	xah-fly-use-meta-key nil)
  (xah-fly-keys t)
#+end_src

* Completion
:PROPERTIES:
:header-args:emacs-lisp: :noweb-ref completion :noweb-sep "\n\n" :results silent
:END:

Completion is a huge part of my experience using Emacs. I have been on
an evolving journey of from the basic type of terminal tab completion 
to spaceship level UI implemented as almost a sub-application in Emacs.

This configuration is aiming at using a new crop of completion enhancements
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.

** [[info:consult#Top][consult]] - Consulting [[info:elisp#Minibuffer Completion][completing-read]]

consult offers enhanced completion similar to ivy and helm, but with the
built in completing read functionality of the minibuffer.

#+begin_src emacs-lisp
  (package-install 'consult)
#+end_src

main entry point would be ~consult-buffer~. however, there are many consult
commands that can enhance any completing read function.  ~consult-themes~ for
example.

i had a bit of a mess with it at first, because i'd implemented my own
solution to a quirk of theme loading. enabling themes is additive,
and can cause unexpected results. so i added [[info:elisp#Advising Functions][advice]]
to ~load-theme~ to automatically disable the old one before enabling
the new. it seems like consult does this as well as switching themes
/as you narrow your selection/.

*** consult keybindings

** corfu

#+begin_src emacs-lisp
  (package-install 'corfu)
#+end_src

** marginalia

#+begin_src emacs-lisp
  (package-install 'marginalia)
#+end_src

** embark

#+begin_src emacs-lisp
  (package-install 'embark)
#+end_src

** vertico

#+begin_src emacs-lisp
  (package-install 'vertico)
#+end_src

* Editing
:PROPERTIES:
:header-args:emacs-lisp: :noweb-ref editing :noweb-sep "\n\n" :results silent
:END:
** [[info:emacs#Matching][electric pair mode]]
I've been using smartparens -> (bookmark-jump "smartparens package") in my
main config. electric pair mode does some of what smartparens does out of
the box. what i'm missing is the generalized ~sp-hybrid-slurp~ or
whatever it was called. but using the built in is good for now. further
config might get what i want with vanilla built ins.

#+begin_src emacs-lisp
  (electric-pair-mode)
#+end_src

** markdown mode
#+begin_src emacs-lisp
  (package-install 'markdown-mode)
#+end_src

* Programming
:PROPERTIES:
:header-args:emacs-lisp: :noweb-ref programming :noweb-sep "\n\n" :results silent
:END:
** Languages
*** Javascript

#+begin_src emacs-lisp
  (package-install 'json-mode)
#+end_src

** Dev Docs
#+begin_src emacs-lisp
  (package-install 'devdocs)
#+end_src
* Projects
:PROPERTIES:
:header-args:emacs-lisp: :noweb-ref projects :noweb-sep "\n\n" :results silent
:END:

** project.el
* External Services
:PROPERTIES:
:header-args:emacs-lisp: :noweb-ref external-services :noweb-sep "\n\n" :results silent
:END:

Packages that enable communication via HTTP or connect with external APIs or other
resources outside of Emacs and/or the local machine.

** plz - http library

this is an http library that intends to solve some of the "pain points" of url.el.
i ran into some of them trying to download and install the Victor Mono font used
by my configuration. the downside of ~plz~ is that it is dependent on ~curl~, rather
than being pure elisp. however, this is a non-issue for me, especially since my
use case had devolved into using ~make-process~ to call ~wget~ and then implement
a "callback" with a process sentinel. kinda neat, but maybe too much.

#+begin_src emacs-lisp
  (package-install 'plz)
#+end_src

the sourcehut package in this config also depends on ~plz~

** sourcehut
there's a new package in GNU ELPA for some basic interaction with the sr.ht http api.
i'm interested to try it out since i still pay for the account, plus the forge is
free software and could be self-hosted if it comes to it.

it also depends on ~plz~ which is another new package providing a nicer API for
HTTP requests I was going 

#+begin_src emacs-lisp
  (package-install 'srht)
  (setq srht-username "shoshin")
#+end_src

an API token is stored in my ~.authinfo~ file.

* UI
:PROPERTIES:
:header-args:emacs-lisp: :noweb-ref user-interface :noweb-sep "\n\n" :results silent
:END:
** basic Emacs UI tweaks

#+begin_src emacs-lisp
  (scroll-bar-mode nil)
  (fringe-mode '(8 . 0))
  (tab-bar-mode t)
  (display-battery-mode t)
#+end_src

** [[file:elpa/darkroom-0.3/darkroom.el::;;; Commentary:][darkroom]] - distraction free writing

the notes suggest using ~darkroom-tentative-mode~ which auto switches
depending on the window layout currently in use.

#+begin_src emacs-lisp
  (package-install 'darkroom)
#+end_src

*** comp warnings
#+begin_example
Warning (comp): darkroom.el:337:13: Warning: Use keywords rather than deprecated positional arguments to `define-minor-mode' Disable showing Disable logging
Warning (comp): darkroom.el:338:9: Warning: reference to free variable ‘darkroom-tentative-mode’ Disable showing Disable logging
Warning (comp): darkroom.el:361:13: Warning: Use keywords rather than deprecated positional arguments to `define-minor-mode' Disable showing Disable logging
Warning (comp): darkroom.el:365:10: Warning: function ‘darkroom-tentative-mode’ defined multiple times in this file Disable showing Disable logging
#+end_example

** Fonts 
For code, I've grown fond of Victor Mono.

#+begin_src emacs-lisp
  (set-frame-font "Victor Mono" t t t)
#+end_src

*** COMMENT Attempt to install the font via Emacs, url.el and ~make-process~

in the end, this "works" but isn't very useful. the font cache needs to be updated
before Emacs runs for the font to register anyway. This will instead be implemented
as a shell script that can be run as a pre-req before initializing emacs.

however, i did learn a bit about [[info:elisp#Sentinels][Sentinels]] they are kinda neat.

#+begin_src emacs-lisp
  ;; this actually doesn't work right, because the process unzipping starts
  ;; before the file is completely written i think.
  (url-retrieve "https://rubjo.github.io/victor-mono/VictorMonoAll.zip"
		#'victor-mono-download-callback)

  (make-process :name "getting victor mono"
		:buffer "*Download Victor Mono*"
		:command '("wget" "--output-document=/home/shoshin/.fonts/VictorMonoAll.zip"
			   "https://rubjo.github.io/victor-mono/VictorMonoAll.zip")
		:sentinel #'victor-mono-download-callback)

  (defun victor-mono-download-callback (process event)
    (if (string-equal "finished\n" event)
	(let ((default-directory  "~/.fonts/VictorMono"))
	  (unless (file-directory-p default-directory)
	    (make-directory default-directory))
	  (make-process :name "unzipping victor mono"
			:buffer "*Unzip Victor Mono*"
			:command `("unzip" ,(expand-file-name "~/.fonts/VictorMonoAll.zip"))
			:sentinel #'victor-mono-sentinel))))

  (defun victor-mono-sentinel (process event)
    (print event)
    (if (string-equal "finished\n" event)
	(progn (message "works!")
	       (make-process :name "run fc-cache" :command '("fc-cache")))))
#+end_src

** Highlights
*** [[help:global-hl-line-mode][global-hl-mode]]
i enjoy having the current line highighted as a visual cue. 

#+begin_src emacs-lisp
  (global-hl-line-mode t)
#+end_src

can be toggled with <leader> l 2 

*** COMMENT lin-global-mode 
Make `hl-line-mode' more suitable for selection UIs

add other hooks to ~lin-mode-hooks~

#+begin_src emacs-lisp
  (setq my-lin-mode-hooks
	'())
#+end_src

#+begin_src emacs-lisp
  (package-install 'lin)
  (require 'lin)
  (setq lin-face 'lin-blue)
  (mapc (lambda (e) (cl-pushnew e lin-mode-hooks)) my-lin-mode-hooks)
  (lin-global-mode)
#+end_src
** Themes

#+begin_src emacs-lisp
  (setq my-chosen-themes
	'(cyberpunk-theme dracula-theme))
  (mapc #'package-install my-chosen-themes)
#+end_src

** windresize

#+begin_src emacs-lisp
  (package-install 'windresize)
#+end_src