Sprinter-SDCC/docs/mdview_guide_and_test_patterns.md

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 — выход.

Сборка и запуск

make -C examples/mdview

Запуск на целевой системе:

mdview.exe <путь_к_файлу.md>

Если путь не указан, открывается SAMPLE.MD.

Тестовые паттерны

Ниже набор паттернов для ручной регрессии.

P01 — Базовый smoke-тест открытия

Вход:

• валидный markdown-файл среднего размера.

Ожидается:

• файл открывается без ошибок;
• статус-бар и меню отображаются корректно;
• прокрутка работает.

P02 — Ошибка открытия файла

Вход:

• несуществующий путь к файлу.

Ожидается:

• сообщение mdview: cannot load file;
• корректный код причины (open failed и т.п.);
• ожидание клавиши перед выходом.

P03 — Пустой файл

Вход:

• пустой .md.

Ожидается:

• сообщение mdview: empty file;
• корректное завершение после нажатия клавиши.

P04 — Обычный параграф и переносы

Шаблон:

Это длинный абзац для проверки переноса строк в обычном тексте.
Вторая строка должна мягко склеиться с первой.

Ожидается:

• строки склеиваются как единый параграф;
• переносы происходят по ширине экрана без потери символов.

P05 — Hard break в параграфе

Шаблон:

Первая строка с двумя пробелами в конце.  
Вторая строка после hard break.

Ожидается:

• между строками сохраняется принудительный разрыв;
• inline-стиль не ломается.

P06 — Многострочный список с lazy continuation

Шаблон:

- Пункт списка, который продолжается
  на следующей строке с отступом.

Ожидается:

• continuation-строка склеивается с пунктом через один пробел;
• лишние ведущие отступы continuation не попадают в итоговый текст;
• переносы не ломают маркер списка.

P07 — Многострочная цитата

Шаблон:

> Первая строка цитаты
> Вторая строка цитаты
> Третья строка цитаты

Ожидается:

• для продолжений корректно повторяется quote-префикс;
• сырой символ > из исходника не «просачивается» в середину текста.

P08 — Пустая quoted-строка как разделитель

Шаблон:

> Первый параграф цитаты
>
> Второй параграф цитаты

Ожидается:

• пустая quoted-строка разделяет два параграфа;
• рендер не объединяет их в один поток.

P09 — Таблица в nowrap-режиме

Шаблон:

| col1 | col2 | col3 |
|------|------|------|
| очень длинное значение | очень длинное значение | очень длинное значение |

Ожидается:

• строка таблицы не переносится по словам;
• работает горизонтальный сдвиг Left/Right;
• индикаторы </> показывают скрытый контент.

P10 — Fenced code-block

Шаблон:

```text
**это не жирный**
_это не подчёркнутый_
```

Ожидается:

• внутри code-блока inline-разметка не применяется;
• текст отображается как литерал.

P11 — Inline-стили на обычном тексте

Шаблон:

Текст с **жирным**, *курсивом*, _подчёркнутым_, ~~зачёркнутым~~ и `code`.

Ожидается:

• все перечисленные стили рендерятся корректно;
• литеральные случаи вроде 2 * 3 не превращаются в стиль.

P12 — Статус-бар и границы прокрутки

Вход:

• документ на несколько экранов.

Ожидается:

• корректные L x-y / total и %;
• Home/End приводят к ожидаемым позициям;
• при выходе за границы документа top-line корректно clamp-ится.

Рекомендация по регрессии

После любых изменений в логике индексации/рендера прогонять минимум:

• P04, P05, P06, P07, P09, P10, P11, P12.