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

Introduction to nowisemacs
Useful Keybindings
- leader keybinds
- vim users should care
Ideas behind nowisemacs
- TL ; NR
- Description in detail
Things you must know before going deeper
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

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

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

Install ripgrep and fd.

Nowisemacs

mv ~/.emacs.d ~/.emacs.d.back ;; Backup your original configuration
git clone https://github.com/nowislewis/nowisemacs ~/.emacs.d ;; Download nowisemacs
cd ~/.emacs.d
make bootstrap-borg & make bootstrap ;; download and build packages
(optional) make native ;; if you build emacs with native-comp, use this command to build all packages ahead-of-time.
emacs ;; Launch emacs, the download, installation and configuration of packages will be done automatically.
M-x
If you upgrade packages or install new packages, just run make in the .emacs.d dir.

Add packages

Inside emacs, run M-x borg-assimilate, and then input your package name and git url sequentially.
Run M-x borg-active, choose the package you just installed.

Remove packages

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

Update packages

make update ;; get all packages update latest
make bootstrap ;; build packages
(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 <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.

Everyday use

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

borg-assimilate for install packages, and borg-remove for remove packages.
make update for updates.
make for everything else( eg, after you changed init.org, or changed packages, you can just run make to configure everything well) related to packages.

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

Some explanation about package configurations/setup.el

Useful Keybindings

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:

leader keybinds

Button	Function
Space b	Buffer-Menu
Space s s	Search the current buffer page
Space s b	Search buffer/file/pdfs using blink-search
Space s d	GREP operation on the current path
Space s f	Find operation of the current path
Space s i	Open imenu
Space f p	Open Personal Config
Space Tab	Open the tabspace management menu
M-L	Translation The current area or user input
M-L	Translation Current Words (need to install SDCV)
M-`	Open/fold Vterm
C-x /	Search on website: google, aur, etc.
Space n	Keybinds about notes

vim users should care

Some useful keybindings for vim user:

Button	Function
C-a	Go to the beginning of the current visible line
C-e	Go to the end of the line, but before ellipsis, if any
M->	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

Ideas behind nowisemacs

TL ; NR

Concise + High maintainability

Description in detail

Understand Emacs from the perspective of system architecture

Emacs can be regarded as a virtual machine of the lisp language. And the core function of a virtual machine is to manage memory.
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.
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:

Try to use built-in functions to reduce redundancy. The rational use of these APIs can greatly reduce the external maintenance burden.
Packages should be designed simple and flexible, which will reduce dependencies.
Packages with less code or active updates will have higher priority.
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

Nowisemacs always uses the latest emacs version and compile it locally, so there may be some incompatible when you use an older version.
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:

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

loonor / nowisemacs

Contents