Token not allowed in PDF string, caused by a macro with an optional arg?

A macro with an optional argument seems to inject tokens into the output that are not allowed within PDF string.

The below MWE should demonstrate this effect.

Where does this token exactly come from, how does it look like, what am I doing wrong, and is there a known workaround?

\documentclass[12pt]{article}

\usepackage[main=english]{babel}

\newcommand{\docTitle}{Works fine}
\renewcommand{\docTitle}[1]{Works fine, too (#1)}
%\renewcommand{\docTitle}[1][]{Does not work}%<- simplified/minimized example

\usepackage[pdfencoding=auto,
final=true,
]{hyperref}
%\usepackage{hyperxmp}
\hypersetup{%
pdfauthor   = {John Doe},
pdftitle    = {\docTitle{Hiho!}},
pdfsubject  = {The Subtitle},
pdfkeywords = {Some keywords},
pdfdisplaydoctitle = true,
pdfstartpage = 1,
pdfstartview = FitH,
}

\setlength{\parindent}{0pt}

\begin{document}
Local tex-environment:

TexLive 2016 (latest updates, frozen), Win7-64bit, Texstudio (latest
stable release)

\bigskip

Step to reproduce:

After uncomenting line~7 the content of \textbackslash docTitle is
ignored (see screenshot of the resulting pdf's metadata).

\bigskip

The log says:

\begin{verbatim}
Package hyperref Warning: Token not allowed in a PDF string (PDFDocEncoding):
(hyperref)                removing \docTitle' on input line 21.
\end{verbatim}

\bigskip

Question[s]:

Where does this token exactly come from, how does it look like, is there
a known workaround?

\end{document}}


Screenshot:

• \docTitle[]{} isn't expandable and as such there is an unexpandable content in the PDF meta key – user31729 May 16 '17 at 21:58

1 Answer

The macro \docTitle[]{} isn't expandable since it has an optional argument, so there is the 'non-useful' token \docTitle left in the PDF meta keys.

One possible solution: Use the \DeclareExpandableDocumentCommand macro from xparse.

\DeclareExpandableDocumentCommand{\docTitle}{O{}m}{Does not work or does it? See #1}


will define an expandable macro with one Optional argument, which has no default value, so just say with {} to leave this empty. This is the xparse equivalent of \newcommand{\foo}[1][]{}.

The \DeclareExpandableDocumentCommand must have mandatory arguments for the macro to be defined.

\documentclass[12pt]{article}

\usepackage[main=english]{babel}

\usepackage{xparse}
\newcommand{\docTitle}{Works fine}
\renewcommand{\docTitle}[1]{Works fine, too (#1)}
\DeclareExpandableDocumentCommand{\docTitle}{O{}}{Does not work or does it? See #1}%<- simplified/minimized example

\usepackage[pdfencoding=auto,
final=true,
]{hyperref}

%\usepackage{hyperxmp}
\hypersetup{%
pdfauthor={John Doe},
pdftitle={\docTitle[FooFoo]{Hiho}},
pdfsubject  = {The Subtitle},
pdfkeywords = {Some keywords},
pdfdisplaydoctitle = true,
pdfstartpage = 1,
pdfstartview = FitH,
}

\setlength{\parindent}{0pt}

\begin{document}
Local tex-environment:

TexLive 2016 (latest updates, frozen), Win7-64bit, Texstudio (latest
stable release)

\bigskip

Step to reproduce:

After uncomenting line~7 the content of \textbackslash docTitle is
ignored (see screenshot of the resulting pdf's metadata).

\bigskip

The log says:

\bigskip

Question[s]:

Where does this token exactly come from, how does it look like, is there
a known workaround?

\end{document}}

• now it's clear to me - thank you very much! – lAtExFaN May 16 '17 at 22:04
• @lAtExFaN: You're welcome, but in my point of view it's best not to use a command with optional argument(s) in this case -- is it really necessary there? – user31729 May 17 '17 at 9:07
• Honestly, I don't now if it is really necessary. As I've some problems to transfer your answer into my real (not mwe) code I try to find an alternative without optional arguments. BTW: I don't understand the {O{}m} part - could you please go into more details here? I already had a look into xparse's package documentation, but I do not understand... Thx – lAtExFaN May 17 '17 at 9:16
• test test test (I cannot address users using the at-letter-useralias in comments. Why is it always removed from my comments?) – lAtExFaN May 17 '17 at 9:23
• @lAtExFaN: Remove the m from the definition -- you don't need a mandatory` argument, it should be easier then. I've added some explanations – user31729 May 17 '17 at 9:35