Как использовать pandoc для преобразования файлов в командной строке Linux

Вы можете использовать pandoc в Linux для преобразования между более чем 40 форматами файлов. Вы также можете использовать его для создания простой системы «документы как код», написав в Markdown, сохранив в git и опубликовав в любом из поддерживаемых форматов.

Преобразование документов и Docs-as-Code

Если у вас есть документ в одном из pandocs многих поддерживаемых форматов файлов, преобразовать его в любой другой не составит труда. Это удобный инструмент!

Но реальная мощь pandoc становится очевидной, когда вы используете его в качестве основы простой системы «документы как код». Предпосылка docs-as-code состоит в том, чтобы принять некоторые методы и принципы разработки программного обеспечения и применить их к написанию документации, особенно для проектов разработки программного обеспечения. Однако вы можете применить его для разработки любого вида документации.

Разработчики программного обеспечения используют свой любимый редактор или интегрированную среду разработки (IDE) для написания своих программ. Вводимый ими код сохраняется в текстовых файлах. Они содержат исходный код программы.

Они используют систему контроля версий, или VCS (самая популярная — Git), для регистрации изменений в исходном коде по мере его разработки и улучшения. Это означает, что у программиста есть полная история всех версий файлов исходного кода. Он или она может быстро получить доступ к любой предыдущей версии файла. Git хранит файлы в репозитории. На компьютере каждого разработчика есть локальный репозиторий и центральный общий удаленный репозиторий, который часто размещается в облаке.

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

Написав свои документы на легком текстовом языке разметки, вы можете использовать VCS для контроля версий вашего письма. Когда вы будете готовы распространять или публиковать документ, вы можете использовать pandoc , чтобы создать столько различных версий вашей документации, сколько вам нужно, включая веб-версию (HTML), текстовую обработку или верстку ( LibreOffice, Microsoft Word, TeX), переносимый формат документа (PDF), электронная книга (ePub) и так далее.

Все это можно сделать из одного набора легковесных текстовых файлов с контролируемой версией.

Установка пандока

Чтобы установить pandoc в Ubuntu, используйте эту команду:

sudo apt-get install pandoc

В Fedora вам нужна следующая команда:

sudo dnf install pandoc

На Manjaro вам нужно ввести:

sudo pacman -Syu pandoc

Вы можете проверить, какую версию вы установили, используя параметр --version:

pandoc --version

Использование pandoc без файлов

Если вы используете pandoc без каких-либо параметров командной строки, он также принимает типизированный ввод. Вы просто нажимаете Ctrl + D, чтобы показать, что вы закончили печатать. pandoc ожидает ввода в формате Markdown и генерирует выходные данные в формате HTML.

Давайте посмотрим на пример:

pandoc

Мы набрали несколько строк Markdown и собираемся нажать Ctrl+D.

Как только мы это сделаем, pandoc создаст эквивалентный вывод в формате HTML.

Однако, чтобы сделать что-нибудь полезное с pandoc, нам действительно нужно использовать файлы.

Основы уценки

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

Markdown легко читается, так как нет визуально громоздких тегов, отвлекающих от текста. Форматирование в документах Markdown напоминает форматирование, которое оно представляет. Ниже приведены некоторые из основ:

• Чтобы выделить текст курсивом, заключите его в звездочки. *Это будет подчеркнуто*
• Чтобы выделенный жирным шрифтом текст, используйте две звездочки. **Это будет выделено жирным шрифтом**
• Заголовки представлены знаком числа/решёткой (#). Текст отделяется от хеша пробелом. Используйте один хэш для заголовка верхнего уровня, два для заголовка второго уровня и т. д.
• Чтобы создать маркированный список, начните каждую строку списка со звездочки и вставьте пробел перед текстом.
• Чтобы создать нумерованный список, начните каждую строку с цифры, за которой следует точка, а затем вставьте пробел перед текстом.
• Чтобы создать гиперссылку, заключите название сайта в квадратные скобки ([]) и URL-адрес в скобки [()] следующим образом: [Ссылка на руководство](https://linux-console.net/).
• Чтобы вставить изображение, введите восклицательный знак непосредственно перед квадратными скобками (![]). Введите любой альтернативный текст для изображения в скобках. Затем заключите путь к изображению в круглые скобки [()“]. Вот пример: ![The Geek](HTG.png).

Мы рассмотрим больше примеров всего этого в следующем разделе.

Преобразование файлов

Преобразование файлов простое. pandoc обычно может определить, с какими форматами файлов вы работаете, по их именам. Здесь мы собираемся создать файл HTML из файла Markdown. Опция -o (вывод) сообщает pandoc имя файла, который мы хотим создать:

pandoc -o sample.html sample.md

Наш образец файла Markdown, sample.md, содержит короткий раздел Markdown, показанный на изображении ниже.

Создается файл с именем sample.html. Когда мы дважды щелкнем файл, наш браузер по умолчанию откроет его.

Теперь давайте создадим текстовый документ Open Document Format, который мы можем открыть в LibreOffice Writer:

pandoc -o sample.odt sample.md

Файл ODT имеет то же содержимое, что и файл HTML.

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

Указание форматов файлов

Параметры -f (из) и -t (в) используются, чтобы сообщить pandoc, из каких форматов файлов вы хотите конвертировать и в какие. Это может быть полезно, если вы работаете с форматом файла, расширение которого совпадает с расширением файла с другими родственными форматами. Например, TeX и LaTeX используют расширение «.tex».

Мы также используем параметр -s (автономный), поэтому pandoc создает все преамбулы LaTeX, необходимые для того, чтобы документ был полным, автономным и хорошо продуманным. сформированный документ LaTeX. Без опции -s (автономный) вывод все равно будет правильно сформированным LaTeX, который можно вставить в другой документ LaTeX, он не будет правильно анализироваться как отдельный документ LaTeX.

Набираем следующее:

pandoc -f markdown -t latex -s -o sample.tex sample.md

Если вы откроете файл «sample.tex» в текстовом редакторе, вы увидите сгенерированный LaTeX. Если у вас есть редактор LaTeX, вы можете открыть файл TEX, чтобы увидеть предварительный просмотр того, как интерпретируются команды набора текста LaTeX. Уменьшение окна, чтобы оно соответствовало изображению ниже, сделало дисплей тесным, но на самом деле все было в порядке.

Мы использовали редактор LaTeX под названием Texmaker. Если вы хотите установить его в Ubuntu, введите следующее:

sudo apt-get install texmaker

В Fedora команда такая:

sudo dnf install texmaker

В Манджаро используйте:

sudo pacman -Syu texmaker

Преобразование файлов с помощью шаблонов

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

С помощью шаблонов вы можете указывать, какие стили pandoc использовать при создании документов. Например, вы можете указать pandoc использовать стили, определенные в файле каскадных таблиц стилей (CSS) с параметром --css.

Мы создали небольшой файл CSS, содержащий приведенный ниже текст. Он изменяет интервал выше и ниже заголовка уровня на один стиль. Он также изменяет цвет текста на белый, а цвет фона на оттенок синего:

h1 {
  color: #FFFFFF;
  background-color: #3C33FF;
  margin-top: 0px;
  margin-bottom: 1px;
}

Полная команда приведена ниже. Обратите внимание, что мы также использовали автономный параметр (-s):

pandoc -o sample.html -s --css sample.css sample.md

pandoc использует единый стиль из нашего минималистского файла CSS и применяет его к заголовку первого уровня.

Еще один вариант тонкой настройки, доступный при работе с HTML-файлами, — включить HTML-разметку в файл Markdown. Это будет передано в сгенерированный файл HTML как стандартная разметка HTML.

Тем не менее, этот метод следует использовать, когда вы создаете только вывод HTML. Если вы работаете с несколькими форматами файлов, pandoc проигнорирует HTML-разметку для файлов, отличных от HTML, и она будет передана им в виде текста.

Мы также можем указать, какие стили используются при создании файлов ODT. Откройте пустой документ LibreOffice Writer и настройте стили заголовка и шрифта в соответствии с вашими потребностями. В нашем примере мы также добавили верхний и нижний колонтитулы. Сохраните документ как «odt-template.odt».

Теперь мы можем использовать это как шаблон с опцией --reference-doc:

pandoc -o sample.odt --reference-doc=odt-template.odt sample.md

Сравните это с примером ODT из предыдущего. Этот документ использует другой шрифт, имеет цветные заголовки и включает верхние и нижние колонтитулы. Однако он был сгенерирован из того же самого Markdown-файла «sample.md».

Шаблоны справочных документов можно использовать для обозначения различных этапов производства документа. Например, у вас могут быть шаблоны с водяными знаками «Черновик» или «Для проверки». Шаблон без водяного знака будет использоваться для окончательного документа.

Создание PDF-файлов

По умолчанию pandoc использует механизм LaTeX PDF для создания PDF-файлов. Самый простой способ убедиться, что у вас есть соответствующие зависимости LaTeX, — это установить редактор LaTeX, такой как Texmaker.

Однако это довольно большая установка — Tex и LaTeX довольно здоровенные. Если место на вашем жестком диске ограничено или вы знаете, что никогда не будете использовать TeX или LaTeX, вы можете предпочесть создать файл ODT. Затем вы можете просто открыть его в LibreOffice Writer и сохранить в формате PDF.

Документы как код

Использование Markdown в качестве языка письма имеет несколько преимуществ, в том числе следующие:

• Быстрая работа с обычными текстовыми файлами: они загружаются быстрее, чем файлы текстового процессора аналогичного размера, и, как правило, быстрее перемещаются по документу. Многие редакторы, в том числе gedit , Vim и Emacs, используют подсветку синтаксиса с текстом Markdown.
• У вас будет временная шкала всех версий ваших документов. Если вы храните свою документацию в системе контроля версий, такой как Git, вы можете легко увидеть различия между любыми двумя версиями одного и того же файла. . Однако на самом деле это работает только в том случае, если файлы представляют собой обычный текст, так как именно с ним должна работать система контроля версий.
• Система контроля версий может записывать, кто и когда вносил какие-либо изменения: это особенно полезно, если вы часто сотрудничаете с другими над большими проектами. Он также предоставляет центральный репозиторий для самих документов. Многие облачные сервисы Git, такие как GitHub, GitLab и BitBucket, имеют уровни бесплатного пользования в своих моделях ценообразования.
• Вы можете создавать документы в различных форматах. С помощью всего пары простых сценариев оболочки вы можете получать стили из CSS и справочных документов. Если вы храните свои документы в репозитории VCS, который интегрируется с платформами непрерывной интеграции и непрерывного развертывания (CI/CD), они могут создаваться автоматически при сборке программного обеспечения.

Последние мысли

В pandoc есть гораздо больше опций и функций, чем мы рассмотрели здесь. Процессы преобразования для большинства типов файлов можно настроить и настроить. Чтобы узнать больше, ознакомьтесь с отличными примерами на официальной (и очень подробной) веб-странице pandoc.