From 797c3736469408d0fe141c5f21b049d7b25e335b Mon Sep 17 00:00:00 2001 From: Marat Zimnurov Date: Sun, 4 Oct 2026 20:35:04 +0000 Subject: [PATCH 1/2] fix(site): the registry page is printed without internal words Task 2325. The jargon guard refused on four reader pages, and the words could not be fixed on the pages themselves: both halves of the registry page are printed by scripts/site/registry-page.fscript, so an edit in the file would be lost at the next printing. The words are fixed in the printer; the pages are then reprinted by a run. What was and what is, measured by the guard itself (bootstrap/flang run-script jargon:check): docs/site/registry.md 10 internal words -> 0 docs/site/registry.ru.md 9 -> 0 docs/site/packages.md 1 -> 0 docs/site/packages.ru.md 1 -> 0 The words and what replaced them: * the Russian word for a ledger, and "ledger" itself, give way to the Russian and English words for a list. The decision ADR-0059 calls the thing a ledger of names, and inside the project that word is shorter and sharper; on a page read by someone who came for the language it requires knowing our kitchen. A list of names says the same and needs no footnote. * "byte for byte" gives way to "unchanged". The guard asks for this one in words, not as a term. The packages pages are written by hand, not printed, so their one word each is fixed in place. No exception was added to docs/jargon.json and no page was moved into the list of surfaces the guard skips. The guard already blanks link targets, so the name of the decision file in the ADR link was never counted -- that is measured, not assumed: the guard lists lines 3, 7, 12, 27, 43, 49, 63 and 74 of registry.md and never line 10, which is the line with the link. Negative control. One internal word was put back into the printer, in the line that counts the records, and the page reprinted: the guard went from 6 faults to 7 and named the planted place -- registry.ru.md, one internal word where none is allowed, line 62. Restored, and the printer and both halves of the page compare equal to the copies taken before the forgery. The guard still refuses on this branch, with 6 faults in six files none of which this branch touches: the roadmap page, three chapters of the course, the guide on how to write flang, and flang_repl.c. Those six are closed by PR 322, which is not in dev yet. On a tree that is PR 322 plus this change the guard answers with exit code 0 and says it looked at 157 surfaces, saw 992 internal words all of them on the debt list of 34 files, and found 0 new ones. --- docs/site/packages.md | 2 +- docs/site/packages.ru.md | 2 +- docs/site/registry.md | 24 +++++++-------- docs/site/registry.ru.md | 24 +++++++-------- scripts/site/registry-page.fscript | 48 +++++++++++++++--------------- 5 files changed, 50 insertions(+), 50 deletions(-) diff --git a/docs/site/packages.md b/docs/site/packages.md index 787d07b30..e7d519041 100644 --- a/docs/site/packages.md +++ b/docs/site/packages.md @@ -2,7 +2,7 @@ A flang package is **one file** that holds a library together with everything it imports. There is no package cache, and the registry is a -[ledger of names](registry.html), not a store of code: it has no command of the +[list of names](registry.html), not a store of code: it has no command of the binary and answers with an address. To publish a package, commit the file to git; to use it, put the file next to your program and write one import line. Building on another machine needs only your program and the package file, and diff --git a/docs/site/packages.ru.md b/docs/site/packages.ru.md index c6c4b5446..79c2043e3 100644 --- a/docs/site/packages.ru.md +++ b/docs/site/packages.ru.md @@ -1,7 +1,7 @@ # Пакеты Пакет flang — **один файл**, в котором лежит библиотека вместе со всем, что она -импортирует. Кеша пакетов нет, а реестр — [ведомость имён](registry.html), а не +импортирует. Кеша пакетов нет, а реестр — [список имён](registry.html), а не склад кода: команды двоичного у него нет, он отвечает адресом. Чтобы опубликовать пакет, закоммитьте файл в git; чтобы им пользоваться, положите файл рядом с программой и напишите одну строку импорта. Для сборки на другой машине diff --git a/docs/site/registry.md b/docs/site/registry.md index 43b7e4e80..0ce8b12af 100644 --- a/docs/site/registry.md +++ b/docs/site/registry.md @@ -1,15 +1,15 @@ # The package registry -The flang registry is a **ledger of names**, not a store of code. The ledger is -a line-based file: five fields per line separated by «|», and nothing else. Asked +The flang registry is a **list of names**, not a store of code. The list is a +line-based file: five fields per line separated by «|», and nothing else. Asked which version of a package will do, the registry answers with an **address** where the package lies, not with the package; a name gets a version here, in the -ledger, and nowhere else; the language gains no new word for any of it. No -server, no database and no accounts are needed — and by decision there are none. -The whole argument: +list, and nowhere else; the language gains no new word for any of it. No server, +no database and no accounts are needed — and by decision there are none. The +whole argument: [ADR-0059](../adr/0059-the-registry-is-a-ledger-of-names-not-a-store-of-code.md). -## The ledger is a file at a stable address +## The list is a file at a stable address ``` https://digitable-lol.github.io/flang/registry.list @@ -24,9 +24,9 @@ the language already has — «Запросить»: и тело равным "" ``` -What the site serves is a copy of the ledger in the tree, +What the site serves is a copy of the same file from the tree, [`scripts/registry-example/registry.list`](../../scripts/registry-example/registry.list), -byte for byte — put there by the same build that prints this page. +unchanged — put there by the same build that prints this page. ## The five fields @@ -40,13 +40,13 @@ byte for byte — put there by the same build that prints this page. A need reads `name: range`, needs are separated by semicolons. There are four ranges: `любая`, `ровно 1.2.3`, `не ниже 1.2.3`, `в пределах 1.x`. Parsing the -ledger and choosing a version are written and proved in +list and choosing a version are written and proved in [`flang/stdlib/registry.flang`](../../flang/stdlib/registry.flang); the choice is made by running a plan, not by a command of the binary. ## The records as they stand -The table below is printed **from the ledger** by +The table below is printed **from that file** by `flang run-script registry:page`; it is not edited by hand — an edit is lost at the next printing. @@ -60,7 +60,7 @@ the next printing. | Множество строк | 1.1.0 | `a9a776e153d9789c7e29f8c66ad92df36a834f21630c6388b41ebd4f8d2effc2` | `registry-example/sets-1.1.0.flang-package` | Списки: в пределах 1.x; Логика: в пределах 1.x | | Опциональное значение | 0.9.0 | `17eac86ce77be366094d22be0f537d4bab5bb00958fb41df3bd7353060957c7d` | `registry-example/optional-0.9.0.flang-package` | Логика: ровно 2.0.0 | -Records in the ledger: 7. +Records in the list: 7. ## The fingerprint is checked against the file as the page is printed @@ -71,7 +71,7 @@ and the page is not printed at all: the run exits with 1 and `FLANG_REESTR_OTPECHATOK`, names the record, both fingerprints and the address, and the site build goes red on it instead of reaching the reader. -The check is not a precaution: the fingerprints of the example ledger did part +The check is not a precaution: the fingerprints in the example did part from the files once, and there was nobody to see it — no CI job called the registry at all (task [4909](../tasks/4909-the-registry-resolution-rule-has-no-guard-and-example-fingerprints-rotted.md)). diff --git a/docs/site/registry.ru.md b/docs/site/registry.ru.md index 4d23bbd83..fdbae3a0e 100644 --- a/docs/site/registry.ru.md +++ b/docs/site/registry.ru.md @@ -1,14 +1,14 @@ # Реестр пакетов -Реестр flang — это **ведомость имён**, а не склад кода. Ведомость — строчный -файл: в каждой строке пять полей через знак «|», и больше в ней ничего нет. На -вопрос «какая версия пакета годится» реестр отвечает **адресом**, по которому -лежит пакет, а не самим пакетом; имя получает версию только здесь, в ведомости; -ни одного нового слова в языке реестр не заводит. Ни сервера, ни базы, ни -учётных записей для этого не нужно — и по решению их нет. Довод целиком: +Реестр flang — это **список имён**, а не склад кода. Список — строчный файл: +в каждой строке пять полей через знак «|», и больше в ней ничего нет. На вопрос +«какая версия пакета годится» реестр отвечает **адресом**, по которому лежит +пакет, а не самим пакетом; имя получает версию только здесь, в списке; ни одного +нового слова в языке реестр не заводит. Ни сервера, ни базы, ни учётных записей +для этого не нужно — и по решению их нет. Довод целиком: [ADR-0059](../adr/0059-the-registry-is-a-ledger-of-names-not-a-store-of-code.md). -## Ведомость лежит файлом по постоянному адресу +## Список лежит файлом по постоянному адресу ``` https://digitable-lol.github.io/flang/registry.list @@ -23,7 +23,7 @@ https://digitable-lol.github.io/flang/registry.list и тело равным "" ``` -На сайте лежит копия ведомости дерева +На сайте лежит копия того же файла из дерева [`scripts/registry-example/registry.list`](../../scripts/registry-example/registry.list) — знак в знак, и кладёт её туда та же сборка, что печатает эту страницу. @@ -39,13 +39,13 @@ https://digitable-lol.github.io/flang/registry.list Нужда пишется как `имя: диапазон`, нужды разделяются точкой с запятой. Диапазонов четыре: `любая`, `ровно 1.2.3`, `не ниже 1.2.3`, `в пределах 1.x`. -Разбор ведомости и выбор версии написаны и доказаны в +Разбор списка и выбор версии написаны и доказаны в [`flang/stdlib/registry.flang`](../../flang/stdlib/registry.flang); сдаётся выбор прогоном плана, а не командой двоичного — нового слова реестр не заводит нигде. ## Нынешние записи -Таблица ниже напечатана **из ведомости** прогоном +Таблица ниже напечатана **из этого файла** прогоном `flang run-script registry:page`; руками её не правят — правка затрётся следующей печатью. @@ -59,7 +59,7 @@ https://digitable-lol.github.io/flang/registry.list | Множество строк | 1.1.0 | `a9a776e153d9789c7e29f8c66ad92df36a834f21630c6388b41ebd4f8d2effc2` | `registry-example/sets-1.1.0.flang-package` | Списки: в пределах 1.x; Логика: в пределах 1.x | | Опциональное значение | 0.9.0 | `17eac86ce77be366094d22be0f537d4bab5bb00958fb41df3bd7353060957c7d` | `registry-example/optional-0.9.0.flang-package` | Логика: ровно 2.0.0 | -Записей в ведомости: 7. +Записей в списке: 7. ## Отпечаток сверен с файлом при печати @@ -70,6 +70,6 @@ https://digitable-lol.github.io/flang/registry.list `FLANG_REESTR_OTPECHATOK`, называет запись, оба отпечатка и адрес, а сборка сайта краснеет на нём и до читателя не доезжает. -Проверка заведена не впрок: отпечатки ведомости примера однажды разошлись с +Проверка заведена не впрок: отпечатки в примере однажды разошлись с файлами, и увидеть это было некому — реестр не звала ни одна работа сборки (задача [4909](../tasks/4909-the-registry-resolution-rule-has-no-guard-and-example-fingerprints-rotted.md)). diff --git a/scripts/site/registry-page.fscript b/scripts/site/registry-page.fscript index bd4bf6396..8e8d675ff 100644 --- a/scripts/site/registry-page.fscript +++ b/scripts/site/registry-page.fscript @@ -93,15 +93,15 @@ возвращает список строки ["# Реестр пакетов", "", - "Реестр flang — это **ведомость имён**, а не склад кода. Ведомость — строчный", - "файл: в каждой строке пять полей через знак «|», и больше в ней ничего нет. На", - "вопрос «какая версия пакета годится» реестр отвечает **адресом**, по которому", - "лежит пакет, а не самим пакетом; имя получает версию только здесь, в ведомости;", - "ни одного нового слова в языке реестр не заводит. Ни сервера, ни базы, ни", - "учётных записей для этого не нужно — и по решению их нет. Довод целиком:", + "Реестр flang — это **список имён**, а не склад кода. Список — строчный файл:", + "в каждой строке пять полей через знак «|», и больше в ней ничего нет. На вопрос", + "«какая версия пакета годится» реестр отвечает **адресом**, по которому лежит", + "пакет, а не самим пакетом; имя получает версию только здесь, в списке; ни одного", + "нового слова в языке реестр не заводит. Ни сервера, ни базы, ни учётных записей", + "для этого не нужно — и по решению их нет. Довод целиком:", "[ADR-0059](../adr/0059-the-registry-is-a-ledger-of-names-not-a-store-of-code.md).", "", - "## Ведомость лежит файлом по постоянному адресу", + "## Список лежит файлом по постоянному адресу", "", "```", "https://digitable-lol.github.io/flang/registry.list", @@ -116,7 +116,7 @@ " и тело равным \"\"", "```", "", - "На сайте лежит копия ведомости дерева", + "На сайте лежит копия того же файла из дерева", "[`scripts/registry-example/registry.list`](../../scripts/registry-example/registry.list)", "— знак в знак, и кладёт её туда та же сборка, что печатает эту страницу.", "", @@ -132,13 +132,13 @@ "", "Нужда пишется как `имя: диапазон`, нужды разделяются точкой с запятой.", "Диапазонов четыре: `любая`, `ровно 1.2.3`, `не ниже 1.2.3`, `в пределах 1.x`.", - "Разбор ведомости и выбор версии написаны и доказаны в", + "Разбор списка и выбор версии написаны и доказаны в", "[`flang/stdlib/registry.flang`](../../flang/stdlib/registry.flang); сдаётся выбор", "прогоном плана, а не командой двоичного — нового слова реестр не заводит нигде.", "", "## Нынешние записи", "", - "Таблица ниже напечатана **из ведомости** прогоном", + "Таблица ниже напечатана **из этого файла** прогоном", "`flang run-script registry:page`; руками её не правят — правка затрётся", "следующей печатью.", ""] @@ -147,7 +147,7 @@ принимает сколько: число возвращает список строки ["", - (соединить ["Записей в ведомости: ", (к строке сколько), "."] по ""), + (соединить ["Записей в списке: ", (к строке сколько), "."] по ""), "", "## Отпечаток сверен с файлом при печати", "", @@ -158,7 +158,7 @@ "`FLANG_REESTR_OTPECHATOK`, называет запись, оба отпечатка и адрес, а сборка", "сайта краснеет на нём и до читателя не доезжает.", "", - "Проверка заведена не впрок: отпечатки ведомости примера однажды разошлись с", + "Проверка заведена не впрок: отпечатки в примере однажды разошлись с", "файлами, и увидеть это было некому — реестр не звала ни одна работа сборки", "(задача [4909](../tasks/4909-the-registry-resolution-rule-has-no-guard-and-example-fingerprints-rotted.md)).", ""] @@ -167,16 +167,16 @@ возвращает список строки ["# The package registry", "", - "The flang registry is a **ledger of names**, not a store of code. The ledger is", - "a line-based file: five fields per line separated by «|», and nothing else. Asked", + "The flang registry is a **list of names**, not a store of code. The list is a", + "line-based file: five fields per line separated by «|», and nothing else. Asked", "which version of a package will do, the registry answers with an **address**", "where the package lies, not with the package; a name gets a version here, in the", - "ledger, and nowhere else; the language gains no new word for any of it. No", - "server, no database and no accounts are needed — and by decision there are none.", - "The whole argument:", + "list, and nowhere else; the language gains no new word for any of it. No server,", + "no database and no accounts are needed — and by decision there are none. The", + "whole argument:", "[ADR-0059](../adr/0059-the-registry-is-a-ledger-of-names-not-a-store-of-code.md).", "", - "## The ledger is a file at a stable address", + "## The list is a file at a stable address", "", "```", "https://digitable-lol.github.io/flang/registry.list", @@ -191,9 +191,9 @@ " и тело равным \"\"", "```", "", - "What the site serves is a copy of the ledger in the tree,", + "What the site serves is a copy of the same file from the tree,", "[`scripts/registry-example/registry.list`](../../scripts/registry-example/registry.list),", - "byte for byte — put there by the same build that prints this page.", + "unchanged — put there by the same build that prints this page.", "", "## The five fields", "", @@ -207,13 +207,13 @@ "", "A need reads `name: range`, needs are separated by semicolons. There are four", "ranges: `любая`, `ровно 1.2.3`, `не ниже 1.2.3`, `в пределах 1.x`. Parsing the", - "ledger and choosing a version are written and proved in", + "list and choosing a version are written and proved in", "[`flang/stdlib/registry.flang`](../../flang/stdlib/registry.flang); the choice is", "made by running a plan, not by a command of the binary.", "", "## The records as they stand", "", - "The table below is printed **from the ledger** by", + "The table below is printed **from that file** by", "`flang run-script registry:page`; it is not edited by hand — an edit is lost at", "the next printing.", ""] @@ -222,7 +222,7 @@ принимает сколько: число возвращает список строки ["", - (соединить ["Records in the ledger: ", (к строке сколько), "."] по ""), + (соединить ["Records in the list: ", (к строке сколько), "."] по ""), "", "## The fingerprint is checked against the file as the page is printed", "", @@ -233,7 +233,7 @@ "`FLANG_REESTR_OTPECHATOK`, names the record, both fingerprints and the address,", "and the site build goes red on it instead of reaching the reader.", "", - "The check is not a precaution: the fingerprints of the example ledger did part", + "The check is not a precaution: the fingerprints in the example did part", "from the files once, and there was nobody to see it — no CI job called the", "registry at all (task", "[4909](../tasks/4909-the-registry-resolution-rule-has-no-guard-and-example-fingerprints-rotted.md)).", From f0726711d6bbd754185c21dd94e8a4f761788790 Mon Sep 17 00:00:00 2001 From: Marat Zimnurov Date: Wed, 7 Oct 2026 19:22:55 +0000 Subject: [PATCH 2/2] chore(jargon): the four registry and package pages leave the debt list The registry printer now writes the two halves of the registry page without internal words, and the two packages pages were fixed by hand, so each of the four pages has zero internal words. The jargon guard refuses when a file's count falls below its recorded debt, so the four rows are removed from docs/jargon.json. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01PNHrA3rG7FTWhB11E7pjDQ --- docs/jargon.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/jargon.json b/docs/jargon.json index 3ff654b00..b05c99901 100644 --- a/docs/jargon.json +++ b/docs/jargon.json @@ -525,12 +525,8 @@ "docs/site/browser-app.ru.md": 2, "docs/site/index.md": 2, "docs/site/index.ru.md": 2, - "docs/site/packages.md": 1, - "docs/site/packages.ru.md": 1, "docs/site/proofs.md": 2, "docs/site/proofs.ru.md": 2, - "docs/site/registry.md": 10, - "docs/site/registry.ru.md": 9, "docs/site/roadmap.ru.md": 1, "docs/site/shortener.md": 7, "docs/site/shortener.ru.md": 9,