Nota, Typst и Evidence. Языки программирования для генерации документов

Все настолько привыкли к Markdown, что считают его неким стандартом для оформления документов в вебе. Но это не конечная истина, высеченная на камне, а просто популярный язык разметки, как HTML и TeX.

В то же время появляется всё больше новых языков, которые позиционируют себя как замену, альтернативу или дополнение к Markdown и TeX. В некоторых случаях они включают функции программирования, то есть позволяют добавить в документ исполняемый код. Веб-редакторы нового поколения можно использовать даже вместо Google Docs.

▍ Языки программирования для документов

Пассивные документы и активные программы всё чаще сливаются в единое целое. С одной стороны, языки разметки включают в себя фрагменты кода с полнотой по Тьюрингу ^[2]. С другой стороны, языки программирования (ЯП) включают сложные нотации документов.

Некоторые исследователи отмечают проблему отсутствия формальных основ, моделирующих все эти языки. Это важно, поскольку взаимодействие между документом и программой может быть тонким и чреватым ошибками. В то же время существует определённая граница между «содержанием» и «вычислениями» в документе. Более детальная формализация поможет устранить недостатки в существующих ЯП и создать новые, более продвинутые языки, говорится в научной статье «Базовое счисление для документов» ^[3] (первая версия опубликована 6 октября 2023 года для ежегодной конференции по принципам языков программирования POPL 2024).

Самые известные языки разметки ^[4]:

• HyperText Markup Language ^[5] (HTML) — оригинальный язык разметки документов для веба, созданный под влиянием метаформата SGML ^[6], который стал образцом для многих языков разметки.
• Keyhole Markup Language ^[7] (KML/KMZ) — язык разметки на основе XML для обмена географической информацией с Google Earth.
• Markdown ^[8] — простая текстовая разметка, популярная в блогах и CMS, существует множество реализаций, в том числе оригинальная реализация в редакторе Хабра.
• Mathematical Markup Language ^[9] (MathML).
• Scalable Vector Graphics ^[10] (SVG).
• TeX ^[11], LaTeX ^[12] — формат для описания сложной типографики и вёрстки математических, технических и научных публикаций.
• Вики-разметка ^[13] — используется в Википедии, MediaWiki ^[14] и других вики-проектах.
• Extensible 3D ^[15] (X3D).
• Extensible HyperText Markup Language ^[16] (XHTML): HTML в синтаксисе XML.
  • XHTML Basic ^[17] — подмножество XHTML для простых (обычно мобильных) устройств. Предполагается в качестве замены WML и C-HTML.
  • XHTML Mobile Profile ^[18] (XHTML MP) — стандарт для мобильных телефонов и других устройств с ограниченными ресурсами.

Но это лишь малое подмножество языков программирования, которые работают с документами. Авторы предлагают следующую таксономию языков:

Уровень в таксономии задаётся парой из доменной области документа и конструктора. Каждый уровень соответствует определённому семейству существующих языков. В правой колонке приведён пример синтаксиса для языка, выделенного курсивом.

В общем, сейчас мы наблюдаем истинный расцвет языков для генерации/программирования документов. Кроме старых и проверенных, появляются новые интересные проекты, некоторые из которых перечислены ниже.

▍ Typst

На Хабре уже рассказывали о новом языке Typst ^[19]. Он позиционируется как современная альтернатива LaTeX ^[20] (хотя в некоторых аспектах уступает ему), в виде веб-редактора (IDE) с возможностью совместного редактирования, сохранения документов на сервере и пр. В принципе, его можно рассматривать также как альтернативу Word и Google Docs.

В целом, синтаксис представляет собой нечто среднее между LaTeX и Markdown:

Редактор лучше всего подходит для написания научных статей, хотя никто не мешает использовать его в иных целях: для ведения обычного блога или написания рефератов. Интерфейс достаточно удобный, например, есть добавление картинок перетаскиванием мышкой:

В общем, гораздо проще, чем LaTeX, хотя все так привыкли к последнему, что мигрировать достаточно тяжело. Наверное, у Typst основной расчёт на новых пользователей, а также на принципиальных ненавистников TeX:

«Это хаос из кучи консольных утилит, которые запускают друг друга. Ни одну из них я не знаю и не хочу изучать. tex, xetex, latex, xelatex, biblatex, texi2dvi, latexmk… Что всё это такое? Почему меня должно волновать? Кто здесь главный?.. Это мешает работать. Если я открываю статью в текстовом редакторе, то хочу видеть название, автора, аннотацию и первый абзац. А не сто строк компьютерного бла-бла с обратным слэшем. Если я хочу вставить картинку, мне не нравится для этого каждый раз копипастить абзац кода:

begin{figure}
  centering 
  includegraphics[width=linewidth]{boat.jpg}
end{figure}

», — пишет ^[21] один из хейтеров.

Автор жалуется, что аспирантов заставляют учить TeX, и они якобы сильно страдают из-за этого, целые ночи пытаясь отформатировать таблицу. Рецензенты критикуют работы в другом формате. Всё это «токсичная культура, заразившая научное сообщество» и вариант стокгольмского синдрома, а вместо синтаксиса TeX студенты могли бы выучить нормальный язык программирования.

Возвращаясь к Typst, кроме веб-версии, есть локальное приложение с утилитой командной строки ^[22]. Она поддерживает команды типа таких:

# Скомпилировать file.pdf в рабочей папке
typst compile file.typ

# Скомпилировать файл PDF по указанному пути из указанного исходника
typst compile path/to/source.typ path/to/output.pdf

# Отслеживать исходники и перекомпилировать документ при их изменении
typst watch file.typ

▍ Nota

Nota ^[23] — ещё один язык для создания документов. Здесь тоже есть удобный веб-редактор (IDE), так что можно одновременно редактировать (программировать) документ и видеть конечный результат:

Документы Nota содержат множество структур. Например, внутренние сноски, похожие на хабровский тег abbr, только со ссылкой на контент из другой части документа и с поддержкой двойного щелчка, по которому контент ещё и подсвечивается.

Ключевые особенности:

• Документ Nota компилируется в программу на JavaScript.
• Его можно просматривать на любом устройстве и в любом браузере.
• Поддержка переменных, функций и структур данных.
• Интеграция с библиотеками JavaScript, такими как KaTeX, Vega-Lite и Penrose.
• Поддержка скринридеров.

▍ Evidence = Markdown + SQL

На основе Markdown создаются и специализированные программные проекты вроде Evidence ^[24], ориентированные на конкретную сферу применения. В данном случае — на бизнес-аналитику.

Как показано в примере ниже, Evidence — это генератор статических сайтов для дата-аналитиков. Что-то вроде Jekyll или Hugo, но конкретно для аудитории, работающей с SQL-запросами.

Генерация статического сайта из документа Markdown

Расширение Evidence для VSCode ^[25] — программистская альтернатива GUI-инструментам бизнес-аналитики. Расширение просто генерирует сайт на основе кода Markdown.

Все страницы — это документы Markdown. Код SQL из этих документов выполняется в реальной БД на проде (поддерживаются BigQuery, Snowflake, Postgres и др.). На результаты этих запросов можно ссылаться с помощью простого синтаксиса шаблонов, который используется для вставки результатов запроса в текст или для генерации секций отчёта на основе запроса.

Evidence также включает библиотеку компонентов, которая позволяет добавлять диаграммы и графики (тоже на базе запросов) через декларативные теги вроде <LineChart />.

Ключевые особенности:

• Операторы SQL в файлах разметки выполняют запросы к хранилищу данных.
• Диаграммы и компоненты с результатами SQL-запросов.
• Шаблоны разметки.
• Циклы и операторы If / Else.

Как можно понять, перед нами своеобразный гибрид Markdown и SQL, или скорее Quarto ^[26] и SQL (плюс ещё несколько технологий).

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

Примечание. Разработчики начали тестирование приватной беты Evidence Cloud, запись в очередь здесь ^[27].

▍ Базовое счисление для документов

Кроме перечисленных выше, можно упомянуть и другие любопытные коммерческие проекты, в том числе Markdoc ^[28], Quarto ^[26], MDX ^[29] и Living Papers ^[30]. Они присоединяются к числу предыдущих открытых разработок в области ЯП для документов, таких как Pandoc ^[31]. Небольшое сравнение синтаксиса семи разных языков при выполнении одинаковых задач можно посмотреть в этом репозитории ^[32] (pdflatex/LaTeX, CommonMark/Markdown, MDX/Markdown с поддержкой JSX, React JSX, Nota, Living Papers и Scribble).

Quarto

В то же время есть примеры языков, которые не очень удачно попытались использовать парадигму документов-программ: это PHP ^[33], React ^[34], Scribble ^[35] (диалект Racket). В каждом из них есть известные «косяки».

Сейчас действительно золотой век для языков программирования документов. Некоторые не сильно отличаются от настоящих языков программирования. Авторы документов хотят систематически форматировать коллекции данных, ставить сноски на похожие тексты, создавать аббревиатуры, скрывать текст для анонимного просмотра и т. д. Программный контроль над документом помогает решить эти задачи. И наоборот, отсутствие возможности программирования в HTML породило целую индустрию шаблонизаторов ^[36]. Специализированные шаблонизаторы включают Jinja ^[37] для Python и Liquid ^[38] для Ruby.

Всё это подводит к общему выводу: документы — это программы. И возможно, действительно следует разработать формальную модель для основных вычислительных функций языков программирования документов. Концепция базового счисления для документов ^[3] может стать фундаментом этой работы.