diff options
Diffstat (limited to 'emacs/README.org')
-rw-r--r-- | emacs/README.org | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/emacs/README.org b/emacs/README.org new file mode 100644 index 0000000..7dc1366 --- /dev/null +++ b/emacs/README.org @@ -0,0 +1,120 @@ +:PROPERTIES: +:UPDATED: [2023-06-12 Mon 15:28] +:END: +#+title: Yuchen Pei's GNU Emacs Configuration +#+author: Yuchen Pei +#+language: en +#+email: id@ypei.org + +I started using Emacs and ditched Vim in 2020, and the content of this +repo is the result of the config over the years. This config has +several characteristics. + +It tries to stay close to the Emacs core. If a feature is needed, the +quest to realise it always favours the Emacs core, followed by the GNU +ELPA, then the NonGNU ELPA. In the same spirit, the keybindings follow +the convention of Emacs core. + +Acknowledgement: this config is influenced by many people's configs, +most notably Protesilaos Stavrou's, both in organisation and the +actual configuration. + +Here's how the files are organised: + +- The =early-init.el= file :: The first file loaded by emacs, it + does the following + - Set the =my-profile= variable from the =EMACS_PROFILE= environment + variable. This variable controls which packages to allow or + ignore. Examples include =emms= and =erc= which causes a dedicated + emacs instance to run =emms= or =erc=, in which case most packages + are disabled. The default profile, by contrast, disables these two + packages. + - Add a hook to report the time taken at the end of initialisation + - Some optimizations + +- The =init.el= file :: The init file, it adds the =load-path=, and + =requires='s ='my-package=, ='ycp-package= and the remaining + configurations. Apart from =my-package= and =ycp-package=, the + remaining =require='s may be needed to be in a loose order. + +- The =lisp/my/my-package.el= file :: This file defines macros needed + by the rest of the initialisation. After comparing [[https://protesilaos.com/emacs/dotemacs][Protesilaos + Stavrou's]] and [[https://github.com/jwiegley/dot-emacs][John Wiegley's]] approaches, I decided to adopt the + former, with the simple =my-package= macro, given that the delay and + installation directives are sufficient for the use of this config, + and it is closer to the emacs core. Another design decision is to + not use org literate configuration. + + This file also defines functions and macros related to local + config. The local config is a mechanism for separating out variables + concerning machine-specific and/or personal information from the + emacs config files in this repository. Values of these variables are + set with the macro =my-setq-from-local= after running + =my-read-from-local-config= to read the local config in + =my-local-config=. + + Finally, this file defines some other convenience macros for + overriding functions and setting timers. + +- The =init/ycp-package.el= file :: This file determines what packages + to allow or omit depending on the profile, calls + =my-read-from-local-config= as mentioned above, starts the server, + and sets the package archives to use. It also configure package + related options, like the rest of the files in the =init= directory. + +- The =init= directory :: Files under this directory are + customisations to various parts and they use the =ycp-= prefix. Each + file is mainly organised into blocks of =my-package= and + =my-configure= defined in =lisp/my/my-package.el=. They follow some + principles: + - The delay depends on the importance and the size of the package. + - Packages are either installed from GNU or NonGNU ELPA or loaded + from packages under the =lisp= directory. + - The files are organised by functionalities, rather than specific + packages, even if some of them are named after specific + packages. For example =ycp-editing= is customisations about + editing, and =ycp-grep= is concerned with grep, occur, isearch and + so on. Some packages may belong to multiple files, in which case a + certain precedence is used to resolve this. For example, =magit= + provides vc features (=ycp-vc.el=) and is itself mostly a git + client (=ycp-client.el=). Because =ycp-client= is for things that + do not belong to other files, we place =magit= customisation in + =ycp-vc=. + - Avoid lambdas in hooks and keybinding, and name all functions + instead. + +- The =lisp/my= directory :: Files under this directory are my + extensions to other packages, as well as features that I have worked + on but have not grown into a standalone package yet. Most features + here have =my-= prefix. They are organised in a more refined manner + than files under the =init= directory: + - There are certainly files named after functionalities like under + =init=, examples including =my-buffer.el= and =my-complete.el=, + but they are strictly extensions to features that come with the + Emacs core. For packages outside of the Emacs core, individual + =my-foo.el= files are used, however small they may be. Examples + include =my-consult.el= and =my-corfu.el=. Despite the + customisation of both are inside =init/ycp-complete.el= + - There are also files that are like libraries, like =my-utils.el= + (defining common utility functions) and =my-algos.el= (algorithms + and data structure implementation) + - There are a few features without the =my-= prefix. They are more + like standalone features, but have not graduated to their own + packages or been merged into obvious packages they belong to, like + =generic-search.el= and =emms-info-ytdl.el=. + +- The =lisp= directory :: Files under this directory are packages that + cannot be installed from [Non]GNU ELPA. All but =lisp/my= and + =lisp/mis= are git submodules. Apart from =lisp/my=, packages here + belong to one of the follow cases. + - My own packages that have not been submitted to GNU ELPA yet, for + instance =hmm.el= and =buildbot.el=. + - Third party packages not in either ELPA, like =directionary-el= + and =nov.el=. + - Individual packages that are a small part of a bigger non elisp + project. They are placed under =lisp/misc=. Examples include + =cmake-mode.el=. + +- The =tempel-templates= file :: tempel templates. There's also a + gitignored =local-tempel-templates= for machine-specific and/or + personal templates. |