review from AI

Author: ctapmex

docs/advanced/catalog-xml.md

@@ -1,13 +1,11 @@
 # catalog.xml
 
-В **catalog.xml** описываются пути до hrc и hrd файлов.
-
-Формат файла catalog.xml имеет фиксированную структуру, описанную в [catalog.xsd](https://colorer.github.io/schema/v1/catalog.xsd).
-
-Простой пример содержимого файла выглядит представлен ниже на вкладке Simple.
-
-В базовой библиотеке схем широко применяются возможности синтаксиса xml по вставке одного файла в другой (external entity). Поэтому пример файла, поставляемого в базовой библиотеке схем, выглядит немного сложнее, вкладка Hard.
+Файл **catalog.xml** является центральным конфигурационным файлом для Colorer Library. Его основная задача – индексировать и указывать пути к файлам HRC-схем (определяющих синтаксис типов файлов) и HRD-стилей (определяющих правила их раскраски).
+Структура файла catalog.xml строго определена и соответствует XML-схеме, доступной по адресу: [catalog.xsd](https://colorer.github.io/schema/v1/catalog.xsd).
+Ниже представлены два примера структуры файла catalog.xml:
 
+1. **Простой пример (вкладка "Simple"):** Демонстрирует базовую структуру с прямым указанием файлов.
+2. **Сложный пример (вкладка "Hard"):** Иллюстрирует использование XML External Entities для включения содержимого из других файлов. Этот подход активно применяется в базовой библиотеке схем Colorer для лучшей организации и модульности.
 
 === "Simple"
 
@@ -57,24 +55,46 @@
     </catalog>
     ```
 
-## Подстановки файлов (external entity)
+## Включение файлов с помощью XML External Entities
 
-**external entity** - вставка внешнего файла в структуру текущего.
+**XML External Entity (внешняя сущность)** – это стандартный механизм языка XML, который позволяет включать содержимое одного XML-файла (или другого внешнего ресурса) в структуру текущего XML-документа.
 
-Запись вида
+Объявление внешней сущности, например:
 ```
 <!ENTITY catalog-console SYSTEM "hrd/catalog-console.xml">
 ```
-в начале xml файла говорит о том, что вместо `&catalog-console;` ниже в файле будет подставляться содержимое файла `hrd/catalog-console.xml`. При указании относительного пути, путь рассчитывается от текущего файла. Работа с путями описана в разделе [Форматы путей файлов](file-paths.md).
+размещается в секции DOCTYPE в начале XML-файла (как показано в примере "Hard"). Это объявление связывает имя сущности (`catalog-console`) с внешним файлом (`hrd/catalog-console.xml`).
+Впоследствии, когда XML-парсер встречает в теле документа ссылку на эту сущность (например, `&catalog-console;`), он заменяет её содержимым указанного внешнего файла.
+Относительные пути в атрибуте SYSTEM (как `hrd/catalog-console.xml`) разрешаются относительно местоположения текущего файла catalog.xml. Подробнее о форматах путей см. в разделе [Форматы путей файлов](file-paths.md).
+
+## Элемент `<catalog>`
+
+Это корневой элемент XML-документа catalog.xml. Он служит контейнером для двух основных секций: `<hrc-sets>` и `<hrd-sets>`.
 
-## catalog
+## Элемент `<hrc-sets>`
 
-Основной блок xml-файла. Содержит в себе hrc-sets и hrd-sets.
+Секция `<hrc-sets>` предназначена для регистрации HRC-схем в библиотеке. Внутри этого элемента используются дочерние элементы `<location link="..."/>` для указания путей:
 
-## hrc-sets
+* **К конкретному HRC-файлу:** Например, `<location link="hrc/myparser.hrc"/>`.
+* **К каталогу с HRC-файлами:** Например, `<location link="hrc/languages/"/>`. В этом случае Colorer Library автоматически загрузит все файлы с расширением `.hrc` из указанного каталога.
+    * **Исключение:** Файлы с расширением `.ent.hrc` (обычно используемые как фрагменты для XML External Entities) игнорируются при сканировании каталога.
+    * **Нерекурсивный поиск:** Сканирование каталога происходит только на первом уровне вложенности; файлы в подкаталогах не загружаются автоматически через указание родительского каталога.
 
-В блоке `hrc-sets` задаются пути до hrc файлов. Это может быть путь как до конкретного файла, так и до папки. В случае указания пути до папки в ней обрабатываются все файлы с расширением `.hrc`, исключая `.ent.hrc`. Но только на первом уровне, во вложенных папках поиск файлов не производится.
+## Элемент `<hrd-sets>`
 
-## hrd-sets
+Секция `<hrd-sets>` служит для регистрации доступных HRD-стилей раскраски. Каждый стиль определяется элементом `<hrd>`, который имеет следующие атрибуты и дочерние элементы:
+
+* **Атрибут `class`**: Определяет тип вывода, для которого предназначен стиль (например, "console" для консольного вывода, "rgb" для HTML/графического вывода с RGB-цветами, "text" для простого текстового вывода).
+* **Атрибут `name`**: Уникальное имя стиля в рамках его класса (например, "default", "eclipse", "dark_blue"). Это имя используется для выбора стиля в приложениях.
+* **Атрибут `description`**: Краткое описание стиля (например, "Aqua on blue", "White (crimsoned)").
+* **Элемент `<location link="..."/>`**: Указывает путь к файлу `.hrd`, содержащему определение данного стиля.
+
+Пример:
+
+```xml
+<hrd class="rgb" name="default" description="White (crimsoned)">
+    <location link="hrd/rgb/white.hrd"/>
+</hrd>
+```
 
-В блоке `hrd-sets` задаются пути до файлов цветовых стилей.
+Это определяет стиль с именем "default" для класса "rgb", описание которого "White (crimsoned)", а само определение стиля находится в файле hrd/rgb/white.hrd.

docs/catalog-base.md

@@ -1,23 +1,26 @@
 # Библиотека схем
 
-**Библиотека схем** - это структура файлов/папок, содержащая набор описаний схем типов файлов и стилей раскраски. Её центральной частью является файл **catalog.xml**.
+**Библиотека схем** (Scheme Library) – это организованный набор файлов и каталогов, который содержит описания HRC-схем для различных типов файлов и HRD-стили для их раскраски. Ключевым элементом этой структуры является файл **catalog.xml**, который индексирует все доступные схемы и стили.
 
-Для старта работы Colorer Library или программ на ней построенных, необходимо указать путь до **catalog.xml**.
+Для инициализации Colorer Library или приложений, её использующих, необходимо указать путь к файлу **catalog.xml**.
 
-Библиотеки схем можно разделить на два типа:
+Существует два основных типа библиотек схем:
+
+- **Базовая библиотека**: поставляется вместе с Colorer Library и содержит предустановленный набор схем и стилей.
+- **Пользовательская библиотека**: создается пользователем, либо "с нуля", либо путем расширения или модификации базовой библиотеки.
 
-- базовая, поставляемая вместе с Colorer Library.
-- пользовательская, созданная на основе базовой или самостоятельно
 
 ## Форматы поставки базовой библиотеки схем
 
-Актуальную базовую библиотеку схем можно скачать со [страницы проекта](https://github.com/colorer/Colorer-schemes/releases).
-На ней представлены три вида архивов:
+Актуальную версию базовой библиотеки схем можно загрузить с [страницы релизов проекта](https://github.com/colorer/Colorer-schemes/releases).
+
+Библиотека поставляется в трех вариантах архивов:
+
+* **unpacked**: Все файлы библиотеки (HRC-схемы, HRD-стили, catalog.xml и др.) представлены в исходном, неупакованном текстовом виде.
+* **packed**: Файлы, содержащие определения HRC-схем, упакованы в архив. Другие компоненты (например, HRD-стили, catalog.xml) могут оставаться неупакованными.
+* **allpacked**: Все файлы библиотеки схем, за исключением корневого catalog.xml, упакованы в единый архив.
 
-* **unpacked** - все файлы внутри библиотеки идут в текстовом не упакованном виде.
-* **packed** - файлы со схемами, за исключением их описаний, сложены в архив.
-* **allpacked** - все файлы библиотеки схем, за исключением catalog.xml, сложены в один архив
+С точки зрения функциональности все три варианта поставки эквивалентны. Выбор конкретного формата зависит от требований к развертыванию и при условии, что используемая сборка Colorer Library поддерживает работу с архивами (для packed и allpacked вариантов).
 
-С точки зрения функционала все виды поставки ничем не отличаются. Можно использовать любой из них, если Colorer Library собрана с поддержкой архивов.
+Различные форматы предназначены для разных сценариев использования. Например, вариант **allpacked** удобен для включения в дистрибутивы других программных продуктов, поскольку он минимизирует количество файлов библиотеки схем, упрощая интеграцию и управление зависимостями.
 
-Три формата нужны для разных условий использования. Например allpacked удобно поставлять в составе других продуктов, т.к. нет зависимости от смены содержимого библиотеки схем.

docs/index.md

@@ -1,11 +1,13 @@
 # Обзор
 
-**Colorer Library** - это библиотека подсветки синтаксиса и разбора текста, которая предоставляет возможности по разбору текста в редакторах в режиме реального времени и преобразованию результатов разбора в цветной текст. Результат разбора позволяет выполнять поиск и создавать общие списки функций, структур, а также выполнять поиск и добавлять отступы в конструкции языка программирования (скобки, парные теги). Colorer Library использует C++, XML, полностью переносим и работает на платформах Windows/Linux/MacOS.
+**Colorer Library** – это библиотека для подсветки синтаксиса и анализа текста. Она позволяет выполнять разбор текста в редакторах в реальном времени и преобразовывать результаты этого разбора в стилизованный (например, цветом) текст. Результаты анализа могут использоваться для: навигации по коду (поиск элементов), создания списков структурных элементов (функции, классы), а также для интеллектуальных функций редактирования, таких как автоматическая подсветка для парных языковых конструкций (например, скобок, парных тегов).
 
-Разбор текста производится на основании описания синтаксиса/структуры типа файлов в формате Colorer HRC. Такие файлы называются **Схемами** типов файлов.
+Colorer Library написана на C++ и использует XML для конфигурационных файлов. Она является кроссплатформенной и поддерживает Windows, Linux и macOS.
 
-Подсветка текста разными цветами производится путем сопоставления регионов, полученных на выходе разбора структуры файла по схеме, цветам или заменяющей их информации. Набор пар регион-цвет задается в формате Colorer HRD. Такие файлы называются **Стилями раскраски**.
+Анализ текста осуществляется на основе описаний синтаксиса и структуры конкретных типов файлов. Эти описания хранятся в XML-файлах формата Colorer HRC, которые называются **Схемами** (или HRC-схемами).
 
-Схемы и стили раскраски объединяются в [**библиотеку схем**](catalog-base.md).
+Визуальное выделение текста (например, цветом) происходит путем сопоставления синтаксических регионов, определённых HRC-схемой, с правилами оформления. Эти правила (набор пар "регион-оформление") задаются в XML-файлах формата Colorer HRD, которые называются **Стилями раскраски** (или HRD-стилями).
 
-Варианты текущего использования библиотеки перечислены в разделе [Usage](usage/index.md).
+Схемы и Стили раскраски вместе формируют [**Библиотеку схем**](catalog-base.md).
+
+Примеры использования библиотеки приведены в разделе [Usage](usage/index.md).