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ů.

Přejít: navigace | na začátek stránky | na konec stránky

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

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.

Přejít: navigace | na začátek stránky | na konec stránky

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.

Přejít: navigace | na začátek stránky | na konec stránky

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í.

Přejít: navigace | na začátek stránky | na konec stránky

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


Přejít: navigace | na začátek stránky | na konec stránky

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ů.

Přejít: navigace | na začátek stránky | na konec stránky

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ů.

Přejít: navigace | na začátek stránky | na konec stránky

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).

Přejít: navigace | na začátek stránky | na konec stránky

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).

Přejít: navigace | na začátek stránky | na konec stránky

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.

Přejít: navigace | na začátek stránky | na konec stránky

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ě.

Přejít: navigace | na začátek stránky | na konec stránky

Průběžná integrace na GitLabu FI

Další způsob automatizace se nazývá průběžná integrace (anglicky continuous integration nebo krátce CI) a pojí se s programy pro správu verzí jako Git, které jsme si představili v dřívějším cvičení.

Při práci s Gitem často používáme webové služby jako GitLab FI a GitHub pro zálohu lokálních repozitářů a pro spolupráci s dalšími lidmi. Průběžná integrace nám umožňuje tyto služby nastavit tak, aby se při každé změně obsahu repozitáře automaticky spustil výpočetní uzel, který obsah stáhne, vykoná nad ním zadané příkazy a zpřístupní vytvořené soubory.

Ukážeme si, jak můžeme pomocí průběžné integrace automatizovat přípravu TeXových dokumentů na GitLabu FI.

1. Stáhněte si repozitář s pohádkou o Bílé paní Vrbenské, který jsme si vytvořili na cvičení o správě verzí: $ git clone https://gitlab.fi.muni.cz/xnovot32/PB029_sprava_verzi.git xnovot32_PB029_sprava_verzi
Cloning into "xnovot32_PB029_sprava_verzi"...
remote: Counting objects: 6, done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 6 (delta 1), reused 0 (delta 0)
Receiving objects: 100% (6/6), done.
Resolving deltas: 100% (1/1), done.
Checking connectivity... done.


   Tip: Části vyznačené kurzívou nahraďte svými údaji.

   Pokud repozitář vytvořený nemáte, splňte alespoň kroky 1–5 ze cvičení o správě verzí a poté pokračujte dalšími kroky zde.
2. Stáhněte si soubor s konfigurací průběžné integrace a uložte jej do kořenového adresáře vaší pracovní kopie: $ cd xnovot32_PB029_sprava_verzi
$ wget https://sojka.pages.fi.muni.cz/PB029_web/practices/automatizace-sazby/files/.gitlab-ci.yml
--2024-10-15 15:33:14-- https://sojka.pages.fi.muni.cz/PB029_web/practices/automatizace-sazby/files/.gitlab-ci.yml
Ukládám do: „.gitlab-ci.yml“

dokument.tex 100%[===================>] 1,09K --.-KB/s in 0s

2024-10-15 15:33:14 (18,3 MB/s) – „.gitlab-ci.yml“ uloženo [607/607]
Soubor si otevřete v textovém editoru a prohlédněte: $ cat .gitlab-ci.yml
vysazej-dokument:
 image: texlive/texlive:latest  # Následující kód spouštěj uvnitř dockerového obrazu
                                # „texlive/texlive“ s instalací TeXu.
 tags:
 - shared-fi  # Použij výpočetní uzly poskytované Fakultou informatiky. Namísto nich
              # bychom mohli využít také vlastní server.
 script:
 - xelatex dokument.tex  # Přelož soubor „dokument.tex“ pomocí TeXového stroje XeTeX
                         # s formátem LaTeX.
 artifacts:
   paths:
   - dokument.pdf  # Ulož a zpřístupni vytvořený soubor „dokument.pdf“.

3. Následně dokument přidejte do seznamu souborů spravovaných systémem Git a vložte jako další revizi do svého lokálního repozitáře: $ git add .gitlab-ci.yml
$ git commit --message "Vložen konfigurační soubor průběžné integrace."
[main 19e34ce] Vložen konfigurační soubor průběžné integrace.
 1 file changed, 9 insertions(+)
 create mode 100644 .gitlab-ci.yml
Následně své změny odešlete do vašeho repozitáře na fakultním serveru: $ git push
Counting objects: 3, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 981 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://gitlab.fi.muni.cz/xnovot32/PB029_sprava_verzi.git
   18f0fe6..19e34ce  main -> main

4. Stav překladu dokumentu můžete sledovat na adrese https://gitlab.fi.muni.cz/xnovot32/PB029_sprava_verzi/-/jobs.
5. Po úspěšném překladu si můžete vytvořené soubory prohlédnout a stáhnout na perzistentní adrese https://gitlab.fi.muni.cz/xnovot32/PB029_sprava_verzi/-/jobs/artifacts/main/browse?job=vysazej-dokument.

Přejít: navigace | na začátek stránky | na konec stránky

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.
• Použijte průběžnou integraci pro spuštění vybraného automatizačního nástroje a pro zpřístupnění vyvořených souborů PDF.

Přejít: navigace | na začátek stránky | na konec stránky

Navigace:

• PB029
  • Program make a soubor Makefile
    • Praktické úkoly k procvičení
  • Program arara
    • Základní použití
    • Konfigurace pravidel
  • Program latexmk
    • Základní použití
    • Průběžná kompilace
    • Konfigurace používaných nástrojů
    • Praktické úkoly k procvičení
  • Průběžná integrace na GitLabu FI
  • Praktické úkoly k procvičení