Можете да използвате pandoc на Linux, за да конвертирате между повече от 40 файлови формата. Можете също да го използвате за създаване на проста система документи като код, като пишете в Markdown, съхранявате в git и публикувате във всеки от поддържаните от него формати.
Съдържание
Преобразуване на документи и документи като код
Ако имате документ в някой от pandoc’s много поддържани файлови формати, преобразуването му в някое от другите е лесно. Това е удобен инструмент!
Но истинската сила на pandoc става очевидна, когато го използвате като основа на проста система документи като код. Предпоставката на docs-as-code е да приеме някои от техниките и принципите на разработката на софтуер и да ги приложи при писане на документация, особено за проекти за разработка на софтуер. Можете обаче да го приложите при разработването на всякакъв вид документация.
Разработчиците на софтуер използват любимия си редактор или Интегрирана среда за разработка (IDE), за да напишат своите програми. Кодът, който въвеждат, се записва в текстови файлове. Те съдържат програмен код за програмата.
Те използват а система за контрол на версиите, или VCS (Git е най-популярният), за да заснема промените в изходния код, докато се развива и подобрява. Това означава, че програмистът има пълна история на всички версии на файловете с изходния код. Той или тя има бърз достъп до всяка предишна версия на файл. Git съхранява файлове в хранилище. Има локално хранилище на компютъра на всеки разработчик и централно, споделено, отдалечено хранилище, което често се хоства в облак.
Когато са готови да създадат работеща версия на програмата, те използват a компилатор за да прочетете изходния код и да генерирате двоичен изпълним файл.
Като пишете вашите документи на лек, текстов език за маркиране, можете да използвате VCS, за да контролирате версията си. Когато сте готови да разпространявате или публикувате документ, можете да използвате pandoc, за да генерирате толкова различни версии на вашата документация, колкото са ви необходими, включително уеб базирани (HTML), текстова обработка или набор (LibreOffice, Майкрософт Уърд, 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.wdzwdz.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 документ, няма да се анализира правилно като самостоятелен 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“.
Вече можем да използваме това като шаблон с опцията –reference-doc:
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Сравнете това с примера за ODT от по-рано. Този документ използва различен шрифт, има цветни заглавия и включва горни и долни колонтитули. Въпреки това, той е генериран от същия файл „sample.md“ Markdown.
Шаблоните на референтни документи могат да се използват за посочване на различни етапи от производството на документ. Например, може да имате шаблони, които имат водни знаци „Чернова“ или „За преглед“. За финализиран документ ще се използва шаблон без воден знак.
Генериране на 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 уеб страница.