arara und externe LaTeX-/PDF-Dokumente erzeugen und einbinden

Für eine grö­ße­re Arbeit soll­ten ins­ge­samt drei exter­ne PDF-Doku­men­te (dok-ext-01 usw.) in eine Haupt­da­tei (main.tex) so ein­ge­bun­den wer­den, dass jedes der der exter­nen Doku­men­te mit eige­nem Titel­blatt und eige­nem Inhalts­ver­zeich­nis sich im Haupt­do­ku­ment (main.pdf) befin­det.

Die drei exter­nen Doku­men­te sol­len mit rich­ti­gen Sei­ten­an­ga­ben im Inhalts­ver­zeich­nis der Haupt­da­tei auf­ge­führt wer­den.

Nun könn­te man die drei exter­nen Doku­men­te von Hand jeweils selb­stän­dig erzeu­gen und anschlie­ßend die­se drei PDF mit dem Paket pdfpa­ges ein­bin­den. Abge­se­hen davon, dass sich hier schnell Feh­ler ein­schlei­chen, wenn nicht die aktu­ells­te Ver­si­on des exter­nen PDF ein­ge­bun­den wird, ist es doch ein recht hoher Auf­wand.

Die drei exter­nen Doku­men­te wer­den in einem Unter­ver­zeich­nis (hier im Bei­spiel sub­dir genannt) des Ver­zeich­nis­ses gepflegt, in dem sich die Datei main.tex befin­det.

Automatisierung mit arara

ara­ra ist ein coo­les TeX-Auto­ma­ti­sie­rungs­tool. Sich in die Syn­tax von ara­ra ein­zu­ar­bei­ten ist nicht gera­de tri­vi­al. Dafür gibt es hier gleich den fer­ti­gen Code.

Was wollen wir tun?

  1. dok-ext-03.pdf mit allen not­wen­di­gen Schrit­ten aus dok-ext-01.tex erzeu­gen
  2. dok-ext-02.pdf mit allen not­wen­di­gen Schrit­ten aus dok-ext-01.tex erzeu­gen
  3. dok-ext-03.pdf mit allen not­wen­di­gen Schrit­ten aus dok-ext-01.tex erzeu­gen
  4. Das Haupt­do­ku­ment main.pdf aus mein.tex erzeu­gen und die drei PDF dok-ext-01 bis *03.pdf ein­bin­den und im Inhalts­ver­zeich­nis mit den kor­rek­ten Sei­ten­an­ga­ben auf­füh­ren.

Die Lösung mit arara und dem Paket pdfpages

ara­ra ist in der neu­es­ten Ver­si­on Teil der TeX-Dis­tri­bu­ti­on. Mög­li­cher­wei­se muss Java nach­in­stal­liert wer­den. Bein ers­ten Auf­ruf von ara­ra bekommt man ggf. einen ent­spre­chen­den Hin­weis.

In den Kopf der Datei main.tex schreibt man fol­gen­den Code (ich arbei­te aus­schließ­lich mit xela­tex, aber eine Anpas­sung an pdfla­tex ist ein­fach):

tex-Dateien anpassen:

% arara: xelatex: {
% arara: --> shell: yes,
% arara: --> synctex: yes,
% arara: --> directory: subdir,
% arara: --> files: [ dok-ext-01.tex,dok-ext-01.tex,dok-ext-01.tex,
% arara: --> dok-ext-02.tex, dok-ext-02.tex,dok-ext-02.tex,
% arara: --> dok-ext-03.tex, dok-ext-03.tex, dok-ext-03.tex
% arara: --> ]
% arara: --> }
% arara: xelatex: { 
% arara: --> shell: yes,
% arara: --> synctex: yes,
% arara: --> files: [maintex, main.tex, main.tex] }
% !arara: --> if missing('pdf')
% !arara: --> || changed('tex'),

Die jewei­li­gen *.tex-Datei­en wer­den jeweils drei­mal auf­ge­ru­fen um alle inter­nen Refe­ren­zen auf­zu­lö­sen.

In Datei main.tex wer­den die drei PDF wie folgt ein­ge­bun­den:

% Code-Schnippsel
\begin{document}
 \tableofcontents
 \include{kap_a}
 \include{kap_b}
 \include{kap_c}
 \includepdf[pages=-, link, addtotoc={1,chapter,1,Titel ext-dok-01,cha:ext-dok-01}]{subdir/ext-dok-01}
 \includepdf[pages=-, link, addtotoc={1,chapter,1,Titel ext-dok-02,cha:ext-dok-02}]{subdir/ext-dok-02}
 \includepdf[pages=-, link, addtotoc={1,chapter,1,Titel ext-dok-03,cha:ext-dok-03}]{subdir/ext-dok-03}
 \include{kap_n}
\end{document)

arara anpassen:

araconfig.yaml

Eine Datei araconfig.yaml anle­gen.

!config
paths:
- '.'

Wer mag, kann gleich noch die Aus­ga­ben von ara­ra auf Deutsch umstel­len, eine log-Datei mit allen Aus­ga­ben erstel­len las­sen und die Bild­schirm­aus­ga­ben unter­drü­cken. Die Datei araconfig.yaml hat dann fol­gen­den Inhalt:

!config
language: de
logging: true
verbose: false
paths:
- '.'

Durch die Anwei­sung paths wird ara­ra ange­wie­sen, loka­le rules – hier xelatex.yaml – im Ver­zeich­nis der Mas­ter-TeX-Datei (main.tex) auf­zu­ru­fen.

xelatex.yaml anlegen:

Eine Datei xelatex.yam anle­gen mit fol­gen­dem Inhalt:

!config
identifier: xelatex
name: XeLaTeX
authors:
- Paulo
commands:
- name: XeLaTeX engine
 command: >
  @{
    if (isEmpty(directory)) {
      return getCommand('xelatex', interaction, shell,
         synctex, options, file);
    }
    else {
      return getCommandWithWorkingDirectory(directory, 'xelatex',
         interaction, shell, synctex, options, file);
    }
  }
arguments:
- identifier: interaction
 flag: >
  @{
    if ([ 'batchmode', 'nonstopmode', 'scrollmode',
       'errorstopmode' ].contains(parameters.interaction)) {
      return '--interaction='.concat(parameters.interaction);
    }
    else {
      throwError('The provided interaction value is not valid.');
    }
  }
- identifier: shell
 flag: >
  @{
    isTrue(parameters.shell, '--shell-escape', '--no-shell-escape')
  }
- identifier: synctex
 flag: >
  @{
    isTrue(parameters.synctex, '--synctex=1', '--synctex=0')
  }
- identifier: options
 flag: >
  @{
    if (isList(parameters.options)) {
      return parameters.options;
    }
    else {
      throwError('I was expecting a list of options.');
    }
  }
- identifier: directory
 flag: >
  @{
    return parameters.directory;
  }

Wenn die­se Datei­en fer­tig­ge­stellt sind, auf der Kom­man­do­zei­le in das Ver­zeich­nis der Datei main.tex wech­seln.

Mit

 arara main.tex

wer­den die Anwei­sun­gen von ara­ra im Kopf der Datei main.tex abge­ar­bei­tet. Fer­tig!

Hier auf TeXWelt.de gibt es noch ein paar Infor­ma­tio­nen, um ara­ra in eini­ge der TeX-Edi­to­ren ein­zu­bin­den, wenn man nicht auf der Kom­man­do­zei­le arbei­ten möch­te.

Mein Dank gilt Ulri­ke Fischer und Pau­lo Cere­da – Autor von ara­ra – für ihre Unter­stüt­zung für die­se Lösung.