Вы можете использовать pandoc в Linux для преобразования между более чем 40 форматами файлов. Вы также можете использовать его для создания простой системы «документы как код», написав в Markdown, сохранив в git и опубликовав в любом из поддерживаемых форматов.
Оглавление
Преобразование документов и преобразование документов в код
Если у вас есть документ в любом из pandoc’s множество поддерживаемых форматов файлов, преобразовать его в любой из остальных очень просто. Это удобный инструмент!
Но настоящая мощь pandoc становится очевидной, когда вы используете его как основу простой системы «документы как код». Предпосылка docs-as-code состоит в том, чтобы принять некоторые методы и принципы разработки программного обеспечения и применить их при написании документации, особенно для проектов разработки программного обеспечения. Однако вы можете применить его для разработки любой документации.
Разработчики программного обеспечения используют свой любимый редактор или интегрированная среда разработки (IDE) писать свои программы. Код, который они вводят, сохраняется в текстовых файлах. Они содержат исходный код для программы.
Они используют система контроля версий, или VCS (Git является наиболее популярным), чтобы фиксировать изменения в исходном коде по мере его разработки и улучшения. Это означает, что у программиста есть полная история всех версий файлов исходного кода. Он или она может быстро получить доступ к любой предыдущей версии файла. Git хранит файлы в репозитории. На компьютере каждого разработчика есть локальный репозиторий и центральный общий удаленный репозиторий, который часто размещается в облаке.
Когда они будут готовы создать рабочую версию программы, они используют компилятор для чтения исходного кода и создания двоичного исполняемого файла.
Написав свои документы на легком текстовом языке разметки, вы можете использовать VCS для управления версиями вашего письма. Когда вы будете готовы распространить или опубликовать документ, вы можете использовать pandoc для создания любого количества различных версий вашей документации, включая веб-версию (HTML), текстовый или наборный (LibreOffice, Microsoft Word, TeX), переносимый формат документа (PDF), электронная книга (ePub), и так далее.
Все это можно сделать из одного набора облегченных текстовых файлов с контролем версий.
Установка pandoc
Чтобы установить 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 легко читается, так как нет визуально громоздких тегов, отвлекающих от текста. Форматирование в документах Markdown похоже на форматирование, которое оно представляет. Ниже приведены некоторые основы:
Чтобы выделить текст курсивом, заключите его в звездочки. * Это будет подчеркнуто *
Чтобы выделить текст жирным шрифтом, используйте две звездочки. ** Это будет выделено жирным шрифтом **
Заголовки представлены знаком числа / решетки (#). Текст отделяется от хеша пробелом. Используйте один хэш для заголовка верхнего уровня, два — для второго уровня и т. Д.
Чтобы создать маркированный список, начинайте каждую строку списка со звездочки и вставляйте пробел перед текстом.
Чтобы создать нумерованный список, начинайте каждую строку с цифры, за которой следует точка, а затем вставляйте пробел перед текстом.
Чтобы создать гиперссылку, заключите название сайта в квадратные скобки ([]), а URL-адрес в скобках [()] вот так: [Link to How to Geek](https://www.howtogeek.com/).
Чтобы вставить изображение, введите восклицательный знак непосредственно перед скобками (![]). Введите любой альтернативный текст для изображения в скобках. Затем заключите путь к изображению в круглые скобки. [()“]. Вот пример:.
Мы рассмотрим больше примеров всего этого в следующем разделе.
Преобразование файлов
Преобразование файлов выполняется просто. pandoc обычно может определить, с какими форматами файлов вы работаете, по их именам. Здесь мы собираемся сгенерировать HTML-файл из файла Markdown. Параметр -o (output) сообщает pandoc имя файла, который мы хотим создать:
pandoc -o sample.html sample.md
Наш пример файла Markdown, sample.md, содержит короткий раздел Markdown, показанный на изображении ниже.
Создается файл с именем sample.html. Когда мы дважды щелкаем файл, наш браузер по умолчанию откроет его.
Теперь давайте сгенерируем Формат открытого документа текстовый документ, который мы можем открыть в LibreOffice Writer:
pandoc -o sample.odt sample.md
Файл ODT имеет то же содержимое, что и файл HTML.
Аккуратный штрих — альтернативный текст для изображения также используется для автоматического создания подписи к рисунку.
Указание форматов файлов
Параметры -f (от) и -t (до) используются, чтобы указать pandoc, какие форматы файлов вы хотите преобразовать из и в. Это может быть полезно, если вы работаете с форматом файла, который имеет расширение файла с другими родственными форматами. Например, TeX, и Латекс оба используют расширение «.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;
}
Полная команда приведена ниже — обратите внимание, что мы также использовали автономную опцию (-ы):
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.
У вас будет временная шкала всех версий ваших документов: если вы храните документацию в VCS, таком как Git, вы можете легко увидеть различия между любыми двумя версиями одного и того же файла. Однако это действительно работает только тогда, когда файлы представляют собой обычный текст, поскольку VCS ожидает, что именно с этим будет работать.
VCS может записывать, кто и когда вносил какие-либо изменения: это особенно полезно, если вы часто сотрудничаете с другими над крупными проектами. Он также предоставляет центральное хранилище для самих документов. Многие облачные сервисы Git, такие как GitHub, GitLab, и BitBucket, имеют бесплатные уровни в своих моделях ценообразования.
Вы можете создавать свои документы в нескольких форматах: с помощью всего лишь пары простых сценариев оболочки вы можете извлекать стили из CSS и справочных документов. Если вы храните свои документы в репозитории VCS, который интегрируется с Непрерывная интеграция и непрерывное развертывание (CI / CD), они могут создаваться автоматически при создании программного обеспечения.
Последние мысли
Есть еще много вариантов и функций внутри пандок чем то, что мы здесь рассмотрели. Процессы преобразования для большинства типов файлов можно настроить и настроить. Чтобы узнать больше, ознакомьтесь с отличными примерами на официальном (и очень подробном) веб-страница pandoc.