Jcs Emacs Save

Emacs configuration works across all OSs

This is Jen-Chieh Shen's emacs configuration started from Casey Muratori's Emacs configuration. It has been repeatedly utilized and modified since 2015 and is now very different from his configuration.

I wouldn't claim this is the best Emacs config, but this is the best config to myself. If you wish to learn Emacs, this could be a good start, because this configuration has been rewritten basically from scratch. Hopefully, this config will help someone who is new or struggle to Emacs. This configuration should work on most OSs, indicating Windows, macOS, and Linux.

Emacs itself supports multiple programming languages. I managed all the programming languages I personally used. I dabble in numerous technologies, incorporating hardware, firmware, and software. Here is the list of programming languages I know and are extended from this configuration.

• ActionScript 2.0 or 3.0 / Ada / Agda / AppleScript / Assembly Language
• BASIC / Batchfile / Beancount
• C / C++ / C# / Clojure / / COBOL / Common Lisp / Crystal / CSS / CUDA / Cython
• Dart / Dockerfile
• Elixir / Elm / Emacs Lisp / Erlang
• F# / Fountain
• GLSL / Go / GDScript / Groovy
• Haskell / Haxe / HLSL / HTML
• Idris / INI
• Java / JavaScript / JSON / JSX / Julia
• Kotlin
• LESS / Lisp / Lua
• Makefile / Markdown / Mermaid / Mint
• Nim / Nix / Noir
• Object Pascal (Delphi) / Objective-C / OCaml
• P4 / Pascal / Perl / PHP / PowerShell / Properties / Python
• R / Racket / Ruby / Rust
• Sass / Scala / SCSS / ShaderLab / Shell script / SQL / Swift
• Terraform / TOML / TSX / TypeScript
• Verilog / VHDL / Vimscript / Vue
• XML
• YAML
• Zig

This configuration polished and goes toward to the modern text editor, or even better, it goes beyond modern IDE. e.g. Atom, Brackets, Sublime Text 2 or 3, Visual Studio Code, etc.

Table of Contents

• 📚 Philosophy
• 📰 News
• 💾 Installation
• 🕒 Startup Time
• 🏆 Features
  • Highlight
  • Details
• 📁 Package Archives
• 🏆 Powered by
  • Functionalities
• 🧰 Write your own customization
• ❓ FAQ
• Contribute

📚 Philosophy

I have experienced many different kinds of IDEs and text editors. But I’ve had a hard time finding the best tool to use. I’ve jumped from one working field to another trying to find something that suits my needs. So instead of struggling with the tool itself, I chose Emacs and configured the entire thing from scratch, to suit my needs.

Here are a few goals that I want this config to accomplish.

• Having the same set of key bindings across different IDEs and text editors as many as possible.
• Having the same font and theme across different OSs and environments.
• Automating trivial or redundant tasks.
• Improve user experiences approach to modern text editor or IDE.
• Make compatible with most features work inside the terminal as well.

Having these implementations makes my life easier, and having a genuinely portable workspace, which is great because it lets me work on different machines efficiently, without having to get used to a new IDE.

📰 News

Here is the list of few essential and recent changes to this configuration.

• 9.0.2 - Replace package topsy with breadcrumb-mode for better UX
• 8.2.2 - Add emp as the default Music Player
• 8.2.1 - Replace package docstr with ts-docstr for better parsing capability
• 8.2.0 - Drop support for Emacs 27.x
• 8.1.0 - Remove config tabify/untabify save, and replace it with whitespace-cleanup-mode.
• 8.0.1 - Switch from ivy to vertico.
• 8.0.0 - Move everything to .emacs.d. (#32)
• 7.1.0 - Replace quelpa with github-elpa.
• 7.0.0 - Switch from quickhelp to box for company frontend.
• 6.5.0 - Add pinned archive feature to package module.

💾 Installation

To install, clone this repo to ~/.emacs.d, i.e. ensure that the init.el contained in this repo ends up at ~/.emacs.d/init.el:

git clone https://github.com/jcs-emacs/jcs-emacs ~/.emacs.d

Then startup Emacs; will automatically install all necessary packages due to this configuration.

‼️[ATTENTION]‼️ -- MAKE SURE YOU INSTALLED THE CORRECT VERSION OF EMACS!

🕒 Startup Time

(in seconds)

The average startup time for this configuration is around 15 to 25 seconds. You can use the command emacs-init-time to check the startup time on your machine. Not quite sure what causes that much performance, hopefully, I'm able to lower the startup time down to 5 to 15 seconds.

Edit 1: After version 5.3.2, the average startup time is around 5 to 15 seconds. Solved this issue by removing the unnecessary require keyword load file and using :defer keyword with use-package package to delay some packages load time.

📝 P.S. Here is a great article about Speeding Up Emacs written by Anurag Peshne.

Edit 2: Using esup package to test and optimize the configuration. Call package-refresh-contents only when package installation is needed. By doing the thing, lower the startup time from around 4 to 8 seconds.

📝 P.S. Some good hints from one StackExchange question, What can I do to speed up my start-up? answered by Jordon Biondo.

📝 P.S. The above cases are tested on Windows. Other OSs are not Windows should start within a second.

🏆 Features

Highlight

Here is the list of the major highlights of this configuration. Hope you would like my taste!

• Out of the box - Out of the box anywhere.
• Cross Platform - Work on all operating systems, including the terminal.
• Fast Startup - Lazy loading for all unnecessary packages on startup.
• Old-Fashioned - Doesn't use any beautiful GUI because it may not work in the terminal.
• Multiple Languages - Support multiple programming languages.
• Consistent - Having the same coding experience in different major modes.
• Easy to use - Design close to other modern text editors. It shouldn't spend you too much time.
• Dual Windows - Design for people who like multiple windows opened simultaneously.
• Keyboard Focused - You can do everything by using the keyboard and the mouse are just optional.

Details

This is the list of features that are built-in to this configuration. These features are heavily based on my personal habits, and so these could be very tiny things. But I believe details make things better and make life smoother.

• Auto Install Package - Automatically installs the package that this config relies on.
• Build Run - Implementation for executing script for building and running the software.
• Capital Word - You can navigate/kill word by seeing capital letter.
• Changelog Helper - Help to create changelog while creating CHANGELOG file using template.
• Consistent Key Bindings - Has consistent key bindings across all modes.
• Curly Bracket Modes - Use curly bracket depends on different mode.
• Display File - Utility function to use to view a file on the other window.
• Charset Table - Built-in functions that displays character sets.
• Enhanced Multiple Cursors
• Similar Multiple Cursors - Mark with cursor by similarity.
• VS Multiple Cursors - VSCode like methods to mark and unmark multiple cursor.
• Fast Incremental Search - Fast keys for incremental search forward/backward to the cursor is currently pointing.
• Indent Control - Generic control the indentation level for each mode, for more information see indent-control.
• License Helper - Help to create license while creating LICENSE file using template.
• Mini State - Mini mode state use to visually see what backend is the config currently running. (Deprecated)
• Explicit States - Automatcially switch mini state depends on certain circumstances.
• Modern Text Editor - Design to have the preset settings close to modern text editors but faster.
• Multiple Output - Handle multiple output/compilation buffers.
• Navigate Blank Line - Use C-<up> and C-<down> to navigate previous and next blank line.
• Navigate Table - Navigate org-mode's table easier by using arrow keys.
• Preview HTML - Preview rendered HTML file on the other window.
• Switch Window - Fast keys switch between windows quickly.
• Trim Trailing Whitespace - Remove trailing spaces and tabs automatically on save.
• Visualize Undo/Redo - Improved the user experience on undoing and redoing by showing the undo-tree-visualizer at the other window.
• VS Curly Bracket - Visual Studio IDE like curly bracket implementation.
• VS Multiple Terminal - VSCode like multiple shell control.
• VS Navigate Word - Visual Studio IDE like navigating between word implementation.

📁 Package Archives

A list of package archives that this configuration uses.

• GNU - The standard GNU ELPA
• NonGNU - The standard NonGNU ELPA
• MELPA - Milkypostman’s ELPA
• JCS-ELPA - Jen-Chieh Shen's ELPA for this confinguration

📝 P.S. Here is a good talk comparing all package archives from a StackExchange question, What are the practical differences between the various Emacs Package Repositories? answered by Tikhon Jelvis.

🏆 Powered by

Here is the list of all packages that powered and made this configuration works. Thanks to all the package maintainers; this configuration cannot be made without them, and if you wish to support them, you can go to this elisp-maintainers repo/site and search for the maintainer you want to support. There should be some kind of methods to support the maintainer you wish to.

Functionalities

• Abbreivation Definition - powered by project-abbrev.
• Alt-Codes - powered by alt-codes.
• Auto Completion - powered by company.
• Auto Highlight Symbol - powered by auto-highlight-symbol-mode.
• Banner - powered by dashboard.
• Binary/Hex Editor - powered by hexl-mode.
• Breadcrumb - powered by breadcrumb.
• Collaborative Editing - powered by togetherly.
• Completion Frontend - powered by vertico.
• Context Menu - powered by context-menu-mode.
• Document String - powered by ts-docstr.
• End of Line - powered by show-eol.
• Execute Commands - powered by compile.
• File Explorer - powered by treemacs.
• File Header - powered by file-header.
• Folding/Unfolding - powered by ts-fold.
• Font - powered by use-ttf.
• Goto Declaration/Definition - powered by dumb-jump.
• Highlight Indentation - powered by highlight-indent-guides.
• Highlight Matched Pairs - powered by show-paren-mode.
• Highlight Same Region - powered by region-occurrences-highlighter.
• Indentation Management - powered by indent-control.
• Language Server Protocol - powered by lsp-mode.
• Line Annotation - powered by line-reminder.
• Line Numbers - powered by display-line-numbers and linum.
• Minimap - powered by minimap.
• Mode Line - powered by jcs-modeline.
• Multiple Cursor - powered by iedit and multiple-cursors.
• Multiple Terminal - powered by multi-shell.
• Music Player - powered by emp.
• Navigation/Searcher - powered by searcher and isearch-project.
• Package Archive - see here.
• Package Management - powered by use-package and github-elpa.
• PDF Viewer - powered by doc-view-mode and ghostscript.
• Project Management - powered by project.
• Recent Files - powered by recentf.
• Regexp - powered by re-builder and visual-regexp.
• Remote Access - powered by tramp.
• Restart Emacs - powered by restart-emacs.
• Scroll Bar - powered by auto-scroll-bar.
• Shell - powered by shell and exec-path-from-shell.
• Smooth Scrolling - none, originally powered by sublimity.
• Snippet - powered by yasnippet.
• Startup Screen - powered by dashboard.
• Syntax Check - powered by flycheck.
• Tab Bar - powered by centaur-tabs.
• Tags - powered by gtags.
• Theme - powered by vs-dark-theme and vs-light-theme. (For more info see here)
• Todo - powered by hl-todo.
• Undo/Redo - powered by undo-tree.
• Version Control Management - powered by magit.
• Video Player - none.
• White Space - powered by whitespace.

🧰 Write your own customization

You can customize the configuration by editing the file located at ~/.emacs.d/site-lisp/config.el. You should put all your own customize code there, then other than that are the core files.

❓ FAQ

Here is the list of Frequently Asked Questions.

• List of FAQ

🛠️ Contribute

If you would like to contribute to this project, you may clone and make pull requests to this repository. Or you can clone the project and establish your own branch of this tool. Any methods are welcome!

⚜️ License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

See LICENSE for details.