# PB029: Automatizace sazby dokumentu

Vývoj dokumentů v TeXu se v mnoha ohledech podobá vývoji programů. Proces překladu dokumentu se může skládat z několika kroků, jejichž provádění je vhodné automatizovat. Pro automatizaci překladu tedy můžeme použít obdobné prostředky jako pro řízení překladu programů.

## Program `make` a soubor `Makefile`

Jedním z klasických řešení automatizace procesů je použití programu `make`. Jeho použití pro automatizaci překladu dokumentů je podobné jako pro překlad větších softwarových projektů. Pokud jste se s programem ještě nesetkali, přečtěte si článek Ať maká make.

`make` pracuje podle speciálního předpisu – vizte komentovaný příklad `Makefile`.

Ukázkový `Makefile` předpokládá existenci souboru `dokument.tex` a slouží k jeho překladu do formátů PDF, DVI a PostScript. Soubor `dokument.tex` vytvoříme zkopírováním ukázkového LaTeXového dokumentu `sample2e.tex`. `cp -vi $(kpsewhich sample2e.tex) dokument.tex` V `Makefile` jsou definovány cíle, kterých chcete dosáhnout (soubor v PDF, soubor v DVI, vymazání dat apod.) a jejich závislosti.

Např. dokument v PostScript je generován transformací PDF dokumentu, který vzniká překladem `dokument.tex`. Jelikož je postup zaznamenám v `Makefile`, uživateli stačí specifikovat žádaný cíl a o zbytek se postará program `make`: `make ps`

Pokud se `make` zavolá bez parametrů, použije se tzv. implicitní cíl, tj. cíl, který je v `Makefile` uveden na prvním místě. V našem ukázkovém `Makefile` to je „falešný“ cíl `all`, který má definovánu závislost na cílech `dvi`, `pdf` a `ps`. Efektivně tedy doje k vytvoření všech výstupních formátů: `make`

Tip: Povšimněte si, že překlad probíhá efektivně – znovu vytvořeny jsou pouze výstupy, které dosud neexistují, a kterým se zároveň nezměnily zdrojové podklady, tj. nejsou zastaralé.

Vyzkoušejte opakovaně volat příkaz: `make` Následně simulujte změnu zdrojového dokumentu a opakujte volání `make`: `touch dokument.tex # Jen aktualizuje čas modifikace souboru
make`

V rámci `Makefile` máme definován také cíl `clean`, který zajistí odstranění všech vygenerovaných výstupních dokumentů a ponechá pouze čisté zdrojové soubory, které jsou minimem nutným k novému vygenerování všech výstupů: `make clean` Takto vyčištěný projekt je vhodný k archivaci, respektive odeslání do systému pro správu verzí, kde typicky chceme ukládat jen čisté zdrojové soubory, nikoliv z nich vygenerovatelné výstupy.

Tip: `make` řízený `Makefile` je obecný nástroj. I když jsme ho zde použili pro řízení překladu TeXových dokumentů, dá se stejně dobře použít pro automatizaci libovolného jiného procesu, který jsme schopni popsat v `Makefile`.

### Praktické úkoly k procvičení

- Vytvořte Makefile automatické spuštění programu `vlna`.
- Vytvořte Makefile pro řízení sazby dokumentu s bibliografií.
- Vytvořte Makefile pro řízení sazby dokumentu s rejstříkem.
- Vytvořte Makefile pro řízení překladu svého prvního zápočtového dokumentu.

## Program `arara`

Jednou z nevýhod programu `make` je skutečnost, že vyžaduje distribuci dodatečného souboru `Makefile` spolu s dokumentem. Pokud soubor `Makefile` ztratíme, neumíme dokument přeložit. Další z nevýhod je, že program `make` není součástí standardních TeXových distribucí, což přináší problémy s přenositelností.

### Základní použití

Program `arara` čte pravidla pro překlad dokumentu přímo z dokumentu samotného, čímž se řeší problém jejich distribuce. Uživatel zadává pravidla formou komentářů, jak ilustruje rozšířený dokument ze cvičení o sazbě bibliografie:

     1 % arara: pdflatex
     2 % arara: biber
     3 % arara: pdflatex
     4
     5 % Začátek preambule.
     6 \documentclass{article}
     7 \usepackage[resetfonts]{cmap}
     8 \usepackage{lmodern}
     9 \usepackage[czech]{babel}
    10 \usepackage[latin2]{inputenc}
    11 \usepackage[T1]{fontenc}
    12 …

Uživatel následně provede překlad příkazem `arara` následovně: `arara arara-s-biblatexem.tex`

Při překladu obdržíme následující výstup: `__ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
Processing 'arara-s-biblatexem.tex' (size: 2 KB, last modified:
11/04/2018 21:23:50), please wait.
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS
(Biber) The Biber reference management software ......... SUCCESS
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS
Total: 5.60 seconds
`

Tip: Program `arara` je psaný v programovacím jazyce Java. Pokud pracujete na vlastním počítači, musíte si před spuštěním programu `arara` nainstalovat interpret Javy, např. z balíčku `default-jre` pro Debian a Ubuntu Linux nebo z webu firmy Microsoft pro operační systém Windows.

### Konfigurace pravidel

Platí, že názvy pravidel, např. `pdflatex`, neodpovídají přímo příkazům, ale pojmenovávají soubor s definicemi, např. `pdflatex.yaml`. Nevýhoda oproti Makefile tedy spočívá v nutnosti připravit soubor definic pro jednotlivá pravidla. Výhoda použití pravidel spočívá ve větší míře odstínění od samotných spouštěných příkazů.

## Program `latexmk`

Do souboru `Makefile` a pravidel programu `arara` zadáváme konstantní počet běhů TeXového kompilátoru. Pokud toto číslo nadhodnotíme, budou se naše dokumenty překládat neúměrně dlouho a pokud naopak zadáme nedostatečný počet, mohou nám části dokumentu chybět a křížové reference uvádět chybná čísla stránek. Při následujících překladech již také existují pomocné soubory a pro opětovné vysázení dokumentu nám tedy mnohdy stačí pouze jeden běh TeXového kompilátoru.

Program `latexmk` sleduje výstup TeXového kompilátoru při použití formátu LaTeXu a zaznamenává vznik/změny pomocných souborů. Díky tomu je schopen automaticky provést korektní počet překladů pro vyřešení křížových referencí a automaticky spustit externí nástroje, jako je `biber` nebo `makeindex`, pokud detekuje vznik příslušných pomocných souborů.

### Základní použití

Schopnosti programu si můžeme demonstrovat na jednoduchém LaTeXovém dokumentu, který obsahuje křížovou referenci. Při překladu kompilátorem pdfLaTeXu potřebujeme dva překlady k tomu, aby se reference správně vyhodnotila: `pdflatex krizova-reference.tex
pdflatex krizova-reference.tex` Při použití nástroje `latexmk` nám k překladu stačí jediný příkaz: `latexmk -pdf krizova-reference.tex`

Vidíme, že nástroj správně provedl dva překlady a ukončil se. Kromě běžných pomocných souborů nám vznikly i soubory s koncovkou `.fls` a `.fdb_latexmk`, ve kterých si `latexmk` udržuje informace o souborech, na kterých je překládaný dokument závislý. Pokud tedy příkaz zopakujeme, obdržíme informaci o tom, že vysázený dokument je aktuální a není třeba provádět překlad.

Pokud chceme odstranit pomocné soubory, můžeme použít příkaz `latexmk -c` Pro odstranění pomocných souborů i výstupních dokumentů pak slouží příkaz `latexmk -C` Další užitečné volby nalezneme v uživatelském manuálu (viz `man latexmk`).

### Průběžná kompilace

Velice příjemnou schopností programu `latexmk` je průběžná kompilace. Pokud překlad spustíme s volbou `-pvc`, `latexmk` náš dokument vysází, otevře výstupní dokument v prohlížeči a při jakýchkoliv změnách ve vstupních souborech náš výstupní dokument přesází: `latexmk -pvc -pdf rejstrik.tex`

Takto můžeme na svých dokumentech pracovat interaktivně způsobem, jaký známe z online služeb Overleaf. Ve skutečnosti tyto služby interně využívají právě `latexmk` a úpravami konfiguračního souboru `latexmkrc` lze mnohdy dosáhnout chování, které je jinak přes uživatelské rozhraní těchto služeb nedostupné, vizte např. ukázku využití programu `vlna` na službě Overleaf.

Pro prohlížení PDF dokumentů `latexmk` implicitně používá příkaz `acroread`. Pokud na svém systému používáme jiný prohlížeč PDF dokumentů (např. Evince), upozorníme na tuto skutečnost `latexmk` zanesením následujícího textu do všeobecného konfiguračního souboru `.latexmkrc` ve svém uživatelském domovském adresáři, nebo opět do konfiguračního souboru `latexmkrc` v adresáři s dokumentem: `$pdf_previewer = "start evince %O %S";` Na systému Windows jsou otevřené soubory standardně zamykány, kvůli čemuž `latexmk` není schopný prohlížený dokument přesázet. Řešením je použít prohlížeč dokumentů, který soubory nezamyká (např. Sumatra PDF).

### Konfigurace používaných nástrojů

Některé z nástrojů, se kterými jsme během semestru pracovali, nejsou standardní a `latexmk` je nezná. Jedná se např. o program `texindy`, kterým jsme zpracovávali rejstříky; `latexmk` namísto tohoto programu použije standardní `makeindex`, který však není schopný správně řadit češtinu: `latexmk -pdf rejstrik.tex`

Musíme tedy programu `latexmk` o `texindy` říci. Pokud ve složce s překládaným dokumentem vytvoříme konfigurační soubor `latexmkrc` s následujícím obsahem (pro slovenštinu nahraďte `czech` za `slovak-large`): `$makeindex = "texindy %O -I latex --language czech --codepage utf8 -o %D %S";` a překlad opakujeme: `latexmk -C
latexmk -pdf rejstrik.tex` obdržíme již správný výstup. Vizte také ukázku na službě Overleaf.

Informace o parametrech, které lze zadávat do konfiguračního souboru nalezeme v uživatelském manuálu pod sekcí „Configuration/initialization (rc) files“. Autor programu rovněž zveřejnil sadu ukázkových konfigurací, ze kterých můžeme vyjít.

### Praktické úkoly k procvičení

- Prostudujte si v uživatelském manuálu sekci „Using `latexmk` with `make`“ a rozšiřte svůj Makefile tak, aby pro sazbu dokumentu používal program `latexmk`.
- V uživatelském manuálu zjistěte, jakým způsobem lze program `latexmk` požádat, aby namísto pdfTeXu používal kompilátory XeTeXu a LuaTeXu. Svá zjištění experimentálně ověřte na dokumentech ze cvičení o české sazbě.

## Praktické úkoly k procvičení

- Použijte některý automatizační nástroj (`make`, `latexmk`, `arara`, ...) ve svém prvním zápočtovém dokumentu.