References, slogans, and history

For a while now I have been thinking about adding “layers” to the Stacks project. You can find some discussions of this in post 1, post 2, post 3, post 4, and comment 1. Some possibilities for layers are “sign-offs”, “slogans”, “history”, and “references”. References are the most important for now, so let’s focus on that one.

One mathematical point: the idea of finding references is not that we’ll use them anywhere in the Stacks project. It is just to point out that such and such a result, or something similar, can be found in the literature. This way we don’t have to check the proofs given in the literature and we don’t have to worry about circular reasoning. In other words, we should think of “references” more as pointers to the literature than anything else.

In the rest of this post we discuss the mechanism for dealing with references. If you are a mathematician and only interested in the mathematical aspects of the Stacks project, then please check back when an implementation is in place (hopefully this summer) and help us do the hard work, i.e., actually finding precise references for results. Hopefully by then there’ll be an interface (or even a phone app) where it is easy to quickly suggest a reference.

Recall that the Stacks project consists of a bunch a LaTeX files + one extra file dealing with the tags. All the material is reviewed (by the maintainer = me currently). The Stacks website extracts information out of the LaTeX files and displays it and allows for visitors to leave comments (which are not part of the Stacks project and no correctness of the comments is claimed by the authors of the Stacks project).

Clearly, this means references go into the LaTeX files. Visitors can suggest references in the comments on the website, which can then be reviewed and put in the LaTeX file if suitable. We’ll need to write more code for the Stacks website to suitably display them.

Namely, since we (eventually) want references for each single lemma, I think by default we do not want to display references in the pdf or even on the website. There should be a button one can click which shows the references (if there are any) and asks the visitor for references / slogans / historical remarks. Pieter points out that we can show a list of references in the side bar on the tags pages, which may be a good solution.

LaTeX implementation: Currently every lemma is coded as follows

\begin{lemma}
\label{lemma-about-smooth-morphisms}
A smooth morphism is wonderful!
\end{lemma}

in the LaTeX files. Suppose we have a reference for this lemma is EGA II, Theorem 5.4.1.1. Then I suggest we put this into the LaTeX file as follows

\begin{lemma}
\label{lemma-about-smooth-morphisms}
\begin{reference} This is \cite[II Theorem 5.4.1.1]{EGA}. \end{reference}
A smooth morphism is wonderful!
\end{lemma}

If there are more references then maybe the formatting would be like so

\begin{lemma}
\label{lemma-about-smooth-morphisms}
\begin{reference}
The first part of this lemma can be found in \cite[page 455]{A}
and the second part of the lemma can be found in \cite[Lemma 5]{B}.
\end{reference}
A smooth morphism is wonderful!
\end{lemma}

What needs to be done (in no particular order):

  1. Change preamble.tex so \begin{reference} … \end{reference} gets ignored.
  2. Change the current Stacks website code so that \begin{reference} … \end{reference} gets ignored on rendering the LaTeX but so \begin{reference} … \end{reference} does show when clicking the “code” view button.
  3. Make a “show / add references” button on the stacks website which pops up a window showing the current content of \begin{reference} … \end{reference} and asks for a comment
  4. Write a python function extracting the actual \cite commands from the text in between \begin{reference} and \end{reference}
  5. Add a database table with references (both text and actual cite commands) and add a script which populates the table on each update
  6. Add to the script checking correctness of the Stacks project to check correctness of the format of \begin{reference} … \end{reference}
  7. Add a sidebar gadget which shows references (not the surrounding text)
  8. Write a phone app, eg asking for references for a “random” tag
  9. Put your idea here!

If you are comfortable with using LaTeX, php, and python, then you can probably jump right in and help develop. In fact, it might even be fun! If you are interested just email me or Pieter and we can make sure we aren’t doubling up on the work.

Contributors

This is just a quick post to point out that I’ve just updated the contributors file. Please let the Stacks project maintainer (currently me) know if you should be there and you’re not, or if I spelled your name wrong, or if you want your name removed. If you want to learn more precisely who did what you have to look at the commit log and you actually have to look into the commits themselves to see who is thanked for what. A quicker way, if you have a question about this, is to email me and ask.

There are lot’s of things you can do to get onto this list. A suggestion is to browse the project online and find typos/errors and leave a comment on the site. You can also leave comments with an imaginary name, e.g., I think that Levi Civita once send me a suggestion. Be creative. Thanks!