HowTo_UseKomaVar

How to use KOMA-Script variables to set PDF metadata with hyperref

As letters are often no longer archived in paper form but as PDFs, it makes sense to provide them with useful meta information. Often you want to use the information already defined in the KOMA script variable via \setkomavar. However, a simple \hypersetup{author=\usekomavar{fromname}} will not work, as \usekomavar cannot be expanded. However, as the following example shows, the optional argument of \usekomavar can be used here:

\documentclass[english]{scrlttr2}
\usepackage{babel}
\usepackage{hyperref}

\setkomavar{fromname}{Meinereiner}
\setkomavar{fromaddress}{Seinestraße 13 \\34567 Meinestadt}
\setkomavar{fromemail}{mail@example.com}
\setkomavar{yourref}[Order Number]{12345}
\setkomavar{yourmail}[Order Date]{2014-11-08}

\setkomavar{invoice}[Quotation]{2015-0012}

\setkomavar{subject}{Quotation} % very intrusive

\newcommand*{\hypersetupone}[2]{\hypersetup{#1={#2}}}
\newcommand*{\hypersetupbykomavar}[2]{%
 \usekomavar[\hypersetupone{#1}]{#2}%
}
\newcommand*{\hypersetupbykomadescandvar}[2]{%
 \begingroup
 \usekomavar*[\def\desc]{#2}%
 \usekomavar[\def\value]{#2}%
 \hypersetup{#1={\desc{} \value}}%
 \endgroup
}
\hypersetupbykomadescandvar{pdftitle}{invoice}
\hypersetupbykomavar{pdfauthor}{fromname}
\hypersetupbykomavar{pdfkeywords}{invoice}
\hypersetupbykomavar{pdfsubject}{subject}

\begin{document}
\begin{letter}{Peter Pan\\Meinestraße 12\\34567 Meinestadt}

\opening{Hello Peter,}

Thank you for your request. We have several "Lorem Ipsum" in stock and
can adapt them to your requirements at short notice.
However, we are currently working at full capacity, so it will take a few days.

\closing{Best regards}

\end{letter}
\end{document}

If you now look at the metadata with pdfinfo, for example, you will find, among other things:

Title:           Quotation 2015-0012
Subject:         Quotation
Keywords:        2015-0012
Author:          Meinereiner

How does it work?

First, we define a new \hypersetupone statement that can be used to set exactly one hyperref option to a new value. The name of the option is the first argument and the value is the second:

\newcommand*{\hypersetupone}[2]{\hypersetup{#1={#2}}}

We then use this new statement in the definition of \hypersetupbykomavar in the optional argument of \usekomavar to set a hyperref option (first argument) to the value of a KOMA-Script variable (second argument):

\newcommand*{\hypersetupbykomavar}[2]{%
  \usekomavar[\hypersetupone{#1}]{#2}%
}

The third statement:

\newcommand*{\hypersetupbykomadescandvar}[2]{%
  \begingroup
    \usekomavar*[\def\desc]{#2}%
    \usekomavar[\def\value]{#2}%
    \hypersetup{#1={\desc{} \value}}%
  \endgroup
}

shows, how to proceed if you want to do more than just use the value of the variable. Two auxiliary instructions \desc and \value are defined locally in a group via \usekomavar* and \usekomavar. \desc is then the description of the variable and \value the value. These are then processed again with \hypersetup. Of course, you could also have used \hypersetupone again at this point.

It should be noted that this method does not work if KOMA-Script variables themselves use KOMA-Script variables. For example, if you were to use

\setkomavar{subject}{\usekomavar*{invoice} \usekomavar{invoice}}

the whole thing would no longer work. In such cases, there is no getting around the definition of auxiliary macros, for example:

\providecaptionname{ngerman}{\invoicename}{Angebot}
\newcommand*{\invoicevar}{2015-0012}
\setkomavar{invoice}{\invoicevar}
\setkomavar{subject}{\invoicename{} \invoicevar}

Of course, you can also use \hypersetup{title={\invoicename{} \invoicevar}} directly.