Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nowislewis/nowisemacs

A full-blown emacs configuration framework with easy abstraction
https://github.com/nowislewis/nowisemacs

Last synced: 4 months ago
JSON representation

A full-blown emacs configuration framework with easy abstraction

Awesome Lists containing this project

README 

        
#+begin_src elisp



 _____    _____           ____        _______     _______     ____________             _____

|\    \   \    \      ____\_  \__    /      /|   |\      \   /            \       _____\    \

 \\    \   |    |    /     /     \  /      / |   | \      \ |\___/\  \\___/|     /    / \    |

  \\    \  |    |   /     /\      ||      /  |___|  \      | \|____\  \___|/    |    |  /___/|

   \|    \ |    |  |     |  |     ||      |  |   |  |      |       |  |      ____\    \ |   ||

    |     \|    |  |     |  |     ||       \ \   / /       |  __  /   / __  /    /\    \|___|/

   /     /\      \ |     | /     /||      |\\/   \//|      | /  \/   /_/  ||    |/ \    \

  /_____/ /______/||\     \_____/ ||\_____\|\_____/|/_____/||____________/||\____\ /____/|

 |      | |     | || \_____\   | / | |     | |   | |     | ||           | /| |   ||    | |

 |______|/|_____|/  \ |    |___|/   \|_____|\|___|/|_____|/ |___________|/  \|___||____|/

                     \|____|

#+end_src

* Contents                                                              :toc:

- [[#introduction-to-nowisemacs][Introduction to nowisemacs]]

  - [[#features][Features]]

  - [[#how-to-use][How to use]]

  - [[#how-to-customize][How to customize]]

- [[#useful-keybindings][Useful Keybindings]]

  - [[#leader-keybinds][leader keybinds]]

  - [[#vim-users-should-care][vim users should care]]

- [[#ideas-behind-nowisemacs][Ideas behind nowisemacs]]

  - [[#tl--nr][TL ; NR]]

  - [[#description-in-detail][Description in detail]]

- [[#things-you-must-know-before-going-deeper][Things you must know before going deeper]]

  - [[#radical][Radical]]

  - [[#sacrifice-for-simplicity][Sacrifice for simplicity]]

  - [[#beginners-are-encouraged-to-access-package-website][Beginners are encouraged to access package website]]

- [[#optinal-reading][Optinal reading]]

  - [[#why-setup-instead-of-simpler-manual-configuration-or-full-blown-use-package][Why setup instead of simpler manual configuration or full-blown use-package?]]

  - [[#how-to-become-a-proficient-user-in-emacs][How to become a proficient user in emacs]]

- [[#related-great-solutions][Related great solutions]]



* Introduction to nowisemacs

Nowisemacs is a configuration framework for GNU Emacs that tends to be used in everyday scenarios with a wealth of

features but on an easy-to-maintain

basis.



It's designed by following principles:

+ *Close to metal*. As a core idea of nowisemacs, there should be less between users and vanilla emacs.

+ *Easy to use and modify*.

  Generally, the

  higher degree of abstraction, the stronger the applicability of programs. But the abstraction will increase the

  distance between users and native codes and make it more difficult for users to maintain codes. Nowiemacs trys to solve this problems in two ways:

  1. Nowisemacs uses a tiling scheme to avoid high level code abstraction, and uses an org-structure to combine all

     components to avoid the code confusion caused by the tile scheme. Thus, nowisemacs separate the code structure and

     functional structure. Users are supposed to focus only on the functional structure when using it, and focus only on code structure

     when modifying code.

  2. Nowisemacs provides many simple macros to simplify the daily configuration of users. With the help of =setup=, users

     can quickly handle the configuration cycle of a new or existing package. At the same time, users are encouraged to get the real native code

     everywhere by using =emacs-lisp-macroexpand=.

** Features

+ Affected by lazycat-emacs, there is a clear process chain in nowisemacs.

+ Easy to expand new features, easy to understand the framework.

+ Writing on the fly with a full configured org-mode, includes beautiful interfaces, a deep integration with denote and denote-citar to manage references with notes.

  Use a GTD methods to manage personal trials based on org-agenda.

+ Many useful English auxiliary writing tools and so on.

+ Universal programming solution including completion, jump, search under different path or files. With the help of *Language Server Protocol* powered by Microsoft and the great ctags

  front-end *citre*, users can easily use and expand almost all programming languages under emacs.

+ Rime integration, orderless completion everywhere.

** How to use

----------------------------------------------------------------------------------------------------------------------------

|*All configs can be seen [[file:init.org][here]], it is highly recommended that you read this document first.*|

---------------------------------------------------------------------------------------------------------------------------



Nowisemacs uses a single org file to manage all configurations. To reduce the startup time of emacs, users need to

generate =.el= configuration files before the first startup



*** Installation

**** Dependences

1. Install =ripgrep= and =fd=.

**** Nowisemacs

1. =mv ~/.emacs.d ~/.emacs.d.back= ;; Backup your original configuration

2. =git clone https://github.com/nowislewis/nowisemacs ~/.emacs.d= ;; Download nowisemacs

3. =cd ~/.emacs.d=

4. =make bootstrap-borg & make bootstrap= ;; download and build packages

5. (optional) =make native= ;; if you build emacs with native-comp, use this command to build all packages ahead-of-time.

6. =emacs= ;; Launch emacs, the download, installation and configuration of packages will be done automatically.

7. M-x

7. If you upgrade packages or install new packages, just run =make= in the =.emacs.d= dir.

*** Add packages

1. Inside emacs, run =M-x borg-assimilate=, and then input your package name and git url sequentially.

2. Run =M-x borg-active=, choose the package you just installed.

*** Remove packages

1. Inside emacs, run =M-x borg-remove=, choose the package you want to remove.

*** Update packages

1. =make update= ;; get all packages update latest

2. =git add .=, then =make build= ;; build packages

3. (optional) =make native= ;; if you build emacs with native-comp, use this command to build all packages ahead-of-time.

*** display icons correctly

[nerd-icons](https://github.com/rainstormstudio/nerd-icons.el) are necessary.  Run `M-x nerd-icons-install-fonts` to

install the resource fonts. On Windows, the fonts should be installed manually. `nerd-icons` supports bot GUI and TUI.

** How to customize

*** Change configurations

Nowisemacs use =setup.el= to config all the configuration but you can also use built-in methods, =setup= is just a simple wrapper of these methods. You can get a clear understand in anywhere by typing =M-x emacs-lisp-macroexpand=, and the =setup= code will be expanded to normal built-in methods.



Every time you make some changes on =~/.emacs.d/init.org= (eg, write down =            | Move point to the end of the buffer                                            |

| M-<            | Move point to the beginning of the buffer                                      |

| M-v            | Scroll text of selected window down ARG lines; or near full screen if no ARG   |

| C-v            | Scroll text of selected window upward ARG lines; or near full screen if no ARG |

| C-w            | Kill ("cut") text between point and mark                                       |

| e              | meow-next-word, select to the end of the next Nth word                         |

| b              | meow-back-word, select to the beginning the previous Nth word                  |

| f              | meow-find, find the next N char read from minibuffer                           |

| c c            | meow-change, kill current selection and switch to INSERT state                 |

| n              | moew-search, search and select with the car of the current regexp-search-ring  |

| v a            | text-object based operation (arounding objects)                                |

| v i            | text-object based operation (inside objects)                                   |

| m + any letter | save the current location into registers with name "letter"                    |

| ' + any letter | load the location registers of name "letter"                                   |

| g d            | jump to definition                                                             |

| g D            | jump to reference                                                              |

| g a            | code actions                                                                   |



Press =Space ?= to get a view of keybings under normal status.

* Ideas behind nowisemacs

** TL ; NR

Concise + High maintainability

** Description in detail

*** Understand Emacs from the perspective of system architecture

1. Emacs can be regarded as a virtual machine of the lisp language. And the core function of a virtual machine is to

   manage memory.

2. The built-in variables and functions defined by Emacs are set together with the user-defined functions, and they are

   all equivalent as First-class citizen.

3. Therefore, most of the user's operation on Emacs correspond to a function, and users can modify all external or

   built-in variables and functions. In other words, users should regard themselves as internal schedulers of the

   system, not external users.

*** Packages and related configurations should be simple

Simplicity doesn't mean that the number of packages used is few, or the interface is ugly, but that the following

concepts should be met as far as possible:

1. Try to use built-in functions to reduce redundancy. The rational use of these APIs can greatly reduce the external

   maintenance burden.

2. Packages should be designed simple and flexible, which will reduce dependencies.

3. Packages with less code or active updates will have higher priority.

4. Try to use the default configuration or select packages with enough default configuration to avoid the update burden

   caused by numerous hacks.

*** Balance

I like rich functionality, which allows me to have suitable solutions for various scenarios. Usually adding a functionality

will increase the complexity of configurations. Nowisemacs looks for a balance between functionality and complexity by

"concise" choices.

* Things you must know before going deeper

** Radical

1. Nowisemacs always uses the latest emacs version and compile it locally, so there may be some incompatible when you use an older version.

2. Fast iteration, no option of "all" packages. If there is a package with a cleaner code implementation than the one

   used now, or fewer dependencies, or better functionality, only *one* will be left.

** Sacrifice for simplicity

The code will be kept iteratively updated and thus less stable, because any duplicated or useless code will be

   updated or optimized immediately, with little consideration for compatibility.

** Beginners are encouraged to access package website

Many functions provided by packages are invoked manually as APIs with =M-x= with few key bindings. Users are encouraged to

access the website of packages to get a comprehensive understanding.

* Optinal reading

** Why setup instead of simpler manual configuration or full-blown use-package?

As mentioned above, nowisemacs hoped to reduce the abstraction level of configuration as much as possible while meeting

practical requirements, so as they facilitate the understanding of configuration maintenance code.



After heavy use for a period of time, I gave up use-package and leaf. They have a high degree of abstraction and thus

complex mechanisms, which is not conducive to understanding and debugging.



At the suggestion of Lazycat, a great Emacs contributor, I have used the native way to configure Emacs for a while. I

really like this idea, it is clear and easy to drill down. No black box here.



But if you use the native way, you will find that there is a lot of duplicated codes, which make the work tedious and

increase the maintenance work. =setup= comes into view. First, =setup= is almost indistinguishable from the native

way at the level of abstraction. =setup= is actually a bunch of simple macros to generate code. And the code generated

after macro-expand is almost the same as native methods. So =setup= is also clear and easy to drill down as native way.



The function of =setup= is to turn these repeated codes into simple calls, which are equivalent to defining one place, but

can be used everywhere.



What's more, =setup= can easily change the code context such as keymap context or hook context. It's easy to get complex

configuration clear.

** How to become a proficient user in emacs

I would like to first give my own experience through these difficulties for beginners:



1. I have been using doom emacs for a long time, which is a great configuration framework for vim users. During that, I

   was mainly familiar with various cool or practical functions of emacs, which greatly aroused interest and made it

   clear what an excellent emacs should be and what does it look like.

2. Then I found I need some personal features for my daily work, but it's hard to achieve an end because it's always

   easy to get stuck in a lot of code traps. I don't know how to sort out my own process.

3. After some time I found a very native configuration, lazycat-emacs, and learned how to configure all the code in the lowest-level way, including manually managing packages, manually controlling the loading order, etc.

4. After understanding what I need to set after startup. Things I needed to figure out became clear again:

   + First, to implement whatever features I need.

   + Second, to control the abstraction level of the configuration so as not to increase maintenance pressure.



The configuration of nowisemacs is not there all at once. There is an article "Understanding emacs from the perspective of operating system architecture" that gave me a good inspiration, let me try to use emacs from the perspective of an emacs itself rather than an emacs user. As an emacs, how can I meet user needs?



+ First, when users give me requirements, I need to know how to combine existing functions to achieve this requirement;

+ Second, I can find or implement these functions.



With this idea in mind, nowisemacs tries to separate functional structure and code structure to solve this problem.

* Related great solutions

+ [[https://github.com/hlissner/doom-emacs][doom emacs]]

+ [[https://github.com/manateelazycat/lazycat-emacs][lazycat-emacs]]

+ [[https://github.com/seagle0128/.emacs.d][centaur emacs]]