This note describes how the papers in this folder are stored and how their integrity can be checked. The arrangement is experimental: the layout and the format of the metadata may change.
The repository holds the index index.json, its readable forms index.tm (for TeXmacs) and index.html (for browsers), this note, and one folder for each paper, named by its identifier SLUG:
SLUG/sources/ holds the TeXmacs sources exactly as they were deposited, the main one being SLUG.tm, and the metadata files metadata-v1.json, metadata-v2.json, …, one for each version;
SLUG/html/ holds the HTML version, exported by TeXmacs from the sources;
SLUG/SLUG.pdf is the typeset paper.
It can be browsed in TeXmacs, starting from index.tm, and in a web browser, starting from index.html; the stylesheets, scripts and fonts of the pages are in resources/. It contains an empty file .texmacs-noconvert, which tells the website converter of TeXmacs (with the max-html plugin) to leave it alone, so that the deposited files are never rewritten.
Each metadata file is a JSON document, written in UTF-8, with the fields
the version of this format, mgubi-papers-metadata/0.1 (experimental);
the name SLUG of the folder of the paper;
the version number \(n\) of the deposit, the same as in the file name metadata-vn.json;
the title, and the list of authors, each with a name and possibly an affiliation;
the date of the deposit, as YYYY-MM-DD;
the copyright notice: all rights are reserved to the authors;
the hash function, sha256;
the path of the main TeXmacs source;
the list of the deposited sources, each with its path (relative to the folder of the paper), its size in bytes and its SHA-256 hash;
the same for the files produced from the sources (the HTML version and the PDF). They are recorded so that the published files can be checked, but they are not part of the deposit: a new export may differ while the sources do not;
for the first version null; for a later version, the path and the SHA-256 hash of the metadata file of the previous version;
optional, links to the same work elsewhere, for instance "arxiv": "2611.14296".
The index index.json is a JSON document, written in UTF-8, with the fields format (mgubi-papers-index/0.1 (experimental)), hash (sha256) and papers, the list of the papers, newest deposits first. Each entry gives the identifier, title, authors (names), deposited date and version of a paper, copied from its metadata, the path metadata of its current metadata file and the SHA-256 hash sha256 of that file.
index.tm is generated from index.json and the template index-template.tm, which holds the surrounding text, and index.html is exported from index.tm by TeXmacs. They show the same hashes, but only index.json is authoritative: programs should start from it.
The index index.json records, for each paper, the SHA-256 hash of the metadata file of its current version. That file records the hashes of the sources and the hash of the metadata of the previous version, which records the hashes of the sources of that version, and so on. Given the index, each version of each paper is therefore fixed: changing a source, or rewriting the history of the versions, changes a hash that is recorded one level up. Since the papers are kept in a git repository, the index is also part of the history of its commits.
A revision is a new deposit under the same identifier: its sources replace the old ones, a new metadata file metadata-v(n+1).json points to metadata-vn.json, which is kept, and the index records the hash of the new file. The sources of older versions remain in the history of the repository.
To check a paper by hand, compute the hash of its metadata file, for instance with shasum -a 256 SLUG/sources/metadata-v1.json, compare it with index.json, and do the same for each file listed in the metadata. In the repository, tools/papers.py verify checks every file, every chain of versions and the index; tools/papers.py deposit adds a paper or a version, and tools/papers.py index regenerates index.json, index.tm and the HTML pages.