+
+
+**Альтернатива: интеграция с IDE**
+
+Во многих IDE для Rust, например RustRover или VS Code, есть встроенная поддержка анализа покрытия тестами.
diff --git a/docs/ru/helpers.md b/docs/ru/helpers.md
new file mode 100644
index 00000000..bd63b7c4
--- /dev/null
+++ b/docs/ru/helpers.md
@@ -0,0 +1,494 @@
+---
+layout: default
+lang: ru
+ref: helpers
+title: Руководство переводчика и разработчика правил
+---
+# Использование grcov в macOS
+ +В этом подходе для создания отчётов о покрытии тестами используются `llvm-cov` и `grcov`. [grcov](https://github.com/mozilla/grcov) должен работать и в других операционных системах, но может потребовать некоторых изменений путей LLVM и конфигурации. + +**Однократная настройка:** + +```bash +# Установить необходимые компоненты +rustup component add llvm-tools-preview +cargo install grcov +``` + +**Создание отчёта о покрытии:** + +```bash +# Задать переменную среды для данных профилирования +export LLVM_PROFILE_FILE="target/coverage/%p-%m.profraw" + +# Запустить тесты со сбором данных о покрытии +RUSTFLAGS="-Cinstrument-coverage" cargo test + +# Пример: запустить один тест +# RUSTFLAGS="-Cinstrument-coverage" cargo test Languages::zh::tw::units::without_prefix_powers_of_2 + +# Создать HTML-отчёт +grcov . \ + --source-dir . \ + --binary-path ./target/debug/deps \ + -t html \ + --branch \ + --ignore-not-existing \ + --ignore "target/*" \ + -o target/coverage/html + +# Открыть отчёт в браузере +open target/coverage/html/index.html +``` + +
Руководство переводчика и разработчика правил
+
+## Информация для разработчиков правил и переводчиков MathCAT
+Эта страница находится в процессе подготовки.
+
+## Начало работы
+Если вы планируете участвовать в разработке MathCAT, используйте GitHub:
+1. Создайте форк репозитория MathCAT `github.com/NSoiffer/MathCAT`.
+2. Клонируйте форк, чтобы получить локальную копию для работы.
+3. Переключитесь на созданную для вашей работы ветку, обычно названную кодом языка перевода, и работайте в ней.
+
+Если вы ещё не знакомы с этими действиями, найдите одно из многочисленных руководств. Они достаточно просты, поэтому отсутствие опыта не должно вас останавливать.
+
+
+## Переводчикам на другие языки
+Если вы хотите перевести MathCAT, свяжитесь с @NSoiffer. Он подготовит начальный вариант перевода, который может значительно сэкономить время. В результате будут созданы файлы в каталоге `Rules/Languages/xx`, где `xx` — код языка, например `fr`, `de` или `el`. Перевод выполняется в этом каталоге. Необходимо отредактировать четыре категории файлов:
+1. `definitions.yaml`: содержит переводы числительных, в том числе количественных и порядковых. Проверьте начальный перевод и внесите необходимые исправления. Эти числительные используются, например, при озвучивании фразы «три пятых». На некотором этапе образование числительных в языках становится регулярным, поэтому некоторые списки в файле можно сократить, а некоторые следует дополнить. Подробнее см. английские комментарии в файле.
+2. Файлы `xxx_Rules.yaml`, сейчас это `ClearSpeak_Rules.yaml` и `SimpleSpeak_Rules.yaml`. Они соответствуют разным стилям речи. Настоятельно рекомендуется сначала выбрать только один стиль. Эти файлы обычно содержат слова, описывающие структуру выражения, например «дробь» и «степень», а также связующие слова. Поскольку стили речи во многом похожи, существует также каталог `SharedRules` с общими файлами правил. Они подключаются в `ClearSpeak_Rules.yaml` и `SimpleSpeak_Rules.yaml` с помощью правил `- include: file_name`. Их тоже необходимо перевести.
++
+Примечание: диалог настроек MathCAT ищет файлы с именами вида `XXX_Rules.yaml` и добавляет их в раскрывающийся список для языка. Использовать имена SimpleSpeak и ClearSpeak необязательно. Если вы хотите перевести только один стиль, например SimpleSpeak, но не хотите удалять `ClearSpeak_Rules.yaml`, переименуйте его, например, в `ClearSpeak_Rules.yaml.untranslated`. +
+
+Эти файлы содержат автоматически созданные начальные переводы. Хотя текст уже переведён, используется ключ `t:`, а не `T:` с прописной буквы. Каждый перевод необходимо проверить и только после этого изменить ключ на вариант с прописной буквы. Подробнее об автоматическом переводе см. ниже. + + * В некоторых языках нет смысла произносить эквиваленты слов «the» и, возможно, «of» во фразе «the square root of x». В таком случае замените их пустыми строками. + * В некоторых языках меняется порядок слов. Переставляйте слова свободно, но внимательно следите за отступами: в YAML они значимы. + * В некоторых языках могут потребоваться слова, отсутствующие в английской версии, до или после существующих фраз. Добавляйте их при необходимости. Условное добавление выполняется с помощью `test`. Если нужна помощь, свяжитесь с @NSoiffer. + * Паузы между словами и фразами могут значительно улучшить понятность речи. Исходные паузы выбраны для английского языка. Настройте их в соответствии со звучанием синтезаторов вашего языка. Паузы легко добавлять, удалять и изменять. Их длительность масштабируется в соответствии с текущей скоростью речи. +3. Файлы Unicode: `unicode.yaml` и `unicode-full.yaml`. Они содержат такие символы, как `<` и `∫`. + * Начните с перевода `unicode.yaml`. В нём находится подавляющее большинство используемых математических символов. Сейчас список основан на практическом опыте, но в дальнейшем планируется уточнить его по статистике из реальных книг. В `unicode.yaml` около 270 символов, примерно 50 из которых — греческие буквы. Как и в файлах правил речи, здесь есть автоматически созданные начальные переводы. Проверьте их и измените `t:` на `T:`. Подробнее об автоматическом переводе см. ниже. + * В `unicode-full.yaml` тысячи строк. Вернитесь к нему после завершения остальных переводов и работайте столько, сколько сможете: большинство этих символов встречаются только в сложной математике и даже там используются редко. Наиболее важны: + * некоторые стрелки, начиная с 0x2190; + * символы из блока математических операторов 0x2200–0x22ff; + * некоторые диакритические знаки 0x2d8–0x2dd; + * некоторые простые чёрные и белые фигуры, начиная с 0x25a0 и 0x2b1a. +4. Файлы навигации `navigate.yaml` и `overview.yaml`. Переводите только `navigate.yaml`: `overview.yaml` ещё не готов к использованию. Многие слова в `navigate.yaml` многократно повторяются, поэтому удобно применять глобальный поиск и замену. В дальнейшем файл планируется переработать и выделить повторяющиеся слова. + +__ПРИМЕЧАНИЕ__: Сейчас почти завершён переход правил на использование `intent`. Сложная логика распознавания абсолютных величин, определителей и других конструкций будет перенесена в независимый от языка каталог `intent`. Это упростит перевод, поскольку правилу потребуется сопоставлять только тег `absolute-value` или `determinant`. Тесты также следует вынести в независимый от языка каталог `intent`. + +### Пометка переведённого текста +Эти файлы имеют формат YAML, описанный ниже. +Во всех этих файлах переводимый текст задаётся ключом YAML `t`, а в редких случаях — `ot`, `ct`, `spell`, `pronounce` и `IfThenElse`. После проверки перевода запишите ключ прописными буквами, например `T` или `IFTHENELSE`, чтобы обозначить переведённый фрагмент. + +Например, в `unicode.yaml` есть два правила: +``` + - "=": [t: "equals"] # 0x3d + - ">": # 0x3e + - test: + if: "$Verbosity!='Terse'" + then: [t: "is"] + - t: "greater than" +``` +При переводе на французский язык слова после `t:` заменяются примерно так: +``` + - "=": [T: "égale"] # 0x3d + + - ">": # 0x3e + - test: + if: "$Verbosity!='Terse'" + then: [T: "est"] + - T: "supérieur à" +``` + +Примечание: иногда значение `IfThenElse` не требует перевода, но ключ всё равно следует изменить, чтобы было видно, что строка проверена. В следующем примере перевод не нужен, поскольку части `then` и `else`, соответственно `count(*/*[1])` и `$LineCountTry`, не являются словами: +``` + - LineCount: "IfThenElse($LineCountTry=0, count(*/*[1]), $LineCountTry)" +``` + +Подробнее о содержимом файлов правил см. ниже. + +### Примечание о переведённых файлах +Для получения начального перевода файлов Unicode используются переводы MathPlayer и SRE, а также Google Translate. +Если переводы SRE и MathPlayer совпадают либо перевод есть только в одном из них и совпадает с Google Translate, в комментарий в конце строки добавляется только исходный английский вариант. Например: +``` + - "!": [t: "factorielle"] # 0x21 (en: 'factorial') +``` + +Если переводы MathPlayer и SRE различаются, выбирается вариант, совпадающий с Google Translate, а другой вариант включается в комментарий. Например: +``` + else: [t: "parenthèse gauche"] # (en: 'left paren', MathPlayer: 'parenthèse ouvrante') +``` +Если не совпадает ни один перевод, выбирается один из вариантов, а остальные приводятся в комментарии. Например: +``` + else: [t: "parenthèse gauche"] # (en: 'open paren', MathPlayer: 'parenthèse ouvrante', google: 'parenthèse ouverte') +``` +Наконец, если перевод отсутствует, используется Google Translate и добавляется комментарий `google translation`. Вероятность неудачного перевода в таком случае заметно выше, поэтому внимательно проверяйте эти строки. Пример, где доступен только Google Translate: +``` + then: [t: "ligne verticale"] # (en: 'vertical line', google translation) +``` + + +### Проверка перевода +Если вы используете NVDA, начатый перевод можно сразу проверить. Предполагается, что дополнение MathCAT уже установлено: +1. Скопируйте новый каталог перевода в `%AppData%\nvda\addons\MathCAT\globalPlugins\MathCAT\Rules\Languages`. +2. Запустите NVDA и откройте меню настроек MathCAT: параметры NVDA, затем «Настройки MathCAT...». +3. Выберите новый язык в раскрывающемся списке `Languages`. +4. Проверьте озвучивание. Хорошим источником примеров служат страницы Википедии. +5. Если произошла ошибка, часто выражающаяся в отсутствии речи, откройте журнал NVDA из подменю «Сервис». Ошибка должна быть указана там. Объяснение сообщений об ошибках приведено ниже. +6. MathCAT должен заметить изменение файла и перезагрузить его. Сейчас это не работает для файлов, подключённых с помощью `include`, например для файлов каталога `Shared`. После изменения такого файла перезагрузите MathCAT через «Сервис: Перезагрузить плагины» в NVDA или перезапустите NVDA. + +Перевод диалога настроек выполняется отдельно от перевода речи. Им занимаются добровольцы, которые переводят и другие дополнения. Подробнее см. [эту рассылку](https://groups.io/g/nvda-translations). + +### Автоматические тесты перевода +Тестирование очень важно. MathCAT написан на Rust и содержит множество автоматических тестов, использующих встроенную систему тестирования Rust. Чтобы писать и проверять собственные тесты, [скачайте и установите Rust](https://www.rust-lang.org/tools/install). Знать Rust необязательно: достаточно заменить некоторые английские строки ожидаемыми строками на вашем языке. + +Предположим, что вы переводите на французский язык с кодом `fr`. + +Сначала откройте файл `languages.rs` в каталоге тестов и добавьте строку `mod fr;` после `mod en;` или аналогичной строки другого языка. + +В каталоге `tests\Languages` находятся файл `en.rs` и каталог `en`. +1. Скопируйте `en.rs` в `fr.rs`. +2. Скопируйте каталог `en` в `fr`. +3. Если вы выбрали только один стиль речи, например SimpleSpeak, отредактируйте `fr.rs`: удалите строки, начиная с `mod ClearSpeak {` и заканчивая соответствующей строкой `}`. Удалите подкаталог `ClearSpeak` из каталога `fr`. +4. Желательно перевести все файлы, но на начальном этапе можно ограничиться несколькими. В `fr.rs` закомментируйте каждый непереведённый файл, добавив `//` в начало строки. Например, если вы не перевели файл SimpleSpeak `geometry.yaml`, строка должна выглядеть так: `// mod geometry;`. +5. Начните редактировать файлы: сначала глобально замените `"en"` на `"fr"`, а затем замените английские строки подходящими французскими или другими строками. + +Пример теста: +``` +#[test] +fn common_fraction_half() { + let expr = ""; + test("en", "SimpleSpeak", expr, "1 half"); +} +``` +Для французского языка строка `test` будет выглядеть так: +``` + test("fr", "SimpleSpeak", expr, "un demi"); +``` + +После перевода нескольких тестов запустите автоматическую проверку. +Сначала убедитесь, что английские тесты работают: +``` +cargo test Languages::en +``` +Затем запустите свои тесты. В нашем примере: +``` +cargo test Languages::fr +``` +MathCAT добавляет паузы. В ожидаемых строках тестов они записываются символами `,` и `;`. При необходимости добавьте или удалите эти символы в ожидаемом результате. Если паузы звучат неуместно, добавьте или удалите `pause: xxx` в соответствующем месте одного из файлов `Rules\fr`. + +__Совет__: возможно, быстрее всего сначала запустить тесты на своём языке, не меняя ожидаемые результаты. Все тесты завершатся с ошибкой, но в сообщениях будет показана речь, созданная MathCAT на вашем языке. _Если она верна_, просто замените ей английский текст. После обработки всех ошибок снова запустите тесты. В идеальном случае ошибок больше не будет. + + +### Поддержание перевода в актуальном состоянии +Раздел предстоит написать... + +Со временем планируется создать инструмент, который будет: +1. предупреждать об отсутствующих переводах; +2. предупреждать о правилах из каталога `en`, которые не были скопированы в другой язык, вероятно из-за добавления новых английских правил. + +Такие инструменты будут искать переведённый и непереведённый текст. + + +## Переводчикам Брайля +Если вы хотите добавить поддержку новой системы записи Брайля, скорее всего, придётся начать с нуля, если только она не похожа на уже существующую. +Создайте три файла `.yaml` в каталоге `Rules\Braille\your-braille-language` по образцу файлов из других каталогов Брайля: +1. `xxx_Rules.yaml`, где `xxx` — имя новой системы записи Брайля. Файл содержит правила преобразования MathML в Брайль. +2. `unicode.yaml` — перевод наиболее распространённых символов Брайля. Используйте `Nemeth\unicode.yaml` как отправную точку. Замените `t: xxx` подходящими значениями для вашей системы. Вероятно, для символов, зависящих от контекста, потребуется удалить часть логики или добавить собственную. Например, в коде Немета запятая представляется по-разному внутри числа и вне его. +3. `unicode-full.yaml` — переводы остальных символов. + +Два отдельных файла Unicode нужны потому, что небольшой файл с распространёнными символами ускоряет запуск. Цель этого файла — охватить 99,99 % используемых символов. + +Для UEB и кода Немета потребовалось написать на Rust код очистки. Если для вашего перевода Брайля тоже нужна очистка, создайте issue, чтобы мы вместе могли реализовать необходимый код. + +Перевод Брайля можно сразу проверить. Используйте приведённые выше инструкции для перевода языка, где предлагается скопировать файлы в `%AppData%\nvda\addons\MathCAT\globalPlugins\MathCAT\Rules\Languages`, но замените `Languages` на `Braille`. Остальные действия почти не отличаются. + +Для автоматического тестирования следуйте приведённым выше инструкциям. Текущие тесты взяты из руководств по коду Немета и UEB. Можно поступить так же. Примеры тестов Брайля находятся в каталогах Nemeth и UEB. + +## Понимание сообщений об ошибках MathCAT +Если ошибка вызвана проблемой в правиле, при непосредственном запуске MathCAT сообщение выводится в консоль терминала, а при использовании NVDA — в журнал NVDA. + +Сообщения об ошибках могут показаться сложными. Ниже приведены пример и объяснение. + +Библиотека, которую MathCAT использует для чтения файлов YAML, не сохраняет номера строк, поэтому MathCAT не может сообщить строку с ошибкой. +Вместо этого указываются имя файла, а также значения `name` и `tag` правила в этом файле. +Затем рекурсивно перечисляются разделы правила, в которых обнаружена ошибка. + +Например, ниже приведено сообщение об ошибке, созданное намеренной заменой `test:` на `textx:`: +``` +caused by: in file "...\\MathCAT\\Rules\\Languages\\en\\ClearSpeak_Rules.yaml" +caused by: value for 'replace' in rule (fraction: fraction-over-simple). Replacements: + - test: + if: "$ClearSpeak_Fractions='FracOver'" + then: + - testx: + if: "$Verbosity!='Terse'" + then: [ot: the] + - t: fraction + - x: "*[1]" + - t: over + - x: "*[2]" + - test: + if: "$ClearSpeak_Fractions='OverEndFrac' or ($ClearSpeak_Fractions='EndFrac' and not( ($ClearSpeak_Fractions='Auto' or $ClearSpeak_Fractions='Ordinal' or $ClearSpeak_Fractions='EndFrac') and *[1][*[1][self::m:mn][not(contains(., '.')) and ($ClearSpeak_Fractions='Ordinal' or text()<20)] and *[2][self::m:mn][not(contains(., '.')) and ($ClearSpeak_Fractions='Ordinal' or (2<= text() and text()<=10))] ] and *[2][*[1][self::m:mn][not(contains(., '.')) and ($ClearSpeak_Fractions='Ordinal' or text()<20)] and *[2][self::m:mn][not(contains(., '.')) and ($ClearSpeak_Fractions='Ordinal' or (2<= text() and text()<=10))] ] ) )" + then: + - pause: short + - t: end fraction + - pause: short +caused by: replacement #1 of 5 +caused by: replacement #1 of 2 +caused by: Unknown 'replace' command (testx) with value: if: "$Verbosity!='Terse'" then: [ot: the] +``` +Первые две строки содержат имя файла, а также значения `tag` и `name`. Соответствующее правило: +``` +- name: fraction-over-simple + tag: fraction + match: + - "($ClearSpeak_Fractions='Over' or $ClearSpeak_Fractions='FracOver' or $ClearSpeak_Fractions='OverEndFrac') or" + - "( not($ClearSpeak_Fractions='General' or $ClearSpeak_Fractions='GeneralEndFrac') and" + - " (IsNode(*[1],'simple') and IsNode(*[2],'simple')) )" # simple fraction in ClearSpeak spec + replace: + - test: + if: "$ClearSpeak_Fractions='FracOver'" + then: + - testx: + if: "$Verbosity!='Terse'" + then: [{ot: "the"}] + - t: "fraction" + - x: "*[1]" + - t: "over" + - x: "*[2]" + - test: + # very ugly!!! -- replicate nested ordinal fraction as they are an exception + if: "$ClearSpeak_Fractions='OverEndFrac' or ($ClearSpeak_Fractions='EndFrac' and not( ($ClearSpeak_Fractions='Auto' or $ClearSpeak_Fractions='Ordinal' or $ClearSpeak_Fractions='EndFrac') and *[1][*[1][self::m:mn][not(contains(., '.')) and ($ClearSpeak_Fractions='Ordinal' or text()<20)] and *[2][self::m:mn][not(contains(., '.')) and ($ClearSpeak_Fractions='Ordinal' or (2<= text() and text()<=10))] ] and *[2][*[1][self::m:mn][not(contains(., '.')) and ($ClearSpeak_Fractions='Ordinal' or text()<20)] and *[2][self::m:mn][not(contains(., '.')) and ($ClearSpeak_Fractions='Ordinal' or (2<= text() and text()<=10))] ] ) )" + then: + - pause: short + - t: "end fraction" + - pause: short +``` + +Следующая часть сообщения, `caused by: replacement #1 of 5`, указывает, что проблема находится в первой замене, то есть первом элементе с `-`. +Строка `caused by: replacement #1 of 2` означает, что ошибка находится в первой части этой замены. +Последняя строка сообщает о неизвестной команде замены: `Unknown 'replace' command (testx) with value`. Теперь проблему можно исправить. +Часто сообщение об ошибке удобнее читать снизу вверх. + + +## Разработчикам Rust +Раздел предстоит написать... + +`build.rs` и файлы в `src`. + +## Тестирование +Независимо от того, разрабатываете вы код или пишете правила, крайне важно писать и запускать тесты. Они позволяют убедиться, что новый код работает и не нарушает существующую функциональность. + +Каталог `tests` похож на каталог `Rules`. Если вы переводчик, см. инструкции в соответствующем разделе выше. + +Rust поддерживает тестирование с помощью команды `cargo test`. Подробнее о тестах и покрытии тестами см. в [руководстве разработчика](developers.md). + + +## Файлы +MathCAT считывает важную информацию из следующих файлов: +* Rules + * `intent.yaml` — правила, определяющие намерение автора по MathML. Они используются разными стилями речи на разных языках, чтобы не дублировать процесс определения смысла, и добавляют к MathML атрибут `intent`. + * `definitions.yaml` — различные списки для канонизации MathCAT, то есть определения правильной структуры, и сопоставления правил. Например, `TrigFunctionNames` содержит имена тригонометрических функций, такие как `tan` и `lim`. + * `prefs.yaml` — значения по умолчанию для доступных настроек. MathCAT также ищет этот файл в зависящем от платформы пользовательском каталоге, чтобы отдельные пользователи могли задавать собственные значения. + * Windows: `%AppData%\prefs.yaml`. + * Linux: `$XDG_CONFIG_HOME` или `$HOME/.config`. + * `definitions.yaml` — независимые от языка определения, например имена тригонометрических функций. +* Rules/[lang] + * `Unicode.yaml` — длинный список способов произнесения встречающихся символов Unicode. Не используется для строк из нескольких символов. + * `XXX_rules.yaml` — правила озвучивания математических выражений. MathCAT сканирует каждый подкаталог `Rules`, ищет файлы с суффиксом `_rules.yaml` и добавляет их в список доступных пользователю вариантов. Часть `XXX` должна соответствовать стилю речи. Например, `ClearSpeak_rules.yaml` и `MathSpeak_rules.yaml` добавляют варианты стиля речи ClearSpeak и MathSpeak. + * `definitions.yaml` — зависящие от языка определения, например способы произнесения порядковых числительных: «первый», «половина» и т. д. + * `navigate.yaml` — правила, определяющие результат каждой команды навигации и соответствующий текст для озвучивания. + +Подкаталог `lang` должен соответствовать двухбуквенному коду языка или комбинации языка и региона согласно [стандарту ISO](https://en.wikipedia.org/wiki/Language_localisation#Language_tags_and_codes). Например, в каталоге `Rules` есть подкаталог `en`. Если требуется региональный вариант речи, можно добавить подкаталог региона, например `gb`, который будет использоваться для языка `en-gb`. + +MathCAT сначала читает правила основного языка, а затем правила региона. Региональные правила заменяют существующие правила или добавляются к ним в соответствующих языковых файлах `Unicode.yaml` и `XXX_rules.yaml`. + +MathCAT ищет каталог `Rules` в следующих местах: +1. В каталоге, заданном переменной среды `MathCATRulesDir`. +2. В соседнем с исполняемым файлом подкаталоге Rules. В Windows это обычно `C:\Program Files\MathCAT\Rules`. + +# Формат файлов +Файлы, как следует из их суффикса, имеют [формат YAML](https://lzone.de/cheat-sheet/YAML). Если вы ещё не знакомы с YAML, это надмножество JSON с более удобными для чтения и записи вариантами синтаксиса. + +## Введение в YAML +Основные типы YAML: +* скалярные типы, например целые и вещественные числа, а также строки. Строки можно заключать в одинарные или двойные кавычки, а в некоторых случаях оставлять без кавычек; +* массивы, которые внутри строки записываются как `["a", "b", "c"]`; +* словари или отображения, которые внутри строки записываются как `{key: value, foo: bar}`. + +Комментарии начинаются с символа `#` и продолжаются до конца строки. Блочных комментариев в YAML нет. + +В более подробном синтаксисе YAML для массивов вместо скобок используются отступы, поэтому приведённый выше массив выглядит так: +``` + - a + - b + - c +``` +Обратите внимание, что в такой форме строки не требуется заключать в кавычки, хотя для некоторых текстов кавычки необходимы. + +Словарь в подробной форме выглядит так: +``` + key: value + foo: bar +``` + +Ниже приведён более реалистичный пример из определений Unicode с несколькими вариантами записи. +Обратите внимание на отступы: все элементы, сдвинутые вправо относительно предыдущей строки, являются вложенными элементами массива или словаря. +``` +# Два способа задать простую замену для символа '∞'. +# Для краткости и ясности предпочтительна первая форма. + - "∞": [t: "infinity"] # 0x221e + - '∞': + - t: infinity # 0x222e + +# Несколько способов задать более сложное определение с проверкой. +# Компактная форма использует синтаксис JSON для значения. +- 0x003C: [test: {if:Verbosity!='terse', then: [t: is]}, t: "less than"] + +# Эта форма подчёркивает, что выполняются два действия: проверка и вывод "less than". +- 0x003C: + - test: [{if: Verbosity!='terse', then: {t: is}}] + - t: "less than" + +# Эта форма немного подробнее, но ясно показывает части проверки. +- 0x003C: + - test: + if: Verbosity!='terse' + then: [t: is] + - t: less than + +# Самая подробная форма YAML. +- 0x003C: + - test: + if: Verbosity!='terse' + then: + - t: is + - t: less than +``` +Все формы допустимы, но второй и третий варианты предпочтительны как хороший компромисс между краткостью и ясностью. + +Примечание: все файлы YAML начинаются с `---`, обозначающего начало документа. + +## Основные части правила речи + +``` +# rule: +# name:
`"simple"` — заданный набор элементов ClearSpeak;
`"leaf"` — один из листовых элементов MathML;
`"2D"` — двумерный узел, например `mfrac` или `mroot`;
`"modified"` — узел с индексом или элементом над ним либо под ним;
`"scripts"` — узел с подстрочным и (или) надстрочным индексом;
`"common_fraction"` — целочисленные числитель и знаменатель. | +| `ToOrdinal` | | +| `ToCommonFraction` | | +| `IsBracketed(openChar, closeChar, requiresComma)` | | +| `BaseNode(node)` | Рекурсивно возвращает основу узла с индексами. | +| `IsInDefinition(node, name)` | Возвращает true, если узел входит в список `name`, заданный в `definitions.yaml`. | +| `IfThenElse(test, then-part, else-part)` | Возвращает `then-part`, если условие истинно, иначе возвращает `else-part`. Все аргументы являются XPath. | +| `DistanceFromLeaf(node, left_side, treat_2d_elements_as_tokens)` | Возвращает расстояние от текущего узла до крайнего левого или правого листа: для символа 0, для токена 1. Если `left_side` равно `true`, обход выполняется по крайним левым дочерним узлам до листа. Если `treat_2d_elements_as_tokens` равно `true`, двумерные обозначения, например дроби, считаются листами. | +| `EdgeNode(node, "left"/"right", stopNodeName)` | Возвращает узел остановки, если исходный узел находится у левого или правого края указанного предка. Значением `stopNodeName` также может быть `"2D"`. Если соответствие не найдено, возвращается исходный узел. Если `stopNodeName=="math"`, учитывается пунктуация, поскольку она не является частью математического выражения. | +| `DEBUG(xpath)` | Добавляет полезные для диагностики сведения в отладочный вывод. | + +Следующие функции используются правилами кода Немета: + +| Функция | Значение | +| ----- | ---- | +| `NestingChars` | Используется правилами `mfrac`, `msqrt` и `mroot`, чтобы повторять символы нужное количество раз. | +| `BrailleChars` | Используется элементами-токенами для сложной перестановки индикаторов кода Немета, например прописных букв и начертания шрифта. | diff --git a/docs/ru/index.md b/docs/ru/index.md new file mode 100644 index 00000000..8d06d475 --- /dev/null +++ b/docs/ru/index.md @@ -0,0 +1,207 @@ +--- +layout: default +lang: ru +ref: index +title: MathCAT +--- +# MathCAT: средство обеспечения доступности математики +
+— библиотека, которая преобразует MathML в:
+
+* текст для озвучивания со встроенными командами речевого синтезатора;
+* Брайль (код Немета, технический вариант UEB, а в дальнейшем и другие математические системы записи Брайля);
+* представление для навигации по математическим выражениям, в том числе с возможностью обзора.
+
+Цель MathCAT — предоставить программам экранного доступа и другим вспомогательным технологиям удобную библиотеку для качественного озвучивания MathML и преобразования MathML в Брайль. MathCAT продолжает идеи MathPlayer (подробнее об этом будет сказано ниже) и использует накопленный в этом проекте опыт, чтобы ещё лучше озвучивать математические выражения, представлять их в Брайле и обеспечивать навигацию по ним. В MathCAT применяются новые идеи, которые разрабатывает [рабочая группа MathML](https://mathml-refresh.github.io/charter-drafts/math-2020.html): они позволяют авторам указывать смысл использованного обозначения. Например, $(3, 6)$ может обозначать точку на плоскости, открытый интервал или даже сокращённую запись наибольшего общего делителя. Если эта информация передана в MathML, MathCAT использует её для более естественного озвучивания.
+
+Предстоит сделать: подключить сторонние библиотеки для поддержки общего подмножества математических команд TeX и ASCIIMath.
+
+
+# Документация для разных пользователей MathCAT
+
+MathCAT используют разные аудитории с различными потребностями и задачами. Подробности приведены в соответствующих разделах документации:
+* Пользователи вспомогательных технологий: [информация о доступных настройках](users.md).
+* Разработчики вспомогательных технологий и пользователи библиотеки: [информация об API MathCAT](callers.md).
+* Переводчики и авторы правил: [информация о файлах, которые необходимо перевести](helpers.md).
+* Разработчики MathCAT: [информация о процессе разработки и тестировании](developers.md).
+
+# Некоторые технические подробности
+MathCAT написан на Rust и может использоваться из многих языков программирования. На данный момент есть интерфейсы для:
+* [C/C++](https://github.com/NSoiffer/MathCATForC);
+* [Python](https://github.com/NSoiffer/MathCATForPython) — этот интерфейс используют [дополнение NVDA](https://addons.nvda-project.org/addons/MathCAT.en.html) и программа экранного доступа [Orca](https://help.gnome.org/users/orca/stable) для Linux, написанные на Python;
+* [Java](https://github.com/mwhapples/MathCAT4J) — сейчас этот интерфейс используется для экспериментов с MathCAT в [BrailleBlaster](https://www.brailleblaster.org/);
+* [WebAssembly (Wasm, отчасти похожий на JavaScript)](https://github.com/NSoiffer/MathCATDemo/) — этот интерфейс используется в веб-демонстрации MathCAT.
+
+MathCAT применяет несколько эвристик, чтобы исправлять некачественный MathML и приводить его к рекомендованному виду. Например, конвертеры TeX и WYSIWYG-редакторы могут разделить число «1,234» в выражении «1,234+1» по запятой. MathCAT распознаёт такую ситуацию и объединяет число в один элемент `mn`. Другие исправления затрагивают структуру: MathCAT создаёт элементы `mrow` с учётом словаря операторов MathML и при необходимости добавляет невидимые знаки применения функции, умножения, сложения (для смешанных дробей) и разделители (например, между $i$ и $j$ в $a\_{ij}$). Это упрощает генерацию речи и кода Немета, а также может быть полезно другим приложениям. Сейчас очистка MathML не доступна через API, но в дальнейшем может стать ещё одной функцией MathCAT. В целом MathCAT исправляет MathML достаточно осторожно. Иногда результат может оказаться неверным, однако ожидается, что правильных исправлений будет значительно больше. Поиск типичных ошибок в конвертерах MathML и исправление некачественного MathML остаются постоянной задачей проекта.
+
+## Текущее состояние (обновлено 27.03.2026)
+
+MathCAT активно развивается. DAISY принимает деятельное участие в разработке, и вклад новых участников приветствуется. MathCAT распространяется с открытым исходным кодом. [Репозиторий проекта доступен на GitHub](https://github.com/daisy/MathCAT). [О проблемах дополнения MathCAT, относящихся к NVDA, можно сообщить здесь](https://github.com/daisy/MathCATForPython/issues).
+
+* MathCAT поддерживает озвучивание и навигацию для английского, немецкого, испанского, финского, индонезийского, норвежского, шведского, вьетнамского и китайского языков (традиционное письмо).
+* MathCAT поддерживает код Немета, UEB, CMU, вьетнамскую систему записи Брайля, а также немецкую и австрийскую системы записи LaTeX и ASCIIMath.
+* Существует [дополнение NVDA](https://addons.nvda-project.org/addons/MathCAT.en.html). Оно может заменить MathPlayer для пользователей английского языка и поддерживаемых переводов. Начиная с NVDA 2026.1 MathCAT встроен в NVDA, поэтому скачивать дополнение не нужно.
+
+Преобразование в код Немета в MathCAT значительно качественнее, чем в MathPlayer и других конвертерах MathML → код Немета. Оно также интегрировано с навигацией: точки 7 и 8 обозначают текущий узел, а маршрутизация курсора Брайля работает во время навигации. Благодаря высокому качеству вывода [BrailleBlaster](https://www.brailleblaster.org/) использует MathCAT для преобразования MathML в код Немета и UEB.
+
+Ряд других разработчиков вспомогательных технологий также включили MathCAT в свои продукты. Среди них особенно выделяется Vispero/JAWS. Сейчас JAWS поддерживает озвучивание MathCAT на английском и испанском языках, а также вывод в коде Немета и UEB. В дальнейшем появятся другие языки и системы записи Брайля. В средстве просмотра математических выражений JAWS доступны все предусмотренные MathCAT команды озвучивания и навигации, в том числе навигации по Брайлю. Настройки MathCAT находятся в центре настроек JAWS.
+
+Другие вспомогательные технологии, использующие MathCAT:
+
+* программа экранного доступа Orca для Linux использует MathCAT для озвучивания, навигации и вывода в Брайле;
+* Dolphin EasyReader использует MathCAT;
+* Kurzweil 3000 использует озвучивание MathCAT и одновременно выделяет соответствующее подвыражение двумя цветами, обеспечивая наглядное визуальное сопровождение для зрячих пользователей;
+* Microsoft объявила, что Экранный диктор будет использовать MathCAT в одной из будущих версий.
+
+[_Другим компаниям_: если вы включили MathCAT в свой продукт и хотите, чтобы он был упомянут здесь, напишите мне по электронной почте или создайте issue с предложением обновить документацию.]
+
+Была разработана [демонстрационная версия](https://nsoiffer.github.io/MathCATDemo/), которая показывает некоторые возможности MathCAT и помогает при отладке. Сообщайте, пожалуйста, обо всех найденных ошибках. Эта демонстрация _не_ отражает типичный способ взаимодействия пользователей вспомогательных технологий с MathCAT, но показывает функции, которые такие технологии потенциально могут предоставить конечным пользователям: выделение озвучиваемого фрагмента, навигацию и вывод в Брайле.
+
+Планы дальнейшей работы:
+
+* Добавить другие языки. Если вы хотите перевести MathCAT на язык, который пока не поддерживается, создайте issue в [репозитории MathCAT на GitHub](https://github.com/daisy/MathCAT/issues).
+* Поддержать дополнительные системы записи Брайля. Для добавления такой поддержки нужны три составляющие:
+ * спецификация системы;
+ * возможность задавать вопросы специалисту по соответствующей системе записи Брайля;
+ * человек, готовый перенести не менее 200 примеров из спецификации в используемый для тестов формат: MathML и строку символов Брайля в Unicode. Это может занять 30 часов или больше.
+
+ Если вы можете собрать всё необходимое, создайте issue в [репозитории MathCAT на GitHub](https://github.com/daisy/MathCAT/issues).
+* Реализовать преобразование _из_ Брайля _в_ MathML.
+* Разработать двумерные варианты систем записи Брайля для многострочных обновляемых дисплеев Брайля, например Monarch и Canute 360.
+
+
+
+## Почему MathCAT?
+
+MathCAT — продолжение MathPlayer. Я начал разрабатывать функции доступности MathPlayer в компании Design Science в 2004 году вскоре после прихода в компанию. В то время MathPlayer был главным образом подключаемым модулем C++ для Internet Explorer (IE), отображавшим MathML на веб-страницах. Долгое время это была наиболее полная из доступных реализаций MathML. Первоначальную работу над отображением математических выражений выполнили основатель Design Science Пол Топпинг и технический директор компании, ныне покойный Роберт Майнер. Позже по ряду причин IE отказался от интерфейса, который MathPlayer использовал для отображения, и не предложил ему замену: веб переходил к использованию JavaScript в браузере и отказывался от рисков безопасности, связанных с внешним кодом. После этого MathPlayer стал библиотекой, предназначенной исключительно для обеспечения доступности и вызываемой другими программами, главным образом NVDA. MathPlayer был проприетарным, но распространялся бесплатно.
+
+В начале 2017 года я покинул Design Science. Позже в том же году WIRIS приобрела компанию. Я предложил бесплатно исправлять ошибки MathPlayer, и сначала эта инициатива получила поддержку. Но когда пришло время выпускать новую версию, многие сотрудники, работавшие в компании во время приобретения, уже ушли, а оставшаяся команда не была заинтересована в поддержке MathPlayer. Окончательное решение было принято только в конце 2020 года. В 2021 году я начал работать над заменой MathPlayer. В качестве дополнительной задачи я решил изучить Rust и реализовал проект на нём. Rust — низкоуровневый язык со строгой типизацией и безопасной работой с памятью, но без автоматической сборки мусора или подсчёта ссылок. Его часто называют более безопасной заменой C/C++.
+
+Rust достаточно эффективен. На компьютере с Core i7-770K (мощным по меркам примерно 2017 года процессором) для выражения среднего размера
+
+требуется около 4 мс, чтобы создать строку ClearSpeak на английском языке
+"_e raised to the exponent, negative 1 half times; open paren; the fraction with numerator; x minus mu; and denominator sigma; close paren squared, end exponent_"
+и строку в коде Немета "⠑⠘⠤⠹⠂⠌⠆⠼⠈⠡⠷⠹⠭⠤⠨⠍⠌⠨⠎⠼⠾⠘⠘⠆".
+Примерно 2 мс занимают очистка MathML, 1 мс — генерация речи, ещё 1 мс — генерация Брайля. Сюда входит проверка актуальности всех файлов правил, которая оказывается достаточно затратной. Эту проверку можно отключить с помощью настройки: она нужна главным образом при отладке. Если проверка отключена, время уменьшается до 2,3 мс.
+На более мощном процессоре Intel Core Ultra 9 285 2025 года генерация речи и Брайля в одном потоке занимает около 1 мс.
+
+
+
+
+Для генерации речи и Брайля MathCAT использует внешние правила.
+Их загрузка занимает около 40 мс. Она выполняется только при первом использовании правил или после изменения стиля речи, языка либо другой внешней настройки. Ещё 50 мс требуется для загрузки полных файлов Unicode для речи и Брайля, однако исследования показали, что в подавляющем большинстве англоязычных математических материалов для школьного обучения используются лишь немногие символы.
+Судя по книгам по математике с открытым исходным кодом, первоначально загружаемого набора должно быть достаточно как минимум для 99,99 % символов, встречающихся в выражениях англоязычных школьных учебников математики.
+
+Размер библиотеки составляет около 3 МБ.
+
+Если вы разрабатываете решение для работы непосредственно в браузере, то есть используете JavaScript или другой браузерный язык, MathCAT, вероятно, не будет оптимальным выбором. При этом я, скорее всего, выделю из [MathCATDemo](https://github.com/NSoiffer/MathCATDemo/) интерфейс JavaScript, на котором построена демонстрационная версия. Пока обратите внимание на [Speech Rule Engine](https://github.com/zorkow/speech-rule-engine) (SRE) Фолькера Зорге. Он написан на TypeScript и, вероятно, подойдёт для браузерного решения, если вам не требуется Брайль. MathCAT поддерживает несколько систем записи Брайля и как минимум для кода Немета обеспечивает более качественный результат.
+
+# Благодарности
+
+Проекту помогали многие люди, и я очень признателен им за это!
+
+* Дэвид Карлайл — оказал неоценимую помощь с некоторыми выражениями сопоставления XPath.
+* Сьюзан Джолли — терпеливо консультировала по генерации кода Немета и UEB, а также давала обратную связь о правильных и ошибочных результатах. Кроме того, она помогла мне при разработке эвристик для химических формул.
+* Элейн А. Мур — помогла определить, что следует и не следует произносить для химических формул, а также какие записи имеют смысл с точки зрения химии.
+* Ричард Орм — полностью разработал диалог настроек MathCAT для NVDA.
+* Сэм Дули, Мюррей Сарджент и Фолькер Зорге — предоставили таблицы перевода символов в код Немета и тесты этого кода.
+* Мориц Гросс ([Math4VIP](https://www.math4vip.de/)) — работал над различными частями кодовой базы Rust и создал инструмент Python для отслеживания прогресса локализации.
+
+Переводчики:
+
+* Китайский язык (традиционное письмо) — Хон-Джанг Янг.
+* Финский язык — Сами Мяяття, Accessibility Library Celia и независимый специалист Эсси Вииппола.
+* Немецкий язык — Назли Анджич, Роберт Граф и Пол Либбрехт (IU International University of Applied Sciences).
+* Индонезийский язык — доктор Пинта Дениянти Сампоэрно, магистр наук; доктор Мейлиасари, бакалавр педагогических наук, магистр наук; Ари Хендарно, бакалавр педагогических наук, магистр компьютерных наук.
+* Норвежский язык — Марте Гьельстад, Национальная библиотека Норвегии, Kvile.
+* Русский язык — Данил Костенков.
+* Испанский язык — Ноэлия Руис Мартинес, которая также помогала в разработке дополнения NVDA, и Мария Алло Рольдан.
+* Шведский язык — Тим Арбореалис Лётберг, Шведское агентство доступных медиа (MTM), и Андерс Эклунд, SPSM.
+* Вьетнамский язык — Данг Хоай Фук и Транг Фам.
+* Другие языки??? — присоединяйтесь, чтобы я мог указать вас здесь...
+
+Первоначальный перевод многих символов Брайля для систем записи, разработанных в 2024 году и позднее, был существенно упрощён благодаря таблице, которую мне предоставил Георгиос Курупретроглу и над которой работала большая команда. Для получения подробной информации обратитесь к:
+
+* [MathBrailleCodes Repository](https://access.uoa.gr/mathbraille/index.php/en/), Speech and Accessibility Lab, National and Kapodistrian University of Athens, Greece: P. Riga, T. Antonakopoulou, D. Kouvaras, S. Lentas and G. Kouroupetroglou (2021) “[The BrailleMathCodes Repository](https://access.uoa.gr/mathbraille/index.php/en/)”, Proceedings of the 4th International Workshop on “[Digitization and e-Inclusion in Mathematics and Science 2021](https://workshop.sciaccess.net/deims2021/DEIMS2021_Proceedings.zip)” DEIMS2021, February 18-19, 2021, Tokyo, pp. 105-114.
+
+Спасибо всем участникам!
+
+# Обо мне
+
+Я работаю над обеспечением доступности математических выражений с 2002 года. В то время я занимался WYSIWYG-редактором формул Mathematica и другими элементами пользовательского интерфейса. Профессор Джон Гарднер, потерявший зрение пятнадцатью годами ранее, спросил, могу ли я сделать интерфейс Mathematica доступным. Мне удалось выполнить, вероятно, около 80 % работы, но компания не захотела продолжать проект. В конечном итоге я ушёл, а компания удалила код. Так начался мой путь в сфере доступности: шаг вперёд, шаг назад и снова вперёд, потому что возможность дать _каждому_ шанс открыть для себя радость математики и науки наполнила мою жизнь смыслом.
+
+Затем я перешёл в компанию Design Science, Inc (DSI), заинтересованную в обеспечении доступности математики. Незадолго до этого DSI разработала MathPlayer — подключаемый модуль для IE6, отображавший MathML. Я добавлял в него новые функции и при поддержке компании подал заявку на грант NSF для обеспечения доступности MathPlayer. Заявка была одобрена, а работа оказалась весьма успешной. В последующие годы я продолжал развивать MathPlayer. Однако из соображений безопасности Internet Explorer удалил интерфейс, от которого зависел MathPlayer. Возникает соблазн сказать, что именно это и погубило IE... После этого MathPlayer стал дополнением NVDA, предназначенным исключительно для обеспечения доступности. Дальнейшая работа по гранту IES совместно с ETS помогла усовершенствовать возможности MathPlayer. Финансируемые грантом пользовательские исследования дали ценную информацию.
+
+Подробнее об истории MathPlayer и появлении MathCAT вы можете узнать в разделе [«Почему MathCAT?»](#why-mathcat).
+
+На протяжении всего этого времени я стремился обеспечить поддержку математических выражений в интернете и сделать их доступными. Работая в Wolfram Research, я помог запустить проект W3C MathML и с тех пор участвую в деятельности рабочей группы. Сейчас я являюсь сопредседателем рабочей группы W3C Math. За эти годы я также участвовал в работе нескольких других комитетов и активно добивался включения доступности математических выражений в их стандарты. Среди таких групп — NIMAS, EPUB и PDF/UA.
+
+Для меня большая честь, что в 2023 году Национальная федерация слепых присудила мне премию Джейкоба Болотина в размере $25 000. Из этой суммы я пожертвовал $15 000 проекту _Open Collective_ для улучшения поддержки MathML в браузерах. [По этой ссылке можно узнать, как помочь улучшить поддержку MathML в браузерах](https://opencollective.com/mathml-core-support).
diff --git a/docs/ru/nav-commands.md b/docs/ru/nav-commands.md
new file mode 100644
index 00000000..e26f526e
--- /dev/null
+++ b/docs/ru/nav-commands.md
@@ -0,0 +1,54 @@
+---
+layout: default
+lang: ru
+ref: nav-commands
+title: Команды навигации MathCAT
+---
+# Команды навигации MathCAT и соответствующие сочетания клавиш
+
+При навигации используются два независимых режима:
+* Режим озвучивания после перемещения: выражение читается или описывается, то есть после каждого перемещения озвучивается его краткое описание или обзор.
+* Режим навигации: перемещение по подвыражениям, небольшим фрагментам или символам. Сочетания Shift+стрелка вниз и Shift+стрелка вверх циклически переключают более подробные и более общие режимы.
+
+Объяснение этих режимов приведено после таблицы в разделе [«Режимы навигации»](#navigation-modes).
+
+Примечание: при навигации по выражению сочетание Ctrl+C в NVDA копирует математическое содержимое текущего узла в формате MathML, LaTeX, ASCIIMath или текста для озвучивания.
+
+
+## Таблица команд навигации
+
+| Клавиша | Без модификатора | + Ctrl | + Shift | + Ctrl + Shift |
+| --- | --- | --- | --- | --- |
+| **Стрелка влево** | Перейти к предыдущему элементу | В таблице: перейти к предыдущей ячейке.Показать MathML этого выражения
++<math> + <mrow> + <msup> + <mi>e</mi> + <mrow> + <mo>−</mo> + <mfrac> + <mn>1</mn> + <mn>2</mn> + </mfrac> + <msup> + <mrow> + <mrow> + <mo>(</mo> + <mrow> + <mfrac> + <mrow> + <mi>x</mi> + <mo>−</mo> + <mi>μ</mi> + </mrow> + <mi>σ</mi> + </mfrac> + </mrow> + <mo>)</mo> + </mrow> + </mrow> + <mn>2</mn> + </msup> + </mrow> + </msup> + </mrow> +</math> ++
В столбиковой записи: перейти к предыдущей цифре.
Примечание: также можно использовать Ctrl+Alt+стрелка влево. | Прочитать предыдущий элемент | Описать предыдущий элемент | +| **Стрелка вправо** | Перейти к следующему элементу | В таблице: перейти к следующей ячейке.
В столбиковой записи: перейти к следующей цифре.
Примечание: также можно использовать Ctrl+Alt+стрелка вправо. | Прочитать следующий элемент | Описать следующий элемент | +| **Стрелка вверх** | Уменьшить детализацию | В таблице: перейти к ячейке выше.
В столбиковой записи: перейти к цифре выше.
Примечание: также можно использовать Ctrl+Alt+стрелка вверх. | Перейти к более общему режиму навигации: расширенному, простому или посимвольному | Уменьшить детализацию до минимальной | +| **Стрелка вниз** | Увеличить детализацию | В таблице: перейти к ячейке ниже.
В столбиковой записи: перейти к цифре ниже.
Примечание: также можно использовать Ctrl+Alt+стрелка вниз. | Перейти к более подробному режиму навигации: расширенному, простому или посимвольному | Увеличить детализацию до максимальной | +| **Enter** | Сообщить текущую позицию | Сообщить полную текущую позицию | | | +| **Цифры**
**1–10 (0 означает 10)** | Перейти к метке позиции | Установить метку позиции | Прочитать содержимое метки позиции | Описать содержимое метки позиции | +| **Пробел** | Прочитать текущий элемент | Прочитать текущую ячейку | Переключить режим речи между чтением и описанием | Описать текущий элемент | +| **Home** | Перейти к началу выражения | Перейти к началу строки | Перейти к началу столбца.
Перейти к верхней цифре. | _Пока не реализовано:_ прочитать от начала выражения | +| **End** | Перейти к концу выражения | Перейти к концу строки | Перейти к концу столбца.
Перейти к нижней цифре. | _Пока не реализовано:_ прочитать до конца выражения | +| **Backspace** | Вернуться к предыдущей позиции | | | | + + +## Режимы навигации + +MathCAT поддерживает три режима навигации: расширенный, простой и посимвольный. Первые два режима следуют смыслу озвученного выражения, если только не выбран режим LiteralSpeech. Например, в выражении $\vert x+y \rvert > 0$ вертикальные линии, обозначающие абсолютную величину, не читаются буквально. Вместо них произносится «модуль». При увеличении детализации MathCAT сразу перейдёт к чтению «x плюс y». В посимвольном режиме при перемещении по выражению будут последовательно произнесены «вертикальная линия», «x», «плюс», «y», «вертикальная линия», «больше», «ноль». + +* _Расширенный режим_: перемещение между математически значимыми фрагментами: операторами, ограничителями и операндами. +* _Простой режим_: перемещение по словам. Когда встречается двумерное обозначение, например дробь или корень, оно читается целиком. Увеличение детализации позволяет изучить двумерное обозначение в том же режиме. После уменьшения детализации или выхода из двумерного обозначения выполняется возврат на внешний, более общий уровень навигации. +* _Посимвольный режим_: в действительности включает два полезных режима — режим слов и режим символов. Чтобы перейти к настоящему посимвольному режиму, увеличьте детализацию. Перемещение выполняется по словам или символам. Разница заметна в многозначных числах и именах функций из нескольких символов, например `sin`. В остальных случаях навигация по словам и символам работает одинаково. В обоих вариантах детализация дробей и других подобных элементов увеличивается автоматически. + +## Типичный сценарий использования + +Обычно навигация начинается с первого члена выражения, после чего пользователь при необходимости перемещается вправо. Для перехода между уровнями используются стрелки вверх и вниз. Для перемещения по элементам таблицы используется Alt+Ctrl+стрелка. + +Нажатие Backspace возвращает к предыдущей позиции, что не всегда совпадает с перемещением влево. Например, если стрелка вправо вывела вас из дроби, Backspace вернёт в ту же позицию знаменателя, а стрелка влево перейдёт ко всей дроби. + +Вероятно, большую часть времени вам будет удобнее один определённый режим навигации. Его можно задать в настройках MathCAT. +Однако в любой момент навигации режим можно переключить с помощью Shift+стрелка вверх или Shift+стрелка вниз. +Это полезно, поскольку у каждого режима навигации есть свои преимущества и ограничения. + +## Благодарности +Одна из версий этого документа была подготовлена в рамках проекта ClearSpeak. +ClearSpeak поддерживался Институтом педагогических наук Министерства образования США в рамках гранта R324A110355, предоставленного Educational Testing Service. diff --git a/docs/ru/new_translators_guide_MathCAT_revised.md b/docs/ru/new_translators_guide_MathCAT_revised.md new file mode 100644 index 00000000..a44bb640 --- /dev/null +++ b/docs/ru/new_translators_guide_MathCAT_revised.md @@ -0,0 +1,568 @@ +--- +layout: default +lang: ru +ref: new-translators-guide +title: Руководство переводчика MathCAT +--- +# Руководство переводчика MathCAT + +В этом руководстве объясняется, как создать или обновить перевод MathCAT. В качестве примера целевого языка используется португальский. + +Большая часть руководства посвящена **переводу речи (TTS)**. Если вы работаете над Брайлем, всё равно сначала прочитайте описание основного процесса: настройка среды и тестирование во многом похожи. Затем перейдите к разделу [«Перевод Брайля»](#braille-translation), чтобы узнать об отличиях. + +Для качественного перевода **необязательно** быть опытным программистом. Некоторые успешные переводчики начинали с базовыми знаниями программирования без опыта работы с YAML и Rust. Важнее всего хорошо знать целевой язык, понимать, как на нём обычно произносят или записывают математические выражения, и тщательно проверять результат. + +Знание математики будет очень полезно. Необязательно быть профессиональным математиком, но необходимо замечать неестественные, неясные или математически неверные формулировки. Хорошей отправной точкой будет владение языком на уровне носителя и уверенное знание математики примерно на уровне университета. + +## Оценка трудозатрат + +Полный перевод требует времени, особенно если вы стремитесь сделать его надёжным и удобным. + +Судя по реальным проектам, тщательный перевод TTS может занять около **300–450 часов**, а перевод Брайля — около **160–240 часов**. Сроки сильно зависят от качества исходной заготовки, наличия похожего языка и вашего опыта программирования. + +## Нужна помощь в начале работы? + +Это руководство написали Марте Гьельстад, Тим Арбореалис Лётберг и Андерс Эклунд, создавшие норвежский и шведский переводы MathCAT. Если вам нужна помощь, напишите нам: + +**[mathcat-wg@daisylists.org](mailto:mathcat-wg@daisylists.org)** + +--- + +## Рекомендуемый процесс + +Работу над переводом MathCAT удобно организовать так: + +1. Настроить рабочую копию. +2. Обновить и проверить перевод с помощью аудита. +3. Как можно раньше начать слушать речь. +4. Добавить и запустить тесты. +5. Изучить режимы речи и уровни подробности. +6. Работать с файлами правил. +7. Попросить математика проверить перевод. +8. Провести пользовательское тестирование. +9. Отправить перевод. +10. Поддерживать перевод в актуальном состоянии. + +--- + +## Шаг 1. Настройте рабочую копию + +### Получите репозиторий + +MathCAT размещён на GitHub. + +Если вы раньше не использовали GitHub, не позволяйте этому вас остановить. Для перевода нужна лишь небольшая часть его возможностей: получить копию проекта, редактировать файлы и сохранять изменения. + +Часто проще всего начать с **GitHub Desktop**: +[https://desktop.github.com/](https://desktop.github.com/) + +Основной процесс: + +1. Создайте форк репозитория MathCAT. +2. Клонируйте его на свой компьютер. +3. Работайте в собственной ветке, например `pt`. + +Этого достаточно для начала. + +### Установите необходимые инструменты + +Потребуется несколько инструментов. Поначалу список может показаться длинным, но у каждого инструмента есть ясное назначение. + +* Git: [https://git-scm.com/](https://git-scm.com/) +* GitHub Desktop: [https://desktop.github.com/](https://desktop.github.com/) +* Редактор кода, например VS Code: [https://code.visualstudio.com/](https://code.visualstudio.com/) +* Rust: [https://rust-lang.org/tools/install/](https://rust-lang.org/tools/install/) +* NVDA: [https://www.nvaccess.org/download/](https://www.nvaccess.org/download/) +* MathCAT, установленный из магазина дополнений NVDA. + +Rust требуется только для запуска автоматических тестов. Чтобы переводить MathCAT, изучать программирование на Rust не нужно. + +--- + +## Шаг 2. Обновите перевод и выполните аудит + +Перед началом перевода убедитесь, что файлы вашего языка соответствуют текущей структуре английских файлов. Если пропустить этот шаг, можно потратить время на исправление проблем, вызванных устаревшими файлами. + +### Используйте инструмент аудита + +Документация: +[https://github.com/daisy/MathCAT/blob/main/PythonScripts/audit_translations/README.md](https://github.com/daisy/MathCAT/blob/main/PythonScripts/audit_translations/README.md) + +Используйте инструмент аудита, чтобы найти отсутствующие правила в файлах `pt`, и добавьте их. Подробные инструкции приведены в документации инструмента, поэтому начните с неё. + +### По возможности начните с похожего языка + +Если уже существует грамматически очень похожий язык, часто лучше начать с него, а не с английского или автоматически созданного перевода. + +Например, норвежский перевод был основан на шведском. Это может значительно сэкономить время, особенно если грамматика и порядок слов систематически отличаются от английских. Но перед переводом на свой язык всё равно используйте инструмент аудита для поиска отсутствующих правил. + +--- + +## Шаг 3. Как можно раньше начните слушать речь + +Слушайте результат по мере работы, чтобы быстро замечать ошибки. Перевод может выглядеть безупречно в файле YAML, но при озвучивании оказаться неестественным, повторяющимся или неясным. После перевода каждого файла полезно прослушать несколько выражений с помощью программы экранного доступа. + +### Настройте NVDA для локальных правил + +1. Скачайте NVDA: [https://www.nvaccess.org/download/](https://www.nvaccess.org/download/). +2. В NVDA откройте **Сервис → Магазин дополнений** и установите MathCAT. +3. Создайте копию каталога своего языка, например `pt`, и добавьте её в: + +```text +%AppData%\nvda\addons\MathCAT\globalPlugins\MathCAT\Rules\Languages +``` + +Теперь локальный перевод можно слушать в NVDA. + +### Проверяйте реальные выражения + +Для практической проверки речи возьмите выражения MathML из файлов тестов Rust и поместите их в простой HTML-документ. Затем откройте файл и прослушайте его в NVDA. + +Вносите по одному изменению, снова слушайте результат и делайте заметки. Так удобно изучать реальное поведение правил. + +--- + +## Шаг 4. Добавьте и запустите тесты + +Автоматические тесты — важнейшая часть процесса. Они помогают обнаруживать синтаксические ошибки, документируют ожидаемую речь и позволяют убедиться, что будущие изменения MathCAT незаметно не нарушат перевод. Полезно переводить тесты по мере работы, а не откладывать их напоследок. + +Откройте файл `languages.rs` в `MathCAT/tests` и добавьте строку, в случае португальского языка: + +```rust +mod pt; +``` + +Затем в каталоге `MathCAT/tests/Languages`: + +1. Скопируйте `en.rs` в `pt.rs`. +2. Скопируйте каталог `en` в `pt`. + +Если сначала вы выбрали только один стиль речи, другой можно удалить или закомментировать. + +В каждом тесте замените `"en"` на `"pt"`. + +После этого запустите: + +```bash +cargo test Languages::pt +``` + +Вероятно, при первом запуске многие тесты завершатся с ошибкой. Это нормально. + +### Понимание ошибок тестов + +Типичное сообщение об ошибке выглядит примерно так: + +```rust +left: "1 half" +right: "1 halv" +``` + +Главное здесь — сравнение: + +* `left` — ожидаемый текст, записанный в тесте; +* `right` — текст, фактически созданный MathCAT. + +Если созданный текст верен, скопируйте его в тест. Если неверен, исправьте правило. + +Иногда быстрее запустить тесты до перевода всех ожидаемых результатов. Сообщения об ошибках покажут, что MathCAT уже создаёт на вашем языке, и правильные строки можно будет перенести в тесты. + +### Пример простого теста + +```rust +#[test] +fn common_fraction_half() -> Result<()> { + let expr = ""; + test("pt", "ClearSpeak", expr, "um meio")?; + return Ok(()); +} +``` + +Здесь: + +* `common_fraction_half` — имя теста; +* `expr` содержит выражение MathML; +* `"pt"` — код языка; +* `"ClearSpeak"` — режим речи; +* `"um meio"` — ожидаемый текст для озвучивания. + +### Пример с настройками + +Некоторые тесты используют `test_prefs`, чтобы проверять правило с заданными настройками. + +```rust +#[test] +fn common_fraction_tenths() -> Result<()> { + let expr = ""; + test_prefs("en", "ClearSpeak", vec![("Verbosity", "Medium"), ("ClearSpeak_Fractions", "Auto")], expr, "17 tenths")?; + test_prefs("en", "ClearSpeak", vec![("Verbosity", "Medium"), ("ClearSpeak_Fractions", "Ordinal")], expr, "17 tenths")?; + return Ok(()); +} +``` + +В таких тестах: + +* `test_prefs` запускает обработку выражения с заданными настройками; +* `vec![]` содержит эти настройки; +* `("Verbosity", "Medium")` задаёт уровень подробности; +* `("ClearSpeak_Fractions", "Auto")` задаёт настройку ClearSpeak. + +В некоторых местах MathCAT также добавляет паузы. В строках тестов они обозначаются знаками препинания, например запятыми и точками с запятой. Если результаты почти совпадают, всегда проверяйте, не связана ли разница с паузами, а не с формулировкой. + +--- + +## Шаг 5. Изучите режимы речи и уровни подробности + +Есть два основных режима речи: ClearSpeak и SimpleSpeak. В статье Нила [A Comparison of Different Styles of Speech for Mathematics](https://scholarworks.calstate.edu/downloads/5t34sv64c) хорошо объясняется различие между ними. Кратко: + +* ClearSpeak должен быть похож на то, как учитель произносит математическое выражение на уроке. +* SimpleSpeak компактно озвучивает простые выражения. Например, $\frac{x}{y} + 1$ читается как «x over y plus one». Слова, обозначающие начало и конец дроби, не используются, потому что числитель и знаменатель просты. Выражение $\frac{x}{y+1}$ читается как «fraction, x over y plus one, end fraction». Здесь такие слова используются, поскольку знаменатель не является простым. + +Вы можете перевести оба стиля речи или сосредоточиться на одном. В зависимости от принятого способа произнесения математических выражений в целевом языке переведённые стили могут различаться сильнее или слабее английских. + +MathCAT также поддерживает уровни подробности **Terse**, **Medium** и **Verbose**. Переводчик сам определяет, насколько они должны различаться в его языке. Иногда естественный перевод объединяет два английских варианта в один, например если в целевом языке нет слова `the`. В других случаях для одного английского варианта может существовать несколько способов произнести выражение. Это нормально. Ясность важнее искусственно созданных различий. + +В ClearSpeak доступно много настроек, используемых в правилах и тестах. Подробнее см. [настройки ClearSpeak](https://github.com/daisy/MathCAT/blob/main/docs/ClearSpeakRulesAndPreferences.docx). Сейчас эти настройки не видны пользователям в настройках MathCAT в NVDA. + +--- + +## Шаг 6. Работайте с файлами правил + +### Какие файлы требуется перевести? + +Основная работа выполняется в файлах правил YAML. При переводе на португальский язык файлы находятся в каталоге `MathCAT\Rules\Languages\pt`: + +* `ClearSpeak_Rules.yaml` +* `definitions.yaml` +* `navigate.yaml` +* `overview.yaml` (необязательно) +* `SimpleSpeak_Rules.yaml` +* `unicode.yaml` +* `unicode-full.yaml` (частично необязательно) + +В подкаталоге `MathCAT\Rules\Languages\pt\SharedRules` находятся небольшие правила, из которых состоят правила в `ClearSpeak_Rules.yaml` и `SimpleSpeak_Rules.yaml`. Все эти файлы также требуется перевести. + +### С чего начать + +Для знакомства с принципами работы правил удобно начать, например, с `ClearSpeak_Rules.yaml` и нескольких файлов из `SharedRules`. + +Как указано выше, многие необходимые изменения будут обнаружены с помощью тестов. Однако файлы `unicode.yaml`, `unicode-full.yaml`, `navigate.yaml` и `definitions.yaml` недостаточно хорошо покрыты тестами и требуют особого внимания при ручной проверке. + +Не тратьте много времени на `unicode-full.yaml` в начале работы. Он содержит несколько тысяч строк, а большинство символов крайне редко встречаются на практике. Некоторые из них даже не отображаются в VS Code. Оставьте этот файл напоследок: достаточно просмотреть его и проверить наиболее узнаваемые символы. + +Файл `overview.yaml` также менее важен, чем остальные, поскольку не влияет непосредственно на чтение математических выражений. Однако он предоставляет программам экранного доступа краткие структурные обзоры выражений, поэтому со временем его стоит проверить. + +### Что делать + +Основная задача — найти все ключи YAML `t:`, соответствующие произносимым текстовым строкам. Строчная буква в ключе `t:` означает, что текст ещё не проверен переводчиком. Проверьте автоматически созданный перевод или измените его. После проверки замените ключ на `T:`, чтобы отметить обработанный фрагмент. + +Тот же принцип применяется ко всем ключам `ct:`, `ot:`, `spell:`, `pronounce:` и `IfThenElse:`, однако они встречаются гораздо реже, чем `t:`. + +### Адаптация и создание собственных правил + +Тесты покрывают большинство правил. Однако в португальском или другом языке могут существовать грамматические особенности, которых нет в английском и которые не охвачены тестами. Поэтому полезно просмотреть все правила и убедиться в их корректности. + +При грамматических различиях простой замены текстовых строк недостаточно. Необходимо изменить правила или добавить новые. Для совершенно новых правил полезно написать тесты, подтверждающие правильность результата. Не бойтесь пробовать разные варианты. + +Ниже приведён краткий обзор структуры правила MathCAT. Каждое правило описывает условия применения и произносимый текст. Основные части: + +* `name` — имя правила; +* `tag` — элемент MathML, к которому применяется правило; +* `match` — условие применения правила; +* `replace` — результат и действия MathCAT. + +Внутри `replace` часто используются следующие команды: + +* `t:` — произносимый текст; +* `ct:` — присоединить текст без пробела перед ним; +* `ot:` — необязательный текст для предотвращения повторений; +* `x:` — выражение XPath; +* `test:` — условная логика; +* `pause:` — пауза в речи; +* `bookmark:` — синхронное выделение. + +#### Пример 1 + +```yaml +- name: squared + tag: power + match: "*[2][self::m:mn][.='2'] and $ClearSpeak_Exponents = 'Auto'" + replace: + - x: "*[1]" + - bookmark: "*[2]/@id" + - t: "squared" # phrase(7 'squared' equals 49) +``` + +Это правило означает: если степень имеет показатель 2 и настройка `ClearSpeak_Exponents` равна `Auto`, следует вывести «основание в квадрате». Например, $x^2$ озвучивается как «x squared». + +Обратите внимание: + +* `match` определяет выражения, к которым применяется правило. +* Выражение после `x` — это XPath. Оно получает первый дочерний узел элемента степени, то есть основание. +* Строка после `t` должна быть переведена. После проверки перевода измените `t` на прописную `T`. + +#### Пример 2 + +```yaml +- name: fraction-over-text + tag: fraction + match: + - "not($ClearSpeak_Fractions='General' or $ClearSpeak_Fractions='GeneralEndFrac') and" + - "( " + - " ((*[1][self::m:mi or self::m:mtext][string-length(.)>1]) or " + - " (*[1][self::m:mrow][count(*)=3][ " + - " *[1][self::m:mn] and " + - " *[2][self::m:mo][.=''] and " + - " *[3][self::m:mi or self::m:mtext][string-length(.)>1] ]) ) and" + - " ((*[2][self::m:mi or self::m:mtext][string-length(.)>1]) or " + - " (*[2][self::m:mrow][count(*)=3][ " + - " *[1][self::m:mn] and " + - " *[2][self::m:mo][.=''] and " + - " *[3][self::m:mi or self::m:mtext][string-length(.)>1] ]) )" + - ")" + replace: + - x: "*[1]" + - t: "over" # phrase(the fraction 3 'over' 4) + - x: "*[2]" + - test: + if: "$ClearSpeak_Fractions='EndFrac' or $ClearSpeak_Fractions='OverEndFrac'" + then: + - pause: short + - t: "end fraction" # phrase(7 over 8 'end fraction') + - pause: short +``` + +Для применения правила должны выполняться все условия из `match`. + +В обычной формулировке: + +* настройка `ClearSpeak_Fractions` не должна иметь значение `General` или `GeneralEndFrac`, **и** +* числитель должен быть текстовой строкой длиной более одного символа или числом, неявно умноженным на такую строку, **и** +* знаменатель должен удовлетворять тем же условиям, что и числитель. + +Если все условия выполнены, дробь озвучивается как «числитель над знаменателем». Если `ClearSpeak_Fractions` имеет значение `EndFrac` или `OverEndFrac`, также добавляется короткая пауза перед фразой «конец дроби». + +Например, выражение $\frac{\text{meter}}{\text{second}}$ озвучивается как «meter over second». + +--- + +## Шаг 7. Попросите математика проверить перевод + +Когда перевод станет достаточно полным, попросите математика, учителя математики или другого специалиста-предметника, владеющего языком как родным, проверить представительный набор результатов. + +Полезно подготовить несколько примеров выражений вместе с расшифровками текста MathCAT. Попросите проверяющего отметить всё, что звучит математически странно, неоднозначно или непривычно. + +Такая проверка важна: перевод может быть грамматически верным, но не похожим на настоящую математическую речь. Специалист часто замечает проблемы в терминологии, именах символов и способах озвучивания крупных структур. + +При этом не всегда возможно идеально удовлетворить каждое пожелание. Особенности программ экранного доступа и структуры MathCAT могут означать, что наиболее элегантная с математической точки зрения формулировка не является самой удобной. + +--- + +## Шаг 8. Проведите пользовательское тестирование + +Если вы сами не являетесь опытным пользователем программы экранного доступа, пользовательское тестирование обязательно. + +Лучше всего привлекать незрячих пользователей, уверенно работающих с математикой, особенно специалистов в области STEM. Предоставьте им локальную версию MathCAT с переводом и HTML-файл с представительными выражениями MathML. + +Сначала полезно дать пользователям возможность самостоятельно попробовать перевод. Затем встретьтесь с ними и разберите дополнительные примеры вместе. Спрашивайте не только о правильности формулировок, но и о ясности структуры, полезности пауз и соответствии привычному способу восприятия. + +Устная математика оценивается не только по корректности: она должна быть удобна в реальной работе с программой экранного доступа. На практике обратная связь пользователей часто важнее теоретических предпочтений в грамматике, особенно если спор касается ясности или навигации, а не математического смысла. + +--- + +## Шаг 9. Отправьте перевод + +Перед созданием pull request или передачей перевода полезно выполнить итоговую проверку. Это уменьшит количество лишних исправлений и упростит рецензирование. + +### Итоговый список проверок + +Проверьте следующие пункты. + +#### Файлы и структура + +* Файлы вашего языка соответствуют текущей структуре английских файлов. +* Правила не пропущены: инструмент аудита запущен. +* В переводе нет очевидных остатков английского текста. + +#### Состояние перевода + +* Во всём проверенном тексте `t:` заменено на `T:`, `ct:` на `CT:`, `ot:` на `OT:` и т. д. +* Вы осознанно проверили формулировки, а не только использовали автоматический перевод. + +#### Речь + +* Вы прослушали представительный набор выражений в NVDA. +* На вашем языке результат звучит естественно и однозначно. +* Паузы и структура хорошо воспринимаются на слух. + +#### Тесты + +* Для вашего языка добавлены тесты. +* Все тесты проходят: + + ```bash + cargo test Languages::pt + ``` + +* Ожидаемые результаты тестов соответствуют задуманной речи, включая паузы. + +#### Экспертная проверка + +* Математик или другой специалист проверил представительный набор результатов. +* Основные проблемы терминологии и структуры устранены. + +#### Пользовательское тестирование + +* Проведено хотя бы некоторое тестирование с пользователями программ экранного доступа. +* Учтена обратная связь о ясности и удобстве использования. + +### Отправка перевода + +После выполнения списка проверок: + +1. **Создайте коммит с изменениями** в своей ветке, например `pt`. +2. **Отправьте ветку** на GitHub. +3. **Создайте pull request** в основной репозиторий MathCAT. + +В pull request полезно указать: + +* краткое описание перевода; +* завершённые части, например ClearSpeak, SimpleSpeak и тесты; +* известные ограничения и области, требующие дальнейшей работы. + +После этого сопровождающие проекта проверят работу и могут предложить изменения перед слиянием. + +### Когда перевод станет доступен пользователям? + +После слияния перевода с MathCAT: + +* он войдёт в будущие выпуски MathCAT; +* пользователи смогут выбрать язык в поддерживаемых программах экранного доступа, например NVDA. + +Чтобы использовать перевод сразу, не дожидаясь официального выпуска: + +* продолжайте использовать каталог локальных правил в NVDA или +* установите разрабатываемую версию MathCAT, содержащую ваши изменения. + +--- + +## Шаг 10. Поддерживайте перевод в актуальном состоянии + +Строго говоря, перевод никогда не бывает «завершён». Даже после слияния со временем появятся небольшие улучшения, особенно когда пользователи начнут работать с реальными материалами. + +Кроме того, английская версия активно развивается, и новые функции необходимо добавлять в перевод. Для синхронизации используйте [инструмент аудита перевода](https://github.com/daisy/MathCAT/blob/main/PythonScripts/audit_translations/README.md). + + + +--- + + +## Перевод Брайля + +Общий процесс перевода Брайля похож на перевод речи, но есть несколько важных отличий. + +Перед работой над правилами Брайля определите, какой стандарт математической записи используется в вашей стране. В некоторых странах существуют установленные системы записи Брайля, а в других применяются обозначения другого типа, например LaTeX или ASCIIMath. Решите заранее, какому стандарту должен следовать MathCAT. + +Если уже существует похожая система Брайля, её можно использовать как отправную точку. В противном случае, скорее всего, придётся начинать почти с нуля. + +### Файлы Брайля + +Для новой системы записи Брайля создайте три файла `.yaml` в `Rules\Braille\your-braille-language`: + +1. `xxx_Rules.yaml`, где `xxx` — имя системы записи Брайля. Файл содержит правила преобразования MathML в Брайль. +2. `unicode.yaml` — переводы наиболее распространённых символов. +3. `unicode-full.yaml` — переводы остальных символов. + +Два файла Unicode используются по практической причине: небольшой файл с распространёнными символами ускоряет запуск. + +### Пример шведского языка + +Шведский перевод Брайля следует официальной шведской системе математической записи Брайля. Это шеститочечный стандарт, предназначенный для печатных материалов. Устоявшегося восьмиточечного математического стандарта не было, поэтому перевод основывался на единственном признанном стандарте. + +Работа над шведским переводом также показала, что исходные стандарты не всегда достаточно строги для программного обеспечения. Некоторые печатные стандарты допускают расстановку пробелов в соответствии с печатным оригиналом. Для MathCAT этого недостаточно. Правила должны быть явными, поэтому иногда потребуется устранить несогласованности и принять однозначные решения о пробелах. + +### Тестирование Брайля + +Основной принцип похож на тестирование TTS, но вместо строк речи проверяются символы Брайля в Unicode. + +Удобно писать тесты Rust с ожидаемым выводом Брайля из национального стандарта или согласованных примеров. Запускайте тесты, изучайте ошибки и дорабатывайте правила до совпадения результата. + +В шведском переводе использовались примеры непосредственно из шведского стандарта Брайля, особенно для арифметики, дробей, подстрочных и надстрочных индексов, а также основных функций. Это помогло прочно связать правила с реальным стандартом. + +### Особые сложности Брайля + +При работе с Брайлем часто возникают проблемы, не встречающиеся в переводе речи. Например: + +* стандарт может быть неполным или несогласованным; +* стандарт может предполагать печатный контекст, а не автоматически создаваемый вывод; +* у некоторых символов может не быть однозначного устоявшегося представления; +* правила пробелов могут потребовать большей строгости, чем предполагает исходный стандарт. + +### Пользовательское тестирование Брайля + +Пользовательское тестирование Брайля так же важно, как тестирование речи. + +При работе над шведским переводом тестировщики использовали NVDA вместе со средством просмотра Брайля, чтобы контролировать результат во время удалённых сеансов. Это позволяло наблюдать вывод, даже если сами рецензенты читали его на физическом дисплее Брайля. + +Как и для речи, важна не только техническая правильность. Результат должен быть читаемым, согласованным и полезным в реальной работе. + +--- + +## Приложение + +### Практические советы для эффективной работы + +Инструменты искусственного интеллекта могут быть полезны при подготовке чернового перевода, поиске альтернативных формулировок и разборе сложного правила. Они также могут помочь при написании и редактировании правил. + +Однако относитесь к ним как к помощникам, а не как к авторитетным источникам. Автоматический перевод всегда требует проверки человеком, а изменения правил — тестирования на реальном выводе. + +В целом полезно вносить по одному изменению, часто запускать тесты и при возможности обсуждать сложные случаи с другими переводчиками или специалистами. + +### Устранение проблем + +Если что-то работает не так, как ожидалось, сначала проверьте отступы. Ошибки YAML распространены, и их бывает неожиданно трудно заметить. При использовании VS Code полезно установить расширение YAML, помогающее находить такие ошибки. + +Также внимательно изучайте результаты тестов и снова слушайте речь. Многие проблемы легче услышать, чем увидеть. + +### XPath + +Во многих частях правил речи используется XPath. Это распространённый и хорошо документированный способ выбора частей XML-документа. В интернете есть множество руководств. Если вы ещё не знакомы с XPath, рекомендуется прочитать одно из них. В MathCAT используется немного расширенная реализация XPath 1.0. + +В MathCAT обычно применяются лишь некоторые возможности XPath, а также несколько специальных функций. Ниже кратко описаны распространённые варианты использования XPath. + +| Запись | Значение | +| --- | --- | +| `*` | Соответствует всем дочерним узлам. | +| `[...]` | Выбирает узлы из текущего сопоставления. | +| `*[1]` | Выбирает первый дочерний узел. | +| `*[self::m:mn]` | Выбирает все дочерние элементы `mn`. Префикс `m` показывает, что элемент находится в пространстве имён MathML. | +| `*[1][self::m:mn]` | Выбирает первый дочерний узел, если он является элементом `mn`. | +| `*[1][self::m:mo][text()='-']` | Выбирает первый дочерний узел, если он является элементом `mo` с содержимым `-`. Можно записать `*[1][text()='-']`, поскольку другие узлы, скорее всего, не содержат `-`, но такое содержимое допустимо для `mtext`, поэтому безопаснее указать имя элемента. | +| `count(*[2]/*)` | Количество дочерних узлов второго дочернего узла. | +| `count(preceding-sibling::*)+1` | Количество одноуровневых узлов перед текущим элементом плюс один. | + +MathCAT добавляет специальные функции, упрощающие написание правил: + +| Функция | Значение | +| --- | --- | +| `IsNode(nodes, type)` | Возвращает true, если все узлы имеют одинаковый тип. Допустимые типы:
`"simple"` — заданный набор элементов ClearSpeak;
`"leaf"` — один из листовых элементов MathML;
`"2D"` — двумерный узел, например `mfrac` или `mroot`;
`"modified"` — узел с индексом или элементом над ним либо под ним;
`"scripts"` — узел с подстрочным и (или) надстрочным индексом;
`"common_fraction"` — целочисленные числитель и знаменатель. | +| `ToOrdinal` | | +| `ToCommonFraction` | | +| `IsBracketed(openChar, closeChar, requiresComma)` | | +| `BaseNode(node)` | Рекурсивно возвращает основу узла с индексами. | +| `IsInDefinition(node, name)` | Возвращает true, если узел входит в список `name`, заданный в `definitions.yaml`. | +| `IfThenElse(test, then-part, else-part)` | Возвращает `then-part`, если условие истинно, иначе возвращает `else-part`. Все аргументы являются выражениями XPath. | +| `DistanceFromLeaf(node, left_side, treat_2d_elements_as_tokens)` | Возвращает расстояние от текущего узла до крайнего левого или правого листа: для символа 0, для токена 1. Если `left_side` равно `true`, обход выполняется по крайним левым дочерним узлам до листа, иначе по правым. Если `treat_2d_elements_as_tokens` равно `true`, двумерные обозначения, например дроби, считаются одиночными токенами, подобными листам. | +| `EdgeNode(node, "left"/"right", stopNodeName)` | Возвращает узел остановки, если исходный узел находится у левого или правого края указанного предка. Значением `stopNodeName` также может быть `"2D"`. Если соответствие не найдено, возвращается исходный узел. Если `stopNodeName` равно `"math"`, учитывается пунктуация, поскольку она не является частью математического выражения. | +| `DEBUG(xpath)` | Добавляет полезные для диагностики сведения в отладочный вывод. | + +Следующие функции используются правилами кода Немета: + +| Функция | Значение | +| --- | --- | +| `NestingChars` | Используется правилами `mfrac`, `msqrt` и `mroot`, чтобы повторять символы нужное количество раз. | +| `BrailleChars` | Используется элементами-токенами для сложной перестановки индикаторов кода Немета, например прописных букв и начертания шрифта. | diff --git a/docs/ru/users.md b/docs/ru/users.md new file mode 100644 index 00000000..29d4fa9f --- /dev/null +++ b/docs/ru/users.md @@ -0,0 +1,203 @@ +--- +layout: default +lang: ru +ref: users +title: Руководство пользователя MathCAT +--- +#
Руководство пользователя
+
+## Рекомендации по выбору голоса
+
+В NVDA можно использовать разные синтезаторы речи. Для выбора откройте `Параметры:Настройки...` в NVDA, а затем выберите категорию `Речь`. Обычно доступны как минимум три варианта: eSpeak NG, Microsoft Speech API и голоса Windows OneCore. Все синтезаторы работают, но голоса Windows OneCore неправильно произносят «a», поэтому рекомендуется выбрать другой вариант. В частности, хорошей заменой голосам OneCore служит Microsoft Speech API.
+
+## Информация для пользователей MathCAT
+
+MathCAT поддерживает ряд настроек озвучивания, Брайля и навигации. Они описаны ниже.
+Пока поддерживаются не все настройки. Для каждой настройки указано текущее состояние поддержки. Символ ✓ перед настройкой означает, что она поддерживается хотя бы частично.
+
+Примечание: в NVDA настройки задаются в диалоге параметров MathCAT. Чтобы открыть его, перейдите в параметры NVDA, выберите «Параметры», а затем «Настройки MathCAT...». Настройки разделены на три категории: «Речь», «Навигация» и «Брайль». Такое же разделение используется ниже.
+
+MathCAT поддерживает несколько режимов навигации. Способ входа в режим навигации и выхода из него зависит от используемой вспомогательной технологии (подробнее в списке ниже). MathCAT принимает те же команды и сочетания клавиш, что и MathPlayer. Они [перечислены в этом документе](nav-commands.md).
+Документация описывает множество полезных способов навигации по математическим выражениям. Чтобы быстро начать работу:
+
+* Используйте клавиши-стрелки для перемещения влево, вправо, вверх и вниз по структуре математического выражения, например для входа в дробь и выхода из неё.
+* Внутри таблицы нажимайте Ctrl+стрелка для перемещения по ячейкам.
+* Нажимайте Home и End для перехода к началу и концу выражения.
+* Нажимайте пробел для озвучивания текущей позиции.
+* Нажимайте Shift+стрелка вверх или Shift+стрелка вниз для изменения режима навигации (см. [документацию по навигации](nav-commands.md)).
+
+Чтобы начать навигацию:
+
+* NVDA: нажмите NVDA+Alt+M или пробел для входа в режим навигации по математическому выражению, а для выхода нажмите Escape.
+
+Навигация MathCAT работает одинаково в Word и в браузере.
+
+При навигации по выражению сочетание Ctrl+C в NVDA копирует математическое содержимое текущего узла. Поддерживаются следующие форматы:
+
+* MathML (по умолчанию);
+* LaTeX;
+* ASCIIMath;
+* текст для озвучивания.
+
+## Список настроек
+
+Ниже перечислены настройки. Большинство из них принимают только ограниченный набор значений, который указан в описании.
+Значение по умолчанию приведено в \[квадратных скобках\].
+
+### Настройки речи
+
+* ✓Impairment: [Blindness]
+ * Значения: Blindness, LowVision, LearningDisability.
+ * Описание: определяет, следует ли устранять неоднозначность некоторых обозначений при озвучивании.
+ * Состояние: основное внимание уделялось значению Blindness, но другие значения также частично поддерживаются. Эту поддержку необходимо улучшить.
+
+* ✓Language: [en]
+ * Значения: любой известный код языка и подкод, например `en-uk`.
+ [Список вариантов приведён на этом сайте](https://www.venea.net/web/culture_code).
+ * Описание: определяет используемый язык.
+ Если региональный вариант не найден среди правил озвучивания, используется основной язык. Если не найдены и правила для основного языка, используется английский язык (`en`).
+ * Состояние: сейчас поддерживаются только английский, испанский, финский, индонезийский, шведский, вьетнамский и китайский языки.
+ Другие языки будут добавляться с помощью добровольцев.
+
+* ✓SpeechStyle: [ClearSpeak]
+ * Значения: любой реализованный стиль речи. Сейчас доступны только ClearSpeak и SimpleSpeak.
+ * Описание: стиль речи, то есть согласованный подход к озвучиванию выражения.
+ * ClearSpeak был разработан ETS для важных экзаменов, например SAT. [Подробности спецификации ClearSpeak приведены в этом документе Word](../ClearSpeakRulesAndPreferences.docx).
+ * SimpleSpeak стремится сократить озвучивание: простые выражения, например $\frac{a}{b}$, читаются быстро, без обрамляющих слов («a over b»). Они отличаются от более сложных выражений, например $\frac{a}{b+1}$, в которых обрамляющие слова используются всегда («fraction a over b plus 1 end fraction»).
+ * Состояние: сейчас реализованы только ClearSpeak и SimpleSpeak, но в дальнейшем, вероятно, будет реализован MathSpeak.
+
+* ✓Verbosity: [Medium]
+ * Значения: Terse, Medium, Verbose.
+ * Описание: определяет количество дополнительных слов при озвучивании. Например, в подробном режиме квадратный корень читается как «the square root of x», а в кратком — как «square root x».
+ * Состояние: настройка поддерживается, но со временем, вероятно, будет дорабатываться.
+
+* ✓MathRate: [100]
+ * Значения: число от 1 до 100.
+ * Описание: изменяет относительную скорость речи в процентах от стандартной скорости речевого синтезатора. Значение `100` означает, что математические выражения читаются с той же скоростью, что и обычный текст.
+ Настройка работает только в реализациях, которые указывают MathCAT создавать разметку речевого синтезатора, например SSML.
+ * Состояние: настройка должна работать в NVDA.
+
+* ✓PauseFactor: [50]
+ * Значения: число от 0 до 100.
+ * Описание: изменяет относительную длительность добавляемых MathCAT пауз. Значение 0 отключает все паузы, а значение 100 увеличивает обычную длительность пауз в десять раз.
+ Настройка работает только в реализациях, которые указывают MathCAT создавать разметку речевого синтезатора, например SSML.
+ * Состояние: настройка должна работать в NVDA.
+
+* ✓SpeechSound: [None]
+ * Значения: None, Beep.
+ * Описание: перед чтением выражения и после него воспроизводится звуковой сигнал.
+ * Состояние: настройка должна работать в NVDA.
+
+* SubjectArea: [General]
+ * Состояние: настройка использовалась в MathPlayer, но пока не реализована. Я жду дальнейшего обсуждения в рабочей группе MathML: возможно, эта настройка будет использоваться для задания разных значений `intent` по умолчанию.
+
+* Chemistry: [SpellOut]
+ * Значения: SpellOut, AsCompound, Off.
+ * Описание: определяет способ чтения химических формул. Примеры для $\mathrm{H}_2\mathrm{O}$:
+ * ✓SpellOut: «H 2 O» (настройка подробности определяет, произносятся ли слова `sub` и `super`);
+ * AsCompound: «Water»;
+ * ✓Off: «H sub 2 O».
+ * Состояние: реализовано множество эвристик для определения того, является ли запись химической формулой. Распознавание химических обозначений не всегда очевидно, поэтому MathCAT иногда может не распознать формулу или по ошибке принять другую запись за химическую. Работа группы MathML может существенно упростить авторам явное указание химических формул.
+
+SpeechOverrides:
+
+* ✓CapitalLetters: "cap" # слово-префикс для прописных букв, если оно не задано в unicode.yaml; пустая строка передаёт обработку программе экранного доступа
+* LeftParen: "" # переопределение слова
+* RightParen: "" # переопределение слова
+
+ClearSpeak содержит ряд настроек. Они предназначены для авторов, но могут задаваться и пользователями, хотя обычно не слишком им полезны.
+
+* ✓CapitalLetters: Auto, SayCaps или изменение высоты тона
+* ✓AbsoluteValue: Auto, AbsEnd, Cardinality, Determinant
+* ✓Fraction: Auto, Ordinal, Over, FracOver, General, EndFrac, GeneralEndFrac, OverEndFrac, Per
+* ✓Exponent: Auto, Ordinal, OrdinalPower, AfterPower
+* ✓Roots: Auto, PosNegSqRoot, RootEnd, PosNegSqRootEnd
+* ✓Functions: Auto, None
+* ✓Trig: Auto, TrigInverse, ArcTrig
+* ✓Log: Auto, LnAsNaturalLog
+* ✓ImpliedTimes: Auto, MoreImpliedTimes, None
+* ✓Paren: Auto, Speak, SpeakNestingLevel, Silent, CoordPoint, Interval
+* ✓Matrix: Auto, SpeakColNum, SilentColNum, EndMatrix, Vector, EndVector, Combinatorics
+* ✓MultiLineLabel: Auto, Case, Constraint, Equation, Line, None, Row, Step
+* ✓MultiLineOverview: Auto, None
+* ✓MultiLinePausesBetweenColumns: Short, Long
+* ✓Sets: Auto, woAll, SilentBracket
+* ✓MultSymbolX: Auto, By, Cross
+* ✓MultSymbolDot: Auto, Dot
+* ✓TriangleSymbol: Auto, Delta
+* ✓Ellipses: Auto, AndSoOn
+* ✓VerticalLine: Auto, SuchThat, Divides, Given
+* ✓SetMemberSymbol: Auto, Belongs, Element, Member
+* ✓Prime: Auto, Angle, Length
+* ✓CombinationPermutation: Auto, ChoosePermute
+* ✓Bar: Auto, Bar, Conjugate, Mean
+
+### Настройки навигации (см. [документацию по навигации](nav-commands.md))
+
+* ✓NavMode: Enhanced — Enhanced, Simple, Character.
+* ResetNavMode: false — запоминать и использовать предыдущее значение.
+* Overview: false — озвучивать выражение или давать его описание и обзор.
+* ResetOverView: true — запоминать и использовать предыдущее значение.
+* ✓NavVerbosity: Medium — Terse, Medium, Full (слова для произнесения команды навигации).
+* ✓AutoZoomOut: true — автоматически уменьшать детализацию двумерных выражений. Если настройка отключена, для принудительного уменьшения детализации используйте Shift+стрелка.
+ * `true`: если вы находитесь у края двумерного выражения, например дроби или надстрочного индекса, и пытаетесь выйти из него влево или вправо, перемещение разрешается, а уровень детализации устанавливается в соответствии с предыдущим или следующим элементом.
+ * `false`: перемещение влево или вправо за край двумерного выражения запрещено. Чтобы переместиться, необходимо уменьшить детализацию, возможно несколько раз, пока вы не перестанете находиться у края.
+* CopyMathAS: определяет формат копирования математического содержимого текущего узла навигации: MathML, LaTeX, ASCIIMath или текст для озвучивания.
+
+
+### Настройки Брайля
+
+* ✓BrailleCode: [Nemeth]
+ * Значения: любая реализованная система записи Брайля.
+ * Описание: используемая система математической записи Брайля.
+ * Состояние: сейчас поддерживаются ASCIIMath, ASCIIMath-Finnish, CMU, LaTeX, код Немета, шведская система, UEB и вьетнамская система. Поддержка других систем записи Брайля зависит от помощи новых участников.
+* ✓BrailleNavHighlight: [EndPoints]
+ * Значения: Off, FirstChar, EndPoints, All.
+ * Описание: выделяет выбранный узел навигации точками 7 и 8.
+* UEB:
+ * ✓START_MODE: [Grade2]
+ * Значения: Grade1, Grade2.
+ * Описание: предполагаемый начальный режим UEB. Значение Grade1 означает, что используется режим фрагмента Grade 1.
+ * ✓UseSpacesAroundAllOperators: [false]
+ * Значения: true/false.
+ * Описание: рекомендации UEB предполагают, что в младших классах может быть полезно добавлять пробелы вокруг таких операторов, как `+` и `-`. Обычно пробелы добавляются только вокруг операторов отношений, например `=` и `<`.
+
+Во многих системах записи Брайля можно определять пользовательские символы. MathCAT предоставляет для этого несколько настроек.
+
+В коде Немета определены начертания Bold, Italic, SansSerif и Script, но не определено начертание DoubleStruck (Blackboard Bold).
+Здесь можно задать определяемое транскрибатором изменение начертания. По умолчанию DoubleStruck сопоставляется с Italic.
+
+* Nemeth:
+ * ✓SansSerif: "⠠⠨"
+ * ✓Bold: "⠸"
+ * ✓DoubleStruck: "⠨"
+ * ✓Script: "⠈"
+ * ✓Italic: "⠨"
+
+В [руководстве UEB по техническим материалам](https://iceb.org/Guidelines_for_Technical_Material_2008-10.pdf) рекомендуется обычно обрабатывать Fraktur и DoubleStruck как Script.
+Вместо этого здесь можно задать пользовательский префиксный индикатор начертания.
+Примечание: префиксы с первого по пятый: "⠈⠼", "⠘⠼", "⠸⠼", "⠐⠼", "⠨⠼".
+
+* UEB:
+ * ✓DoubleStruck: "⠈" [script]
+ * ✓Fraktur: "⠈" [script]
+ * ✓SansSerif: "⠈⠼" [первый определяемый транскрибатором префиксный индикатор начертания]
+ * ✓GreekVariant: "⠨" [по умолчанию Greek]
+
+Набор определяемых символов для вьетнамской системы ещё обсуждается. Вероятно, некоторые значения изменятся.
+
+* Vietnam:
+ * ✓UseDropNumbers: [false]
+ * Значения: true, false.
+ * Описание: опускает цифры на строку ниже в простых числовых дробях.
+ * ✓DoubleStruck: "⠈" [script]
+ * ✓Fraktur: "⠈" [script]
+ * ✓SansSerif: "⠈⠼" [первый определяемый транскрибатором префиксный индикатор начертания]
+ * ✓GreekVariant: "⠨" [по умолчанию Greek]
+
+### Другие настройки
+
+MathCAT исправляет некачественный MathML. В MathML числа часто размечаются неправильно. Чтобы исправить их корректно, MathCAT должен знать региональные настройки: символы, которые могут разделять группы цифр, и символы десятичного разделителя. Обычно ассистивная технология задаёт эти параметры на основе кода страны в документе. Но код страны может отсутствовать, и тогда ассистивной технологии приходится определять формат по коду языка.
+
+* DecimalSeparators: "." # [по умолчанию]
+* BlockSeparators: ", \u00A0\u202F" # [по умолчанию; включает два варианта неразрывных пробелов]
diff --git a/src/braille.rs b/src/braille.rs
index b944578f..6b259776 100644
--- a/src/braille.rs
+++ b/src/braille.rs
@@ -50,6 +50,7 @@ pub fn braille_mathml(mathml: Element, nav_node_id: &str) -> Result<(String, usi
"CMU" => cmu_cleanup(pref_manager, braille_string),
"Finnish" => finnish_cleanup(pref_manager, braille_string),
"Swedish" => swedish_cleanup(pref_manager, braille_string),
+ "Russian" => russian_cleanup(pref_manager, braille_string),
"LaTeX" => LaTeX_cleanup(pref_manager, braille_string),
"ASCIIMath" => ASCIIMath_cleanup(pref_manager, braille_string),
"ASCIIMath-fi" => ASCIIMath_cleanup(pref_manager, braille_string),
@@ -2167,6 +2168,38 @@ fn swedish_cleanup(pref_manager: Ref