If you have a LaTeX document which
- is large (probably several hundreds of pages at least)
- is regularly updated
- needs to be externally referenced often
you will run into the problem that
- large PDFs are not easily navigable
- PDFs of any size are not very searchable
- the internal numbering changes often, making external references outdated
Gerby addresses these problems by providing an online tag-based view, instead of just having a big PDF. Gerby is tailored towards making large online textbooks and reference works more accessible.
A tag is a short identifier (usually four symbols long, e.g.
02DX), that is permanently associated to a label in your LaTeX document. If the number associated to the label changes, because you move it or because the text before the label changes, the tag remains the same.
Anything in your document which has a number (sections, theorems, equations, …) needs to have a label associated to it in your LaTeX code, and then in a separate file (the tags file) you set up a dictionary between labels and tags. This file looks like
0000,first-definition 0001,first-lemma 0002,second-lemma 0003,second-definition 0004,second-lemma 0005,main-theorem
albeit it much longer probably.
At this point you only have a LaTeX document, and a tags file. These are all the ingredients you need for the next step.
When everything has been assigned a tag, Gerby will convert your LaTeX document into small HTML files, one for each tag. We then import these into the database, which in turn is used by a Flask website. This way you get
- a page for every tag
- easy navigation around your document
- a fulltext search
- the bibliography is taken care of
- there are statistics pages for each tag
- it is possible to comment on each tag, so that readers can interact when there are questions, typos or mistakes
The main example is the Stacks project, and Gerby was originally developed for this purpose.
We are currently working on Kerodon, which will be a collection of works by Jacob Lurie.
If you are interested in using the system for your own project and have questions, please get in touch.
How to use it
The process consists of 3 parts, which we will explain in detail below.
plastexon your LaTeX file and tags file
- run the import script on the output from step 2
- start the server
The result of each step is
- a large number of small HTML and auxiliary files
- an SQLite3 database containing the output of step 1, together with all the metadata
- a local web server that serves your Gerby instance
The following detailed instructions allow you to run a local copy of the Stacks project website. Currently the website code is tailored towards this, but one can modify the Jinja2 templates for your own project. The instructions are based on the continuous integration code for Gerby, and a possibly more up-to-date version of the instructions can be extracted from that Makefile.
We are in the process of making the code more generic, please get in touch if you are interested in running your own instance.
First you need to install a modified version of plasTeX. We assume that you are using Python 3 by default, change accordingly if that is not the case. Perform the following in the location where you want to install plasTeX:
git clone https://github.com/gerby-project/plastex.git
git checkout gerby
pip install .
The following is only required if you have a complicated bibliography containing mathematical expressions in the titles, and can be safely skipped. Perform the following steps where you want to install
git clone https://github.com/live-clones/pybtex.git
git apply ../no-protected-in-math-mode.patch
pip install .
Now we can run plasTeX on the Stacks project’s LaTeX code. Perform the following steps where you want to place the Stacks project.
git clone https://github.com/stacks/stacks-project.git
echo yes | python2 scripts/add_tags.py
plastex --renderer=Gerby book.tex
If all went well, you now have a directory called
WEB/book/ containing several tens of thousands small HTML files, and files named
The next step is to install Gerby, and import the result from the previous step into the database.
git clone https://github.com/gerby-project/gerby-website.git
git clone https://github.com/aexmachina/jquery-bonsai
cp jquery-bonsai/jquery.bonsai.css css/
pip install .
The following is only necessary if you use
xypic, as is the case for the Stacks project.
git clone https://github.com/sonoisa/XyJax.git
sed -i -e 's@\[MathJax\]@/static/XyJax@' XyJax/extensions/TeX/xypic.js
We can now import things into the database. The Python script for this is found in
gerby-website/gerby/tools/update.py, and the configuration in
gerby-website/gerby/configuration.py needs to make the files
book.paux, and the
book/ directory known to this script. With the default configuration, this is done by creating the following softlinks from within
ln -s ../../../WEB/book stacks
ln -s ../../../WEB/book.paux stacks.paux
ln -s ../../../WEB/tags stacks.tags
Assuming Gerby is now correctly configured to read the output of plasTeX, it suffices to run the following.
Running the website
Having done all this, running the website should be easy. This is assuming you have installed all the dependencies. You might have to install quite a few Python packages, but they can all be easily
pip install‘d. Perform the following steps in
Now you have a website which you can access via