(credit: Alex Tudorache)

Introduction

UnderGrad is an open source note taking software/toolkit specifically designed for Mathematics and Physics Undergraduates. It's built with Python (3.9.6) and comes with a GUI as well as a library of snippets (shortcuts) for LaTeX.

YOU CAN VIEW THE UNDERGRAD WIKI HERE

This README contains 4 main sections:

• Introduction (above)
• Section I: Setup and Configuration
• Section II: Tutorial and Snippet Dictionary
• FAQs

Section I is split into three parts:

• Part I: Prerequisites
• Part II: Setup VSCode with LaTeX
• Part III: Setup and Configure UnderGrad

Section I: Setup and Configuration

Part I: Prerequisites

Before you start setting up UnderGrad, make sure you have:

• Windows 10 or 11
• Package manager 'Winget' (this should already be installed if you're running Windows)
• VS Code (you can either go to the end of the guide and follow the steps or install VSCode on your own from the official VSCode website: https://code.visualstudio.com/download)
• Python (version 3.9.6) (again, you can install this from here: https://www.python.org/downloads/)

Part II: Setup VSCode with LaTeX

Step 1: Install MiKTeX

Open Command Prompt (CMD). You can either type the following command in full:

winget install MiKTeX.MiKTeX && miktex packages update && winget install StrawberryPearl.StrawberryPearl && exit

or follow step-by-step until Step 3:

winget install MiKTeX.MiKTeX

This should install LaTeX on your system.

Step 2: Update MiKTeX and Configure

Use the terminal and update MiKTeX using this command:

miktex packages update

Step 3: Install Strawberry Perl

latexmk and latexindent are the two essential LaTeX modules that UnderGrad and VSCode need to be able to produce .tex files and convert them into viewable PDFs. They both require Perl to run. So, you now need to install 'Strawberry Perl' on your system using this command:

winget install StrawberryPerl.StrawberryPerl

VERY IMPORTANT: CLOSE AND REOPEN YOUR TERMINAL AFTER INSTALLATION IS COMPLETE!

Step 4: Configure your Perl Environment

If you have multiple Perl installations, you might need to prioritize Strawberry Perl. (If your system didn't have Perl before you just installed it, you can skip to Step 5):

1. First, check which Perl is being used:

where perl
perl --version

2. If the wrong Perl is being used (Not Strawberry), temporarily set the correct path:

set PATH=C:\Strawberry\perl\bin;C:\Strawberry\c\bin;%PATH%

Most users can ignore this as you probably don't have any version of perl on your system.

Step 5: Install Some Important Perl Modules

Install the modules needed by latexindent by running these commands on your terminal (one-by-one):

cpan YAML::Tiny
cpan File::HomeDir
cpan Log::Log4perl
cpan Log::Dispatch

Step 6: Install Some Important MiKTeX Packages

Again, you can either copy this command in full:

miktex packages install latexindent && miktex packages install latexmk && winget install Microsoft.VisualStudioCode

or follow steps 7 and 8 separately.

Install the required LaTeX packages (one-by-one):

miktex packages install latexindent
miktex packages install latexmk

Step 7: Install and Configure VS Code

Install VS Code with winget (if not already installed):

winget install Microsoft.VisualStudioCode

Step 8: Configure VS Code Settings

Open VS Code settings (bottom left corner), click the JSON icon in the top right corner of the navigation bar. You should now be in a file called 'setting.json'. Check to see if the following is included in this file (if it isn't, copy and paste from here):

{
  "editor.wordWrap": "on",
  "editor.formatOnSave": true,
  
  // LaTeX Workshop configuration
  "latex-workshop.latex.tools": [
    {
      "name": "latexmk",
      "command": "latexmk",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-pdf",
        "%DOC%"
      ]
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "latexmk",
      "tools": [
        "latexmk"
      ]
    }
  ],
  "latex-workshop.view.pdf.viewer": "tab",
  "latex-workshop.latex.clean.fileTypes": [
    "*.aux",
    "*.bbl",
    "*.blg",
    "*.idx",
    "*.ind",
    "*.lof",
    "*.lot",
    "*.out",
    "*.toc",
    "*.acn",
    "*.acr",
    "*.alg",
    "*.glg",
    "*.glo",
    "*.gls",
    "*.fls",
    "*.log",
    "*.fdb_latexmk",
    "*.snm",
    "*.nav",
    "*.dvi"
  ],
  "latex-workshop.latex.autoBuild.run": "onSave",
  
  // LaTeX formatting configuration
  "latex-workshop.formatting.latex": "latexindent",
  "latex-workshop.formatting.latexindent.path": "latexindent",
  "latex-workshop.formatting.latexindent.args": [
    "-c", "%DIR%/", "%TMPFILE%", "-y=defaultIndent: '%INDENT%'"
  ],
  
  // Language-specific formatting settings
  "[latex]": {
    "editor.defaultFormatter": "James-Yu.latex-workshop",
    "editor.formatOnSave": true
  },
  "[json]": {
    "editor.defaultFormatter": "vscode.json-language-features"
  },
  "[jsonc]": {
    "editor.defaultFormatter": "vscode.json-language-features"
  }
}

Step 9: Test Your Setup

1. Create a test file test.tex:

\documentclass[11pt, a4paper]{article}
\usepackage[left = 2cm, right = 2cm, top = 2cm, bottom = 2cm]{geometry} % Set margins
\usepackage{graphicx} % Required for inserting images
\usepackage{amsmath} % Required for Writing Mathematics
\usepackage{amssymb} % Contains some mathematical symbols
\usepackage{amsfonts} % Contains some mathematical fonts

% This is a template file for writing Mathtematics Lecture Notes.

\title{Title}
\author{Author}

\begin{document}
\maketitle

\textbf{Definition:} This is a definition.

\textbf{Remark:} This is a remark.

\textbf{Example:} This is an example.

\begin{equation}
    F_{12}=\frac{Q_1Q_2}{4\pi\varepsilon_0r^2}
\end{equation}

\end{document}

Part III: Setup and Configure UnderGrad

Outline

• Download the 'UnderGrad' folder and unzip it.
• Run the following command in your terminal replacing "[CustomTkinter Path]" and "[Path to Python Script]" with the relevant paths on your device.

pip install pyinstaller && pyinstaller --noconfirm --onedir --windowed --add-data "[CustomTkinter Location]/customtkinter;customtkinter/"  "[Path to Python Script]"

• In 'UnderGrad\', open 'config.json' and configure as you see fit:

Config	Description	Options
gen_type	Defines whether or not you'd like to create a separate folder for each LaTeX bundle (a LaTeX bundle consits of the .tex file, PDF and other files which are needed to integrate LaTeX with VSCode)	"boxed" (creates separate folders) or "free" (doesn't create separate folders)
gen_path	Defines the path where you'd like to save your files	-
home_path	Defines UnderGrad\ path	-
instant_open	Defines whether or not you want to open .tex files upon generation	"true" or "false"

• Create a shortcut for 'UnderGrad\UnderGrad.exe' on your desktop and/or your taskbar.

Section II: Tutorial and Snippet Dictionary

Snippet Dictionary

Snippet	Description	Maps To
beq	Creates an equation environment
list	Creates a list environment
def	Starts a definition	\textbf{Definition:}
lem	Starts a lemma	\textbf{Lemma:}
thm	Starts a theorem	\textbf{Theorem:}
cor	Starts a corollary	\textbf{Corollary:}
rem	Starts a remark	\textbf{Remark:}
example	Starts an example	\textbf{Example:}
section	Begins a new numbered section
ssection	Begins a new unnumbered section
frac	Creates a fraction	\frac{}{}
ileq	Starts in-line equation environment	$$
nl	Starts new line	\\
inn	Writes 'belongs to' or 'in' symbol	\inn
indef	Writes an indefinite integral
integ	Writes a definite integral (between 0 and 1 by default)
sum	Writes a finite sum (between 1 and n by default)
infsum	Writes infinite sum
prod	Writes finite product (between 1 and n by default)
der	Writes derivative operator (with respect to x by default)	\frac{d}{dx}
pder	Writes partial derivative operator (with respect to x by default)	\frac{\partial}{\partial x}
dot	Time derivative	\dot{}
ddot	Double time derivative	\ddot{}
mat2	Writes 2x2 identity matrix
mat3	Writes 3x3 identity matrix
mat4	Writes 4x4 identity matrix
rset	Writes 'real' set symbol	\mathbb{R}
cset	Writes 'complex' set symbol	\mathbb{C}
zset	Writes 'integer' set symbol	\mathbb{Z}
nset	Writes 'natural' set symbol	\mathbb{N}
bra	Writes 'bra' bracket. NEEDS \usepackage{braket}	\bra{}
ket	Writes 'ket' bracket. NEEDS \usepackage{braket}	\ket{}
braket	Writes 'braket' bracket. NEEDS \usepackage{braket}	\braket{}
vec	Writes bold vector notation	\textbf{}
vvec	Writes arrow vector notation	\vec{}
cross	Writes cross product	\times{}
dott	Writes dot product	\cdot{}

MORE SNIPPETS WILL BE ADDED IN THE FUTURE!

However, you don't have to wait for the latex.json file to be updated to get new commands: as you'll need to download it for UnderGrad to work with the above commands, you can add your own custom commands (snippets) to the file or change the ones already in it. (The above snippets are just the ones I myself frequently use)

Tutorial

Using UnderGrad with the GUI

Upon opening UnderGrad, you will be greeted with the following screen (without Roman numerals)

I will prompt you to name your file.

Once you give a name and click OK, VSCode should open a .tex file with your pre-defined template. You can open previous projects by clicking II. You'll be directed to your generation path.

III allows you to change your configurations. You may edit the config.json file in VSCode. Similarly, you may also edit your template in VSCode by clicking IV. Clicking it will open your temp.tex file in VSCode where you're then free to edit it.

If you'd like, you can also use UnderGrad through the terminal through V. (see next section)

Finally, VI will direct you to this page.

Using UnderGrad with the Terminal

This is a feature in development

You can also use UnderGrad via the Terminal. The terminal will open in the UnderGrad context (UnderGrad path) and you may execute the following commands

Command	Description
newfile	Create new .tex file. Takes one argument: document title.
notes	Opens your generation path in file explorer.
helpme	Lists all available commands and definitions.
config.json	Opens config file.

As this feature is still in development, the first 3 commands require a python environment and need the .py extension. i.e. to create a new file, you're really running the newfile.py script directly. (python newfile.py DOC_NAME)

FAQs

What's wrong with the icon?

Sometimes, the UnderGrad icon won't appear on installation. This can easily be fixed:

• First, right click on your desktop shortcut and open the 'Properties' window.
• Next, click on the 'Change Icon' option in the middle at the bottom.
• Click on the 'browse' button and navigate to the 'UnderGrad' folder (wherever you installed it).
• Select either .ico files in the folder and click 'Open'.
• Finally, click 'Apply' and 'Save'.

This should change the default Python .exe icon the UnderGrad logo.