Books

A book in Parseh is a reading edition in the Ilya Frank manner: the text cut into small pieces — chunks, a phrase or a sense group each — and every chunk glossed where it stands, with its transliteration, the words it is made of and what it means. You read the sentence whole first, then chunk by chunk with the help beside it, then the sentence whole again without the help. A recording of the book can play in step with the text, a subparagraph at a time.

The Books door of the hub opens the library at /books/. Everything in this section is done from there and from the pages it leads to: nothing here needs a terminal, even the way of adding a book that hands the work to an AI coding assistant — the folder is made by a button, the assistant is the one you choose, and you watch the book grow from the library.

1. Where to start#

Open the library (The library), pick a book, and read (The reader). To make a book of your own, start at Adding a book; to hear one, at Adding a narration. While you read, flag a chunk without stopping and come back to it later (Review later); every setting of the page is in its ⚙ panel (The ⚙ settings of a page). The pages of this section are listed at the foot of this one, in the order a book is usually met: finding it, reading it, hearing it, writing it, taking it away.

2. Levels: the same text, several ways#

Each subparagraph of a book is set several times over, one level after the other. Which levels there are depends on the language, and the header of the reader has one button for each, named for what it shows, to show or hide it:

Language	The levels, by the name on their button
Persian	With vowels · Chunks · Plain · Nastaliq
Arabic	With vowels · Chunks · Plain
Japanese	Furigana · Kana only · Chunks · Plain · Vertical
Chinese	Pinyin · Pinyin only · Chunks · Plain · Vertical
Italian, French, German, Turkish, English, Hindi, Spanish	Sentence · Chunks

The first level is your own attempt at the sentence, before any help arrives; the chunks level is the help; the others give the sentence again — as it is really printed, in its other face, or, in Japanese and Chinese, as it is read aloud. The names are yours to change, and a Persian or Arabic book can put the vowel marks away: Levels and their names. The list comes from Parseh’s language registry, so a language added to the toolbox brings its own levels with it.

3. Where a book lives#

A book is a folder, and nothing anywhere keeps a list of books: a folder with a book.json in it, under its language’s folder, is on the shelf.

text

books/  persian/    farsi-shakar-ast/      book.json      the title, the author, the language      main.tex       the frame: title page, one \input per chapter      ch1.tex ...    the text, chunk by chunk, with the glosses      source/        the original paragraphs, to check the text against      reading.json   what you folded away      markdown/      the notes in the seams      audio/         the recordings (never committed)      timings.json   where each subparagraph starts and ends      main.pdf       the printed edition, once built      reader/        the reading page, built from the .tex

The toolbox ships with no book: each language’s folder under books/ holds only a .gitkeep until you add one, bring one back from a bundle or start an empty one. The files themselves are described in What a book is made of.

The libraryThe book cards, building a book, taking one off the shelf, bringing one back, and backing up the whole shelf.
Adding a bookThree ways to begin a book — by hand, onto a book already here, or made by an agent you choose — and a book whose glosses are still to write.
A book made by an agentWatching a book grow in the library while an agent you choose writes it — the making panel, the asks you steer it with, and Finish.
The readerEvery control of the reading page — levels, glosses, the hover cloud, copying, the ⚙ settings, Japanese and Chinese, book info, the bars, the keys.
Contents and foldingThe contents as a tree, naming chapters and sections, and folding a run of paragraphs out of the way.
Levels and their namesThe levels a book is set in, what each language calls them, hiding and renaming them, and Diacritics, which hides Persian's and Arabic's vowel marks.
Playing and listeningThe narration, a subparagraph at a time or straight through — keep going, loop, between repeats, the speed, wait at each new chapter, listen, highlight.
Review laterFlag a chunk in a book or a video without stopping, then come back to the list — go to it, make its card, test yourself, copy it.
Adding a narrationThe narration panel — adding a recording, transcripts, align and estimate times, a book in several recordings, keeping a narration file.
Fixing the timingsWhere each subparagraph starts and ends in the recording — edit times, one subparagraph at a time, and by ear, boundary by boundary over a picture of the sound, with the rest — or only the next few seconds of it — estimated again by the text or by the sound.
Writing a chunkThe pencil and the chunk sheet — the text, the reading, the transliteration, the vocabulary line, the meaning, the four colours, the words strip — deleting a gloss, and what a save does and refuses.
Cutting and joining chunksMoving the boundary between two chunks — where a chunk may be cut, what becomes of its gloss, and what the sheet refuses.
Notes in the seamA note between two subparagraphs — writing one, reading it, where it lives and how it says where it sits.
Reading unglossed chunksThe dictionary switch and its panel — the dictionary, the machine's reading, sentences somebody translated, Load more — and the sources sidebar and Ask LLM, which put them into a gloss; what the verb draft does in each language, and why a gloss is not a fluent translation.
Glossing with an LLMThe header's gloss with an LLM sheet — picking a stretch, the two checkboxes, the prompt, the answer pasted back, the report — and why a gloss already written is never touched.
Taking a book awayThe reader's download — what a bundle carries, the three shapes of a narrated book and their sizes — and working on the files in a text editor.
The printed editionBuilding a book's PDF from the pages, following the build, where the PDF is, and rebuilding the reader alone.
The files of a bookbook.json, a chapter .tex argument by argument, the chunk macros and the vocabulary line, the source paragraphs, reading.json and a chunk with no gloss yet — for reading or writing the files directly.