emacs30init: Emacs Configuration with Support for Structured Editing

• Moved from GitHub
• Purpose
• Features
• What the landing page (dashboard) will resemble when first loaded
• Math Equations in README.org
  • Math equation rendering on Codeberg
  • Math equation rendering in Emacs
    • Using latex-math-preview-expression
    • Using org-preview-latex-fragment
    • Using org-preview-html-mode

Moved from GitHub

Moved from GitHub 8 April 2023 and revised.

Purpose

This configuration supports structured editing of computer code with concrete syntax trees. The built-in package tree-sitter and the new package combobulate support this kind of editing. Emacs has to be compiled with support for tree-sitter. See for a protocol for compiling Emacs 30 from source code on macOS in the section on math equations below and this one for doing likewise with Ubuntu. These protocols should work with Emacs 29.

This configuration file is also a rewrite of my basic configuration file with the packages in use listed at the top to speed up the start-up of Emacs. The package package is used to install the missing packages rather than by using the `:ensure t` option in use-package, but use-package is still used to customize packages and load packages when needed. This massive rearrangement reduced the start-up time by about 30%. Many thanks go to Jeff Bowman for this suggestion.

However, after two weeks of use, I am having trouble with not all the elisp files in the elpa folder compiled after upgrading packages. Fixing this issue can take 30 minutes. I did not have this issue when I used `:ensure t` with use-package. I recommend not updating your packages frequently; once a month may be frequent enough. Likewise, I also recommend using the emacs-server and emacsclient for instant access.

The init.el file was developed on Ventura (macOS 13.3.1), but it should be transferrable to older Mac operating systems. There are several Mac-specific lines in the basic configuration section that can be quickly switched for Linux or Windows. There are also several file paths that may need customizing. Both kinds of sites are marked with ;; ==> adjust here in the init.el file.

The manual-packages folder contains the packages that were not added via accessing MELPA. Their *.elc files will only work on Ventura with Emacs compiled the same way that I compiled mine. I removed the *.elc files before pushing the folder to this repo. You may have to byte-recompile these packages.

Features

The content of the configuration file supports my academic research writing with occasional code writing for research purposes.

• Configured for structured editing with combobulate and tree-sitter.
• Uses the Vertico and friends for completion by default. I love the in-line documentation from Marginalia.
• Fuzzy matching is turned on for use in Ido.
• Can opt in the use of Helm or Icicles.
• Helm's helm-google-suggest command is very cool. Use google-this when helm-mode is toggled off.
• Configured for org-mode, org-agenda, org-babel, and org-roam to get organized, track notes, and do literate programming.
• Supports org-pomodoro.
• Supports pdf-tools.
• Uses booksmarks+, dired+, and iscicles (the last is off by default–it is a heavy-duty completion engine for the minibuffer). These require custom installation because they are on the Emacs Wiki and not in a repository.
• Uses evil-nerd-commenter for smart commenting of lines and regions.
• Configured for Clojure, Python, and R programming.
• Supports the use of LaTeX via AUCTeX.
• Supports google-this. Select a region and enter `C-x g n` to submit as search term to Google in default browser.
• Eglot is built into this version of Emacs.

I invoke org-pomodoro with the point on a Project's headline in a org file to generate the logbook for storing the record of pomodoros. I store my lists of manuscripts, grant applications, service activities, etc in separate org files rather than in a single task.org folder because I have too many projects for a singe org file. I bookmarked the headlines for specific projects to accelerate my access to a project via the Bookmarks List buffer. I use the area under a project headline to store the logbook and over relevant information. Perhaps I would not need the bookmarks if I used org-agenda for scheduling my daily activities, which I do not because it is too hard to stay on top of everything. I just use org-agenda to schedule upcoming meetings.

Note that the bookmarks+ package runs on top of the built-in bookmarks.el package. Bookmarks+ can bookmark a much wider array of items. You can bookmark PDFs for later reading and websites of interest. I find it much easier to bookmark URLs of heavily visited sites than to store them in my private index.html file. You can also bookmark project directories and even dired buffers.

What the landing page (dashboard) will resemble when first loaded

The default image for the dashboard is the Emacs logo. I substituted another image that is included above for testing. The bottom of the dashboard has the top 10 Hackernews items. This is an attention trap, so you may want to comment it out.

The startup time should be shorter on Linux and longer on Windows.

I tried zsh and bash. There was no difference in Emacs startup times on the Mac, although these two shells differ in the startup times of new tabs. The Emacs binary starts up in a flash without an init.el.

Note that bookmarks are normally accessed via the bookmarks list buffer, but some can be listed on the dashboard automatically. For example, clicking on the icon in the dashboard of the PDF of a book opens the book in Emacs for immediate reading. The bookmarks are a way of keeping track of material that needs to be read soon. You can configure Emacs to use the bookmarks file as the startup page. With bookmarks+, you add bookmarks to websites with the C-x x c u keybinding.

You can also add bookmarks to directories. Navigate to the directory of interest in a Dired buffer. With the directory name selected in the Dired buffer, enter C-x x m to add the directory as a bookmark. Remember to save the bookmarks list buffer. I add bookmarks to my writing projects on Overleaf, to the project folder in my local drive, and to a PROJ headline in my journalArticles.org file where I store my logbook for tracking my pomodoros on a project. I can pop into any of those three locations in a flash via the click of a mouse thanks to bookmarks+ and its developer Drew Adams.

Math Equations in README.org

Math equation rendering on Codeberg

GitHub Markdown renders LaTeX equations directly with Mathjax as of May 2022. This math equation rendering works in org files on GitHub but not Codeberg. Math equation rendering works in md files on Codeberg. The work around in org files is to import the equation as an image file.

Math equation rendering in Emacs

There are many ways to preview math equations in Emacs. I listed three below because this information may be useful in the preparation of README files in Emacs. The last option may be the most attractive, but you might have to compile Emacs from source, especially if you are on a Mac.

Using latex-math-preview-expression

The LaTeX code can be rendered with the latex-math-preview package in Emacs using the latex-math-preview-expression command from this package. The package is available in MELPA. Although it is designed for use with LaTeX files, it works with org files. This package requires the program dvipng that can be installed with macports or home brew on the Mac or apt-get on Linux. The rendered equation will appear in a separate buffer.

Using org-preview-latex-fragment

To have the rendered equation appear in the org file in Emacs, use the org-preview-latex-fragment command, which is mapped to the keybinding C-c C-x C-l. Enter this keybinding with the cursor (or point in Emacs parlance) on the equation. This command uses the dvisvgm program. Install this program if missing with macports or home brew on the macOS or with apt-get on Linux.

Using org-preview-html-mode

You can also use Jacob Boxerman's org-preview-html package in Emacs to semi-automate the rendering of the math equations upon each file save of an org file. The package org-preview-html is on MELPA. The README file for this package has a nice animation.

Do M-x org-preview-html-mode to activate this minor mode in an org file. A buffer with the org file rendered to HTML will appear. The math equations were not rendered using the default eww option. I reset the configuration for org-preview-html-mode to the alternative xwidgets, and then the math equations were rendered. The rendered buffer is updated automatically every time that org buffer is saved (see image below).

To use xwidgets to get the nice black and white buffer and the rendered math equations, I had to compile Emacs from source with support for xwidgets. I did this on macOS using Ventura 13.3.1 and the following protocol on 8 April 2023.

cd ~/software
git clone git://git.sv.gnu.org/emacs emacs30
cd emacs30
git checkout -b emacs29
export LDFLAGS=-L/usr/local/Cellar/giflib/5.2.1/lib
./autogen.sh
mkdir build
cd build
../configure --with-gnutls=ifavailable --with-x-toolkit=gtk3 --with-xwidgets \
--with-cairo --with-tree-sitter --with-imagemagick --program-suffix=30 --prefix=/Users/blaine/bin
make -j8
make install -j8

# Note that the install did not go quite as planned: Nothing appeared in ~/bin. 
# I resolved the problem by the next steps.
cd nextstep
cp -R Emacs.app /Applications/Emacs30.app

# Make a profile directory
mkdir emacs30
# git clone this repo or cp -R your favorite profile into this new folder.

# I stored the following bash alias in a .bashAppAliases file that I source from my .zshrc file.
alias e30='/Applications/Emacs30.app/Contents/MacOS/Emacs --init-directory ~/emacs30 --debug-init'
e30 # Emacs should fire up.

# To check the Emacs was compiled with support for xwidgets, do the following in Emacs:

C-h v

# Enter at the prompt:

system-configuration-features RET

# You should get back a new buffer with the following. Note XWIDGETS in the second to last position.

"ACL DBUS GIF GLIB GMP GNUTLS IMAGEMAGICK JPEG JSON LCMS2 LIBXML2 MODULES NOTIFY KQUEUE NS PDUMPER \
PNG RSVG SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XIM XWIDGETS ZLIB"