Install Emacs

1. Install GNU Emacs 27.1 or newer. On macOS, brew install --cask emacs or the build at emacsformacosx.com; on Windows, the release from gnu.org/software/emacs; on Linux, your distribution’s emacs package.
2. Download the bundle ZIP from the book’s FirstPair page.
3. Extract the ZIP completely. Do not open files while they are still inside the archive.
4. Note the extracted folder’s location. It contains init.el, Guide.md, two .info files, and the lisp/, data/, lexicon/, and texi/ folders.

Keep the ZIP until you have verified the bundle. It is a clean recovery copy.

Open the book

Start Emacs, then load the bundle’s loader once:

M-x load-file RET /path/to/the/bundle/init.el RET

M-x is Alt+x (or Esc then x), and RET is the Return key. Then:

M-x firstpair-read RET

The frame divides into two windows. The book opens in the upper window at its Top node with the contents menu. The lower window shows the Top node of the references manual. The first dictionary lookup replaces that introductory references pane, keeping the book and dictionary visible without a third window. Close restores the references introduction. Once a citation has opened an actual source below, the dictionary preserves it and uses a third window when the frame has room.

To make the bundle available every time Emacs starts, add one line to your Emacs configuration file (~/.emacs.d/init.el or ~/.config/emacs/init.el):

(load "/path/to/the/bundle/init.el")

Install the reader once, for every FirstPair book

Each bundle carries its own copy of the reader, so the step above is all a single book needs. If you read several FirstPair books, install the reader as an Emacs package instead and let it find your bundles:

;; From a downloaded firstpair-reader-<version>.tar:
M-x package-install-file RET /path/to/firstpair-reader.tar RET

;; Or straight from the FirstPair repository (Emacs 29 or newer):
(package-vc-install '(firstpair-reader
                      :url "https://github.com/firstpair/firstpair"
                      :lisp-dir "publishing/emacs/lisp"))

Then tell it where your bundles live and open one:

(setq firstpair-reader-bundle-directories '("~/Books/FirstPair"))
M-x firstpair-read RET

firstpair-read registers every bundle found in those folders and offers a choice when there is more than one. A bundle’s init.el still works and uses the installed reader when it is at least as new as the bundled copy; otherwise the book uses its own reader. Restart Emacs after upgrading the package so an older version already loaded in memory cannot linger. The package also installs this handbook as an Info manual: C-h i m FirstPair Reader RET.

Your first five minutes

Everything is ordinary Info. The keys you need:

C-h m means hold Control, press h, release, press m. Use the mouse if you prefer: menu items and references are clickable.

Reading order runs through the Top node’s menu: the contents, then each part, then the guide you are reading now, then the colophon. SPC at the end of a chapter continues into the next one, so a book can be read start to finish with one key.

You cannot damage the edition by exploring. Info never writes to its files.

References open below the text

A cited passage in the book is followed by a citation in parentheses, shown as “(see Letters to Atticus 1.17.6)”. Press RET on it, or click it, and the record opens in the lower window: the original text, the translation, its witness and translator, its rights, and a Quoted in list pointing back to every chapter that uses it. The upper window does not move.

The lower window is a complete Info manual of its own. n, p, u, and s work there; RET on a Quoted in entry brings that chapter back into the upper window. C-c C-o moves the cursor between the windows; C-x o also works.

Two keys reach references without hunting for the citation:

C-c C-f matters for evidence that is a file rather than text: an image, a transcription, a data table. It opens inside Emacs, in the lower window, and q returns to the reference.

The dictionary window

Words the bundle’s lexicon can explain are underlined. Hover the mouse over one to see a one-line gloss. In an aligned poem, click or tap any word of the original to update the Dict pane immediately; the poem keeps focus and no keyboard-input prompt opens. Both the poem and Dict panes are read-only. You can also use the keys:

The entry is deliberately small enough for a phone. Its first row is the source lexicon’s headword — Italian in a Dante edition — in bold. Genuine ambiguities share that one row. After it come at most two senses for each selected language, one per unwrapped row. It spends no rows on language headings, translated headwords, parts of speech, grammatical analysis, or blank separators. More on the dictionary bar (or m) reveals every remaining sense; Less restores the compact view. A new word starts compact again. Lookup reads tables from the bundle’s lexicon/ folder, with no network and no external program. C-c C-d also works on words that are not underlined, and reports honestly when the selected dictionaries have no entry.

An edition may answer in more than one language — say English and Russian for a Latin book. Their scripts distinguish the sense rows without headings. C-c C-t in the book (or t in the dictionary window) cycles through each language alone and then all of them together; C-u C-c C-t (or T) lets you pick by name. The choice sticks for every lookup, for the one-line glosses, and for the mouse hover.

Set firstpair-reader-highlight to nil in your configuration to turn the underlines off while keeping every key.

Aligned editions

Some editions align an original with its translations unit by unit — a tercet of Dante with its English and Russian, say. Each unit shows the original first and then the translations you have on; C-c C-t cycles the choice exactly as it does for the dictionary, hiding the other translation in place so the original never moves. Every word of the original can be looked up with C-c C-d. RET walks forward through the original one word at a time and opens each entry with the current dictionary languages. The compact headword and sense rows leave the original and translations as the visible context for how that form is being used. RET on an Info link still follows it.

The top Emacs bar has a separate Translations menu. Its first line says exactly which editions are currently visible, in their display order and with the ≈ mark for an approximate alignment. Reading or clicking that Showing line, or pressing =, changes nothing. The rest of the menu offers Show or Hide Translation, Next Translation at Point, Add Favorite Translations, Favorite Translations Only, This Language First, Choose Languages, and Cycle Languages.

In a text terminal such as Emacs under 1Unix or iSH, the top bar has two compact language menus instead of the graphical drop-down. Tr-Eng opens the English editions and Tr-Rus opens the Russian editions. Each list begins with None, which hides that language, followed by every edition that covers the current part in book order — each with a checkbox. Choosing an unchecked edition shows it in addition to whatever the language already shows (any number of editions may be on screen at once); choosing a checked edition hides it again, and hiding the last one hides the language. Choosing an edition of a hidden language restores the language; English and Russian remain independent. Neither menu invokes a minibuffer, Emacs’s large text-mode menu, or a *Completions* window.

If every list choice runs its first item, check the ordinary File menu: Quit must quit rather than opening Find File. The latter behavior means the terminal host has lost either the touched row or the pointer-movement report Emacs uses to select a TTY menu item; it is not a translation-selection problem. Use 1Unix build 818 or newer before testing the Reader menus or mode-line buttons again; build 818 completes a DECSET 1003 tap at the initial touch cell, before finger drift can move its release.

A persistent row immediately below the top bar lists the visible edition names grouped by language, in the same order in which their text appears — and it is itself the ordering control. Tap an edition’s name to hide it. Tap the ◀ before a name to move that edition one step earlier within its language; the tercets rearrange in place, the original text never moving. Tap a language tag (EN, RU) to bring that language’s whole block first. Press = for the compact, non-mutating translation report. After a menu choice, the language’s edition list, or None, remains in the bottom message line until another command or message replaces it. The Lang button cycles visible languages. Tr< and Tr> swap the edition under the cursor for the previous or next unshown one. 2nd (or b) adds every configured favorite edition without replacing anything already shown; B keeps the favorites and removes the other editions of those languages. The defaults are Palma for English and Ilyushin for Russian. Change them with M-x customize-option RET firstpair-reader-favorite-translations RET.

Rearranging windows

C-c C-l restores the standard layout: book above, with the references or dictionary below; an active cited source may keep a third dictionary pane. The customisation variables firstpair-reader-references-height (a fraction of the frame) and firstpair-reader-lexicon-height (the expanded dictionary’s maximum number of lines) adjust the proportions. A compact dictionary pane automatically shrinks to its headword plus the available two-per-language sense rows. You may also drag the divider between windows.

Reading without the FirstPair reader

The manuals do not depend on the reader. In plain Emacs:

C-u C-h i /path/to/the/bundle/<book>.info RET

or, in a terminal:

info -f /path/to/the/bundle/<book>.info

Citations still work; they open in the same window, and l returns. The manual name appears after the label, as Info shows any reference to another manual. The dictionary keys are not available without the reader.

Add the manuals to Info’s directory

M-x firstpair-read never touches your system. If you would rather find the book under C-h i or the info command beside the Emacs and GNU manuals, install its two manuals into an Info directory:

./install.sh                      # into ~/.local/share/info
./install.sh /usr/local/share/info
./install.sh --remove             # take them out again

or, inside Emacs, M-x firstpair-reader-install-info (and firstpair-reader-uninstall-info). Both copy the .info files and update the directory’s dir menu, using GNU install-info when it is present and Emacs itself otherwise. Then add the directory to Emacs:

(add-to-list 'Info-directory-list "~/.local/share/info")

or to your shell, export INFOPATH="$HOME/.local/share/info:", and the book appears under Books in the Info directory. Reading it that way is plain Info: the FirstPair keys need the reader loaded as above.

Re-rendering the edition

The texi/ folder holds the Texinfo source of both manuals, generated from the same document model as the Info files. With GNU Texinfo installed:

makeinfo --html --no-split texi/<book>.texi
makeinfo --plaintext texi/<book>.texi > <book>.txt
texi2pdf texi/<book>.texi

The output is the same book in another form. Cross-references between the two manuals remain references to the companion manual.

Make personal notes without fighting updates

Treat the .info, data/, lexicon/, and texi/ files as edition material. Emacs bookmarks (C-x r m inside a node, C-x r b to return) record your place without touching the bundle. Keep durable notes in a separate file of your own; Org mode links of the form [[info:<book>#Node Name]] point back into the book.

Updating a FirstPair bundle

To update the shared Reader and immediately reopen the current book, quit Emacs completely and run this from the extracted bundle directory:

./dante.sh

Older bundles can acquire the same bundle-relative command once:

curl -fLO https://firstpair.org/emacs/dante.sh
chmod +x dante.sh
./dante.sh

The script first downloads the small SHA-256 release record. When its Reader version is already installed, it skips the package download and immediately opens the book. Otherwise it downloads the current package over HTTPS, verifies its SHA-256 and package identity, installs it in a clean batch Emacs, and only then removes older Reader package versions. It refuses to modify packages while an Emacs process is running. If the update check or package download is unavailable, it reports that briefly and opens the local book with the installed Reader or the Reader carried inside the bundle. Finally it replaces the shell with a fresh interactive terminal Emacs and calls firstpair-read with the bundle directory. It recognises a bundle containing the script, one Dante-Emacs beside it, or one unambiguous child bundle; a path argument overrides discovery.

This updates the Reader application, not the book’s texts, alignments, or dictionaries. Download a new bundle ZIP when those edition files change.

1. Download and verify the new versioned ZIP.
2. Extract it beside the old folder, not over it.
3. Change the path in your configuration, or load the new init.el, and restart Emacs so the old bundle is forgotten.
4. Open the new edition and confirm the Top node, a citation, and a dictionary lookup.
5. Retain the old folder until the replacement has survived a full restart.

Bookmarks and Org links are tied to node names, which stay stable between editions unless a chapter is retitled.

Troubleshooting

If M-x firstpair-read reports that no bundle is registered, the loader has not run: M-x load-file the bundle’s init.el.

If Info reports that it cannot find the manual, the bundle folder was moved after init.el was loaded. Load init.el again from its new place.

If references open in the upper window and replace the text, the reader is inactive in that buffer: press q and start again with M-x firstpair-read.

If words are not underlined, check that firstpair-reader-highlight is non-nil and that the data/marked.tsv and lexicon/ files extracted completely.

If a citation opens the wrong record, note the book version, the chapter, the visible citation, and the destination, and report it. Do not edit the Info files as a permanent repair; the next edition is regenerated from source.

A durable mental model

The upper window is the book. The lower window is the library: every source and record the book stands on, one node each. The dictionary window is the desk reference. l is your thread back through the labyrinth. Bookmarks and your own notes are your work, and live outside the bundle. With those boundaries an Emacs bundle remains approachable for a first-time reader while holding the depth a scholar or a programmer expects.

Getting the reader package

The standalone reader is at https://firstpair.org/emacs/firstpair-reader.tar (always the current release). Fetch it and install it once:

curl -fL -o firstpair-reader.tar https://firstpair.org/emacs/firstpair-reader.tar

then M-x package-install-file RET firstpair-reader.tar RET.

Picking up where you left off

M-x firstpair-read returns to the node and the line where you stopped in that bundle, with the same languages and the same editions, in the same order, on screen. The reader saves this on every page turn, whenever Emacs has been idle for a few seconds, and when Emacs exits, in firstpair-reader-state-file (~/.emacs.d/firstpair-reader-state.el by default — plain Lisp, one entry per bundle). Set firstpair-reader-resume to nil to always open at the top.

Reading by touch and single keys

On a phone (Emacs under 1Unix/iSH) or anywhere you would rather not type chords, the reader offers the same commands as taps and single letters without repeating controls between panes. The middle bar under the book carries Dict · ▲ · ▼ · ◀c · c▶ · Top · Refs · ?. Dict opens or closes the dictionary. The lowest bar carries Tr< · Tr> · 2nd · Lang · << · < · > · >>. < and > move one source word and look it up; << and >> do the same while skipping frequent Italian function words, including articles, prepositions, pronouns, and common forms of essere and avere. The stopword list is customizable through firstpair-reader-significant-stopwords. Tr< and Tr> swap the edition under point for the previous or next unshown one of its language. Tapping a marked word looks it up; tapping a link follows it; a long press (right click) rotates the translation under it. A slight finger drift is treated as the same tap, not as a cancelled button. The reader also consumes the initial press and an accidental second tap, and the small gaps between buttons are inert, so a near miss cannot resize or maximize the neighboring pane, replace the poem with another buffer, or show Emacs’s generic mouse instructions. Dict replaces the introductory References pane. Word movement refreshes that dictionary pane. The word represented in Dict stays underlined in the poem and the underline moves with every lookup; closing Dict removes it. In the book, d opens the dictionary, t chooses languages, [ and ] swap the translation at point, b adds the configured favorite translations, B keeps only those favorites, and T cycles visible languages backward. In 1Unix’s native strip, holding Tr<, Tr>, 2nd, or Lang performs the paired inverse or narrowing action. , and . step between dictionary words, j and k step to the next or previous word and open it, J and K jump between significant words, n and p turn cantos, and RET repeatedly advances through the Italian or other source text with the current dictionary languages; in the dictionary, m toggles More/Less. Space and backspace page, = reports the translations now showing without changing them, ? shows this list, and q quits. Terminals get mouse reporting switched on automatically (xterm-mouse-mode); if taps still do nothing, the terminal app is not forwarding them and the single keys remain. firstpair-reader-touch turns the layer off.

Using a triptych edition

A triptych edition aligns parallel witnesses: an original, a translation, and an editorial or annotation layer. Each aligned row is one node in the references manual, and a citation in the text opens the whole row so the witnesses can be compared without leaving the page. Rows with a missing side are shown as gaps rather than filled by guesswork.

An edition may carry several translations of one language — say four English and five Russian renderings of the same poem. One translation per language is shown at a time, the edition’s default until you choose another: C-c C-v rotates the column of the language at point (or the first shown language) through its translations, and with a prefix argument offers them by name; C-c C-b shows a second translation of that language under the first, and repeated moves it on and finally hides it. Only the translations that cover the current part are offered — a translator who finished only the Inferno steps aside in the Purgatorio. Translations that do not keep the original’s line count are marked ≈ in the dictionary window’s header line, which names the translations on screen; their rows are cut at the same fractions of the chapter and are approximate.

This complete bundle

This is the complete edition. It carries every chapter, every record and evidence target the book cites, and the full projected lexicon for the words those pages contain. The references manual may therefore be large; use s to search it and the contents menus to browse. Evidence delivered as files lives under evidence/ and opens with C-c C-f.

The dictionary window

This bundle carries a italian lexicon compiled from English Wiktionary Italian dictionary, extracted by Wiktextract and published by Kaikki.org. Put point on a marked word and press C-c C-d; the entry replaces the introductory references pane, or opens below a cited source that must remain visible. It shows the dictionary form, the grammatical analysis of the exact form in front of you, and the senses. C-c C-n and C-c C-p move between marked words. Nothing here needs a network connection or an external dictionary program.

Licence: CC BY-SA 4.0. Senses are English Wiktionary text; attribution and share-alike apply to the delivered tables.

Instructions specific to this book

Each canto is one node. Every tercet appears in Italian first, then in the English translation you have chosen — Longfellow by default; C-c C-v rotates the column through Cary, Norton, and (in the Inferno) Sibbald, and any number of them can be shown at once — the Tr-Eng menu is a checkbox list, and the header row below the menu bar hides an edition (tap its name) or reorders it (◀). C-c C-t hides and restores the translations in place, so the Italian never moves; translations that do not keep Dante’s line count are marked ≈ in the column header.

Put point on any Italian word and press C-c C-d: the compact dictionary starts with one bold Italian headword, then shows up to two English senses, one unwrapped line each, from the English Wiktionary and FreeDict. Press RET in the poem to advance to the next Italian word and open it with the current dictionary language. m or More reveals any remaining senses and Less folds them again. A form the edition cannot explain is reported as such, never guessed.

Both texts are public domain (Project Gutenberg ebooks 1012 and 1004); the license notices are in evidence/ beside the Texinfo source.

Build identity

• Source revision: c7b59a2ac253a8c0b37fd5f40456c771188eb579
• Profile: triptych
• Product: desktop
• Edition: full
• Reader manual: dante-commedia.info
• Reference manual: dante-commedia-refs.info