Table of Contents

• Introduction
• Why build Whirlwind?
• The design process and features
• Getting started
• The future

Introduction

I am excited to announce Whirlwind, a highly customizable workstation for scribing faster in-class LaTeX notes.

The design goals of Whirlwind are threefold:

• Simplicity. Experience all of your favorite LaTeX features in a streamlined markdown environment. Enjoy a tiny learning curve with minimal debugging hassles. Effortlessly maintain an organized folder structure.
• Speed. Use dozens of predefined code snippets for rapid note-taking. Set up within seconds, write effortlessly, and update with unparalleled speed.
• Versatility. Export notes directly to the web or convert them into raw LaTeX files effortlessly. Tailor your note-taking experience with highly customizable settings. Collaborate seamlessly with your favorite friends.

Join the email list for more updates.

Why build Whirlwind?

Since Microsoft Word debuted in 1983, classrooms have increasingly witnessed students opting to type their notes instead of handwriting them. While this trend was quickly adopted by humanities students, math students lagged far behind. After LaTeX was introduced in 1984 for typesetting math, it became possible for students to type math notes in class, which eventually became known as live-TeXing. Unfortunately, the experience was abysmal: LaTeX was built for typesetting large textbooks with zero emphasis on user efficiency. In particular, it features an excruciatingly slow compiler and an exceedingly confusing debugger, which has demotivated most students from live-TeXing... all the way until now. Today, we change that with the introduction of Whirlwind: a system built specifically for live-TeXing that integrates the best tools into a simple, quick, and versatile setup.

Before delving into modern efforts to improve the live-TeXing bottleneck, it's important to consider why typing math notes may be preferable to handwriting them. This was the main topic of debate in Lau's 2022 PhD thesis, which we summarize in 2 sentences: For recall tests, handwritten notes offer a slight yet statistically significant advantage over typed notes. However, this advantage for hand-writers may diminish significantly if participants are allowed to review their notes.

Following his argument, we highlight multiple advantages of typing notes instead of handwriting them:

• Short Term: Efficiency. Lau indicates that handwriting speed typically ranges from 5-25 words per minute (WPM). According to monkeytype data from July 2024, 98% of users type faster than 25 WPM, with over 22% exceeding 100 WPM (a fourfold increase in speed compared to a relatively fast hand-writer). This efficiency boost enables students to record more information during lectures, creating more comprehensive notes. Moreover, since typing the same volume of notes takes less time, students can utilize the extra time to synthesize and deeply engage with the content, instead of hurriedly jotting down information.
• Medium Term: Review. For the majority of students, the primary purpose for attending mathematics lectures is to grasp overarching concepts, rather than getting caught up in minute details. Notes serve as a tool for revisiting these concepts and delving into specific details. Typed notes are typically clearer and simpler to edit, which makes studying a more pleasant experience. Furthermore, they serve as a great reference for problem sets. Lastly, in situations where open-note exams are allowed, students with typed notes can swiftly locate and reference information, providing them with a clear advantage over their peers who rely on handwritten notes.
• Long Term: Impact. Typing notes nurtures the ability to craft clear, coherent, and logical expository papers. This is a crucial skill for aspiring research mathematicians, as proficiently conveying complex ideas is one of the main reasons why some mathematicians are more successful than others. Furthermore, high-quality lecture notes often become available on websites and exceptionally high-quality lecture notes often get published as a textbook, serving as valuable resources for future students.

Now that we've seen a plethora of reasons of why one should type notes, let's examine recent solutions to speeding up the live-TeXing process. Below is a comparison of two leading solutions: What You See Is What You Get (WYSIWYG) applications and keyboard-based text editors, across the three main design goals of Whirlwind.

Whirlwind does not belong to either of these categories. Instead, it can be thought of as a Obsidian variant that is heavily optimized for live-TeXing.

While this table highlights the advantageous features of existing apps, both of these solutions have a fatal flaw:

• WYSIWYG editors lack customizability, making it impossible to implement many powerful LaTeX features such as theorem and proof environments.
• While keyboard-based text editors enhance typing efficiency, they still rely on vanilla LaTeX systems for compilation, forcing users to deal with the underlying suboptimal compiler and debugger.

Whirlwind aims to integrate the best features from both worlds while prioritizing its three main design goals and avoiding these two fatal flaws.

The design process and features

The goal is to have the student stay within a single vscode markdown file for an entire class. Markdown was chosen as the base language over LaTeX due to it's simplicity in writing, faster compilation time, and easier debugging capabilities. As simple LaTeX is supported on top of markdown, we can use the best tools from both worlds.

We've enhanced Whirlwind's markdown files with the following additions:

• .vscode/snippets: keyboard shortcuts for reusable pieces LaTeX components, allowing students to type more with less keystrokes.
• whirlwind.css: recreates classic LaTeX theorem and proof environments, tailored for markdown.

After configuring the setup, a student only needs to do the following to start taking notes at the start of class:

• Duplicate notes/template.md, rename the file, and fill in the header
• Open the markdown preview for the markdown file (⌘K V)
• Start typing!

Here is another scenarios that a student might want features for:

• What if the student needs help finding a LaTeX symbol, drawing a commutative diagram, and so on? Run links.sh to see if any of the links will help you.

Getting started

1. Clone the github codebase locally: git clone https://github.com/pretzeledkoala/whirlwind
2. Set up the snippets file: Open command palette (⌘P) $\to$ Snippets: configure user snippets $\to$ new snippets file (both local and global work) $\to$ copy and paste /.vscode/snippets.json into this file.
3. Open /class/live.md, the markdown preview for the markdown file (⌘K V), and start taking notes!

The future

Whirlwind, despite being only a bare-bones project, is already established as a robust piece of open-source software that circumvents many common challenges in live-TeXing.

In the quest of turning Whirlwind into the premier software for live-TeXing, existing code will be improved and optimized. In addition, Whirlwind will soon incorporate more features. Here are four features at the peak of the wish list:

• Website: Allows for more rapid user onboarding without the need for a local set up.
• Bibliography Management: Tools for managing citations and bibliographies quickly, making it easier to reference sources and create well-documented notes.
• Customizable Themes: User designed themes to provide a personalized and visually appealing note-taking experience.
• Enhanced Export Options: Export directly to HTML and other requested formats.
• Image Integration: Novel optimizations for drawing and inserting diagrams in-class.

I'm excited and ready to see Whirlwind grow.

If any of this sounds interesting to you, reach out to garyhu06@gmail.com and/or join the email list.