Kompletní průvodce pro použití AsciiDoc v Linuxu

Stručně:Tento podrobný průvodce pojednává o výhodách používání AsciiDoc a ukazuje vám, jak nainstalovat a používat AsciiDoc v Linuxu.

V průběhu let jsem používal mnoho různých nástrojů k psaní článků, zpráv nebo dokumentace. Myslím, že všechno pro mě začalo s Epistole Luca Bartheleta na Apple IIc od francouzského editoru Version Soft. Poté jsem přešel na nástroje GUI s vynikajícím Microsoft Word 5 pro Apple Macintosh, poté na méně přesvědčivý (pro mě) StarOffice na Sparc Solaris, který byl již známý jako OpenOffice, když jsem definitivně přešel na Linux. Všechny tyto nástroje byly skutečně textové procesory.

Ale redaktoři WYSIWYG mě nikdy příliš nepřesvědčili. Zkoumal jsem tedy mnoho různých více či méně čitelných textových formátů:troff, HTML, RTF, TeX/LaTeX, XML a nakonec AsciiDoc, což je nástroj, který dnes používám nejvíce. Ve skutečnosti ho právě teď používám k psaní tohoto článku!

Pokud jsem se do té historie zapsal, bylo to proto, že smyčka je nějak uzavřená. Epistole byl textový procesor éry textové konzole. Pokud si pamatuji, byly tam nabídky a k výběru textu můžete použít myš – ale většina formátování byla provedena přidáním nevtíravých značek do textu. Stejně jako se to dělá s AsciiDoc. Samozřejmě to nebyl první software, který to dokázal. Ale bylo to první, co jsem použil!

Proč AsciiDoc (nebo jakýkoli jiný formát textového souboru)?

V používání textových formátů pro psaní vidím dvě výhody:za prvé, je zde jasné oddělení obsahu a prezentace. Tento argument je otevřený k diskusi, protože některé textové formáty jako TeX nebo HTML vyžadují dobrou disciplínu, aby dodržely toto oddělení. A na druhou stranu můžete nějakým způsobem dosáhnout určité úrovně oddělení pomocí šablon a stylů s WYSIWYG editory. S tím souhlasím. Ale stále mi připadají problémy s prezentací rušivé s nástroji GUI. Zatímco při použití textových formátů se můžete soustředit pouze na obsah, aniž by vás při psaní rušil jakýkoli styl písma nebo vdova. Ale možná jsem to jen já? Nemohu však spočítat, kolikrát jsem přestal psát, jen abych vyřešil nějaký menší problém se stylem – a když jsem se k textu vrátil, ztratil jsem inspiraci. Pokud nesouhlasíte nebo máte jinou zkušenost, neváhejte mi odporovat pomocí sekce komentářů níže!

Každopádně můj druhý argument bude méně podléhat osobnímu výkladu:dokumenty založené na textových formátech jsou vysoce interoperabilní . Nejen, že je můžete upravovat pomocí libovolného textového editoru na jakékoli platformě, ale můžete snadno spravovat revize textu pomocí nástroje, jako je git nebo SVN, nebo automatizovat úpravy textu pomocí běžných nástrojů, jako je sed, AWK, Perl a tak dále. Abych vám uvedl konkrétní příklad, při použití textového formátu, jako je AsciiDoc, potřebuji pouze jeden příkaz k vytvoření vysoce personalizované pošty z hlavního dokumentu, zatímco stejná úloha pomocí editoru WYSIWYG by vyžadovala chytré použití „polí“ a projít několika obrazovkami průvodce.

Co je AsciiDoc?

Přesně řečeno, AsciiDoc je formát souboru. Definuje syntaktické konstrukce, které pomohou procesoru pochopit sémantiku různých částí vašeho textu. Obvykle za účelem vytvoření pěkně formátovaného výstupu.

I když se tato definice může zdát abstraktní, je to něco jednoduchého:některá klíčová slova nebo znaky ve vašem dokumentu mají zvláštní význam, který změní vykreslování dokumentu. Toto je přesně stejný koncept jako značky v HTML. Ale klíčový rozdíl oproti AsciiDoc je vlastnost zdrojového dokumentu, aby zůstal snadno čitelné pro člověka.

Podívejte se do našeho úložiště GitHub a porovnejte, jak lze vytvořit stejný výstup pomocí několika běžných formátů textových souborů:(nápad na stránku s příručkou kávy s laskavým svolením http://www.linuxjournal.com/article/1158)

• coffee.man používá úctyhodný toff procesor (založený na programu RUNOFF z roku 1964). Dnes se většinou používá k psaní manuálových stránek. Můžete to zkusit po stažení coffee.* soubory zadáním man ./coffee.man na příkazovém řádku.
• coffee.tex používá LaTeX syntaxe (1985) k dosažení většinou stejného výsledku, ale pro výstup PDF. LaTeX je sázecí program zvláště vhodný pro vědecké publikace díky své schopnosti pěkně formátovat matematické vzorce a tabulky. PDF můžete vytvořit ze zdroje LaTeX pomocí pdflatex coffee.tex
• coffee.html používá k popisu stránky formát HTML (1991). Tento soubor můžete přímo otevřít ve svém oblíbeném webovém prohlížeči a zobrazit výsledek.
• coffee.adoc , konečně používá syntaxi AsciiDoc (2002). Z tohoto souboru můžete vytvořit HTML i PDF:

asciidoc coffee.adoc                   # HTML output
a2x --format pdf ./coffee.adoc         # PDF output (dblatex)
a2x --fop --format pdf ./coffee.adoc   # PDF output (Apache FOP)

Nyní jste viděli výsledek, otevřete tyto čtyři soubory pomocí svého oblíbeného textového editoru (nano, vim, SublimeText, gedit, Atom, …) a porovnejte zdroje:existuje velká šance, že budete souhlasit, že zdroje AsciiDoc jsou snáze čitelné — a pravděpodobně také psát.

Jak nainstalovat AsciiDoc v Linuxu?

Instalace AsciiDoc je poměrně složitá kvůli mnoha závislostem. Myslím komplexní, pokud to chcete nainstalovat ze zdrojů. Pro většinu z nás je pravděpodobně nejlepším způsobem použití našeho správce balíčků:

apt-get install asciidoc fop

nebo následující příkaz:

yum install acsiidoc fop

(fop je vyžadován pouze v případě, že potřebujete backend Apache FOP pro generování PDF – toto je backend PDF, který sám používám)

Více podrobností o instalaci naleznete na oficiálních stránkách AsciiDoc. Nyní potřebujete jen trochu trpělivosti, protože alespoň na mém minimálním systému Debian instalace AsciiDoc vyžaduje stažení 360 MB (většinou kvůli závislosti na LaTeXu). Což vám v závislosti na šířce vašeho internetového pásma může poskytnout dostatek času na přečtení zbytku tohoto článku.

Výukový program AsciiDoc:Jak psát v AsciiDoc?

Řekl jsem to několikrát, AsciiDoc je člověkem čitelný formát textového souboru . Své dokumenty tedy můžete psát pomocí textového editoru dle vašeho výběru. Existují dokonce i speciální textové editory. Ale nebudu o nich zde mluvit – jednoduše proto, že je nepoužívám. Pokud však některý z nich používáte, neváhejte se podělit o svůj názor pomocí sekce komentářů na konci tohoto článku.

Nemám v úmyslu zde vytvářet další výukový program syntaxe AsciiDoc:na webu jich je již k dispozici spousta. Zmíním se tedy pouze o zcela základních syntaktických konstrukcích, které využijete prakticky v jakémkoli dokumentu. Z výše uvedeného jednoduchého příkladu příkazu „káva“ můžete vidět:

• názvy v AsciiDoc jsou identifikovány tak, že jsou pod nimi === nebo --- (v závislosti na úrovni názvu),
• tučné rozsahy znaků se zapisují mezi začátek
• a kurzíva mezi podtržítky.

To jsou docela běžné konvence, které pravděpodobně pocházejí z e-mailové éry před HTML. Kromě toho možná budete potřebovat dva další běžné konstrukty, které nejsou znázorněny v mém předchozím příkladu:hypertextové odkazy a obrázky inclusion, jehož syntaxe je docela samovysvětlující.

// HyperText links
link:http://dashing-kazoo.flywheelsites.com[ItsFOSS Linux Blog]

// Inline Images
image:https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

// Block Images
image::https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

Ale syntaxe AsciiDoc je mnohem bohatší. Pokud chcete více, mohu vás odkázat na ten pěkný cheatsheet AsciiDoc:http://powerman.name/doc/asciidoc

Jak vykreslit konečný výstup?

Předpokládám, že zde jste již napsali nějaký text ve formátu AsciiDoc. Pokud tomu tak není, můžete si zde stáhnout některé ukázkové soubory zkopírované přímo z dokumentace AsciiDoc:

# Download the AsciiDoc User Guide source document
BASE='https://raw.githubusercontent.com/itsfoss/asciidoc-intro/master'
wget "${BASE}"/{asciidoc.txt,customers.csv}

Protože AsciiDoc je čitelný pro lidi , můžete poslat zdrojový text AsciiDoc přímo někomu e-mailem a příjemce si bude moci tuto zprávu přečíst bez dalšího otálení. Možná však budete chtít poskytnout nějaký lépe formátovaný výstup. Například jako HTML pro webovou publikaci (stejně jako jsem to udělal pro tento článek). Nebo jako PDF pro tisk nebo zobrazení.

Ve všech případech potřebujete procesor . Ve skutečnosti pod kapotou budete potřebovat několik procesorů. Protože váš dokument AsciiDoc bude před vytvořením konečného výstupu transformován do různých přechodných formátů. Protože se používá několik nástrojů, přičemž výstup jednoho je vstupem dalšího, mluvíme někdy o nástrojovém řetězci .

I když zde vysvětlím některé vnitřní pracovní detaily, musíte pochopit, že většina z toho vám bude skryta. Ledaže byste museli zpočátku instalovat nástroje – nebo pokud chcete doladit některé kroky procesu.

V praxi?

Pro výstup HTML potřebujete pouze asciidoc nářadí. Pro složitější toolchainy vám doporučuji použít a2x nástroj (součást distribuce AsciiDoc), který spustí potřebné procesory v pořadí:

# All examples are based on the AsciiDoc User Guide source document

# HTML output
asciidoc asciidoc.txt
firefox asciidoc.html

# XHTML output
a2x --format=xhtml asciidoc.txt

# PDF output (LaTeX processor)
a2x --format=pdf asciidoc.txt

# PDF output (FOP processor)
a2x --fop --format=pdf asciidoc.txt

I když může přímo vytvářet výstup HTML, základní funkce asciidoc zůstává nástrojem k transformaci dokumentu AsciiDoc do přechodného formátu DocBook. DocBook je formát založený na XML běžně používaný pro (mimo jiné) publikování technické dokumentace. DocBook je sémantický formát. To znamená, že popisuje obsah vašeho dokumentu. Ale ne jeho prezentace. Formátování tedy bude dalším krokem transformace. Za tímto účelem, bez ohledu na výstupní formát, je přechodný dokument DocBook zpracován pomocí procesoru XSLT, aby vytvořil buď přímo výstup (např. XHTML), nebo jiný přechodný formát.

To je případ, kdy generujete dokument PDF, kde bude dokument DocBook (dle vaší vůle) převeden buď jako střední reprezentace LaTeXu, nebo jako XSL-FO (jazyk založený na XML pro popis stránky). Nakonec speciální nástroj převede tuto reprezentaci do PDF.

Další kroky pro generování PDF jsou odůvodněny zejména skutečností, že nástrojová řada musí zvládnout stránkování pro výstup PDF. Něco, co není nutné pro formát „streamu“, jako je HTML.

dblatex nebo fop?

Protože existují dva backendy PDF, obvyklá otázka zní „Který je nejlepší?“ Něco, na co vám nemohu odpovědět.

Oba procesory mají svá pro a proti. A nakonec bude volba kompromisem mezi vašimi potřebami a vaším vkusem. Doporučuji vám tedy, abyste si udělali čas na vyzkoušení obou, než si vyberete backend, který budete používat. Pokud se budete řídit cestou LaTeX, dblatex bude backend použitý k vytvoření PDF. Pokud dáváte přednost použití meziformátu XSL-FO, bude to Apache FOP. Nezapomeňte se tedy podívat na dokumentaci těchto nástrojů, abyste viděli, jak snadné bude přizpůsobit výstup vašim potřebám. Pokud samozřejmě nejste spokojeni s výchozím výstupem!

Jak přizpůsobit výstup AsciiDoc?

AsciiDoc do HTML

Po vybalení AsciiDoc vytváří docela pěkné dokumenty. Ale dříve nebo později přijdete na to, čemu přizpůsobit jejich vzhled.

Přesné změny budou záviset na backendu, který používáte. U výstupu HTML lze většinu změn provést změnou šablony stylů CSS přidružené k dokumentu.

Řekněme, že chci zobrazit všechny nadpisy sekcí červeně, mohl bych vytvořit následující custom.css soubor:

h2 {
    color: red;
}

A zpracujte dokument pomocí mírně upraveného příkazu:

# Set the 'stylesheet' attribute to
# the absolute path to our custom CSS file
asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt

Můžete také provádět změny na jemnější úrovni připojením role atribut k prvku. Tím se převede do třídy atribut ve vygenerovaném HTML.

Zkuste například upravit náš testovací dokument tak, aby do prvního odstavce textu přidal atribut role:

[role="summary"]
AsciiDoc is a text document format ....

Poté přidejte následující pravidlo do custom.css soubor:

.summary {
    font-style: italic;
}

Znovu vygenerujte dokument:

asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt

1. et voila:první odstavec je nyní zobrazen kurzívou. S trochou kreativity, trochou trpělivosti a několika CSS tutoriály byste měli být schopni upravit svůj dokument podle své vůle.

AsciiDoc do PDF

Přizpůsobení výstupu PDF je poněkud složitější. Ne z pohledu autora, protože zdrojový text zůstane stejný. Nakonec pomocí stejného atributu role jako výše k identifikaci částí, které vyžadují speciální ošetření.

Ale již nemůžete používat CSS k definování formátování pro výstup PDF. Pro nejběžnější nastavení existují parametry, které můžete nastavit z příkazového řádku. Některé parametry lze použít jak s dblatexem a fop backendy, ostatní jsou specifické pro každý backend.

Seznam parametrů podporovaných dblatexem naleznete na adrese http://dblatex.sourceforge.net/doc/manual/sec-params.html

Seznam parametrů DocBook XSL naleznete na http://docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html

Vzhledem k tomu, že úprava marže je poměrně častým požadavkem, můžete se také podívat na toto:http://docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

Pokud jsou názvy parametrů mezi dvěma backendy do jisté míry konzistentní, argumenty příkazového řádku použité k předání těchto hodnot do backendů se mezi dblatex liší. a fop . Takže nejprve dvakrát zkontrolujte svou syntaxi, pokud to zjevně nefunguje. Ale abych byl upřímný, při psaní tohoto článku se mi nepodařilo vytvořit body.font.family parametr pracovat s dblatex backend. Protože obvykle používám fop , možná mi něco uniklo? Pokud o tom máte více indicií, velmi rád si přečtu vaše návrhy v sekci komentářů na konci tohoto článku!

Za zmínku stojí použití nestandardních písem – dokonce i s fop – vyžadují nějakou práci navíc. Ale je to docela dobře zdokumentováno na webu Apache:https://xmlgraphics.apache.org/fop/trunk/fonts.html#bulk

# XSL-FO/FOP
a2x -v --format pdf \
    --fop \
    --xsltproc-opts='--stringparam page.margin.inner 10cm' \
    --xsltproc-opts='--stringparam body.font.family Helvetica' \
    --xsltproc-opts='--stringparam body.font.size 8pt' \
    asciidoc.txt

# dblatex
# (body.font.family _should_ work, but, apparently, it isn't ?!?)
a2x -v --format pdf \
    --dblatex-opts='--param page.margin.inner=10cm' \
    --dblatex-opts='--stringparam body.font.family Helvetica' \
    asciidoc.txt

Jemné nastavení pro generování PDF

Globální parametry jsou příjemné, pokud potřebujete pouze upravit některá předdefinovaná nastavení. Pokud však chcete dokument doladit (nebo úplně změnit rozvržení), budete potřebovat nějaké další úsilí.

Jádrem zpracování DocBooku je XSLT. XSLT je počítačový jazyk, vyjádřený v zápisu XML, který umožňuje zapsat libovolnou transformaci z dokumentu XML na … něco jiného. XML nebo ne.

Například budete muset rozšířit nebo upravit šablonu stylů DocBook XSL, abyste vytvořili kód XSL-FO pro nové styly, které budete chtít. A pokud používáte dblatex backend, může to vyžadovat úpravu odpovídající šablony stylů DocBook-to-LaTeX XSLT. V tom druhém případě možná budete muset použít vlastní balíček LaTeXu. Ale na to se od dblatexu nezaměřím není backend, který sám používám. Mohu vás pouze odkázat na oficiální dokumentaci, pokud chcete vědět více. Ale ještě jednou, pokud to znáte, podělte se o své tipy a triky v sekci komentářů!

I když se soustředíte pouze na fop , opravdu zde nemám prostor pro podrobný popis celého postupu. Ukážu vám tedy změny, které byste mohli použít k získání podobného výsledku, jaký byl získán s několika řádky CSS ve výstupu HTML výše. To znamená:názvy sekcí červeně a souhrn odstavec kurzívou.

Trik, který zde používám, je vytvořit novou šablonu stylů XSLT, importovat původní šablonu stylů DocBook, ale přepsat sady atributů nebo šablonu pro prvky, které chceme změnit:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:exsl="http://exslt.org/common" exclude-result-prefixes="exsl"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<!-- Import the default DocBook stylesheet for XSL-FO -->
<xsl:import href="/etc/asciidoc/docbook-xsl/fo.xsl" />

<!--
    DocBook XSL defines many attribute sets you can
    use to control the output elements
-->
<xsl:attribute-set name="section.title.level1.properties">
    <xsl:attribute name="color">#FF0000</xsl:attribute>
</xsl:attribute-set>

<!--
    For fine-grained changes, you will need to write
    or override XSLT templates just like I did it below
    for 'summary' simpara (paragraphs)
-->
<xsl:template match="simpara[@role='summary']">
  <!-- Capture inherited result -->
  <xsl:variable name="baseresult">
    <xsl:apply-imports/>
  </xsl:variable>

  <!-- Customize the result -->
  <xsl:for-each select="exsl:node-set($baseresult)/node()">
    <xsl:copy>
      <xsl:copy-of select="@*"/>
      <xsl:attribute name="font-style">italic</xsl:attribute>
      <xsl:copy-of select="node()"/>
    </xsl:copy>
  </xsl:for-each>
</xsl:template>


</xsl:stylesheet>

Poté musíte požádat o a2x k použití této vlastní šablony stylů XSL k vytvoření výstupu namísto výchozího pomocí --xsl-file možnost:

a2x -v --format pdf \
    --fop \
    --xsl-file=./custom.xsl \
    asciidoc.txt

S trochou znalosti XSLT, zde uvedených rad a několika dotazů ve vašem oblíbeném vyhledávači si myslím, že byste měli být schopni začít přizpůsobovat výstup XSL-FO.

Nebudu však lhát, některé zdánlivě jednoduché změny ve výstupu dokumentu mohou vyžadovat, abyste strávili dost času prohledáváním příruček DocBook XML a XSL-FO, zkoumáním zdrojů stylů a prováděním několika testů, než konečně dosáhnete toho, co chcete. .

Můj názor

Psaní dokumentů pomocí textového formátu má obrovské výhody. A pokud potřebujete publikovat do HTML, není moc důvodů ne pomocí AsciiDoc. Syntaxe je čistá a úhledná, zpracování je jednoduché a změna prezentace v případě potřeby většinou vyžaduje snadné získání dovedností CSS.

A i když nepoužíváte výstup HTML přímo, HTML lze dnes použít jako výměnný formát s mnoha aplikacemi WYSIWYG. Jako příklad jsem udělal toto:Zkopíroval jsem HTML výstup tohoto článku do oblasti edice WordPress, čímž jsem zachoval veškeré formátování, aniž bych musel cokoliv zadávat přímo do WordPressu.

Pokud potřebujete publikovat do PDF – výhody zůstávají pro autora stejné. Věci budou jistě drsnější, pokud budete potřebovat změnit výchozí rozložení do hloubky. V podnikovém prostředí to pravděpodobně znamená najmout si dokument navržený s dovednostmi XSLT k vytvoření sady stylů, které budou vyhovovat vašim požadavkům na značku nebo technickým požadavkům – nebo aby tyto dovednosti získal někdo v týmu. Ale jakmile to uděláte, bude potěšením psát text s AsciiDoc. A vidět, jak se tyto spisy automaticky převádějí na krásné stránky HTML nebo dokumenty PDF!

A konečně, pokud vám AsciiDoc připadá příliš zjednodušený nebo příliš složitý, můžete se podívat na některé další formáty souborů s podobnými cíli:Markdown, Textile, reStructuredText nebo AsciiDoctor, abychom jmenovali alespoň některé. I když je založen na konceptech pocházejících z počátků výpočetní techniky, ekosystém textového formátu čitelného člověkem je poměrně bohatý. Pravděpodobně bohatší to bylo teprve před 20 lety. Důkazem toho je, že na nich je založeno mnoho moderních generátorů statických webových stránek. To je bohužel mimo rámec tohoto článku. Pokud o tom chcete slyšet více, dejte nám vědět!