Як використовувати pandoc для перетворення файлів у командному рядку Linux

| | 0 Comments| 1:25 PM
Categories:

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

Перетворення документів і Docs-as-Code

Якщо у вас є документ в будь-якому з pandoc багато підтримуваних форматів файлів, перетворити його на будь-яку іншу складно. Це зручний інструмент!

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

Розробники програмного забезпечення використовують свій улюблений редактор або інтегроване середовище розробки (IDE), щоб писати свої програми. Код, який вони вводять, зберігається в текстових файлах. Вони містять вихідний код для програми.

Вони використовують a система контролю версійабо VCS (Git є найпопулярнішим), щоб фіксувати зміни у вихідному коді в міру його розробки та вдосконалення. Це означає, що програміст має повну історію всіх версій файлів вихідного коду. Він чи вона може швидко отримати доступ до будь-якої попередньої версії файлу. Git зберігає файли в репозиторії. На комп’ютері кожного розробника є локальне сховище та центральне спільне віддалене сховище, яке часто розміщується у хмарі.

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

Написуючи документи легкою, текстовою мовою розмітки, ви можете використовувати 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.

  Як створити консоль Steam на базі Linux за допомогою SteamOS

Давайте розглянемо приклад:

pandoc

Ми ввели кілька рядків Markdown і збираємося натиснути Ctrl+D.

Як тільки ми це зробимо, pandoc генерує еквівалентний вихідний HTML.

Однак, щоб зробити щось корисне з pandoc, нам дійсно потрібно використовувати файли.

Основи розцінки

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

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

Щоб підкреслити текст курсивом, оберніть його зірочками. *Це буде підкреслено*
Для виділення жирного тексту використовуйте дві зірочки. **Це буде виділено жирним шрифтом**
Заголовки представлені цифрою/решетом (#). Текст відокремлюється від хеша пробілом. Використовуйте один хеш для заголовка верхнього рівня, два для другого рівня тощо.
Щоб створити маркований список, починайте кожен рядок списку із зірочки та вставте пробіл перед текстом.
Щоб створити нумерований список, починайте кожен рядок з цифри, за якою слідує крапка, а потім вставте пробіл перед текстом.
Щоб створити гіперпосилання, введіть назву сайту в квадратні дужки ([]), а URL-адреса в дужках [()] ось так: [Link to How to Geek](https://www.wdzwdz.com/).
Щоб вставити зображення, введіть знак оклику безпосередньо перед дужками (![]). Введіть будь-який альтернативний текст для зображення в дужках. Потім заведіть шлях до зображення в дужки [()“]. Ось приклад: ![The Geek](HTG.png).

Ми розглянемо більше прикладів усього цього в наступному розділі.

Перетворення файлів

Перетворення файлів прості. 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».

  Як встановити та використовувати Stacer на Linux

Ми також використовуємо параметр -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 використовувати стилі, визначені в a Каскадні таблиці стилів (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».

  Як майнити криптовалюту Bitcoin Gold (BTG) на Linux за допомогою Minergate

Тепер ми можемо використовувати це як шаблон з параметром –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.