+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:
- 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.
- 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
- 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
- =git add .=, then =make build= ;; 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 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(a summary)
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. After update, run =git add .= to add all updates, and =make build= to get them compiled.
- =make init-build= if you only changed the =init.org= file.
- 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 [[https://emacsmirror.net/manual/borg/][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 [[file:init.org][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 |
| Space s w | Search on website: google, aur, etc. |
| M-l | Translation Current Words (need to install SDCV) |
| M-L | Translation current selected area or user input |
| C-` | Open/fold Vterm |
| Space n | Keybinds about notes |
| Space ? | For a keybing help for meow |
I use XiaoHeShuangPin for Pinyin search, it will affect all searching jobs with vertico
** 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 |
| 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
- 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.