В операційній системі Linux, за допомогою інструменту pandoc, можна здійснювати конвертацію між понад 40 різноманітними форматами файлів. Крім цього, він надає можливість створити просту систему “документи як код”, де ви пишете текст у форматі Markdown, зберігаєте його у git та публікуєте в будь-якому з підтримуваних форматів.
Перетворення документів та концепція Docs-as-Code
Якщо у вас є документ у будь-якому з численних форматів, які підтримує pandoc, його перетворення в інший формат стає на диво простим завданням. Це дійсно корисний інструмент!
Справжня цінність pandoc розкривається при його використанні як основи для простої системи “документи як код”. Ідея “документи як код” передбачає застосування деяких підходів та принципів з розробки програмного забезпечення до процесу створення документації, особливо в контексті програмних проектів. Однак, ці підходи можна застосовувати до будь-якого виду документації.
Розробники програмного забезпечення використовують свої улюблені редактори або інтегровані середовища розробки (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-адресу в звичайні дужки [()], наприклад: [Посилання на приклад](https://www.example.com/).
Для вставки зображення введіть знак оклику безпосередньо перед дужками (![]). Введіть альтернативний текст для зображення у дужках. Потім вкажіть шлях до зображення в дужках [()]. Ось приклад: .
Ми розглянемо більше прикладів у наступному розділі.
Конвертація файлів
Конвертація файлів є дуже простою. Зазвичай, pandoc може визначити формати файлів за їхніми іменами. Нижче ми згенеруємо HTML-файл із Markdown-файлу. Параметр -o (вихід) вказує 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 і LaTeX використовують розширення “.tex”.
Ми також використовуємо параметр -s (окремий), що гарантує, що pandoc згенерує всю необхідну преамбулу LaTeX, щоб документ був повним, самостійним і правильно відформатованим LaTeX-документом. Без параметра -s вихідний код все ще буде коректним 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 може записувати, хто та коли вніс будь-які зміни: це особливо корисно, якщо ви часто працюєте з іншими над великими проектами. VCS також забезпечує центральне сховище для документів. Багато хмарних сервісів Git, такі як GitHub, GitLab, і BitBucket, надають безкоштовні тарифні плани.
Ви можете створювати документи в різних форматах: використовуючи прості скрипти оболонки, можна використовувати стилі з CSS та довідкових документів. Якщо ваші документи зберігаються в репозиторії VCS, інтегрованому з платформою безперервної інтеграції та безперервного розгортання (CI/CD), то їх можна генерувати автоматично, коли програмне забезпечення буде створено.
Заключні думки
В pandoc є багато інших можливостей, які ми не охопили тут. Процеси перетворення для більшості типів файлів можна налаштувати. Для отримання додаткової інформації відвідайте офіційний сайт pandoc, де є безліч чудових прикладів та детальна документація.