Pandoc v prostředí Linux umožňuje konverzi mezi více než 40 různými formáty souborů. Tento nástroj se také výborně hodí pro vytvoření jednoduchého systému dokumentace, který je založen na principech „docs-as-code“. Píšete v Markdownu, ukládáte do gitu a publikujete v libovolném z podporovaných formátů.
Převod dokumentů a koncept Docs-as-Code
Máte-li dokument v jednom z mnoha formátů podporovaných aplikací Pandoc, jeho konverze do jiného formátu je velmi jednoduchá. Je to skutečně užitečný nástroj!
Skutečná síla Pandocu se však ukáže při jeho použití jako základu pro systém „docs-as-code“. Tento přístup spočívá v aplikaci principů a technik vývoje softwaru na tvorbu dokumentace, především v oblasti vývoje softwaru. Metoda je ale využitelná pro tvorbu jakékoli dokumentace.
Vývojáři softwaru používají svůj oblíbený editor nebo integrované vývojové prostředí (IDE) pro psaní programů. Kód, který zadají, se ukládá do textových souborů, které obsahují zdrojový kód programu.
Pro sledování změn ve zdrojovém kódu během jeho vývoje používají systém správy verzí, neboli VCS. Nejrozšířenější je Git. Díky tomu má programátor kompletní historii všech verzí souborů zdrojového kódu a rychlý přístup k jakékoli předchozí verzi. Git ukládá soubory do úložiště. Každý vývojář má lokální úložiště na svém počítači a centrální sdílené vzdálené úložiště, často hostované v cloudu.
Když jsou připraveni vytvořit funkční verzi programu, použijí kompilátor pro překlad zdrojového kódu do binárního spustitelného souboru.
Pokud své dokumenty píšete v odlehčeném textovém značkovacím jazyce, můžete k řízení verzí svého psaní využít VCS. Když jste připraveni dokument distribuovat nebo publikovat, můžete pomocí Pandoc vygenerovat různé verze své dokumentace, včetně webové (HTML), textově zpracované (LibreOffice, Microsoft Word, TeX), přenosné dokumenty (PDF) nebo e-knihy (ePub) a další formáty.
To vše je možné z jedné sady verzovaných souborů prostého textu.
Instalace Pandoc
Pro instalaci Pandocu na Ubuntu použijte tento příkaz:
sudo apt-get install pandoc
Na Fedoře použijte tento příkaz:
sudo dnf install pandoc
Na Manjaru je potřeba zadat:
sudo pacman -Syu pandoc
Verzi, kterou jste nainstalovali, ověříte pomocí parametru –version:
pandoc --version
Použití Pandoc bez souborů
Pokud spustíte Pandoc bez jakýchkoli parametrů, akceptuje vstup přímo z příkazové řádky. Psaní ukončíte stisknutím Ctrl+D. Pandoc očekává vstup ve formátu Markdown a generuje HTML výstup.
Podívejme se na příklad:
pandoc
Napsali jsme několik řádků v Markdownu a stiskneme Ctrl+D.
Pandoc vygeneruje ekvivalentní HTML výstup.
Pro efektivnější využití Pandocu se vyplatí pracovat se soubory.
Základy Markdownu
Markdown je jednoduchý značkovací jazyk, který přisuzuje speciální význam určitým znakům. Pro tvorbu souborů Markdown můžete použít jakýkoli textový editor.
Markdown je snadno čitelný, protože neobsahuje žádné vizuálně rušivé značky. Formátování v dokumentech Markdown odráží jejich vizuální zobrazení. Zde jsou uvedeny některé základní formátovací prvky:
- Pro text psaný kurzívou jej obalte hvězdičkami. *Tento text bude kurzívou*.
- Pro tučný text použijte dvě hvězdičky. **Tento text bude tučný**.
- Nadpisy se zapisují pomocí znaku křížku/hash (#). Text je oddělen mezerou. Jeden hash pro nadpis nejvyšší úrovně, dva hashe pro nadpis druhé úrovně a tak dále.
- Pro seznam s odrážkami začněte každý řádek hvězdičkou a mezerou před textem.
- Pro číslování seznamu začněte každý řádek číslicí, tečkou a mezerou před textem.
- Pro hypertextový odkaz obalte název odkazu do hranatých závorek ([]) a URL do kulatých závorek [()], například: [Odkaz na How to Geek](https://www.wdzwdz.com/).
- Pro vložení obrázku napište vykřičník těsně před hranaté závorky (![]). V závorkách zadejte alternativní text obrázku. Potom uzavřete cestu k obrázku do kulatých závorek [()]. Příklad: .
Další příklady si ukážeme v následující části.
Převod souborů
Převod souborů je jednoduchý. Pandoc zpravidla dokáže určit formát souborů z názvu souboru. V tomto příkladu vygenerujeme HTML soubor z Markdown souboru. Volba -o (výstup) určuje název výstupního souboru:
pandoc -o sample.html sample.md
Náš ukázkový Markdown soubor, sample.md, obsahuje krátký úryvek Markdown kódu, který je zobrazen níže.
Vytvoří se soubor s názvem sample.html. Po dvojitém kliknutí jej otevře výchozí prohlížeč.
Nyní vygenerujeme textový dokument ve formátu Open Document Format, který můžeme otevřít v LibreOffice Writer:
pandoc -o sample.odt sample.md
Soubor ODT obsahuje stejný obsah jako HTML soubor.
Alternativní text obrázku se také používá pro automatické generování titulků.
Specifikace formátů souborů
Parametry -f (od) a -t (do) slouží pro upřesnění formátů vstupních a výstupních souborů. To je užitečné v případech, kdy formát souboru sdílí stejnou příponu s jinými souvisejícími formáty. Například TeX a LaTeX používají příponu „.tex“.
Použijeme také volbu -s (standalone), díky které Pandoc vygeneruje veškerou preambuli LaTeXu potřebnou k tomu, aby byl dokument kompletní, samostatný a dobře vytvořený. Bez volby -s by výstupem byl stále dobře vytvořený LaTeX, který by mohl být vložen do jiného dokumentu LaTeXu, ale nebyl by správně analyzován jako samostatný dokument LaTeXu.
Zadáme následující:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Pokud otevřete soubor „sample.tex“ v textovém editoru, uvidíte vygenerovaný LaTeX kód. Pokud máte editor LaTeXu, můžete otevřít soubor TEX a podívat se, jak se interpretují sazby LaTeXu. Zmenšením okna na obrázku vypadal výstup stísněně, ale ve skutečnosti je to v pořádku.
Použili jsme LaTeX editor, Texmaker. Pro instalaci do Ubuntu zadejte:
sudo apt-get install texmaker
Ve Fedoře je příkaz:
sudo dnf install texmaker
V Manjaru použijte:
sudo pacman -Syu texmaker
Převod souborů pomocí šablon
Pravděpodobně začínáte chápat flexibilitu, kterou Pandoc nabízí. Můžete psát jednou a publikovat téměř v jakémkoli formátu. Dokumenty ale mohou vypadat poněkud jednotvárně.
Pomocí šablon můžete určit styly, které Pandoc používá při generování dokumentů. Můžete například říct Pandocu, aby používal styly definované v kaskádových stylech (CSS) pomocí volby –css.
Vytvořili jsme malý CSS soubor s následujícím obsahem. Upraví mezery nad a pod nadpisem úrovně 1. Změní také barvu textu na bílou a barvu pozadí na odstín modré:
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
Úplný příkaz je níže. Všimněte si, že jsme použili také volbu standalone (-s):
pandoc -o sample.html -s --css sample.css sample.md
Pandoc použije jediný styl z našeho minimalistického CSS souboru a aplikuje jej na nadpis první úrovně.
Další možností, jak doladit HTML soubory, je zahrnout značky HTML do souboru Markdown. Tyto značky budou předány do vygenerovaného HTML souboru jako standardní HTML.
Tuto techniku byste ale měli používat pouze při generování HTML výstupu. Při práci s více formáty souborů Pandoc ignoruje HTML značky u ne-HTML souborů a předává je jako text.
Můžeme také určit styly pro generování ODT souborů. Otevřete prázdný dokument v LibreOffice Writer a upravte styly nadpisů a písma. V našem příkladu jsme přidali i záhlaví a zápatí. Dokument uložte jako „odt-template.odt“.
Nyní jej můžeme použít jako šablonu pomocí parametru –reference-doc:
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Porovnejte to s dřívějším příkladem ODT. Tento dokument používá jiné písmo, má barevné nadpisy a záhlaví i zápatí. Byl ale generován ze stejného Markdown souboru „sample.md“.
Šablony referenčních dokumentů lze použít pro různé fáze tvorby dokumentu. Můžete mít například šablony s vodoznakem „Koncept“ nebo „Ke kontrole“. Pro finální dokument by se pak použila šablona bez vodoznaku.
Generování PDF
Pandoc standardně používá modul LaTeX PDF pro generování PDF souborů. Nejjednodušší způsob, jak zajistit, že máte potřebné závislosti LaTeXu, je nainstalovat editor LaTeXu, jako je Texmaker.
Ale je to poměrně velká instalace. TeX i LaTeX jsou rozsáhlé. Pokud máte omezený prostor na disku, nebo víte, že TeX nebo LaTeX nebudete nikdy používat, můžete vygenerovat soubor ODT. Poté jej stačí otevřít v LibreOffice Writer a uložit jako PDF.
Docs-as-Code
Používání Markdownu má několik výhod:
- Práce se soubory ve formátu prostého textu je rychlá. Načítají se rychleji než soubory z textových editorů podobné velikosti a pohyb po dokumentu je rychlejší. Mnoho editorů včetně gedit, Vim a Emacs, používá zvýraznění syntaxe pro Markdown.
- Získáte časovou osu všech verzí dokumentů. Pokud uložíte dokumentaci do VCS, jako je Git, snadno porovnáte rozdíly mezi libovolnými dvěma verzemi stejného souboru. To ovšem funguje jen u souborů prostého textu, protože s nimi VCS počítá.
- VCS zaznamená, kdo a kdy provedl změny. To je užitečné zejména při spolupráci s ostatními na velkých projektech. Poskytuje centrální úložiště pro dokumenty. Mnoho cloudových služeb Git, jako je GitHub, GitLab a BitBucket, má v cenových modelech bezplatné verze.
- Dokumenty lze generovat v několika formátech. Pomocí jednoduchých skriptů můžete použít styly z CSS a referenčních dokumentů. Pokud ukládáte dokumenty do úložiště VCS s integrací Continuous Integration and Continuous Deployment (CI/CD), mohou se generovat automaticky při každé změně softwaru.
Závěrečné myšlenky
Možnosti a funkce Pandocu jsou mnohem širší, než to, co jsme zde popsali. Převodní procesy pro většinu typů souborů je možné ladit. Pro další informace se podívejte na příklady na oficiálních (a velmi podrobných) webových stránkách Pandocu.