Anhänge, Ebenen und Medien

TeX Live 2024 liefert eine Datei namens VPlayer.swf mit: 483.412 Byte Flash, zuletzt geändert am 19. Januar 2018. Verwendet man \includemedia aus LaTeX’ Paket media9, wird genau diese Datei vollständig ins PDF eingebettet – fast ein halbes Megabyte Player für ein einziges Video, das nirgends mehr läuft. Flash erreichte am 31. Dezember 2020 sein Lebensende, und ab dem 12. Januar 2021 blockierte Adobe selbst die Wiedergabe von Flash-Inhalten. Ein PDF kann weit mehr tragen als statische Seiten – angehängte Dateien, Ebenen, Anmerkungen, Animation, Video –, doch all das verhält sich in freier Wildbahn höchst unterschiedlich. Diese Seite sortiert das, geprüft mit pdfdetach und pdftotext.

Eine Datei ins PDF einbetten: attachfile2 gegen embedfile

Der Unterschied liegt darin, wohin im PDF die Datei kommt. \attachfile{data.csv} aus attachfile2 setzt eine /FileAttachment-Anmerkung – das Büroklammer-Symbol – auf die Seite. \embedfile{data.csv} aus embedfile legt nichts auf die Seite, sondern trägt die Datei in den dokumentweiten /EmbeddedFiles-Baum unter /Names ein. Die Messung trennt beides sauber: Die attachfile2-Ausgabe enthält zwei /FileAttachment-Anmerkungen (je eine für \attachfile und \textattachfile) und kein /EmbeddedFiles; bei embedfile ist es genau umgekehrt. Die Anhänge-Leiste eines Viewers liest diesen Namensbaum, ein allein mit \attachfile gebautes PDF zeigt dort also nichts – man muss das Symbol auf der Seite finden. Beides zu verwenden ist die sichere Antwort.

\usepackage{attachfile2}
\usepackage{embedfile}

% visible on the page: a clickable paperclip, and custom link text
\attachfile[icon=Paperclip,author={Ada}]{data.csv}
\textattachfile{data.csv}{download the data}

% invisible, but listed in the viewer's Attachments panel
\embedfile[desc={Source data},mimetype=text/csv]{data.csv}

Welches man wählt, beantworten die Pakete selbst. attachfile2 ist Heiko Oberdieks Weiterentwicklung von Scott Pakins attachfile (TeX Live 2024 liefert v2.12 vom 18.01.2024) und ergänzt dvips-Unterstützung sowie automatische Metadaten zur angehängten Datei. Tatsächlich trug ein mit attachfile2 gebautes PDF /Size 12 – die Bytezahl des Originals – und /CheckSum <178ba857…>, während die Ausgabe des alten attachfile gar kein /CheckSum enthält. Und die eigene README sagt unmissverständlich: „See the embedfile package for a newer package supporting this feature.“ Für Neues entscheidet die Frage, ob ein sichtbares Symbol gewünscht ist; wenn nicht, ist embedfile der geradlinige Weg.

Ob der Anhang wirklich angekommen ist, bestätigt poppler mit pdfdetach. pdfdetach -list paper.pdf listet die eingebetteten Dateien, pdfdetach -saveall -o out paper.pdf holt sie heraus – gemessen kam die zurückgewonnene data.csv Byte für Byte identisch zurück. Dabei fällt eines auf: Wird dieselbe Datei zweimal angehängt, steckt sie zweimal drin. \attachfile und \textattachfile nebeneinander genügen, und pdfdetach -list antwortet 2 embedded files. Soll ein großer Datensatz von mehreren Stellen aus erreichbar sein, bettet man ihn besser einmal mit embedfile ein und verweist aus dem Text darauf.

$ pdfdetach -list paper.pdf
2 embedded files
1: data.csv
2: data.csv

$ pdfdetach -saveall -o out paper.pdf && diff out/data.csv data.csv && echo identical
identical

Ebenen (OCG) mit ocgx2 – und warum verborgener Inhalt nicht verborgen ist

Die OCG (Optional Content Groups) eines PDF sind Ebenen, die sich ein- und ausblenden lassen. Alexander Grahns ocgx2 umschließt Inhalte mit \begin{ocg}{name}{id}{initial visibility}…\end{ocg} und liefert \switchocg, \toggleocgs, \showocgs und \hideocgs als anklickbare Schalter. Das erzeugte PDF trägt tatsächlich ein /OCProperties-Wörterbuch, und die Technik eignet sich für schrittweises Einblenden oder das Übereinanderlegen von Varianten derselben Abbildung. Doch das Umschalten funktioniert vor allem in Acrobat; andere Viewer zeigen unter Umständen nur den Anfangszustand.

\usepackage{ocgx2}
Question: what is $2+2$?
\begin{ocg}{Answer}{ans}{0}   % 0 = hidden when the file opens
  The answer is 4.
\end{ocg}

\switchocg{ans}{Show or hide the answer}

Und es gibt eine weit wichtigere Falle: Text auf einer verborgenen Ebene ist nicht verborgen. Übersetzt man obiges Beispiel und lässt pdftotext darüberlaufen, lautet der extrahierte Text Question: what is 2 + 2? The answer is 4. – die Antwort erscheint vollständig, obwohl sie anfangs unsichtbar ist. Eine OCG bestimmt, ob etwas gezeichnet wird; sie ist weder Verschlüsselung noch Löschung. Inhalte, die niemand sehen soll, hinter einer OCG zu verstecken, ist daher zwecklos: Lösungen zu Übungsaufgaben, Schwärzungen für Gutachter, eine zweite Preisliste – wer den Text kopiert oder einmal ein Extraktionswerkzeug laufen lässt, liest alles. Was nicht gesehen werden darf, gehört nicht ins PDF.

Anmerkungen und Kommentare: Notizzettel, Markierungen und Tooltips mit pdfcomment

Josef Klebers pdfcomment (TeX Live 2024 liefert v2.4a) erzeugt PDF-Anmerkungen aus LaTeX-Quelltext. \pdfcomment{…} ergibt einen Notizzettel (/Subtype /Text), \pdfmarkupcomment[markup=Highlight]{der Text}{der Kommentar} markiert eine Passage und hängt eine Notiz daran (/Subtype /Highlight), und \pdftooltip{Text}{Erläuterung} liefert einen Tooltip beim Überfahren. Der Schlüssel author={Reviewer} landet als /T im PDF und erscheint in der Kommentarliste eines Viewers als Name des Verfassers. So lassen sich Gutachterbemerkungen im LaTeX-Quelltext halten und im verteilten PDF als Anmerkungen zeigen.

Zwei praktische Hinweise. Erstens die Farben: color=yellow ohne geladenes xcolor bricht den Lauf mit ! Package pdfcomment Error: This color specification is not supported ab; ein vorangestelltes \usepackage{xcolor} behebt das. Zweitens die Durchläufe: Markierungsanmerkungen erscheinen im ersten Lauf nicht, erst der zweite bringt das /Subtype /Highlight (im Log steht sogar Rerun to get outlines right or use package bookmark.). pdfcomment gehört allerdings zu den Überlebenden – rendert man eine Seite mit poppler zu einem Bild und zählt die Farben, ist das Markierungsgelb (RGB 255,242,0) tatsächlich gezeichnet. Und der Text einer Anmerkung taucht in der Ausgabe von pdftotext nicht auf, Kommentare verunreinigen den extrahierten Text also nie.

\usepackage{xcolor}       % must come before pdfcomment for named colours
\usepackage{pdfcomment}

A sentence.\pdfcomment[author={Reviewer},icon=Note,color=yellow]{Check this reference.}
A \pdfmarkupcomment[markup=Highlight,color=yellow,author={Reviewer}]%
  {highlighted phrase}{needs a citation}.
A \pdftooltip{term}{shown when the pointer rests on it}.

Animation: animate läuft über JavaScript

Alexander Grahns animate ist der einzige Bewegtbild-Mechanismus, der ohne Flash auskommt. Schreibt man \animategraphics[controls,autoplay]{12}{frame-}{0}{59}, entsteht eine Abbildung, die frame-0.png bis frame-59.png mit zwölf Bildern je Sekunde abspielt. Um in TikZ oder PSTricks gezeichnete Einzelbilder direkt zu animieren, dient die Umgebung animateinline mit \multiframe. Der Antrieb ist im PDF eingebettetes JavaScript – das Feld JavaScript in pdfinfo springt entsprechend auf yes. Jeder Viewer, der JavaScript ausführt, kann es abspielen, was weit portabler ist als eingebettetes Video. Der Preis: Alle Einzelbilder wandern mit hinein, Bildzahl und Auflösung schlagen also unmittelbar auf die Dateigröße durch.

\usepackage{animate}
% a numbered image series: frame-0.png ... frame-59.png at 12 fps
\animategraphics[controls,autoplay,width=6cm]{12}{frame-}{0}{59}

% or animate TikZ frames drawn on the fly
\begin{animateinline}[controls,loop]{6}
  \multiframe{12}{i=0+30}{%
    \begin{tikzpicture}\draw[->,thick] (0,0)--(\i:1.5);\end{tikzpicture}}
\end{animateinline}

Multimedia: media9 und das Erbe von Flash

\includemedia aus media9 bettet Video, Audio und 3D in ein PDF ein; movie15 ist der veraltete Vorgänger. Technisch läuft es weiterhin – die Messung erzeugte eine /Subtype /RichMedia-Anmerkung und ein /Subtype /Video-Objekt. Das Problem liegt bei der Wiedergabe. Die im zweiten Argument von \includemedia genannte VPlayer.swf ist eine Flash-Datei, die TeX Live 2024 noch immer mitliefert, während Flash selbst Ende 2020 eingestellt wurde. Mit einem 14 Byte großen Dummy-Video ergab sich ein Ausgabe-PDF von 493.989 Byte – fast ausschließlich ein Player, der nie wieder starten wird. Für neue Dokumente verlinkt man externe Medien oder nutzt animate für bildbasierte Bewegung. media9 als Altlast zu behandeln, ist die richtige Entscheidung.

Welche Funktionen tatsächlich überleben – und wie weit

Die kurze Antwort: Anhänge und Anmerkungen sind bedenkenlos einsetzbar, Ebenen und Video nicht. Die folgende Tabelle hält fest, wie ein mit TeX Live 2024 gebautes PDF den poppler-Werkzeugen (pdfinfo, pdfdetach, pdftotext, pdftoppm) erscheint. Belegt ist damit, ob die richtigen Objekte im PDF stecken und wie poppler sie behandelt; das Verhalten in Adobe Acrobat wurde hier nicht überprüft. Für die Funktionen, denen allgemein eine starke Acrobat-Abhängigkeit nachgesagt wird – OCG-Umschaltung, Wiedergabe über \includemedia –, sollte man selbst in der Umgebung testen, die die Lesenden tatsächlich verwenden.