Pandoc как пользоваться

Pandoc

На страницах этого блога уже не раз встречалось загадочное слово Pandoc. Пожалуй, самое время рассказать об этой штуке подробнее.

Если совсем коротко, то Pandoc — это универсальный текстовый конвертор. Очень удобная и полезная штука, сейчас попробуем разобрать почему.

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

Ценная технология, да. Но при тесном знакомстве с ней возникает ряд вопросов.

, почему только в HTML? А если хочется сохранить подготовленный текст в той же красивой разметке для ? И чтобы одним файлом? В PDF, например, или даже в Word’овском (буэ!) формате?

, почему именно Markdown? Есть ведь и другие стандарты легковесной разметки, вот хотя бы с ходу можно назвать вполне годный TextToTags. Менее распространённые, факт, но мало ли кому что удобнее?

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

Так вот, Pandoc является ответом на все эти вопросы. Он понимает кучу форматов на входе и выходе. Из практически любого «простотекстового» представления может сделать хоть HTML, хоть PDF (с одним уточнением, о котором чуть ниже), хоть (буэ!) Word, хоть даже электронную книгу в FB2 (буээээ!!) или EPUB.

Кроме того, он бесплатен, существует под все хоть распространённые платформы и является внешним инструментом — это не редактор, а именно конвертор. То есть работа над текстом происходит в вашем любимом и привычном редакторе, а дальше вы говорите, например,

pandoc -f markdown MyText.txt -t pdf -o MyText.pdf 

Через весьма непродолжительное время рядом с вашим файлом образуется его красивое со всеми изысками вёрстки и переносами. Здесь ключ -f задаёт входной формат текста, ключ -t формат результата, а ключ -o определяет имя файла, в который нужно результат записать (если не указано, результат уйдёт на стандартный вывод и его можно перенаправить, например, в буфер вот так). Подробности можно найти в обширной документации.

Если ваш любимый текстовый редактор позволяет выполнять вызовы внешних программ применительно к редактируемым файлам, то вам очень повезло — достаточно настроить эти вызовы со всеми их ключами ровно один раз и затем просто нажимать кнопочки для преобразований. Если такие вызовы не поддерживаются — тоже ничего страшного, их можно настроить в файловом менеджере (FAR отлично подойдёт!) или, на совсем уж худой конец, подготовить пакетные файлы.

Несколько важных нюансов.

• Pandoc умеет работать не только с файлами на диске, но и со ссылками. То есть можно сохранять и преобразовывать статьи с любимых сайтов… хотя, скорее всего, результат понадобится доводить до ума руками.
• Часть преобразований (например, в PDF) выполняется посредством вызова pdfLaTeX или его юникодовской инкарнации XeLaTeX. Входит в состав любой современной , хоть платной, хоть бесплатной.
• Поддерживается конвертация с шаблонами и управляющими переменными. Для их полноценного использования придётся поработать со специальным макроязыком, но зато на выходе можно получать что угодно с любыми желаемыми нюансами.
• Поддерживается работа с математическими формулами через тот же LaTeX. То есть — формулы любой красоты и сложности. Вот здесь, например, посмотрите — этот материал полностью набран в обычном текстовом редакторе, затем сконвертирован при помощи Pandoc, и его публикация заняла буквально пару минут.

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

Есть табак, да нечем нюхать

В данном посте описаны решения, которые легли в основу GOSTdown — набора шаблонов и скриптов для автоматической вёрстки. GOSTdown предназначен для тех, кому приходится писать и оформлять научно-технические отчёты (НТО) или программы по Единой системе программной документации (ЕСПД). Такие документы нередко имеют крупный размер, создаются долго и несколькими людьми, и перед сдачей проверяются на соответствие ГОСТам. Традиционно для создания таких документов используется Microsoft Word. Исполнители привыкли делать в Word, заказчики привыкли принимать в Word. Заказчиков мы обсуждать не будем, а поговорим об исполнителях и их проблемах.

Проблема

• Нумерация глав и разделов, генерация оглавления
• Вставка и нумерация формул, таблиц и рисунков
• Нумерация и форматирование многоуровневых списков
• Ссылки на главы, разделы, формулы, таблицы и рисунки
• Ведение перечня использованных источников, генерация списка литературы и ссылок на него в тексте
• Автоматический подсчёт и вставка в текст количества страниц, таблиц, рисунков, приложений
• Вставка текста из других документов и оформление его под стиль
• Протоколирование изменений, внесённых разными людьми
• Слияние изменений, сделанных разными людьми в своих копиях документа

Строго говоря, Word имеет средства для всех вышеперечисленных задач. Да, для всех. С параллельным редактированием и слиянием изменений Word в одиночку не справится, но установка сервера Sharepoint решит и этот вопрос.

• Какие-то заголовки упорно не появляются в оглавлении, а другие, которые в нём не нужны — упорно появляются
• Текст документа пестрит сообщениями [ошибка! источник ссылки не найден] или ненадёжными прямыми номерами, вставленными отчаявшимися коллегами
• Постоянно ломается форматирование многоуровневых списков
• Съезжает форматирование при вставке пункта списка из буфера обмена, вне зависимости от способа вставки
• Отслеживание изменений невозможно, потому что от « Отформатировано: русский » рябит в глазах
• Нет Sharepoint, а если он и появится, никто не научится им пользоваться
• При сохранении doc-файла в .docx работа Word необъяснимо и фатально замедляется
• Любая попытка привести в порядок зоопарк стилей в 100-страничном документе делает всё только хуже
• Есть необходимость редактировать основной текст документа в iOS или Android, и при этом не портить оформление при сохранении.

Решение

Решение заключается в том, чтобы редактировать документ в формате, основанном на тексте (plain text), а для чтения, печати и сдачи осуществлять преобразование текста в docx-файл, оформленный по всем правилам.

Исходный текстовый формат позволит легко отслеживать и сливать изменения (в идеале — с применением git или иной системы контроля версий). Автоматизированная процедура преобразования в docx пронумерует всё необходимое, расставит номера ссылок и применит стили оформления.

Пример исходного текста в Markdown:

Результат в PDF, сохранённом из docx:

Полный пример документа см. в репозитории. Там же находится руководство пользователя (README.md). Примеры результатов см. в архиве артефактов репозитория.

Остальное — технические детали, в которых всё самое интересное.

Выбор исходного формата и конвертера

С конвертером всё просто: он фактически единственный и называется Pandoc. Он обладает уникальным движком преобразования латеховских формул в формулы Word 2010.

Pandoc — универсальный инструмент для преобразования более чем 20 форматов друг в друга. Но схема его работы такова, что любые преобразования идут через внутреннее промежуточное представление документа в самом Pandoc. Модель внутреннего представления не содержит всех возможностей всех исходных форматов (и наоборот, содержит возможности, которые присутствуют не во всех исходных форматах). Это фактически приводит к выбору формата для нашей задачи. Есть только один формат, на 100% соответствующий внутреннему представлению Pandoc: Markdown. Точнее, Pandoc’s Markdown (формат Markdown сам по себе существует во многих вариациях).

Формулы в Pandoc’s Markdown вводятся в формате LaTeX. Для библиографии доступны разные варианты, включая BibTeX. Это привычно многим сотрудникам научных организаций, которые занимаются написанием статей.

Иллюстрации в Markdown вставляются в виде внешних файлов в форматах PNG, JPEG и EMF (последний — для графиков и векторных рисунков).

Ссылками в Pandoc занимаются т.н. фильтры: pandoc-citeproc (для библиографических ссылок) и pandoc-crossref (для всего остального). Эти фильтры — отдельные программы, запускаемые из Pandoc и работающие с документом в его внутреннем представлении.

Библиография

Существует два ГОСТа: 7.1-2003 (Библиографическая запись. Библиографическое
описание) и 7.0.5-2008 (Библиографическая ссылка). При создании списка
литературы в программной и научно-технической документации формально требуется применять ГОСТ 7.1. Но реально его никто не применяет из-за нелепых требований:

• вставлять пометку «[Текст]» в ссылки на любые тексты (т.е. практически во все ссылки);
• повторять имя первого автора дважды (включая случай, если автор всего один);
• писать полный список авторов после названия (до трёх включительно), а если их четыре и более, то упоминать только первого «и др».

ГОСТ 7.0.5 обходится без этих требований, поэтому его более охотно используют
вместо 7.1 — ту его часть, которая называется «затекстовые ссылки», про
которые, впрочем, сказано, что «Совокупность затекстовых библиографических
ссылок не является библиографическим списком».

В пакете pandoc-citeproc, используемом в Pandoc, есть стилевой файл в формате CSL 1.0.1, основанный на ГОСТ 7.0.5 с отдельными элементами ГОСТ 7.1.

В целом, правила ГОСТов (как 7.1, так и 7.0.5) настолько сложны, что автоматизировать библиографию по всем правилам невозможно. Вышеупомянутый формат CSL 1.0.1, задуманный как универсальный окончательный формат для формирования всей библиографии на свете, разумеется, не подходит в полной мере для этих ГОСТов.

В частности, в ГОСТе есть разумное требование: английские ссылки должны быть с английскими вспомогательными словами (Vol., No., pp., ed. и прочие), а русские — с русскими. В CSL 1.0.1 такой опции не предусмотрено. Опция появилась в расширении CSL-M, которое не поддерживается в pandoc-citeproc. Это препятствие удалось частично преодолеть ценой установки вспомогательного поля «note» в русскоязычных статьях и дополнительных изменений в CSL-файле.

Шаблон

Pandoc работает с основным текстом документа. Такие вещи, как титульный лист и колонтитулы, легко создаются пользователями в Word в режиме WYSIWYG, тогда как их создание в Pandoc затруднено или невозможно. Для разрешения этого противоречия в GOSTdown существует файл-шаблон в формате docx, который содержит следующее:

1. Формат колонтитулов (Pandoc «подхватывает» этот формат при генерации документа с основным текстом)
2. Перечень стилей, которые впоследствии использует Pandoc при генерации docx-файла
3. Собственно неосновное содержимое документа, т.е. небольшая часть содержимого, которая не генерируется из Markdown.

Постобработка

Напомним, Pandoc преобразует файл основного текста в формате Markdown в аналогичный файл в формате docx. Сразу после получения этого файла возникает задача вставки его в нужное место шаблона (после титульного листа). Этим занимается скрипт постобработки. И не только этим: файл, сгенерированный Pandoc, хотя и содержит необходимые стили, всё же не является готовым продуктом. Для получения готового продукта необходимо следующее:

1. Установка стилей нумерации и отступы для списков и вложенных списков (Pandoc в настоящий момент не обладает механизмом шаблонизации списков)
2. Исправление выравнивания номеров формул (нумерованные формулы pandoc-crossref генерирует как таблицы из двух колонок)
3. Исправление горизонтального выравнивания ячеек таблиц, в которых есть только формула и больше ничего (Word в таком случае берёт настройки выравнивания из формулы, а не из ячейки, а Pandoc не заботится о том, чтобы выравнивание в формуле совпадало с оным в ячейке.)
4. Установка стилей таблиц (Pandoc не умеет этого делать)
5. Установка стилей ненумерованных заголовков (они отличаются от стилей нумерованных, а Pandoc присваивает всем заголовкам одного уровня один стиль).
6. Разные другие мелочи по части форматирования
7. Вставление оглавления средствами Word
8. Подсчёт количества страниц, рисунков, таблиц, приложений, литературных источников, и вставка этих чисел в необходимое место документа.
9. Сохранение полученного документа не только в docx, но и в PDF.

Вопросы и ответы

1. Где рамочки с боковыми ячейками для подписей?

В представленном примере Описания программы имеются рамки на листе утверждения и титульном листе. В основной части ГОСТ разрешает рамку не наносить. В НТО рамки не требуются нигде.

2. Всё это точно по ГОСТу?

ГОСТы соблюдены в разумных пределах. В редких случаях требования ГОСТов проигнорированы в угоду эстетической составляющей. Например, ГОСТ рекомендует форматировать списки следующим образом:

Также см. выше ремарку о библиографии.

3. Почему шрифты не Arial и Times New Roman, а какие-то другие?

Требований по гарнитуре нет в ГОСТах (за исключением ГОСТов на стандарты и на конструкторскую документацию). В представленных шаблонах используются общедоступные гарнитуры фирмы «Паратайп»: PT Serif (с засечками), PT Sans (без засечек) и PT Mono (моноширинный) Объяснение, почему паратайповские шрифты идеально подходят для документов на русском языке, см. здесь.

4. Почему docx-файлы такие большие?

Из-за вышеупомянутых шрифтов, встроенных в файл. Можно отключить встраивание шрифтов (за него отвечает опция -embedfonts), и тогда файлы станут адекватного размера, но если на компьютере вашего коллеги или заказчика не установлены шрифты PT Serif, PT Sans и PT Mono, то при открытии документа в Word шрифты заменятся на шрифты по умолчанию, и документ в итоге будет выглядеть не так, как было задумано.

5. Почему не LaTeX?

Государственные заказчики не возьмут LaTeX-файл, т.к. не знают, что это такое. В принципе, если заказчику не нужен исходник и достаточно PDF-файла, то можно использовать и LaTeX.

Pandoc умеет генерировать docx-файлы из LaTeX, но генерация осуществляется с потерями из-за разницы в идеологиях LaTeX и Word в области стилей. Теоретически возможен вариант генерации и LaTeX и docx-файлов из одного исходника в Markdown с помощью Pandoc, но в реальности такое средство пока не создано.

6. Почему не Google Docs? Там даже формулы появились

Да, и даже доступны дополнения (Add-ons) для нумерации и библиографии. В Google Docs удобные средства совместной работы, но ограниченные средства форматирования. Нет стилей (кроме небольшого исходного набора). Проблематична вставка векторных рисунков. Нет поддержки офлайновой работы. (На самом деле есть, но тогда перестаёт решаться проблема слияния изменений.)

7. Почему не LibreOffice?

Во-первых, потому, что в LibreOffice/OpenOffice крайне плохо обстоит дело с отображением формул. Позвольте не называть остальные 17 причин.

8. Как преобразовать имеющийся docx в Markdown?

Конечно же, с помощью Pandoc (он ведь преобразует в любую сторону). Конечно, информация о стилях исходного документа при этом потеряется. Возможно, после конвертации потребуется ручная правка. Дополнительные проблемы могут возникнуть с формулами: Pandoc распознаёт в docx-файлах только формулы, набранные средствами Word 2010 (не MS Equation и не MathType). Известен трюк с участием LibreOffice для пересохранения формул MS Equation в Word 2010. Для более позднего MathType он, кажется, не работает.

9. Чем редактировать Markdown?

Любым текстовым редактором, начиная с notepad.exe. Например, для Windows есть Notepad++, для Linux — Emacs, для всех десктопных ОС — Visual Studio Code. Все они бесплатные.

Преимущество текстового представления в том, что вносить правки в текст можно хоть со смартфона в самолёте (и если настроен GitLab CI, вы сразу получаете готовый документ).

10. Что такое Gitlab CI и как мне получить docx, редактируя файл не на Windows?

См. соответствующий раздел руководства. Машина с Windows (удалённая) всё же понадобится, см. раздел «Системные требования».

11. Чем редактировать Markdown так, чтобы сразу видеть результат?

Это сложнее. Вам потребуется или вышеупомянутый Visual Studio Code, или Atom. Потребуется также установить расширение Markdown Preview Enhanced (MPE). Альтернативное расширение — Markdown Preview Plus (MPP), только для Atom. Эти расширения используют Pandoc для того, чтобы делать из вашего Markdown-файла HTML-файл для предпросмотра. Прочие средства редактирования Markdown, в т.ч. онлайновые, рассчитаны на другие диалекты Markdown и не будут отображать Pandoc’s Markdown в полной мере.

Пользовательские настройки для MPE в VS Code таковы:

При нажатии Ctrl+k v включается предпросмотр, который, хоть и не совпадает в точности с будущим docx-файлом, аккуратно отображает все формулы, таблицы, блоки кода и изображения (кроме EMF).

12. Таблицы неудобно редактировать в виде текста, что делать?

В Visual Studio Code и Atom существуют многочисленные расширения для упрощения работы с Markdown, в т.ч. с таблицами. Таблицы самого сложного вида (с многоабзацевыми ячейками) они, к сожалению, не поддерживают. Такие таблицы поддерживает Emacs и его table-mode.

13. Мне нужны вещи, которые есть в Word, но отсутствуют в Markdown, что делать?

Если речь идёт об относительно небольшом фрагменте документа, не укладывающимся в формат (например, сложная таблица с объединёнными ячейками), то пользователь может держать этот фрагмент в отдельном docx-файле, редактируя его в Word. Вставка фрагмента в основной текст может делаться скриптом, аналогично тому, как сейчас сам основной текст вставляется в шаблон на место %MAINTEXT%.

Благодарности

В создании GOSTdown принимала активное участие Алёна Водолагина (ИПА РАН), также помощь оказывал Даниил Аксим (ИПА РАН). Разумеется, GOSTdown не был бы возможен без замечательного ПО: Pandoc, pandoc-citeproc и pandoc-crossref (автор последнего — Николай Якимов, МАИ). Ну и Microsoft помогла своими Word COM и Powershell, чего уж там.

Markdown в науке

С распространением персональных компьютеров научные статьи, а также книги, методические пособия и учебники, обрели новый носитель. Осталась в прошлом печатная машинка и текст с отступами, куда впоследствии аккуратно вставлялись формулы и рисунки от руки. Математические формулы с появлением TeX набирают обычным текстом. Сейчас TeX уже не просто программа верстки, а способ записи формул. Даже если Вам не довелось с ним работать, а подготовка документа ассоциируется с Word, удобным и быстрым способом ввода формулы в Word служат те самые команды из TeX.

Интернет и эпоха Web 2.0 существенно изменили метод подготовки научных публикаций. Сейчас мы читаем статьи с экранов компьютеров, смартфонов и электронных книг, а не только с бумаги. Крайне желательно, чтобы работа над текстом по превращению журнальной статьи в энциклопедическую вики-справку, в презентацию, или же в содержимое сайта, не требовала чрезмерных усилий. Далее мы рассмотрим решение означенной проблемы с помощью текстовой разметки Markdown и попробуем представить себе дальнейшее развитие технологий.

В чём особенность Markdown-разметки? Почему бы не использовать LaTeX?

Краткий ответ: документ Word это doc/docx файл, он открывается с помощью Word, *.tex файлу нужен LaTeX, *.pdf требует для просмотра Acrobat Reader или схожей по функционалу программы. Текст Markdown — это просто текст. Читать и редактировать его чем-то особенным не обязательно.

Хорошо, но это же свойство есть и у файлов LaTeX? Да, но. Сравните:

\begin \title \maketitle \section Здесь мы рассмотрим несколько проблем. \begin \item Разметка предназначена для человека или машины? \item Нужны ли \emph инструменты и какие? \end \end

# Разметка Markdown ## Введение Здесь мы рассмотрим несколько проблем. * Разметка предназначена для человека или машины? * Нужны ли _особые_ инструменты и какие?

Кого не отпугнул LaTeX «программированием» и логической (а не визуальной) разметкой, тот всё еще потратит немало сил на борьбу с ним. Цикл «внес изменения — скомпилировал, прочёл — внёс изменения» не самый продуктивный способ работы с текстом. Да и не все способны к отрисовке формул TeX в голове!

Да простят мне эту инвективу поклонники LaTeX’а, хоть и задумано, что Вам не нужно думать об оформлении, только о содержании, остальное возьмет на себя LaTeX… но, будем честны, это не всегда так! Кто верстал диссертацию или автореферат под вкусы конкретного диссертационного совета, а вкусы у них бывают очень специфичны, тот поймет. Вот одна хорошая инструкция, как писать диплом в LaTeX — Как я написал диплом по химии с (Xe)LaTeX. Под катом мой опыт — посмотрите и оцените сложность задачи для себя.

Преамбула для удовлетворения вкусов какого-то диссовета

% Математические символы и шрифты \usepackage \usepackage \usepackage \usepackage \usepackage % Вместо babel, локализация документа под язык \usepackage \setmainlanguage \setotherlanguage % Чтобы > превращались в кавычки \defaultfontfeatures % Идеологически правильные шрифты \setmainfont \setsansfont \setmonofont % нужно явно указывать шрифт под каждый язык \newfontfamily\russianfont \usepackage \usepackage \usepackage \usepackage \renewcommand\normalsize \abovedisplayskip 10\p@ \@plus2\p@ \@minus5\p@ \abovedisplayshortskip \z@ \@plus3\p@ \belowdisplayshortskip 6\p@ \@plus3\p@ \@minus3\p@ \belowdisplayskip \abovedisplayskip \let\@listi\@listI>\normalsize \linespread % полуторный интервал \clubpenalty=100000 \widowpenalty=100000 \usepackage \usepackage \DeclareCaptionLabelFormat \DeclareCaptionLabelFormat \DeclareCaptionLabelSeparator \captionsetup \captionsetup[figure] \captionsetup[table] \renewcommand> \frenchspacing

LaTeX великолепен в сложных задачах, требующих безупречной верстки. Пусть местами умозаключения еще сырые, но ничто не сравнится с тем чувством, когда идеальные колонки текста обтекают формулы, а таблицы и иллюстрации дышат гармонией. С первого взгляда становится ясно — серьезная статья. Выглядит умно и строго. Мотивирует.

Подружить TeX-разметку с вебом, сделать правку независимой от огромного набора пакетов и самой программы LaTeX, тем не менее, совсем непросто.

С помощью таких инструментов как LyX отчасти удаётся преодолеть порог вхождения. Как ни отрицай, но делать таблицы и сложные формулы проще WYSIWYG (визуально) и LyX тут очень хорошо помогает. Однако, LyX работает поверх LaTeX, тот поверх TeX и вся эта система подчас громоздка.

Есть и другие решения. Например, Authorea или Overleaf. Они хорошо подходят для коллектива авторов желающих совместно написать академическую статью. Для многих журналов уже созданы готовые шаблоны и всё, что остается — наполнить форму содержанием. Тем не менее, недостаток WYSIWYG форматирования и упомянутая заточенность только на журналы остаётся камнем преткновения.

Желаемое

Хочется простой, всем и всеми читаемый текст, чтобы применяя к нему автоматизированные фильтры получать:

1. пригодную к отправке в журнал статью (препринт),
2. контент блога,
3. слайды презентации,
4. техническую документацию.

Препринт

Начнём с первого пункта. Есть множество редакторов Markdown удобных для коллективной и индивидуальной работы. У себя дома я предпочитаю Typora, а всем вместе можно воспользоваться StackEditPro. Выбор редакторов широк и здесь проблемы нет. Макет сделаем с использованием расширенного синтаксиса Markdown, который реализован в конвертере Pandoc.

Макет статьи с использованием расширений Pandoc: paper.md

--- title: "Pizza - A Carbohydrate Based Substrate For Tomato Delivery" date: "Apr 2021" author: "Sergei Malykhin, Pizza Enthusiasts Institute" --- # Abstract Pizza [@pizza2000identification] is an understudied yet widely utilized implement for delivering in-vivo *Solanum lycopersicum* based liquid mediums in a variety of next-generation mastications studies. Here we describe a de novo approach for large scale *T. aestivum* assemblies based on protein folding that drastically reduces the generation time of the mutation rate. See Figure \ref. # Algorithm ![It's Pizza \label](./pizza.png) Cauchy's integral formula [@dixon1971brief] $$ f(a)=\frac∮_γ\frac\,dz. \tag \label $$ As seen in equation $\eqref$ . # Source Code Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labo ```python def foo(): return "bar" ``` # Table | Tables | Are | Cool | | ------------- |:-------------:| -----:| | col 3 is | right-aligned | $1600 | | col 2 is | centered | $12 | | zebra stripes | are neat | $1 | Table: Table styles. \label Seen in table \ref, Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmo # References

Конвертируем в формат LaTeX:

pandoc --filter panflute --natbib --variable --biblio-style=./styles/american-chemical-society.csl --bibliography=paper.bib -s paper.md -t latex > paper.tex

Стили библиографических ссылок доступны в репозитории Zotero. Программа Panflute отвечает за обработку библиографии. Различные варианты тонкой доводки описаны в статье How to write academic papers in Markdown. Я удовлетворился простой проверкой работы конвейера Markdown -> LaTeX -> PDF, и полагаю, что при желании вполне можно сделать свой аналог Authorea. Скажем, на фреймворке bangle.dev реализовать WYSIWYG онлайн-редактор Markdown со специфическим набором расширений, а экспорт препринтов доверить Pandoc и товарищам.

Взглянуть бы на современный отечественный журнал, что принимает статьи в Markdown, не придираясь с мелочной дотошностью: нам пожалуйста файлом MS WORD, Times New Roman 14 пунктов, ссылки оформить согласно ГОСТ. С удобным интерфейсом загрузки манускрипта, данных, иллюстраций. Мечты.

Вывод. К настоящему моменту нет простого решения для решившегося писать в Markdown научную статью, а тем более диплом или диссертацию. Наполнить содержанием — более менее легко (попробуйте упомянутые редакторы Typora и StackEditPro), а дальше. поскольку журналы принимают сугубо LaTeX (или Word) манускрипт оформленный под определенный стандарт. дальше — сложности. Настройка конвертации Pandoc -> LaTeX, возможно, что также понадобится разбираться с Citation Style Language, затем неизбежное составление преамбулы LaTeX, доводка руками — расположение плавающих объектов, неразрывные пробелы, специфические поля, шрифт.

Контент блога

Разметка Markdown прекрасно подходит для статических генераторов сайтов. Вы переносите текст, иллюстрации и математику из статей в свой блог. Лучше один раз увидеть — вот образец того, что достижимо. Wowchemy — конструктор веб сайтов на фреймворке Hugo. Понравилось? Вы или ваша исследовательская группа решили завести такой сайт? Расскажу вкратце о том, какие есть подводные камни.

1. Нужен аккаунт на GitHub и некоторое понимание принципов работы с репозиториями кода.
2. Помимо разметки Markdown, активно используется разметка YAML.

Это совсем не сложно. YAML-разметку я уже приводил в макете статьи с Pandoc. Вот так она выглядит:

--- title: "Pizza - A Carbohydrate Based Substrate For Tomato Delivery" date: "Apr 2021" author: "Sergei Malykhin, Pizza Enthusiasts Institute" ---

Считайте, что YAML — ближайший родственник Markdown. Еще одна читаемая разметка. По-моему, даже новичку в IT вполне по силам. Так выглядит описание страницы блога:

--- title: Slides summary: An introduction to using Wowchemy's Slides feature. authors: [] tags: [] categories: [] date: "2019-02-05T00:00:00Z" slides: # Choose a theme from https://github.com/hakimel/reveal.js#theming theme: black # Choose a code highlighting style (if highlighting enabled in `params.toml`) # Light style: github. Dark style: dracula (default). highlight_style: dracula --- # Create slides in Markdown with Wowchemy [Wowchemy](https://wowchemy.com/) | [Documentation](https://owchemy.com/docs/managing-content/#create-slides) --- ## Features - Efficiently write slides in Markdown - 3-in-1: Create, Present, and Publish your slides - Supports speaker notes - Mobile friendly slides

Презентации в Markdown

Последний пример показывает как делаются презентации с помощью Markdown. В нём мы разбиваем текст на слайды с помощью символов — . Pandoc позволяет конвертировать их в адаптированный под пакет beamer LaTeX. Далее тот компилируется в PDF файл презентации.

pandoc --to=beamer --output=out.pdf test.md

Pandoc в качестве разделителя слайдов использует строки # Название слайда :

--- author: Sergei Malykhin title: Awesome Markdown Presentation! institute: Habr theme: Berlin --- # Slide 1 This is my first slide # Slide 2 $a^2 + b^2 = c^2$

Другая возможность делать слайды — программа Marp. Она доступна как плагин к IDE Visual Studio Code. Очень хорошо подходит тем, кто делает презентацию используя фрагменты из кода и документации к своей программе.

Вы просто включаете в шапке Markdown текста строки

--- marp: true ---

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

Документация

Markdown словно создан для документирования программ, однако, жизнь усложняется тем, что единых стандартов нет. Например, я использую Documenter.jl для генерации документации к своему пакету на языке Julia. А в нем соглашение следующее:

Here's some inline maths: ``\sqrt[n]``.

Вместо $\sqrt[n]$ тут апострофы! Ничего не поделаешь, приходится писать свой фильтр из одного синтаксиса в другой.

Фильтр Markdown для Documenter.jl и обратно

#!/bin/bash #= exec julia -O0 --compile=min "$" "$@" =# using ArgParse function doc2latex(mdfile) formula = false for line in eachline(mdfile) if formula && occursin("```", line) s = replace(line, r"```" => s"$$") formula = false elseif !formula && occursin("```math", line) s = replace(line, r"```math" => s"$$") formula = true else # replace `` -> $ s = replace(line, r"(? <=[^`])``(?=[^`])|^``(?=[^`])|(?<=[^`])``$" =>s"$") end println(s) end end function latex2doc(mdfile) formula = false for line in eachline(mdfile) if formula && occursin(r"\$\$", line) s = replace(line, r"\$\$" => s"```") formula = false elseif !formula && occursin(r"\$\$", line) s = replace(line, r"\$\$" => s"```math") formula = true else # replace $ -> `` s = replace(line, r"(? <=[^$])\$(?=[^$])|^\$(?=[^$])|(?<=[^$])\$$" =>s"``") end println(s) end end function parse_commandline(args) s = ArgParseSettings() add_arg_group!(s, "Mutually exclusive options", exclusive=true, required=true) @add_arg_table! s begin "--to-latex", "-l" help = "convert math formulae from Documenter.jl ``E=mc^2`` to LaTeX \$E=mc^2\$ format" action = :store_true "--to-documenter", "-d" help = "convert math formulae from LaTeX \$E=mc^2\$ to Documenter.jl ``E=mc^2`` format" action = :store_true end add_arg_group!(s, "Required arguments", required=true) @add_arg_table! s begin "input" help = "Markdown text file" required = true end return parse_args(args,s) end function main(args) parsed_args = parse_commandline(args) isnothing(parsed_args) && return try f = open(parsed_args["input"], "r") if parsed_args["to-latex"] doc2latex(f) elseif parsed_args["to-documenter"] latex2doc(f) end catch println("file $(parsed_args["input"]) doesn't exist.") end end main(ARGS) 

Я не единственный, кто столкнулся с этой проблемой, универсального решения не нашёл. Больше на эту тему рассказано в посте Статьи — это тоже исходный код

Возможности, которых еще нет, но хотелось бы

Химикам приходится постоянно иметь дело со структурными формулами. Для них тоже есть подходящий для чтения и машинной обработки формат, но нет фильтра для преобразования его в изображения. Речь идёт о SMILES (Simplified Molecular Input Line Entry System — «система упрощённого представления молекул в строке ввода»). Например, афлавотоксин B₁

Представляется строкой SMILES: O1C=C[C@H]([C@H]1O2)c3c2cc(OC)c4c3OC(=O)C5=C4CCC(=O)5 .

Почему бы ему не быть отрисованым WYSIWYG редактором Markdown? Программа OpenBabel это умеет делать на лету. Кроме структур, полезно иметь возможность включать небольшие графики, 3D структуры молекул, как это делается встраиванием плагина JsMol.

Словом, еще есть куда развиваться. Имеется JavaScript библиотека ChemDoodle Web Components, её бы соединить с Typora — все химики будут ваши.

Заключение

Идеи, заложенные в разметку Markdown, несмотря на кажущуюся простоту и очевидность, (давайте сделаем разметку удобной человеку) несут в себе большой потенциал. Вместо утомительной работы по перегонке информации из переписки в статьи, со статей в презентации, с них в книги и документацию к программам, мы получим много свободного времени для творческой работы. Уже сейчас совместная работа и подготовка слайдов достаточно удобны. В будущем, как мне хочется надеяться, оформление публикаций перестанет быть вавилонским столпотворением и вместо настройки пакетов LaTeX, составления библиографических стилей bibtex, оформления и компоновки таблиц и рисунков мы будем иметь задачу только ясно изложить свою мысль.

Наши серверы можно использовать для разработки и просчета научных экспериментов.

Зарегистрируйтесь по ссылке выше или кликнув на баннер и получите 10% скидку на первый месяц аренды сервера любой конфигурации!

Pandoc: конвертируем текстовую разметку

Конвертер текстовых файлов Pandoc нельзя отнести к классу обязательных программ для каждого пользователя. Но если нужно конвертировать файлы из одного формата разметки в другой, то Pandoc — это, как говорится, универсальный швейцарский армейский нож

Языки разметки

С языками разметки текста сталкиваются практически все пользователи, а многие даже с ними и работают. Текстовый документ, написанный с использованием языка разметки, содержит не только сам текст, но и дополнительную информацию о различных его участках — например, указание на заголовки, списки и т. д. Текстовую разметку ещё часто называют вёрсткой — например, HTML-вёрстка.

С языком разметки мы сталкиваемся, когда, например, используем BB-код при создании сообщения на форумах. И форматов разметки очень много: типографических — TeX, PostScript, PDF; офисных для файлов Microsoft Word и OpenOffice; браузерных — HTML, XML, SVG; почтовых — Markdown.

И бывает ситуации, когда текст из одного формата разметки нужно конвертировать в другой. Для этой цели и существует консольная программа-конвертер Pandoc.

Эта программа может принимать и преобразовывать следующие форматы друг в друга: Markdown, reStructuredText, Textile, HTML, DocBook, LaTeX.

Но выходных форматов, в которые можно конвертировать вышеперечисленные форматы, гораздо больше:

• HTML-форматы XHTML, слайды Slidy, Slideous, S5;
• офисные форматы: Microsoft Word docx, OpenOffice/LibreOffice ODT, OpenDocument XML;
• электронные книги EPUB;
• техническая документация DocBook, GNU TexInfo, Groff man pages
• TeX-разметка: ConTeXt, слайды LaTeX Beamer;
• простая разметка текста: AsciiDoc, MediaWiki, Emacs Org-Mode.

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

Pandoc включает в себя библиотеки Haskell и автономные программы командной строки. Pandoc — это свободное программное обеспечение, распространяемое по лицензии GPL. Автор Джон Макфарлейн.

Pandoc — кроссплатформенное ПО. Существуют версии для Linux, Windows, Mac OS. В зависимости от ОС установочный файл «весит» 4-6 мегабайт. Для пользователей Linux приложение имеется практически во всех официальных репозиториях.

Как и положено, у проекта есть свой сайт и демостраница, где можно ознакомиться с базовыми функциями приложения.

Главный недостаток программы в отсутствии руководства (man) на русском языке. Pandoc имеет множество отдельных опций для разных форматов разметки, рассмотреть которые в отдельной статье затруднительно. Надеюсь, эта статья послужит для кого-нибудь стимулом создания для Pandoc русской справки man.

Основные команды

Ниже рассмотрим самые основные параметры и опции Pandoc, В остальных случаях желательно познакомится с довольно объёмным руководством на сайте или через руководство man.

Pandoc — программа консольная, и ей требуется передавать в качестве параметров имя входного файла, а и при помощи опции «-о» — целевого файла. Программа может понимать входной и выходной формат разметки по расширению файла.

pandoc input.md -o output.html

Однако можно указать входной и выходной форматы при помощи специальных опций. Выходной формат задаётся опциями «-t» или «—to», а входной — опциями «-f» или «—from». Например, следующая команда перекодирует файл input.md с разметкой Markdown в файл output.txt с html-разметкой

pandoc input.md -o output.txt -t html

Если опции форматов или расширения файлов не указаны или не известны для Pandoc, то по умолчанию программа считает форматом входного файла Markdown, а выходного — HTML.

Также Pandoc может работать для некоторых форматов в интерактивном режиме, когда используется стандартный вывод на экран терминала. Выход на стандартный вывод отключен для odt, docx, и epub форматов.

Вместо локальных файлов могут использоваться абсолютные адреса URI в интернет. В этом случае Pandoc будет скачивать содержимое с помощью HTTP:

pandoc -f html -t markdown http://www.fsf.org

Следует не забывать, что Pandoc использует UTF-8 кодировку для входа и выхода. Поэтому, если кодировка не UTF-8, нужно сначала использовать отдельные утилиты для перекодировки — например, iconv.

Pandoc может конвертировать форматированные тексты в файл формата pdf. Но для этого программа использует внешние приложения для получения PDF. Например, для Windows можно использовать TeX-движок MiKTeX, а для Mac OS X — BasicTeX. Для создания файла PDF просто укажите выходной файл с pdf расширением. Pandoc создаст файл LaTeX и использует pdflatex установленного PDF-движка.

pandoc input.txt -o output.pdf

Параметры форматирования

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

Например, при помощи опции «—strict» можно указать строгий синтаксис для входного формата Markdown, где не используются дополнительные расширения этого языка разметки.

При помощи опции «-R» непереводимый код вводного формата HTML и LaTeX не будет игнорироваться, и непереведённые теги HTML или команды LaTeX будут вставляться в выходной файл как есть.

Опция «-S» преобразуют входные форматы Markdown или Textile в типографский правильный вывод. Например, три подряд коротких тире будут преобразованы в длинное тире и т.д.

Для выходного файла форматов HTML или LaTeX при помощи опций «-H», «-B», «-A» можно вставлять содержимое внешних файлов соответственно в конце заголовка, в тело документа или в конец документа. Пример

pandoc input.txt -H footer.html -o output.html

При помощи опции «-c URL» можно добавить в выходной HTML-файл ссылку на css-файл.

Pandoc имеет развитую систему шаблонов. Это такие куски кода-разметки, которые программа будет добавлять в начале и конце документа дополнительно к конвертируемому тексту. Например, шаблон для HTML-файла включает теги DOCTYPE, HEAD, начальный и конечный тег BODY и HTML.

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

pandoc input.txt -s -o output.html

Поглядеть код вставляемого по умолчанию шаблона можно командой

pandoc -D FORMAT

где FORMAT — это имя выбранного формата. Можно создавать свои собственные шаблоны и подключать их опцией «—template». Например,

pandoc input.md -s --template=mytemplate.tex -o output.pdf

Математика

Интересной особенностью Pandoc является поддержка конвертирования математических формул из разметки LaTeX в представление HTML. Для вывода математики в HTML используются на выбор несколько специальных математических движков на основе MathML, Java-Script, онлайн-сервисов, код которых будет вставлен в сконвертированный HTML-файл.

Для конвертирования математических формул можно использовать следующие опции:

• —mathml — преобразует формулы LaTeX в разметку MathML;
• —webtex — преобразует формулы LaTeX при помощи онлайн-сервиса Google Chart API;
• —mathjax — преобразует формулы LaTeX при помощи расширения MathJax для MediaWiki;
• —latexmathml — преобразует формулы LaTeX при помощи JS-библиотеки Latexmathml.

Осталось ещё познакомиться с возможностями Pandoc на каком-нибудь практическом примере. И такой практический пример мы рассмотрим в следующей статье, создавая при помощи этой программы полноценную электронную книгу в формате EPUB.

Михаил АСТАПЧИК