_____    _____           ____        _______     _______     ____________             _____
|\    \   \    \      ____\_  \__    /      /|   |\      \   /            \       _____\    \
 \\    \   |    |    /     /     \  /      / |   | \      \ |\___/\  \\___/|     /    / \    |
  \\    \  |    |   /     /\      ||      /  |___|  \      | \|____\  \___|/    |    |  /___/|
   \|    \ |    |  |     |  |     ||      |  |   |  |      |       |  |      ____\    \ |   ||
    |     \|    |  |     |  |     ||       \ \   / /       |  __  /   / __  /    /\    \|___|/
   /     /\      \ |     | /     /||      |\\/   \//|      | /  \/   /_/  ||    |/ \    \
  /_____/ /______/||\     \_____/ ||\_____\|\_____/|/_____/||____________/||\____\ /____/|
 |      | |     | || \_____\   | / | |     | |   | |     | ||           | /| |   ||    | |
 |______|/|_____|/  \ |    |___|/   \|_____|\|___|/|_____|/ |___________|/  \|___||____|/
                     \|____|

• Introduction to nowisemacs
  • Features
  • How to use
  • How to customize
• Useful Keybindings
  • leader keybinds
  • vim users should care
• Ideas behind nowisemacs
  • TL ; NR
  • Description in detail
• Things you must know before going deeper
  • Radical
  • Sacrifice for simplicity
  • Beginners are encouraged to access package website
• Optinal reading
  • Why setup instead of simpler manual configuration or full-blown use-package?
  • How to become a proficient user in emacs
• Related great solutions

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.

• 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.

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

1. Install ripgrep and fd.

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
8. If you upgrade packages or install new packages, just run make in the .emacs.d dir.

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.

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

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.

[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.

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 <s and then use tab to get a expanded src code), you should run make init-build. You can also just use make to config everything. This will overwrite ~/.emacs.d/init.el and early-init.el. Nowisemacs use this method to guarantee the init.el will not be changed by mistake custom-group or something else.

That’t to say, after installation, there are only things you need to remember for everyday use:

1. borg-assimilate for install packages, and borg-remove for remove packages.
2. make update for updates. After update, run git add . to add all updates, and make build to get them compiled.
3. make init-build if you only changed the init.org file.
4. If you modify a local package under lib such as foo, run make lib/foo to recompile only that package.

It’s suggested to read the borg for more details.

Nowisemacs uses space bars as leader key, you can find most keybindings in the Meow-Leader-Keys section here. Some common usages are as following:

I use XiaoHeShuangPin for Pinyin search, it will affect all searching jobs with vertico

Some useful keybindings for vim user:

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

Concise + High maintainability

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.

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.

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.

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.

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.

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.

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.

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.

• doom emacs
• lazycat-emacs
• centaur emacs