Свежее прочтение документации Parser 3

Spearance 10.03 19:05 / 10.03 19:06

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

Я решил переосмыслить документацию Parser и написать свой вариант, основываясь на формате Markdown. Ссылка на документацию (временная).

Что изменилось в документации по Parser?

1. Структура

Классы вынесены на первое место, потому что являются более актуальными в поиске.

Некоторые разделы переставлены, например, «Комментарии к частям выражения» переехал в ветку «Условных операторов».

Упрощено обращение через адресную строку браузера. Ссылки теперь выглядят так /class/имя_класса/[method|field|option]/имя_метода_поля_или_опции/, например:
URL/class/table/method/count/.

Единая структура для всех страниц с описанием.

Внутри страниц описания код с примерами подсвечивается и получил возможность копирования. Из-за этого пришлось отказаться от прямых ссылок из кода на перекрестные страницы, по крайней мере пока.

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

2. Поиск

Вынесен на все страницы. В целом поиск теперь более практичное решение чем искать по структуре разделов.

Два поиска:
- по заголовкам
- по ключевым словам

3. Горячие клавиши

Поиск активируется горячей клавишей /. Стрелки вверх/вниз перемещения по результатам поиска, отмена поиска (ESC) и подтверждение (Enter).
Клавиша возврата к оглавлению раздела Alt + ← (Win) или ⌘ + ← (Мас) из страницы с описанием.

4. Оформление

Добавлена тёмная тема.
Птиц немного анимирован и добавлен в сноски.

5. Версия для печати

Любую страницу можно напечатать и она будет хорошо свёрстана. Ссылки и аббревиатуры отображаются текстом.

Версия для смартфонов.

6. Прочее

Улучшены семантика и типографика.

В примерах символы табуляции, например в таблицах, стоят правильными знаками и не требуют замены при копировании.

Добавлены аббревиатуры.

---

Сразу скажу что не стоит задача переплюнуть старую версию документации, они немного разные в силу излишней простоты Markdown, но эта же простота, с другой стороны, позволяет легко добавлять новые главы или создавать новые разделы, что может пригодиться в будущем.

Если этот формат приживется, готов предложить его для замены текущей документации на сайте parser.ru, но это должно решить сообщество.

---