Need help to understand xkeyval example

I found an "easy" example how to use xkeyval here using the following code:

\ProvidesPackage{myemph}[2011/03/12 v1.0 a test package]

\providecommand\my@emphstyle{\em}

% Note that the argument must be expandable,
% or use xkvltxp package before \documentclass (see manual of xkeyval)
\RequirePackage{xkeyval}
\DeclareOptionX{style}{%
\def\my@emphstyle{\csname my@style@#1\endcsname}}
% predefined styles
\providecommand\my@style@default{\em}
\providecommand\my@style@bold{\bfseries}

\ProcessOptionsX

% For simple key-value commands, keyval would suffie
\define@key{myemph}{code}{%
\def\my@emphstyle{#1}}
\define@key{myemph}{style}{%
\def\my@emphstyle{\csname my@style@#1\endcsname}}
\newcommand\setemph[1]{%
\setkeys{myemph}{#1}}

\renewcommand\emph[1]{%
{\my@emphstyle #1}}

\endinput


Test file:

\documentclass{article}
\usepackage[style=default]{myemph}

\begin{document}
Something \emph{important}

\setemph{style=bold}
Something \emph{important}

\setemph{code=\Large\sffamily}
Something \emph{important}
\end{document}


My first issue is that I dont know what is ment by

\providecommand\my@emphstyle{\em}


I found here and here that usually '@' is a letter of category 12 and not 11 and, therefore, can't be used in macros, except you manualy set '@' to category 11, which has not been done in the above code. However, I can compile the latex code. Why does it work?

After ignoring this, I moved on to the line

\DeclareOptionX{style}{%
\def\my@emphstyle{\csname my@style@#1\endcsname}}


which gave me the pleasure to explore what \csname does. As far as I understood, it is used to use commands that make use of letters that are not contained in category 11. However, the function '\my@style' has not been definied yet, so I dont see what is happing there. In addition, I do not know what \DeclareOptionX does anyway. I could not find it with google.

After all, I read the offical documentation of the xkeyval package where it was explained how to used it, simply by using the commands '\define@key' and '\setkeys' on page 1. I guess its my bad that I was looking for an easy example to skip the documentation. However, now I am curious how the 'simple' example works.

-

Firstly @ is made a letter in package and class files automatically.

\DeclareOptionX{style}{%
\def\my@emphstyle{\csname my@style@#1\endcsname}}


The xkeyval package uses this to define what happens when in the document you go

\setemph{style=bold}


basically the (x)keyval parser uses the macro defined by the declaration and passes it the value (the part after =) as the TeX argument #1 so style=bold gets executed as

 \def\my@emphstyle{\csname my@style@bold\endcsname}


which is more or less the same as

\def\my@emphstyle{\my@style@bold}


but \csname has allowed the command name to be constructed at run time.

earlier

\providecommand\my@style@bold{\bfseries}


had defined \my@style@bold so the end result is that style=bold causes \bfseries to get executed, and stuff goes bold.

The basic use of keyval is with \setkeys but xkeyval also injects the mechanism into the \usepackage option handler which by default just accepts a comma separated list of options with no = syntax. That is the \DeclareOptionX then \ProcessoptionsX is the extended version of \ProcessOptions that calls \setkeys internally so that

\usepackage[style=default]{myemph}


invokes the key definitions.

-
Thank you. Could you also explain why \setemph{style=bold} works instead of the described Marco \setkeys[my]{emphstyle}{style=bold} as descriped in the offical documentation? –  Adam Feb 5 '14 at 11:38
@Adam oh it's common for packages to do that eg hyperref has \hypersetup which similarly is a very thin wrapper around \setkeys, it just hides the internal key collection names probably (I haven't looked) \def\setemph{\setkeys[my]{emphstyle}} –  David Carlisle Feb 5 '14 at 13:14