From a6fa2219b75a025f1843c3cb618cbab74b82973b Mon Sep 17 00:00:00 2001 From: Vedang Manerikar <ved.manerikar@gmail.com> Date: Fri, 20 Dec 2024 19:08:45 +0530 Subject: [PATCH] Update the README and make it more user-friendly. Add a link to the thread I wrote --- unravel-emacs.org | 126 ++++++++++++++++++++++++++++------------------ 1 file changed, 77 insertions(+), 49 deletions(-) diff --git a/unravel-emacs.org b/unravel-emacs.org index 2e183f1..b766dba 100644 --- a/unravel-emacs.org +++ b/unravel-emacs.org @@ -4,59 +4,27 @@ #+language: en #+options: ':t toc:nil num:t author:t email:t -This configuration is inspired from the work of [[https://github.com/protesilaos/dotfiles/blob/master/emacs/.emacs.d/prot-emacs.org][my hero Prot]]. I've -copied straight from his config file, because I think the explanations -he has created are worthwhile and should be read by everyone. Prot's -files are all prefixed with =prot-emacs-*=. I have changed this to -=unravel-*=. The reason for this is that I have picked up only what I -need and changed it based on my usage. As such, any issues you face -with this configuration are likely introduced by me. +* Quick Start +:PROPERTIES: +:CUSTOM_ID: h:2818C76B-3A6D-4676-8159-ED7BBFA45501 +:CREATED: [2024-12-19 Thu 17:06] +:END: -I use emacs on Mac OSX as my primary development environment. I -install the latest available pre-compiled Emacs (with native -compilation), as provided by Jimeh here: [[https://github.com/jimeh/emacs-builds?tab=readme-ov-file][jimeh/emacs-builds]]. +1. Install the latest available Emacs version, with native-compilation + and tree-sitter support. + - I use the latest release from [[https://github.com/jimeh/emacs-builds?tab=readme-ov-file][jimeh/emacs-builds]] on MacOSX +2. Clone this repository as your =.emacs.d= folder and start Emacs. +3. When you open any programming language file, run =M-x eglot= to + start an LSP server in the background and connect to it. +4. Go through the Table of Contents below and read details of + whichever section you are interested in knowing more about. Reach + out with questions, they will help me improve the README further! -Any quote without attribution is directly taken from [[https://github.com/protesilaos/dotfiles/blob/master/emacs/.emacs.d/prot-emacs.org][Prot's org file]]. -Prot gives even more detailed explanations in his writing, I have only -picked snippets. The interested reader should definitely go through -Prot's notes. - -To make a change to this Emacs configuration, edit this file and then -type =C-c C-v C-t= (=M-x org-babel-tangle=) to republish all the -relevant files. - -#+begin_quote -What you are now reading is not a common literate configuration of -Emacs. In most such cases, you have a generic =init.el= with a call to -the ~org-babel-load-file~ function that gets an Org document as its -value. That method works but is very slow, because we have to load Org -before starting Emacs (and Org loads a bunch of other things we do not -need at such an early stage). - -Whereas this Org document serves as (i) a single point of entry to my -Emacs setup and (ii) the origin of all of my Emacs configurations. -While I am defining everything in a single Org file, I am not actually -starting Emacs by reading this file. Rather, I am instructing Org to -put the code blocks defined herein in standalone files, organised by -scope. The end result is something where you cannot tell whether a -literate program was executed or not. - -This is the beauty of it. I can keep editing a single file as the -"source of truth", though I can still handle each of the files -individually (e.g. someone wants to see how I do a specific thing, so -I share only that file as an email attachment---no need to send over -this massive document). - -When I want to modify my Emacs setup, I edit this file and then -evaluate the following code block or do =C-c C-v C-t=. All files will -be updated accordingly. -#+end_quote - -#+begin_src emacs-lisp :tangle no :results none -(org-babel-tangle) -#+end_src +[ A short thread on the configuration: https://fosstodon.org/@vedang/113685331202099234 (2024-12-20) ] * Table of Contents :TOC: +- [[#quick-start][Quick Start]] +- [[#introduction][Introduction]] - [[#the-early-initel-file][The =early-init.el= file]] - [[#the-early-initel-basic-frame-settings][The =early-init.el= basic frame settings]] - [[#the-early-initel-tweaks-to-startup-time-and-garbage-collection][The =early-init.el= tweaks to startup time and garbage collection]] @@ -90,6 +58,7 @@ be updated accordingly. - [[#the-unravel-essentialsel-block-with-basic-configurations][The =unravel-essentials.el= block with basic configurations]] - [[#the-unravel-essentialsel-section-for-fixing-path-on-osx-exec-path-from-shell][The =unravel-essentials.el= section for fixing PATH on OSX (~exec-path-from-shell~)]] - [[#the-unravel-essentialsel-configuration-to-track-recently-visited-files-recentf][The =unravel-essentials.el= configuration to track recently visited files (~recentf~)]] + - [[#the-unravel-essentialsel-configuration-to-track-my-place-in-visited-files-saveplace][The =unravel-essentials.el= configuration to track my place in visited files (~saveplace~)]] - [[#the-unravel-essentialsel-settings-for-bookmarks][The =unravel-essentials.el= settings for bookmarks]] - [[#the-unravel-essentialsel-settings-for-registers][The =unravel-essentials.el= settings for registers]] - [[#the-unravel-essentialsel-settings-for-files][The =unravel-essentials.el= settings for files]] @@ -214,6 +183,65 @@ be updated accordingly. - [[#the-prot-windowel-library][The =prot-window.el= library]] - [[#the-vedang-personalel-module][The =vedang-personal.el= module]] +* Introduction +:PROPERTIES: +:CUSTOM_ID: h:D8816D6D-3B30-4ED5-9AE5-892029BA6C24 +:CREATED: [2024-12-19 Thu 17:05] +:END: + +This configuration is inspired from the work of [[https://github.com/protesilaos/dotfiles/blob/master/emacs/.emacs.d/prot-emacs.org][my hero Prot]]. I've +copied straight from his config file, because I think the explanations +he has created are worthwhile and should be read by everyone. Prot's +files are all prefixed with =prot-emacs-*=. I have changed this to +=unravel-*=. The reason for this is that I have picked up only what I +need and changed it based on my usage. As such, any issues you face +with this configuration are likely introduced by me. + +I use emacs on Mac OSX as my primary development environment. I +install the latest available pre-compiled Emacs (with native +compilation), as provided by Jimeh here: [[https://github.com/jimeh/emacs-builds?tab=readme-ov-file][jimeh/emacs-builds]]. + +Any quote without attribution is directly taken from [[https://github.com/protesilaos/dotfiles/blob/master/emacs/.emacs.d/prot-emacs.org][Prot's org file]]. +Prot gives even more detailed explanations in his writing, I have only +picked snippets. The interested reader should definitely go through +Prot's notes. + +To make a change to this Emacs configuration, edit this file and then +type =C-c C-v C-t= (=M-x org-babel-tangle=) to republish all the +relevant files. + +#+begin_quote +What you are now reading is not a common literate configuration of +Emacs. In most such cases, you have a generic =init.el= with a call to +the ~org-babel-load-file~ function that gets an Org document as its +value. That method works but is very slow, because we have to load Org +before starting Emacs (and Org loads a bunch of other things we do not +need at such an early stage). + +Whereas this Org document serves as (i) a single point of entry to my +Emacs setup and (ii) the origin of all of my Emacs configurations. +While I am defining everything in a single Org file, I am not actually +starting Emacs by reading this file. Rather, I am instructing Org to +put the code blocks defined herein in standalone files, organised by +scope. The end result is something where you cannot tell whether a +literate program was executed or not. + +This is the beauty of it. I can keep editing a single file as the +"source of truth", though I can still handle each of the files +individually (e.g. someone wants to see how I do a specific thing, so +I share only that file as an email attachment---no need to send over +this massive document). + +When I want to modify my Emacs setup, I edit this file and then +evaluate the following code block or do =C-c C-v C-t=. All files will +be updated accordingly. +#+end_quote + +#+begin_src emacs-lisp :tangle no :results none +(org-babel-tangle) +#+end_src + + * The =early-init.el= file #+begin_quote