This morning I was thinking about the layout of the search results. Cathy suggested the layout should be like what you get on google where you have a first line which is a link to the result (in our case something like “Lemma 7.69.1”) and then, in smaller font, some content which (hopefully) helps you see at a glance what “Lemma 7.69.1” is all about.

Now if you look at the LaTeX code for “Lemma 7.69.1” then you get: \begin{lemma} \label{lemma-resolution-by-finite-free} Let $R$ be a ring. Let $M$ be an $R$-module. \begin{enumerate} \item The exists an exact complex $$\ldots \to F_2 \to F_1 \to F_0 \to M \to 0.$$ with $F_i$ free $R$-modules. \item If $R$ is Noetherian and $M$ finite $R$, then we choose the complex such that each $F_i$ is finite free. In other words, we may find an exact complex $$\ldots \to R^{n_2} \to R^{n_1} \to R^{n_0} \to M \to 0.$$ \end{enumerate} \end{lemma} and you can’t quickly see what the lemma is about (although in this case the LaTeX label does give you a hint, but that isn’t always the case).

But what is the lemma really saying? Well, if I wanted to tell a student or a colleague what it says I would say something like “Modules have free resolutions.” or “Finite modules over a Noetherian ring have a resolution by finite free modules.” (By the way, this already points to a potential problem with this lemma. We should really have had two lemmas, one dealing with the general case and one dealing with the finite over Noetherian case.)

Anyway, it is technologically easy to add this kind of human readable descriptions to the Stacks project. Namely, we could change the start of the LaTeX code above to \begin{lemma} \label{lemma-resolution-by-finite-free} % Modules have free resolutions and finite modules over a % Noetherian ring have a resolution by finite free modules. Let $R$ be a ring. Let $M$ be an $R$-module. Our scripts running the search on the website could pick up the LaTeX comment and print it out on the search results page. Moreover, this also allows us to add bibliographical information, historical information, etc. To do that we could code it like this: \begin{lemma} \label{lemma-resolution-by-finite-free} % Human: % Modules have free resolutions and finite modules over a % Noetherian ring have a resolution by finite free modules. % Ref: % MatCA, page 73 % Hist: % Goes back at least to Hilbert. Let $R$ be a ring. Let $M$ be an $R$-module.  and so on and so forth. This works because there aren’t almost any comments in the stacks project LaTeX files (the symbol % occurs on only 232 lines).

Of course, the problem (as usual) is to find somebody who is willing to add human readable descriptions to each and every lemma, proposition, theorem, remark, situation, etc. Since there are 5889 lemmas, 161 propositions, 134 theorems, 471 remarks, 46 situations this is no mean task! (It will take about 100 hours to do this if you can do one of these per minute. Come on guys, that is only 10 days of hard work! And with a group of 10 people…)

We should have done this from the start! Hmm…

## 9 thoughts on “Human readable”

1. Turning things into slogans (or reading other people’s) is something I really like, so if my reworking of the bibliography ever gets done I will assist.

It should be mentioned that this was one of the motivations for the comments system (if I remember correctly), so everyone is invited to post these ‘slogans’ and historical information or references. People who are scared of editing the Stacks project itself can post comments and other people can incorporate them.

• Right, yes! I guess I never realized the utility of the “slogan” before now. Also, believe it or not, I didn’t realize before how easy it is to add these types of things to the “source” files of the Stacks project.

• The current version of the website completely ignores comments, so anyone can start adding this information to the Stacks project right away, it won’t mess up things. Of course, it won’t show up either :). If this thing gains momentum I’ll implement the functionality, it’s far from difficult.

Having meta-information like this in the TeX files is from a philosophical point of view suboptimal, but I don’t know a way of managing this in a more optimal way (separate files and linking them through tags has its obvious downsides too).

Maybe writing the information in actual TeX commands is better, that way you could build a “decorated” version of the pdf’s incorporating the information (now only the website would be able to display it by parsing the files accordingly). But it would require custom commands, which is something you try to avoid. On the other hand, it’s only a fixed number of constantly recurring commands, so it might be an option. The more I think about it, the better it seems. It would for instance be possible to actually use the bibliographical information, etc.

• OK, so you mean something like this?

\begin{lemma}
\label{lemma-resolution-by-finite-free}
\begin{meta-information}
\Human Modules have free resolutions and finite modules over a
Noetherian ring have a resolution by finite free modules.
\References MatCA, page 73
\History Goes back at least to Hilbert.
\end{meta-information}
Let $R$ be a ring. Let $M$ be an $R$-module.

• Yeah, now I remember why I don’t want this: I want everybody be able to compile these easily… and even chunks of the LaTeX files by slapping just a header on them.

OK, so of course, the LaTeX files we publish on the web site could be different from the “source files”…. but that would probably be too confusing.

2. More along the lines of
\begin{lemma} \label{lemma-resolution-by-finite-free} \human{Modules have free resolutions and finite modules over a Noetherian ring have a resolution by finite free module} \references{\cite[page 73]{MatCA}} \history{Goes back at least to Hilbert.} Let $R$ be a ring. Let $M$ be an $R$-module. \end{lemma}

The notation you suggested seems more difficult to parse. The advantage of this is that citations can actually be checked by BibTeX, and that it doesn’t resort to a custom-made format.

As far as I understood the ‘not using too many macros policy’ was more to prevent people from having to learn all the required macros. But my suggestion only entails 3 (optional) macros with a specific goal. One needs some amsthm definitions anyway, 3 \newcommands that just hide their content (by default) won’t impose a big burden I think.

I hope the markup of this comment is okay. Feel free to edit if it’s not.

• OK about first and second paragraph.

About the macros thing: I have already occasionally regretted having the 9 macros (\lim \colim \Spec \Hom \SheafHom \Sch \Mor \Ob \Sh) we do. Having (too many) more will surely make the whole thing un-maintainable. Still, I appreciate the point you make that, no matter what. you already need some kind of preamble anyways.

• My suggestion is maybe the stacks project is a good chance to make some macro standard.

For example, it is surprising that \Spec \Hom are not defined as math operators in the amsmath package, or at least some algebraic geometry package. Every algebraic geometer who writes latex probably defined these at their own preamble. And there is no standard solution yet.

So why not carefully define these macros and make them widely acceptable, and even announce a algebraic geometry package at some point?