2Installation and use

2.1 Installation

Download the zip file https://nielsthl.github.io/QaDiL/QaDiL.zip. This zip file unzips into

QaDiL/
|__LICENSE  
|__qadil/
|__Notes/
|  |__Generic/
|  |__IMO21/

The Notes directory above contains a directory of the (example) project (set of notes) Generic along with a full blown set of notes for the course Introduction to Mathematics and Optimization given at Aarhus University in the fall of 2021. The qadil directory contains the python code comprising QaDiL.

2.1.1 Does the setup work out of the box?

If your setup with python and make works, the commands

cd QaDiL/Notes/Generic
make

should render compiled (html) versions of the files index.tex and intro.tex. The compiled files index.html and intro.html can then be viewed with any browser. Opening the file index.html from your browser, you should see

If you experience problems at this point, you need to make sure that python3 and make are installed and that the supplied Makefile is compatible with make on your system.

Linux and MacOS are born with python3 and make installed. Windows needs to have make installed. This can be done by downloading and running the Setup program labeled Complete package, except sources from

http://gnuwin32.sourceforge.net/packages/make.htm

This is admittedly old school (the file dates back to 2006). But make is superb software invented in 1976 and still in use.

To make Windows aware of make you need to update the environment PATH variable with

2.2 Basic use

The project directory Generic has the following content

Generic/
|__Makefile
|__index.tex
|__intro.tex
|__css/
|  |__iLaTeXen.css
|  |__index.css
|__img/
|__|__(image/png files here)
|__js/
|__|__bubble.js
|__|__openclosebuttons.js
|__|__orderquiz.js
|__|__quiz.js
|__|__sagecell.js
|__|__search.js
|__|__sidebar.js

and serves as a template for a new project/set of notes. The file index.tex contains the front page and intro.tex is an example of a chapter in the notes.

2.2.1 Compilation

The compilation of the notes is governed by Makefile, which for Generic/ looks like

COMPILER = ../../qadil/qadil.py
GENTOC = ../../qadil/gentoc.py
GENLABELS = ../../qadil/genlbls.py

all: book labels toc
book: index.html intro.html 
labels:
	python3 $(GENLABELS) .
toc:
	python3 $(GENTOC) .
%.html: %.tex
	python3 $<
clean:
	rm -f *.html *.toc *.lbl *~
zip:
	zip -r Generic.zip *.html img/ js/ css/

The entries index.html and intro.html at book: indicate that the project contains the front page file index.tex and the chapter file intro.tex. The make magic is contained in

%.html: %.tex
	python3 $<

The upshot is that if name.tex has been changed more recently than name.html, then name.tex is automatically compiled into name.html when running make.

2.3 Beginning and working on your own project

A simple way to begin or initialize your own project is to clone the Generic directory. Suppose you wish to start a project called Math101. The first step is to run the command

cp -R Generic Math101

on MacOS/Linux or

xcopy /E /I Generic Math101

on Windows systems.

Then your directory Math101 resides along Generic and looks like

Generic/
|  
Math101/
|__Makefile
|__index.tex
|__intro.tex
|__css/
|  |__iLaTeXen.css
|  |__index.css
|__img/
|__|__(image files/png files here)
|__js/
|__|__bubble.js
|__|__openclosebuttons.js
|__|__orderquiz.js
|__|__quiz.js
|__|__sagecell.js
|__|__search.js
|__|__sidebar.js

The cover file index.tex can now be modified reflecting your project/notes. Suppose that your project involves the files chapter1.tex and chapter2.tex. Then the Makefile is changed into

COMPILER = ../../qadil/qadil.py
GENTOC = ../../qadil/gentoc.py
GENLABELS = ../../qadil/genlbls.py

all: book labels toc
book: index.html chapter1.html chapter2.html 
labels:
	python3 $(GENLABELS) .
toc:
	python3 $(GENTOC) .
%.html: %.tex
	python3 $<
clean:
	rm -f *.html *.toc *.lbl *~
zip:
	zip -r Math101.zip *.html img/ js/ css/

The zip file in the Makefile is used for sharing your notes on a web server.

2.4 Sharing and uploading your notes

When your notes are ready for publication on a web server, you go through the following steps in the project directory Math101 (as an example).

make clean
make all
make zip

This gives you the file Math101.zip. If your notes are made available through the URL https://edtech.dk/Math101, then you need access to the root directory of the web server (say /var/www). From there the directory Math101 must exist. From the root of

/var/www/Math101

you simply unzip Math101.zip. Then (the cover/front page of) your notes can be accessed through

https://edtech.dk/Math101

2.4.1 Publishing on GitHub

An account on GitHub automatically gives you access to your own web pages through the repository <username>.github.io. My username is nielsthl. To publish the notes Math101.zip (from above) so that they are accessible from

https://nielsthl.github.io/Math101

I would create the directory Math101 in the repo nielsthl.github.io and unzip Math101.zip inside Math101 and then update, commit and push.