From 6992c1436e3f4a34078263515d487ac9d1da3e9b Mon Sep 17 00:00:00 2001 From: Alexander Petrov Date: Sun, 7 Jun 2026 22:39:14 +0300 Subject: [PATCH] =?UTF-8?q?docs(mdview):=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=B8=D1=82=D1=8C=20=D0=BE=D0=BF=D0=B8=D1=81=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D0=B5=20=D1=80=D0=B0=D0=B1=D0=BE=D1=82=D1=8B=20=D0=B8=20=D1=82?= =?UTF-8?q?=D0=B5=D1=81=D1=82=D0=BE=D0=B2=D1=8B=D0=B5=20=D0=BF=D0=B0=D1=82?= =?UTF-8?q?=D1=82=D0=B5=D1=80=D0=BD=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Oz --- docs/mdview_guide_and_test_patterns.md | 188 +++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 docs/mdview_guide_and_test_patterns.md diff --git a/docs/mdview_guide_and_test_patterns.md b/docs/mdview_guide_and_test_patterns.md new file mode 100644 index 0000000..222baf6 --- /dev/null +++ b/docs/mdview_guide_and_test_patterns.md @@ -0,0 +1,188 @@ +# MDView: описание работы и тестовые паттерны +## Назначение +`mdview` — консольный просмотрщик Markdown для текстового режима 80x32. +Программа загружает `.MD`-файл, индексирует его на экранные сегменты и рендерит содержимое с учётом переносов, стилей и специальных блоков. + +## Как работает программа +### 1) Загрузка файла +- На старте вызывается `load_file(path)`. +- Если путь не передан, используется `SAMPLE.MD`. +- При ошибках загрузки программа показывает причину и завершает работу после нажатия клавиши. + +### 2) Индексация (`index_lines`) +- Файл разбирается в массив сегментов для быстрого рендера. +- Поддерживаются ключевые типы строк: + - заголовки `#..####`, + - маркированные/нумерованные списки, + - цитаты `>`, + - горизонтальные разделители, + - fenced code-блоки, + - таблицы (nowrap-режим), + - обычные параграфы. +- Для list/quote/plain используется общая логика сканирования с режимами склейки строк. + +### 3) Рендер (`render_line`, `render_viewport`) +- Для каждой видимой строки рисуется префикс (маркер списка, цитаты и т.д.) и текст. +- Поддерживаются inline-стили: + - `**жирный**`, + - `*курсив*`, + - `_подчёркнутый_`, + - `~~зачёркнутый~~`, + - `` `code` ``. +- Табы расширяются до фиксированного шага. +- Для длинных nowrap-строк применяется горизонтальный сдвиг и индикаторы `<`/`>`. + +### 4) Навигация +- `Up/Down` — прокрутка на 1 строку. +- `PgUp/PgDn` — прокрутка на экран. +- `Home/End` — начало/конец документа. +- `Left/Right` — горизонтальная прокрутка nowrap-контента. +- `Esc` или `F10` — выход. + +## Сборка и запуск +```bash +make -C examples/mdview +``` + +Запуск на целевой системе: +```bash +mdview.exe <путь_к_файлу.md> +``` + +Если путь не указан, открывается `SAMPLE.MD`. + +## Тестовые паттерны +Ниже набор паттернов для ручной регрессии. + +### P01 — Базовый smoke-тест открытия +Вход: +- валидный markdown-файл среднего размера. + +Ожидается: +- файл открывается без ошибок; +- статус-бар и меню отображаются корректно; +- прокрутка работает. + +### P02 — Ошибка открытия файла +Вход: +- несуществующий путь к файлу. + +Ожидается: +- сообщение `mdview: cannot load file`; +- корректный код причины (`open failed` и т.п.); +- ожидание клавиши перед выходом. + +### P03 — Пустой файл +Вход: +- пустой `.md`. + +Ожидается: +- сообщение `mdview: empty file`; +- корректное завершение после нажатия клавиши. + +### P04 — Обычный параграф и переносы +Шаблон: +```md +Это длинный абзац для проверки переноса строк в обычном тексте. +Вторая строка должна мягко склеиться с первой. +``` + +Ожидается: +- строки склеиваются как единый параграф; +- переносы происходят по ширине экрана без потери символов. + +### P05 — Hard break в параграфе +Шаблон: +```md +Первая строка с двумя пробелами в конце. +Вторая строка после hard break. +``` + +Ожидается: +- между строками сохраняется принудительный разрыв; +- inline-стиль не ломается. + +### P06 — Многострочный список с lazy continuation +Шаблон: +```md +- Пункт списка, который продолжается + на следующей строке с отступом. +``` + +Ожидается: +- continuation-строка склеивается с пунктом через один пробел; +- лишние ведущие отступы continuation не попадают в итоговый текст; +- переносы не ломают маркер списка. + +### P07 — Многострочная цитата +Шаблон: +```md +> Первая строка цитаты +> Вторая строка цитаты +> Третья строка цитаты +``` + +Ожидается: +- для продолжений корректно повторяется quote-префикс; +- сырой символ `>` из исходника не «просачивается» в середину текста. + +### P08 — Пустая quoted-строка как разделитель +Шаблон: +```md +> Первый параграф цитаты +> +> Второй параграф цитаты +``` + +Ожидается: +- пустая quoted-строка разделяет два параграфа; +- рендер не объединяет их в один поток. + +### P09 — Таблица в nowrap-режиме +Шаблон: +```md +| col1 | col2 | col3 | +|------|------|------| +| очень длинное значение | очень длинное значение | очень длинное значение | +``` + +Ожидается: +- строка таблицы не переносится по словам; +- работает горизонтальный сдвиг `Left/Right`; +- индикаторы `<`/`>` показывают скрытый контент. + +### P10 — Fenced code-block +Шаблон: +~~~md +```text +**это не жирный** +_это не подчёркнутый_ +``` +~~~ + +Ожидается: +- внутри code-блока inline-разметка не применяется; +- текст отображается как литерал. + +### P11 — Inline-стили на обычном тексте +Шаблон: +```md +Текст с **жирным**, *курсивом*, _подчёркнутым_, ~~зачёркнутым~~ и `code`. +``` + +Ожидается: +- все перечисленные стили рендерятся корректно; +- литеральные случаи вроде `2 * 3` не превращаются в стиль. + +### P12 — Статус-бар и границы прокрутки +Вход: +- документ на несколько экранов. + +Ожидается: +- корректные `L x-y / total` и `%`; +- `Home/End` приводят к ожидаемым позициям; +- при выходе за границы документа top-line корректно clamp-ится. + +## Рекомендация по регрессии +После любых изменений в логике индексации/рендера прогонять минимум: +- `P04`, `P05`, `P06`, `P07`, `P09`, `P10`, `P11`, `P12`.