[colorer/Colorer-library] master: remove docs (e47ee65)

[farg...@farmanager.com]

Repository : https://github.com/colorer/Colorer-library
On branch : master
Link : https://github.com/colorer/Colorer-library/commit/e47ee65c42407f075c6b63ac052d09a8f378ce0b

>---------------------------------------------------------------

commit e47ee65c42407f075c6b63ac052d09a8f378ce0b
Author: Aleksey Dobrunov <cta...@ctapmex.com>
Date: Sun Jun 8 22:36:23 2025 +0500

remove docs

actual docs in https://github.com/colorer/colorer.github.io


>---------------------------------------------------------------

e47ee65c42407f075c6b63ac052d09a8f378ce0b
README.md | 5 +++
docs/base.md | 113 -----------------------------------------------------
docs/custom.md | 101 -----------------------------------------------
docs/depends.md | 93 -------------------------------------------
docs/dev_spdlog.md | 59 ----------------------------
docs/tools.md | 48 -----------------------
6 files changed, 5 insertions(+), 414 deletions(-)

diff --git a/README.md b/README.md
index 3c7315d..f201be8 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,11 @@
Colorer is a syntax highlighting library.
[](https://github.com/colorer/Colorer-library/actions/workflows/colorer_ci.yml)

+## Documentation
+
+https://colorer.github.io
+https://github.com/colorer/colorer.github.io
+
## How to build from source

### Main
diff --git a/docs/base.md b/docs/base.md
deleted file mode 100644
index 4761605..0000000
--- a/docs/base.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# Библиотека схем
-
-Основной частью библиотеки colorer является библиотека схем (colorer schemes).
-
-**Библиотека схем** - это набор описаний схем типов файлов и стилей раскраски, используемых библиотекой colorer для работы с файлами.\
-**Схема** - файлы с расширением hrc. Hrc это формат описания структуры типа файла, который разбирает colorer. В файле описывается как логически разделить его на отдельные регионы,
-к которым потом будут применяться стили раскраски.\
-**Стиль раскраски** - файлы с расширением hrd. Hrd используются для сопоставления регионов, полученных на выходе разборы структуры файла по hrc-схеме, цветам или заменяющей их
-информации. Цвета могут быть заданы в любом формате - интерпретация зависит от целевой программы, использующей библиотеку.\
-**catalog.xml** - центральный файл библиотеки схем. В нём описываются пути до hrc и hrd файлов.
-
-## catalog.xml
-
-Для старта работы в colorer необходимо передать путь до catalog.xml. Формат xml файла имеет фиксированную структуру, описанную
-в [catalog.xsd](https://colorer.github.io/schema/v1/catalog.xsd). Пример:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE catalog [
- <!ENTITY hrd "hrd">
- <!ENTITY catalog-console SYSTEM "hrd/catalog-console.xml">
- <!ENTITY catalog-rgb SYSTEM "hrd/catalog-rgb.xml">
- <!ENTITY catalog-text SYSTEM "hrd/catalog-text.xml">
- ]>
-<catalog xmlns="http://colorer.github.io/schema/v1/catalog" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://colorer.github.io/schema/v1/catalog https://colorer.github.io/schema/v1/catalog.xsd">
- <hrc-sets>
- <location link="hrc/proto.hrc"/>
- <location link="hrc/auto"/>
- </hrc-sets>
- <hrd-sets>
- &catalog-console;
- &catalog-rgb;
- &catalog-text;
- </hrd-sets>
-</catalog>
-```
-
-В библиотеке схем широко используется возможность синтаксиса xml по вставке одного файла в другой - entity. Запись вида
-
-```
-<!ENTITY catalog-console SYSTEM "hrd/catalog-console.xml">
-```
-
-в начале файла говорит о том, что вместо `&catalog-console;` в xml файле будет подставляться содержимое файла `hrd/catalog-console.xml`. При указании относительного пути, путь
-рассчитывается от текущего файла. Работа с путями описана в разделе `Пути до файлов`.
-
-В блоке `hrc-sets` задаются пути до hrc файлов. Это может быть путь как до конкретного файла, так и до папки или архива. В случае указания пути до папки производится поиск файлов с
-расширением `.hrc` только на первом уровне, во вложенные папки не заходит.
-
-В блоке `hrd-sets` задаются пути до файлов цветовых стилей.
-
-Если упростить структуру файла, убрав вставки внешних файлов, то catalog.xml выглядит так:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<catalog xmlns="http://colorer.github.io/schema/v1/catalog" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://colorer.github.io/schema/v1/catalog https://colorer.github.io/schema/v1/catalog.xsd">
- <hrc-sets>
- <location link="hrc/proto.hrc"/>
- <location link="hrc/auto"/>
- </hrc-sets>
- <hrd-sets>
- <hrd class="console" name="default" description="Aqua on blue">
- <location link="hrd/console/default.hrd"/>
- </hrd>
- <hrd class="rgb" name="default" description="White (crimsoned)">
- <location link="hrd/rgb/white.hrd"/>
- </hrd>
- <hrd class="text" name="tags" description="HTML italic, underline indention">
- <location link="hrd/text/tags.hrd"/>
- </hrd>
- </hrd-sets>
-</catalog>
-```
-
-## Форматы поставки библиотеки схем
-
-Актуальные библиотеки схем можно скачать со [страницы проекта](https://github.com/colorer/Colorer-schemes/releases). На ней представлены три вида архивов:
-
-* unpacked - все файлы внутри библиотеки идут в текстовом не упакованном виде.
-* packed - файлы со схемами, за исключением их описаний, сложены в архив.
-* allpacked - все файлы библиотеки схем, за исключением catalog.xml, сложены в один архив
-
-Изначально библиотека схем поставлялась в packed виде. Но для удобства их поставки в составе других продуктов ([Far Manager](https://github.com/FarGroup/FarManager)), был создан
-allpacked формат. Unpacked вариант применяется для тестирования и в поставке [far2l](https://github.com/elfmz/far2l).
-
-С точки зрения функционала все виды поставки ничем не отличаются. Можно использовать любой из них (кроме far2l, где архивы не поддерживаются).
-
-## Пути до файлов
-
-Ссылки на файлы/папки в библиотеке схем могут быть следующих типов:
-
-1. **Полный путь**\
- Обычный полный путь до файла на файловой системе. Например `c:\user\test\1.xml`, `/home/user/1.xml`.
-2. **Длинный путь**\
- В Windows поддерживаются длинные пути (до 32767 символов). Полный путь может быть указан через `\\?\`, например `\\?\c:\user\test\1.xml`
-3. **Относительный путь**\
- Если в пути нет указания на диск (windows) или корень (linux), а так же встречаются ссылки на текущую папку `./` или на родительскую `../`, то такие пути считаются
- относительными. Такой путь рассчитывается относительно файла, в котором он описан. Т.е. если путь `..\1.xml` указан в `link` атрибуте файла `c:\users\test\base\catalog.xml`, то
- будет прочитан файл `c:\users\test\1.xml`.
-4. **Файл в архиве**
- Файлы библиотеки схем могут храниться в zip архиве. Это позволяет, например, упростить доставку схем, когда их десятки/сотни. Путь, указывающий на файл в архиве имеет следующий
- формат `jar:путь_до_архива!путь_до_файла_в_архиве`. Например `jar:common.zip!base/cpp.hrc`. При этом путь до архива так же может быть полным/длинным/относительным.
-
-Для всех указанных типов путей поддерживается использование переменных окружения в формате текущей операционной системы. Например, `%COLORER_HOME%\catalog\catalog.xml`.
-
-Поддерживается работа с symlink на файлы. Работа идет с файлом и полным путем до него, на который ссылается symlink. Т.е. при обработке относительного пути отсчет идет от
-оригинального файла. Например:
-
-* библиотека схем находится в c:\user\test\base.
-* создан symlink c:\catalog.xml на c:\user\test\base\catalog.xml
-* при работе с symlink поиск файла hrc/proto.hrc будет производиться по пути c:\user\test\base\hrc\proto.hrc
\ No newline at end of file
diff --git a/docs/custom.md b/docs/custom.md
deleted file mode 100644
index cd0f865..0000000
--- a/docs/custom.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# Пользовательские настройки
-
-У вас есть библиотека схем, поставляемая с библиотекой/плагином/утилитой или скачанная со [страницы проекта](https://github.com/colorer/Colorer-schemes/releases) (далее называем её
-базовой библиотекой). Как настроить базовую библиотеку под свои предпочтения? Ниже приведены ответы на часто задаваемые вопросы по этой теме.
-
-Позиция автора заключается в том, что модифицировать базовую библиотеку нужно только в редких случаях. Все настройки необходимо делать во вне, не трогая базовую библиотеку. Это
-позволит в дальнейшем легко обновиться на новую версию. Если вы, всё же, решили изменить базовую библиотеку, создав свою библиотеку, то через параметры приложения можно указать до
-неё путь. Например, FarColorer по умолчанию использует библиотеку схем, находящуюся в папке плагина.
-
-### Как подключить собственную схему?
-
-Своя схема у вас уже создана, процесс создания тут не рассматривается.
-
-Возможны следующие варианты:
-
-* Указать в параметрах приложения путь до файла с описаниями (прототипами) пользовательских схем (аналог proto.hrc), файла с полноценной схемой (прототип + описание типа) или
- директории с *.hrc файлами.
-* Использовать папку `auto`. В зависимости от используемой поставки базовой библиотеки, папка `auto` может находиться по пути `/hrc/auto` или `/auto` относительно корня библиотеки
- схем. Этот вариант совпадает с предыдущим, только пользовательские схемы хранятся внутри базовой библиотеки. Для этого можно:
- * Создать в папке `auto` аналог proto.hrc и прописать туда прототипы своих схем, а в папку `/auto/types` положить описание типа. Минимальный (пустой) пример файла прототипов
- есть в дистрибутиве `/auto/empty.hrc`.\
- Внимание: empty.hrc служит для примера, изменять его не рекомендуется, т.к. при обновлении изменения потеряются.
- * Можно обойтись без отдельного файла прототипов, а разместить схемы непосредственно в папке `/auto`. Прототип в этом случае должен быть определён в самой схеме после
- тега <hrc>, без указания location.
-
- Папка auto загружается после загрузки базовых схем (если не меняли порядок в catalog.xml)
-* Изменить `catalog.xml`. Добавить в блок `<hrс-sets>` путь до папки или файла, где содержаться прототипы или схемы файлов.\
-* Изменить `proto.hrc` базовой библиотеки. Добавить свой прототип и путь до схемы типа файла.\
-
-### Как переопределить существующую схему?
-
-Для того чтобы в существующей схеме использовался пользовательский hrc файл, взамен базового, необходимо идти по пути подключения собственной схемы, но использовать старое имя.\
-Загрузка схем идет в порядке следования в catalog.xml и указанных в нем hrc файлах. При совпадении имен прототипов старый будет удален и загрузится новый.
-
-### Как изменить параметры схемы?
-
-Если требуется изменить только параметры схемы (блок parameters в описании прототипа), то возможны следующие варианты:
-
-* Указать значения параметров в файле `hrcsettings.xml`, путь до которого передается в параметрах приложения.\
- Формат файла:
-
- ```xml
- <?xml version="1.0" encoding='UTF-8'?>
- <hrc-settings>
- <prototype name="c">
- <param name="ansi-defines" value="true"/>
- <param name="win32-specific" value="true"/>
- </prototype>
- <prototype name="default">
- <param name="maxlinelength" value="5000" description="Maximum parsed length of line of the text"/>
- <param name="maxblocksize" value="300" description="Maximum length of regexp block in text"/>
- </prototype>
- </hrc-settings>
- ```
-
-Для нужных прототипов указываются изменяемые параметры и их новые значения. Для прототипа default можно указать параметры, которые будут действовать на все прототипы как значения
-по умолчанию. Атрибут `description` не обязательный, если задан, то заменит название описанное в прототипе.
-
-* Воспользоваться возможностями по настройке параметров в приложении. Например, FarColorer содержит свои диалоги настройки параметров.
-* Переопределить существующую схему, скопировав содержимое прототипа и изменив значения параметров. Обязательно откорректировать путь в location.
-
-### Как правильно "удалить" какую-либо стандартную схему?
-
-Часть схем имеет зависимость от других. Поэтому полное удаление схемы может привести к поломке отображения других. Если необходимо отключить возможность выбора схемы для файлов, то
-достаточно перевести её в разряд пакетов с тем же именем. Т.е. переопределить существующую схему, заменив `prototype` на `package`, и указав путь до неё. Например:
-
-```xml
-
-<package name="ant" description=" ">
- <location link="scripts/gen/ant.hrc"/>
-</package>
-```
-
-Если всё же схему необходимо полностью удалить, то это можно сделать переопределением схемы с указанием несуществующего location. При загрузке могут быть сообщения об ошибке, но
-работа библиотеки продолжится.
-
-### Как подключить собственные стили раскраски?
-
-Возможны следующие варианты:
-
-* Указать в параметрах приложения путь до файла с описаниями пользовательских стилей раскраски.\
- Формат файла:
-
- ```xml
- <?xml version="1.0" encoding="UTF-8"?>
- <hrd-sets>
- <hrd class="rgb" name="my-super" description="My new super style">
- <location link="c:/user/test/super.hrd"/>
- </hrd>
- </hrd-sets>
- ```
-
-* Изменить `catalog.xml`. Добавить в блок `<hrd-sets>` свои собственные стили. Пример добавление одного стиля:
-
- ```xml
- <hrd class="rgb" name="my-super" description="My new super style">
- <location link="c:/user/test/super.hrd"/>
- </hrd>
- ```
-* Изменить один из `hrd/catalog-*.xml`, на который ссылается catalog.xml. Добавить стили по примеру в файле.
-
diff --git a/docs/depends.md b/docs/depends.md
deleted file mode 100644
index 374c900..0000000
--- a/docs/depends.md
+++ /dev/null
@@ -1,93 +0,0 @@
-# Зависимости библиотеки Colorer
-
-## Библиотеки
-### Регулярные выражения
-Работа библиотеки основана на проверке соответствия строк исходного файла шаблонам из конфигурационных файлов.
-В шаблонах используются регулярные выражения с [расширенным синтаксисом](https://colorer.sourceforge.net/hrc-ref/index.html#hrcre).
-Благодаря чему удается обрабатывать блоки текста со стартовым и конечным выражением.
-
-Для обеспечения работы расширенного синтаксиса регулярных выражений был написан свой класс **CRegExp**.
-Заменить свою реализацию на что-то более распространенное, типа pcre, пока видится не реальным.
-Это потребует делать надстройки над стандартными регулярными выражениями, что выльется не в меньший по объему и сложности код.
-
-*Если честно, то сейчас не хватает мозгов осознать CRegExp.*
-
-### Строки и unicode
-Следствием использования своего класса для работы с регулярными выражениями, стала необходимость уметь работать с кодировками текста и свойствами символов.
-Т.е. нужно уметь отличать пробельные символы от цифр, или заглавные буквы от строчных. Эти свойства задаются в регулярных выражениях.
-Добавим сюда желание работать с текстами на разных языках, просто работать со строками (сравнение, преобразование), и
-быть кросс-платформенным.
-
-На текущий момент всё это проще всего обеспечить с помощью библиотеки **[ICU](https://icu.unicode.org)**. В библиотеке всегда
-поддерживается актуальная версия Unicode. Есть все инструменты для работы с символами и их свойствами.
-
-Ранее ([последний commit](https://github.com/colorer/Colorer-library/tree/b4bd3cbc5babb70fffc5a7e523af0311e493b4b5)) использовалась своя реализация строк, работа с
-Unicode, свойствами символов и кодировками. [Скрипт разбора](https://github.com/colorer/Colorer-library/blob/b4bd3cbc5babb70fffc5a7e523af0311e493b4b5/src/colorer/unicode/x_tables_generator.pl) Unicode стандарта версии 3.2, и
-преобразование его в код, на текущий момент не рабочий: генерирует код, отличающийся от текущего. Осознать что он делает - не тривиальная задача. Погрузится в свойства Unicode, изучить Perl - жуть.
-А после этого еще и поддерживать набор классов вокруг этого кода, где многое выглядит как магия, опять же основанная на свойствах Unicode.
-
-ICU всё же не плох.
-
-### XML
-Все настройки (схемы) Colorer хранятся в xml виде. При этом используется xml с external entities. Это позволяет использовать более простые xml файлы,
-перенося часть текста/логики во внешние файлы, или ссылаться внутри xml на ранее объявленные сущности. Так же обеспечивается доступ внешним
-файлам внутри архивов (ниже).
-
-На текущий момент для работы с xml используется библиотека **[Xerces-c](http://xerces.apache.org/)**. Она покрывает все задачи, да и альтернатив [почти нет](https://stackoverflow.com/questions/9387610/what-xml-parser-should-i-use-in-c).
-
-Ранее использовалась своя реализация классов работы с xml. Но она обеспечивала минимально необходимый функционал, и основывалась на старых строках.
-
-### Архивы
-Схемы Colorer (hrc) состоят из нескольких сотен файлов. Работать с таким количеством файлов не удобно. Если их упаковать в архив, то уже куда
-приятнее с ними работать, распространять.
-
-В качестве типа архива используется zip, а библиотека для работы с ним - **[zlib](https://zlib.net)**.
-
-### Логирование
-Для логирования используется **[spdlog](https://github.com/gabime/spdlog)**, одна из лучших реализаций на текущий момент. Она же,
-в свою очередь, зависит от **[fmt](https://github.com/fmtlib/fmt)**.
-
-### Тестирование
-Для тестирования используется **[Catch2](https://github.com/catchorg/Catch2)**.
-
-## Сборка под Windows
-Для сборки библиотеки под Windows, в том числе для FarManager, получаем список зависимостей:
-- icu
-- xerces-c
-- spdlog
-- fmt
-- zlib
-
-Сборка идет с помощью vcpkg, что сильно её упрощает. Но в то же время сборка достаточно медленная, т.к. ICU и Xerces-c зависят от msys платформы.
-И очень чувствительны к смене версий компилятора и зависимостей в окружении.
-Так же есть отдельные заморочки с ICU, чтобы обеспечить сборку только кода для Unicode, без добавления данных по кодировкам, и т.п..
-
-На выходе получаем один бинарный файл без зависимостей.
-
-## Сборка под Linux
-Для сборки библиотеки под Linux, получаем список зависимостей:
-- icu
-- xerces-c
-- spdlog
-- fmt
-- zlib
-
-Для упрощения сборки отключено по умолчанию использование vcpkg. Все зависимости должны быть установлены через системные пакеты.
-Это имеет как плюсы, так и минусы:
-* выполняем правила работы с linux, используя обще библиотеки, без статической сборки
-* ускоряем сборку
-* обеспечиваем более быструю сборку, и возможность ставиться на любые системы
-* сильно зависим от наличия библиотек под платформу, так и от версии этих библиотек.
-
-### far2l
-В far2l используется версия Colorer до перехода на ICU. Список зависимостей:
-- xerces-c
-- spdlog
-- fmt
-
-Поддержка архивов отключена полностью (так удобно? или опять зависимости?).
-Логирование через spdlog опциональное.
-Т.е. фактически зависимость одна - xerces-c. Что, порой, вызывает проблемы для использования на некоторых платформах. Т.к. xerces-c не входит
-в список пакетов по умолчанию.
-
-Так же far2l несет ограничение на использование c++ не выше 11 версии.
\ No newline at end of file
diff --git a/docs/dev_spdlog.md b/docs/dev_spdlog.md
deleted file mode 100644
index 7008739..0000000
--- a/docs/dev_spdlog.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# Использование spdlog
-
-Если вы решили использовать spdlog для логирования в вашем приложении, то для вывода строк с типом
-UnicodeString вам потребуются formatter для этого типа.
-
-## ICU UnicodeString
-```cpp
-#include "fmt/format.h"
-#include "unicode/unistr.h"
-
-namespace fmt {
-template <>
-struct formatter<icu::UnicodeString>
-{
- template <typename ParseContext>
- constexpr auto parse(ParseContext& ctx)
- {
- return ctx.begin();
- }
-
- template <typename FormatContext>
- auto format(const icu::UnicodeString& p, FormatContext& ctx)
- {
- std::string result8;
- p.toUTF8String(result8);
- return format_to(ctx.out(), "%", result8);
- }
-};
-
-} // namespace fmt
-```
-
-## Colorer strings (legacy) - UnicodeString
-
-```cpp
-#include "fmt/format.h"
-#include <string>
-#include "colorer/strings/legacy/UnicodeString.h"
-
-namespace fmt {
-template <>
-struct formatter<UnicodeString>
-{
- template <typename ParseContext>
- constexpr auto parse(ParseContext& ctx)
- {
- return ctx.begin();
- }
-
- template <typename FormatContext>
- auto format(const UnicodeString& p, FormatContext& ctx)
- {
- std::string result8=p.getChars();
- return format_to(ctx.out(), "%", result8);
- }
-};
-
-} // namespace fmt
-```
\ No newline at end of file
diff --git a/docs/tools.md b/docs/tools.md
deleted file mode 100644
index f7e1fb5..0000000
--- a/docs/tools.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# Tools
-
-## Colorer
-
-Конольная программа для работы с возможностями библиотеки.
-
-```
-Usage: colorer (command) (parameters) (logging parameters) [<filename>]
- Commands:
- -l Lists all available languages
- -lt Lists all available languages (HRC types)
- -ll Lists and loads full HRC database
- -r RE tests
- -h Generates plain coloring from <filename> (uses 'rgb' hrd class)
- -ht Generates plain coloring from <filename> using tokens output
- -v Runs viewer on file <fname> (uses 'console' hrd class)
- -p<n> Runs parser in profile mode (if <n> specified, makes <n> loops)
- -f Forwards input file into output with specified encodings
- Parameters:
- -c<path> Uses specified 'catalog.xml' file
- -i<name> Loads specified hrd rules from catalog
- -t<type> Tries to use type <type> instead of type autodetection
- -ls<name> Use file <name> as input linking data source for href generation
- -o<name> Use file <name> as output stream
- -ln Add line numbers into the colorized file
- -db Disable BOM start symbol output in Unicode encodings
- -dc Disable information header in generator's output
- -ds Disable HTML symbol substitutions in generator's output
- -dh Disable HTML header and footer output
- Logging parameters (default logging off):
- -eh<name> Log file name prefix
- -ed<name> Log file directory
- -el<name> Log level (off, debug, info, warning, error). Default value is off.
-```
-
-### Значения по умолчанию
-
-В работу библиотеки заложено следующее поведение по умолчанию, которое применимо и для программ, основанных на ней (если не расширено):
-
-* Если не задан путь до catalog.xml, то производится поиск в переменной окружения **COLORER_CATALOG**. Если и там пусто, то работа библиотеки завершается с ошибкой.
-* Класс стиля раскраски при преобразовании в реальные цвета (Style) по умолчанию "rgb".
-* Класс стиля раскраски при преобразовании в текстовое представление (Text) по умолчанию "text".
-* Если не задано имя стиля раскраски, то проверяется переменная окружения **COLORER_HRD**. Если и там пусто, то используется "default" стиль.
-
-### Переменные окружения
-
-* **COLORER_CATALOG** - путь до catalog.xml. Обрабатывается только в случае если не задан путь через параметры.
-* **COLORER_HRD** - имя стиля раскраски. Обрабатывается только в случае если не задан через параметры.
\ No newline at end of file