Выбор движка документов

Разберитесь, как документы LaTeX, Typst, Markdown, Quarto и Calepin превращаются в PDF, и выберите компилятор, который нужен вашему проекту.

Движок превращает ваш исходник в документ, который читают люди. Язык документа выбирается при создании проекта. Для проекта LaTeX можно также выбрать, какой компилятор LaTeX выполняет сборку.

LaTeX компилируется в Tectonic или latexmk, Typst — версией, закреплённой в проекте. Markdown сначала проходит через Pandoc, затем через Tectonic.

Выбор языка

Ваша работа	С чего начать	Как это становится PDF
Подача в журнал, устоявшийся класс диссертации или существующий проект `.tex`	LaTeX	Tectonic или компилятор, запускаемый через `latexmk`
Новая статья, отчёт или резюме с лаконичным синтаксисом вёрстки	Typst	Встроенный Typst 0.15.1 или другая версия Typst, закреплённая в проекте
Черновик текста, заметки или документ, который вы хотите экспортировать в несколько форматов	Markdown	Pandoc преобразует исходник в LaTeX; Tectonic создаёт PDF
Аналитический отчёт, статья или презентация, результаты в которых даёт код на R, Python или Julia	Quarto	Quarto превращает файлы `.qmd` или `.Rmd` в PDF, веб-страницу или слайды
Документ Typst с блоками кода	Calepin	Calepin запускает код, затем встроенный Typst собирает PDF

Выбор определяет панель инструментов редактора, синтаксис исходника и доступные форматы экспорта. Смена компилятора LaTeX не переводит документ в Typst или Markdown. Чтобы перенести проект LaTeX на Typst, преобразуйте его в новый проект Typst.

Tectonic

Используйте Tectonic для простой настройки LaTeX. Он поставляется с Oleafly, скачивает нужные сборке пакеты TeX и кэширует их для последующих сборок. Начните с него, если ваш шаблон не требует конкретного компилятора.

Скомпилируйте один раз с доступом к сети перед поездкой. Проект с кэшем можно компилировать офлайн; новому пакету загрузка всё же может понадобиться. Включите Настройки → Общие → Офлайн-режим, чтобы Tectonic использовал свой кэш.

pdfLaTeX

Выбирайте pdfLaTeX, когда его указывает издательство или существующий проект. Он следует традиционному рабочему процессу LaTeX и хорошо подходит для старых классов и сочетаний пакетов. Ему нужен дистрибутив TeX с установленным latexmk.

XeLaTeX

Выбирайте XeLaTeX для проекта, который его требует, особенно если он использует fontspec, шрифты OpenType или многоязычный текст. Убедитесь, что названные в исходнике шрифты установлены или включены в проект. Он также запускается через latexmk.

LuaLaTeX

Выбирайте LuaLaTeX для шаблона, который его требует, для вёрстки на Lua или для рабочего процесса тегированных PDF в Oleafly. Тегированные PDF несут структуру документа, которую могут использовать вспомогательные технологии. Запустите предпроверку, чтобы изучить результат; сам по себе выбор компилятора не гарантирует качество тегов.

Typst

Oleafly поставляется с Typst 0.15.1. Создайте проект Typst, пишите в файлах .typ и нажмите Скомпилировать заново. Устанавливать TeX не нужно.

Настройки → Движки → Typst может также установить Typst версий с 0.11 до 0.15 и использовать Typst, уже установленный на вашем компьютере. Каждый проект закрепляет собственную версию, поэтому статья сохраняет вёрстку, когда Oleafly переходит на более новый Typst. Typst скачивает пакеты из Typst Universe при первом импорте их документом, а Офлайн-режим ограничивает его пакетами, уже находящимися в кэше или в проекте.

У Typst собственный синтаксис, пакеты и работа со шрифтами. Версии, пакеты, шрифты и варианты сборки описаны в разделе Проекты Typst. В руководстве по письму на Typst есть полный начальный документ и описание элементов панели инструментов.

Markdown

Markdown использует Pandoc для подготовки свёрстанного документа и Tectonic для сборки его PDF. Откройте Настройки → Движки → Markdown, чтобы установить Pandoc, если его нет. Затем откройте свой проект Markdown и скомпилируйте его.

Заголовки, списки, формулы и визуальный редактор описаны в разделе Письмо в Markdown. В руководстве по экспорту объясняется, какие форматы вывода предлагает проект.

Quarto

Quarto превращает документы .qmd и .Rmd в PDF, веб-страницу или слайды. Oleafly использует Quarto на вашем компьютере, если находит его. Если его нет, откройте Настройки → Движки → Quarto и выберите Скачать Quarto 1.10.19. На кнопке также указан размер загрузки. Oleafly проверяет загруженный файл перед распаковкой и хранит копию в собственной папке приложения. Если вы компилируете до того, как Quarto появился, предпросмотр предлагает сразу установить его или Открыть настройки движка.

Что вы получите, решает первый формат, объявленный в документе:

pdf, typst и beamer собирают PDF. Для format: typst установка TeX не нужна. pdf и beamer проходят через LaTeX, поэтому, если TeX у вас ещё нет, установите TinyTeX в разделе Настройки → Движки → LaTeX.
html, revealjs и dashboard собирают веб-страницу. Чтобы её увидеть, выберите Открыть в браузере в предпросмотре.

Если документ не объявляет формат, Oleafly ищет его в _quarto.yml или _metadata.yml в папке документа и в папках выше, вплоть до корня проекта. Если формат не указан нигде, Quarto собирает веб-страницу. Файл .Rmd, в котором указан output: R Markdown, например pdf_document, получает соответствующий формат Quarto.

Код выполняется в R, Python или Julia, которые уже есть на вашем компьютере. Oleafly никогда их не устанавливает, а раздел Языки на той же вкладке настроек показывает найденные. Для кода на Python в этом Python также нужен Jupyter. Экспорт предлагает DOCX и HTML, оба формата создаёт Quarto. В диалоге Новый проект есть два шаблона Quarto: Quarto article, PDF, который собирается через Typst, и Quarto slides, презентация reveal.js.

Calepin

Calepin запускает код в документе Typst и помещает результаты в PDF. Документ Calepin представляет собой файл .typ, который импортирует /.calepin/calepin.typ. Начните его с шаблона Calepin report или откройте стрелку рядом с Скомпилировать заново в проекте Typst и выберите Calepin в разделе Движок (этот проект).

Установите его в разделе Настройки → Движки → Calepin так же, как Quarto, кнопкой Скачать Calepin 0.0.61. Calepin собирает документ с помощью Typst, который поставляется с Oleafly. Блок кода, язык которого не установлен, показывает короткое примечание, а остальной документ всё равно собирается. Экспорт предлагает HTML, который создаёт Calepin.

Разрешение запуска кода в проекте

Код в документе Quarto или Calepin выполняется с вашими правами, поэтому в каждом проекте он выключен, пока вы его не разрешите. После компиляции, которой нужен был код, баннер над редактором сообщает, что код выключен, и предлагает Разрешить запуск кода в этом проекте. Можно также открыть стрелку рядом с Скомпилировать заново и выбрать Запускать код на этом компьютере в разделе Код (этот компьютер). Выключен снова выключает его. Разрешайте запуск кода, только если доверяете каждому файлу в проекте.

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

Пока код выключен:

Quarto показывает код каждого блока, не запуская его. Фильтры, шорткоды, _extensions, скрипты pre-render и post-render, а также встроенный код R запускают код даже в этом случае, поэтому документ, который их использует, не компилируется, пока вы не разрешите запуск кода.
Calepin не может пропускать код. Oleafly собирает PDF обычным Typst из результатов, которые Calepin сохранил при последнем запуске. Если их нет, компиляция останавливается и просит разрешить запуск кода.

Папке, которую вы открываете на месте, тоже нужно доверять, прежде чем Quarto или Calepin смогут её скомпилировать. Синхронизация исходника и PDF недоступна ни для одного из этих движков.

Значение по умолчанию для новых проектов

Откройте Настройки → Движки → LaTeX и выберите Движок компиляции по умолчанию: Tectonic (встроенный) или latexmk (системный TeX). Каждый созданный после этого проект LaTeX начинается с него:

Пустой проект или шаблон из диалога Новый проект, а также исследовательский проект.
Импортированные ZIP, папка, статья arXiv или репозиторий GitHub.
Документ, преобразованный в проект LaTeX, например файл Word или PDF.

Движок записывается в project.json проекта, поэтому соавтор, открывший проект, компилирует его так же. Импортированный проект, в котором указан pdfLaTeX, XeLaTeX или LuaLaTeX, сохраняет этот компилятор при переходе на latexmk. Сохранённый компилятор существующего проекта остаётся его собственным выбором.

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

Для Typst откройте Настройки → Движки → Typst и выберите версию по умолчанию. Новые проекты Typst закрепляют версию, которая является значением по умолчанию в момент их создания. Изменение значения по умолчанию позже не затрагивает существующие проекты.

Смена компилятора текущего проекта

Откройте стрелку рядом с Скомпилировать заново на панели инструментов проекта. В проекте LaTeX выберите Tectonic, «Автоматически», pdfLaTeX, XeLaTeX или LuaLaTeX в пункте Компилятор (этот проект), затем скомпилируйте. Прочитайте журнал, если шаблону нужен пакет или шрифт, которых нет в выбранной установке.

В проекте Typst это же меню содержит вместо этого пункт Версия Typst (этот проект). Выберите установленную версию или По умолчанию, чтобы следовать настройкам. Группа Движок (этот проект) в этом меню переключает документ между Typst и Calepin.

Обнаружение существующего дистрибутива TeX

Откройте Настройки → Движки → LaTeX и просмотрите обнаруженный набор инструментов. Oleafly проверяет наличие полной установки компиляторов, включая latexmk и вспомогательные инструменты. Частичная системная установка не имеет приоритета над работающей управляемой установкой.

Установка управляемого TinyTeX

Используйте элемент установки в настройках движка LaTeX, если вам нужен традиционный компилятор, а его нет. Oleafly скачивает собственную установку TinyTeX в ~/.oleafly/tinytex; права администратора не требуются. Предусмотрите около 250 МБ для начальной загрузки и дополнительное место для пакетов.

Управление пакетами

Список пакетов в настройках движка LaTeX позволяет фильтровать пакеты, просматривать описания, добавлять и удалять их. Значки тегирования отмечают пакеты, требующие особого внимания при создании тегированного PDF. Эти элементы управляют дистрибутивом TeX, который использует latexmk; у Tectonic отдельный кэш.

Прочитайте руководство по пакетам LaTeX и тегированным PDF →