aboutsummaryrefslogtreecommitdiff
path: root/emacs/README.org
blob: 7dc13664041d69d2c9034980838e96ed582d3711 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
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.