A File That Explains Its Own Entries

On paper, a records office writes on the folder itself: the reference, the office it came from, the date after which it may be destroyed. Scan the folder and that writing has nowhere left to go. Write it inside the file instead and something worse happens — the file quietly stops obeying the archiving rules it says it obeys, and the day somebody checks it, it comes back refused.

Every archiving rule knows a title and an author; a keep-until date belongs to you. So this file carries those entries and, beside each one, a description of it: what it is called, how it is to be read, who it is written for, what it means. That description is what a checker looks for first, and what it accepts information nobody but you invented on. The first page prints the very same five entries as the record hidden inside — a reference, a department, a date in 2056, a classification and a sheet count — so what a person reads and what a machine reads cannot drift apart. A second page shows the other kinds of entry such a description can announce — a yes or no, a type of file, a person's name, a measurement, an address on the web — on a loan record, and gives that page a hidden record of its own, apart from the document's.

An entry can also hold a list, in order or not, or a record with named fields: here the witnesses to the loan, and every time the folder changed hands, each with its date and who took it. The description sets out that record field by field, so a checker reads it as it reads the rest.

What This Example Shows

  • Five entries a records office invented, among them a date in 2056 before which nothing may be destroyed.
  • Each entry arriving with a description of itself, which is what a checker accepts it on.
  • The page and the hidden record printed from one list, so they cannot disagree.
  • Lists and records with named fields, described for the checker like any other entry.

The Source Code, Complete

Nothing is left out and nothing is simplified: this is the program exactly as it runs, for the developer who uses this library. The third is the description itself: a plain list of what the page has to say, which is what the service is sent.

Read the Rust source Read the Python source Read the JSON source

The Document Itself

Open the document in English Open the document in French Open the document in German Open the document in Spanish Open the document in Italian Open the document in Portuguese

A File That Explains Its Own Entries, first page

The Same Document in Other Languages

This document weighs 38.5 kB

Examples Near This One

A Sheet That Measures What It Says

Three rulers — centimetres, inches and points — on a page that tells whatever prints it to put it out at exactly the size it was drawn, and to offer nothing else. Lay a tape measure on the printed sheet and you can check for yourself.

A Register Whose Pages Say Where They Came From

Two sittings bound into one file. Each page carries a record of its own — what it is, whose hand wrote it, the day it was written — the photograph on the second page carries one too, and each transcription is tied to the page it transcribes rather than to the file at large.

A Delivery Note That Knows Its Own Order

Every line of the note carries the order it was picked for, the article code and the shelf it came off, and prints none of them. The place where the driver signs carries the round and the van, and one beside the fold tick carries nothing but its own place.

A Document That Can Be Read Aloud

Two pages carrying a copy of themselves that nobody sees: this is a heading, this is a table, and this is the order to read them in. Software reading the document aloud follows that instead of the order the marks were drawn in, and skips the running head. On the page, nothing looks any different.

A List Whose Pictures Speak Too

A parts list whose first column is a picture rather than a word. Each picture carries the sentence somebody hears in its place, so nothing in the list is lost on a reader who cannot see it. On the page, the pictures are simply pictures.

A Tagged Notice That Says What Each Part Is

A delivery notice whose hidden structure says where each element stands, what an abbreviation stands for and which headings each table cell belongs to, with its running head, page number and line numbers marked as page furniture; then every list numbering and every role an element can be given.

Every example, by subject