Pandoc můžete v Linuxu použít k převodu mezi více než 40 formáty souborů. Můžete jej také použít k vytvoření jednoduchého systému docs-as-code psaním v Markdown, ukládáním do git a publikováním v jakémkoli z podporovaných formátů.
Table of Contents
Konverze dokumentů a Docs-as-Code
Pokud máte dokument v některém z pandoc mnoho podporovaných formátů souborů, převést jej na kterýkoli z ostatních je hračka. To je užitečný nástroj!
Ale skutečná síla pandocu se projeví, když jej použijete jako základ jednoduchého systému docs-as-code. Předpokladem docs-as-code je přijmout některé techniky a principy vývoje softwaru a aplikovat je na psaní dokumentace, zejména pro projekty vývoje softwaru. Můžete jej však použít na vývoj jakékoli dokumentace.
Softwaroví vývojáři používají svůj oblíbený editor popř integrované vývojové prostředí (IDE) psát své programy. Kód, který zadají, je uložen v textových souborech. Tyto obsahují zdrojový kód pro program.
Používají a systém správy verzínebo VCS (Git je nejoblíbenější), k zachycení změn ve zdrojovém kódu při jeho vývoji a vylepšení. To znamená, že programátor má kompletní historii všech verzí souborů zdrojového kódu. Má rychlý přístup k jakékoli předchozí verzi souboru. Git ukládá soubory do úložiště. Na každém počítači vývojáře je místní úložiště a centrální sdílené vzdálené úložiště, které je často hostováno v cloudu.
Když jsou připraveni vytvořit pracovní verzi programu, použijí a kompilátor přečíst zdrojový kód a vygenerovat binární spustitelný soubor.
Když budete své dokumenty psát v odlehčeném, textovém značkovacím jazyce, můžete použít VCS k řízení verzí vašeho psaní. Když jste připraveni distribuovat nebo publikovat dokument, můžete pomocí pandoc vygenerovat tolik různých verzí své dokumentace, kolik potřebujete, včetně webových (HTML), textově zpracovaný nebo vysázený (LibreOffice, Microsoft Word, TeX), přenosný formát dokumentu (PDF), elektronická kniha (ePub), a tak dále.
To vše můžete udělat z jedné sady odlehčených textových souborů s řízenou verzí.
Instalace pandoc
Chcete-li nainstalovat pandoc na Ubuntu, použijte tento příkaz:
sudo apt-get install pandoc
Na Fedoře potřebujete následující příkaz:
sudo dnf install pandoc
Na Manjaro musíte zadat:
sudo pacman -Syu pandoc
Verzi, kterou jste nainstalovali, můžete zkontrolovat pomocí možnosti –version:
pandoc --version
Použití pandoc bez souborů
Pokud používáte pandoc bez jakýchkoli voleb příkazového řádku, přijímá také zadaný vstup. Stačí stisknout Ctrl+D, abyste označili, že jste dokončili psaní. pandoc očekává, že budete psát ve formátu Markdown, a vygeneruje HTML výstup.
Podívejme se na příklad:
pandoc
Napsali jsme několik řádků Markdown a chystáme se stisknout Ctrl+D.
Jakmile to uděláme, pandoc vygeneruje ekvivalentní výstup HTML.
Abychom mohli s pandocem dělat cokoli užitečného, musíme skutečně používat soubory.
Základy markdown
Markdown je lehký značkovací jazyk a určitým znakům je přisuzován zvláštní význam. K vytvoření souboru Markdown můžete použít editor prostého textu.
Markdown lze číst snadno, protože zde nejsou žádné vizuálně těžkopádné značky, které by odváděly pozornost od textu. Formátování v dokumentech Markdown se podobá formátování, které představuje. Níže jsou uvedeny některé základní:
Chcete-li text zdůraznit kurzívou, zalomte jej do hvězdiček. *To bude zdůrazněno*
Pro tučný text použijte dvě hvězdičky. **Bude to tučně**
Nadpisy jsou reprezentovány znakem čísla / křížkem (#). Text je od hashe oddělen mezerou. Použijte jeden hash pro nadpis nejvyšší úrovně, dva pro nadpis druhé úrovně a tak dále.
Chcete-li vytvořit seznam s odrážkami, začněte každý řádek seznamu hvězdičkou a před text vložte mezeru.
Chcete-li vytvořit číslovaný seznam, začněte každý řádek číslicí následovanou tečkou a poté vložte před text mezeru.
Chcete-li vytvořit hypertextový odkaz, uzavřete název webu do hranatých závorek ([]) a URL v závorkách [()] jako tak: [Link to How to Geek](https://www.wdzwdz.com/).
Chcete-li vložit obrázek, napište vykřičník těsně před závorky (![]). Do závorek zadejte libovolný alternativní text obrázku. Poté uzavřete cestu k obrázku do závorek [()“]. Zde je příklad: .
Další příklady těchto všech pokryjeme v další části.
Převádění souborů
Převody souborů jsou jednoduché. pandoc obvykle dokáže zjistit, se kterými formáty souborů pracujete, z jejich názvů souborů. Zde vygenerujeme soubor HTML ze souboru Markdown. Volba -o (výstup) říká pandocu název souboru, který chceme vytvořit:
pandoc -o sample.html sample.md
Náš ukázkový soubor Markdown, sample.md, obsahuje krátkou část Markdown zobrazenou na obrázku níže.
Vytvoří se soubor s názvem sample.html. Když na soubor dvakrát klikneme, otevře jej náš výchozí prohlížeč.
Nyní vygenerujeme Otevřete formát dokumentu textový dokument, ve kterém můžeme otevřít LibreOffice Writer:
pandoc -o sample.odt sample.md
Soubor ODT má stejný obsah jako soubor HTML.
Elegantní dotek je alternativní text pro obrázek, který se také používá k automatickému generování titulku k obrázku.
Určení formátů souborů
Volby -f (od) a -t (do) se používají k tomu, aby pandoc řekli, ze kterých formátů souborů a do kterých chcete převést. To může být užitečné, pokud pracujete s formátem souboru, který sdílí příponu souboru s jinými souvisejícími formáty. Například, TeX, a Latex oba používají příponu „.tex“.
Používáme také volbu -s (standalone), takže pandoc vygeneruje veškerou preambuli LaTeXu potřebnou k tomu, aby dokument byl úplný, samostatný a dobře vytvořený dokument LaTeXu. Bez volby -s (samostatný) by výstupem byl stále dobře vytvořený LaTeX, který by mohl být vložen do jiného dokumentu LaTeXu, 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. Pokud máte editor LaTeX, můžete otevřít soubor TEX a zobrazit náhled toho, jak jsou interpretovány sázecí příkazy LaTeXu. Zmenšením okna, aby se vešlo na obrázek níže, vypadal displej stísněně, ale ve skutečnosti to bylo v pořádku.
Použili jsme editor LaTeXu tzv Texmaker. Pokud jej chcete nainstalovat do Ubuntu, zadejte následující:
sudo apt-get install texmaker
Ve Fedoře je příkaz:
sudo dnf install texmaker
V Manjaro použijte:
sudo pacman -Syu texmaker
Převod souborů pomocí šablon
Pravděpodobně začínáte chápat flexibilitu, kterou pandoc poskytuje. Můžete napsat jednou a publikovat téměř v jakémkoli formátu. To je skvělý výkon, ale dokumenty vypadají trochu vanilkově.
Pomocí šablon můžete diktovat, které styly pandoc používá při generování dokumentů. Můžete například říci pandoc, aby používal styly definované v a Kaskádové styly (CSS) s volbou –css.
Vytvořili jsme malý soubor CSS obsahující níže uvedený text. Změní mezery nad a pod záhlavím úrovně o jeden styl. Také změní 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 také použili samostatnou volbu (-s):
pandoc -o sample.html -s --css sample.css sample.md
pandoc používá jediný styl z našeho minimalistického souboru CSS a aplikuje ho na záhlaví první úrovně.
Další možností jemného doladění, kterou máte k dispozici při práci se soubory HTML, je zahrnout značku HTML do souboru Markdown. To bude předáno do vygenerovaného souboru HTML jako standardní značka HTML.
Tato technika by však měla být vyhrazena, když generujete pouze výstup HTML. Pokud pracujete s více formáty souborů, pandoc bude ignorovat označení HTML pro soubory, které nejsou HTML, a bude jim předáno jako text.
Můžeme také určit, které styly se použijí při generování souborů ODT. Otevřete prázdný dokument LibreOffice Writer a upravte styl nadpisu a písma tak, aby vyhovoval vašim potřebám. V našem příkladu jsme také přidali záhlaví a zápatí. Uložte dokument jako „odt-template.odt“.
Nyní to můžeme použít jako šablonu s volbou –reference-doc:
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Porovnejte to s příkladem ODT z dříve. Tento dokument používá jiné písmo, má barevné nadpisy a obsahuje záhlaví a zápatí. Byl však vygenerován z úplně stejného souboru Markdown „sample.md“.
Šablony referenčních dokumentů lze použít k označení různých fází výroby dokumentu. Můžete mít například šablony s vodoznakem „Koncept“ nebo „Ke kontrole“. Pro dokončený dokument by byla použita šablona bez vodoznaku.
Generování PDF
Ve výchozím nastavení pandoc používá ke generování souborů PDF modul LaTeX PDF. Nejjednodušší způsob, jak se ujistit, že máte vyhovující příslušné závislosti LaTeXu, je nainstalovat editor LaTeX, jako je Texmaker.
To je ale docela velká instalace – Tex a LaTeX jsou oba docela statné. Pokud je na vašem pevném disku omezené místo nebo víte, že nikdy nebudete používat TeX nebo LaTeX, můžete raději vygenerovat soubor ODT. Poté jej stačí otevřít v LibreOffice Writer a uložit jako PDF.
Docs-as-Code
Používání Markdown jako jazyka psaní má několik výhod, včetně následujících:
Práce se soubory ve formátu prostého textu je rychlá: Načítají se rychleji než soubory textového editoru podobné velikosti a mají tendenci se dokumentem pohybovat rychleji. Mnoho editorů, včetně gedit , Vim a Emacs, používá zvýraznění syntaxe s textem Markdown.
Budete mít časovou osu všech verzí svých dokumentů: Pokud uložíte dokumentaci do VCS, jako je Git, můžete snadno vidět rozdíly mezi libovolnými dvěma verzemi stejného souboru. To však skutečně funguje pouze tehdy, když jsou soubory prostý text, protože s tím VCS očekává, že bude pracovat.
VCS může zaznamenat, kdo a kdy provedl změny: To je zvláště užitečné, pokud často spolupracujete s ostatními na velkých projektech. Poskytuje také centrální úložiště pro samotné dokumenty. Mnoho cloudových služeb Git, jako je GitHub, GitLab, a BitBucket, mají ve svých cenových modelech bezplatné úrovně.
Své dokumenty můžete generovat v několika formátech: Pomocí několika jednoduchých skriptů shellu můžete převzít styly z CSS a referenčních dokumentů. Pokud ukládáte své dokumenty do úložiště VCS, které se integruje s Průběžná integrace a průběžné nasazování (CI/CD), mohou být generovány automaticky, kdykoli je vytvořen software.
Závěrečné myšlenky
Uvnitř je mnohem více možností a funkcí pandoc než to, co jsme probrali zde. Procesy převodu pro většinu typů souborů lze vyladit a doladit. Chcete-li se dozvědět více, podívejte se na vynikající příklady na oficiálním (a extrémně podrobném) webová stránka pandoc.