Was heißt hyperrefs Warnung „Token not allowed in a PDF string“?

Manche Sonderzeichen, aber auch Hoch- und Tiefstellungen können nicht als pdf-Bookmarks gesetzt werden. Abhilfe schafft hier \texorpdfstring{<TeX-String>}{<pdf-String>}.

Der TeX-String wird im Dokument gesetzt, der pdf-String kommt zum Beispiel in die pdf-bookmarks. Als Beispiel sei hier \textorpdfstring{CO\textsubscript{2}}{CO\string(2)} gegeben (die Arbeit mit einem Chemiepaket wie chemmacros ist aber zu empfehlen)

\documentclass[]{scrartcl}
\usepackage{hyperref}
\begin{document}
\tableofcontents
\section{\texorpdfstring{CO\textsubscript{2}}{CO\string_(2)}}
\end{document}

Weitere Informationen sind auch unter d.c.t.t. zu finden

Ein Beispiel, mit dem sich die Warnung erzeugen lässt, wäre folgendes

\documentclass{article}
\usepackage{hyperref}
\begin{document}
\section{$a+b=c$}
\end{document}

Im log steht zweimal:

Package hyperref Warning: Token not allowed in a PDF string (PDFDocEncoding):
(hyperref)                removing `math shift' on input line 4.

Die Warnung bedeutet, dass das in dem PDF-Lesezeichen, das hyperref für die \section anlegt, das Math-Shift-Token $ nicht erlaubt ist und daher entfernt wird. Erklärt ist das in hyperrefs Dokumentation (Abschnitt 4.1.2 Replacement macros)

hyperref takes the text for bookmarks from the arguments of commands like section, which can contain things like math, colors, or font changes, none of which will display in bookmarks as is.

Was das bedeutet, wird an einem anderen Beispiel (Dank an Herbert!) noch deutlicher:

\documentclass{article}
\usepackage{hyperref}
\begin{document}
\section{$\int_a^b x^2 dx$}
\end{document}

Das Lesezeichen liest sich jetzt „ab x2 dx“, ist also nicht mehr wirklich sinnvoll zu interpretieren.

Umgehen kann man die Warnung (und das u.U. „kaputte“ Lesezeichen), indem man mit \texorpdfstring{<tex>}{<PDF>} eine extra Eingabe für TeX und für das PDF-Lesezeichen angibt:

\documentclass{article}
\usepackage{hyperref}
\begin{document}
\section{\texorpdfstring{$a+b=c$}{a+b=c}}
\section{\texorpdfstring{$\int_a^b x^2 dx$}{int\_a\textasciicircum b x\textasciicircum2 dx}}
\end{document}

Für Makros gibt es auch eine etwas automatischere Möglichkeit. Z.B. führt \textsuperscript zu den folgenden vielleicht etwas unerwarteten Warnungen:

Package hyperref Warning: Token not allowed in a PDF string (PDFDocEncoding):
(hyperref)                removing `\mathsurround' on input line 4.

Package hyperref Warning: Token not allowed in a PDF string (PDFDocEncoding):
(hyperref)                removing `\z@' on input line 4.

Package hyperref Warning: Token not allowed in a PDF string (PDFDocEncoding):
(hyperref)                removing `superscript' on input line 4.

Man kann aber hyperref sagen, dass es für die PDF-Lesezeichen eine andere Definition für \textsuperscript nehmen soll:

\documentclass{article}
\usepackage{hyperref}
\pdfstringdefDisableCommands{%
  \def\textsuperscript#1{\textasciicircum(#1)}%
}
\begin{document}
\section{x\textsuperscript{2}}
\end{document}