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

Für eine größere Arbeit soll­ten ins­ge­samt drei externe PDF-Doku­mente (dok-ext-01 usw.) in eine Haupt­datei (main.tex) so einge­bun­den wer­den, dass jedes der der exter­nen Doku­mente mit eigen­em Titel­blatt und eigen­em Inhaltsverze­ich­nis sich im Haupt­doku­ment (main.pdf) befind­et.

Die drei exter­nen Doku­mente sollen mit richti­gen Sei­t­e­nangaben im Inhaltsverze­ich­nis der Haupt­datei aufge­führt wer­den.

Nun kön­nte man die drei exter­nen Doku­mente von Hand jew­eils selb­ständig erzeu­gen und anschließend diese drei PDF mit dem Paket pdf­pages ein­binden. Abge­se­hen davon, dass sich hier schnell Fehler ein­schle­ichen, wenn nicht die aktuell­ste Ver­sion des exter­nen PDF einge­bun­den wird, ist es doch ein recht hoher Aufwand.

Die drei exter­nen Doku­mente wer­den in einem Unter­verze­ich­nis (hier im Beispiel sub­dir genan­nt) des Verze­ich­niss­es gepflegt, in dem sich die Datei main.tex befind­et.

Automatisierung mit arara

arara ist ein cooles TeX-Automa­tisierungstool. Sich in die Syn­tax von arara einzuar­beit­en ist nicht ger­ade triv­ial. Dafür gibt es hier gle­ich den fer­ti­gen Code.

Was wollen wir tun?

  1. dok-ext-03.pdf mit allen notwendi­gen Schrit­ten aus dok-ext-01.tex erzeu­gen
  2. dok-ext-02.pdf mit allen notwendi­gen Schrit­ten aus dok-ext-01.tex erzeu­gen
  3. dok-ext-03.pdf mit allen notwendi­gen Schrit­ten aus dok-ext-01.tex erzeu­gen
  4. Das Haupt­doku­ment main.pdf aus mein.tex erzeu­gen und die drei PDF dok-ext-01 bis *03.pdf ein­binden und im Inhaltsverze­ich­nis mit den kor­rek­ten Sei­t­e­nangaben auf­führen.

Die Lösung mit arara und dem Paket pdfpages

arara ist in der neuesten Ver­sion Teil der TeX-Dis­tri­b­u­tion. Möglicher­weise muss Java nachin­stal­liert wer­den. Bein ersten Aufruf von arara bekommt man ggf. einen entsprechen­den Hin­weis.

In den Kopf der Datei main.tex schreibt man fol­gen­den Code (ich arbeite auss­chließ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 jew­eili­gen *.tex-Dateien wer­den jew­eils dreimal aufgerufen um alle inter­nen Ref­eren­zen aufzulösen.

In Datei main.tex wer­den die drei PDF wie fol­gt einge­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 gle­ich noch die Aus­gaben von arara auf Deutsch umstellen, eine log-Datei mit allen Aus­gaben erstellen lassen und die Bild­schir­maus­gaben unter­drück­en. Die Datei araconfig.yaml hat dann fol­gen­den Inhalt:

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

Durch die Anweisung paths wird arara angewiesen, lokale rules – hier xelatex.yaml – im Verze­ich­nis der Mas­ter-TeX-Datei (main.tex) aufzu­rufen.

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 diese Dateien fer­tiggestellt sind, auf der Kom­man­dozeile in das Verze­ich­nis der Datei main.tex wech­seln.

Mit

 arara main.tex

wer­den die Anweisun­gen von arara im Kopf der Datei main.tex abgear­beit­et. Fer­tig!

Hier auf TeXWelt.de gibt es noch ein paar Infor­ma­tio­nen, um arara in einige der TeX-Edi­toren einzu­binden, wenn man nicht auf der Kom­man­dozeile arbeit­en möchte.

Mein Dank gilt Ulrike Fis­ch­er und Paulo Cere­da – Autor von arara – für ihre Unter­stützung für diese Lösung.