Как использовать pandoc для преобразования файлов в командной строке Linux
Гайд в разделе Linux "Как использовать pandoc для преобразования файлов в командной строке Linux" содержит информацию, советы и подсказки, которые помогут изучить самые важные моменты и тонкости вопроса….
Fatmawati Achmad Zaenuri / Shutterstock
Вы можете использовать pandoc в Linux для преобразования между более чем 40 форматами файлов. Вы также можете использовать его для создания простой системы «документы как код», написав в Markdown, сохранив в git и опубликовав в любом из поддерживаемых форматов.
Преобразование документов и Docs-as-Code
Если у вас есть документ в любом из множества поддерживаемых pandoc форматов файлов, конвертировать его в любой из других очень просто. Это удобный инструмент!
Но настоящая сила pandoc становится очевидной, когда вы используете его в качестве основы простой системы «документы как код». Предпосылка docs-as-code состоит в том, чтобы принять некоторые методы и принципы разработки программного обеспечения и применить их при написании документации, особенно для проектов разработки программного обеспечения. Однако вы можете применить его для разработки любой документации.
Разработчики программного обеспечения используют свой любимый редактор или интегрированную среду разработки (IDE) для написания своих программ. Код, который они вводят, сохраняется в текстовых файлах. Они содержат исходный код программы.
Они используют систему контроля версий или VCS (Git – самый популярный), чтобы фиксировать изменения в исходном коде по мере его разработки и улучшения. Это означает, что у программиста есть полная история всех версий файлов исходного кода. Он или она может быстро получить доступ к любой предыдущей версии файла. Git хранит файлы в репозитории. На каждом компьютере разработчика есть локальный репозиторий и центральный общий удаленный репозиторий, который часто размещается в облаке.
Когда они готовы создать рабочую версию программы, они используют компилятор для чтения исходного кода. code и сгенерируйте двоичный исполняемый файл.
Написав документы на легком текстовом языке разметки, вы можете использовать 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/).
- Чтобы вставить изображение, введите восклицательный знак непосредственно перед скобками (! []). Введите любой альтернативный текст для изображения в скобках. Затем заключите путь к изображению в круглые скобки [() “]. Вот пример:! [Компьютерщик] (HTG.png).
Мы рассмотрим больше примеров всего этого в следующем разделе.
Преобразование файлов
File преобразования просты. pandoc обычно может определить, с какими форматами файлов вы работаете, по их именам. Здесь мы собираемся сгенерировать HTML-файл из файла Markdown. Параметр -o (output) сообщает pandoc имя файла, который мы хотим создать:
pandoc -o sample.html sample.md
Наш пример файла Markdown, sample.md, содержит короткий раздел Markdown, показанный на изображении ниже.
Создается файл с именем sample.html. Когда мы дважды щелкаем файл, наш браузер по умолчанию откроет его.
Теперь давайте сгенерируем текстовый документ в формате открытого документа, который мы можем открыть в LibreOffice Writer:
пример pandoc -o sample.odt.md
Файл ODT имеет то же содержание, что и файл HTML.
Аккуратное прикосновение альтернативный текст изображения также используется для автоматического создания подписи к рисунку.
Указание форматов файлов
-f (from) и -t (to ) используются, чтобы указать 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
В Manjaro используйте:
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.
- У вас будет временная шкала всех версий ваших документов. Если вы храните документацию в VCS, например в Git, вы можете легко увидеть различия между любыми двумя версиями одного и того же файла. Однако это действительно работает только в том случае, если файлы представляют собой обычный текст, поскольку VCS ожидает работать с этим.
- VCS может записывать, кто и когда вносил какие-либо изменения: Это особенно полезно, если вы часто сотрудничаете с другими по крупным проектам. Он также предоставляет центральное хранилище для самих документов. Многие облачные службы Git, такие как GitHub, GitLab и BitBucket, имеют бесплатные уровни в своих ценовых моделях.
- Вы можете создавать свои документы в нескольких форматах: с помощью всего лишь пары простых сценариев оболочки вы может использовать стили из CSS и справочных документов. Если вы храните свои документы в репозитории VCS, который интегрируется с платформами непрерывной интеграции и непрерывного развертывания (CI / CD), они могут генерироваться автоматически при каждой сборке программного обеспечения.
Заключительные мысли
Есть в pandoc гораздо больше опций и функций, чем мы рассмотрели здесь. Процессы преобразования для большинства типов файлов можно настроить и настроить. Чтобы узнать больше, ознакомьтесь с отличными примерами на официальной (и чрезвычайно подробной) веб-странице pandoc.