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, 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)).",