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

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

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

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

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

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

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

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

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

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

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

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

 sudo apt-get установить пандок 

В Fedora вам понадобится следующая команда:

 sudo dnf установить пандок 

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

 sudo pacman -Сью пандок 

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

 пандок --версия 

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

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

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

 пандок 

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

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

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

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

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

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

• Чтобы выделить текст курсивом , заключите его в звездочки. *This will be emphasized*
• Чтобы выделить текст жирным шрифтом , используйте две звездочки. **This will be in bold**
• Заголовки представлены знаком номера/решёткой ( # ). Текст отделяется от хеша пробелом. Используйте один хеш для заголовка верхнего уровня, два для второго уровня и так далее.
• Чтобы создать маркированный список, начните каждую строку списка со звездочки и вставьте пробел перед текстом.
• Чтобы создать нумерованный список, начинайте каждую строку с цифры, за которой следует точка, а затем вставляйте пробел перед текстом.
• Чтобы создать гиперссылку, заключите название сайта в квадратные скобки ( [] ) и URL-адрес в круглые скобки [ () ], например: [Link to How to Geek](https://www.howtogeek.com/) .
• Чтобы вставить изображение, введите восклицательный знак непосредственно перед квадратными скобками ( ![] ). Введите любой альтернативный текст для изображения в скобках. Затем заключите путь к изображению в круглые скобки [ () “]. Вот пример: ![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 уценка -t латекс -s -o sample.tex sample.md 

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

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

 sudo apt-get установить texmaker

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

 sudo dnf установить texmaker

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

 sudo pacman -Сью тексмакер

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

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

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

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

 ч1 {
  цвет: #FFFFFF;
  цвет фона: #3C33FF;
  поле сверху: 0px;
  нижняя граница: 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), они могут создаваться автоматически при сборке программного обеспечения.

СВЯЗАННЫЕ С: Что такое GitHub и для чего он используется?

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

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