# Automatic linking (aka code highlight) in Till Tantau's codeexample

I am writing docs for a tikz-based package, and I am trying to reuse Till Tantau's codeexample environment to output source code along with its output. However, I cannot manage to get syntax highlighting (that is, automatic linking of keywords) to work.

[EDIT: as it turns out, the pdflinks / syntax highlighting layer is Christian Feuersänger's work]

This is a minimal example reproducing the problem:

\documentclass[a4paper]{ltxdoc}
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{hyperref}
\hypersetup{%
filecolor=blue,
urlcolor=blue,
citecolor=blue,
pdfborder=0 0 0,
}
\usepackage{tikz}

% pgfmanual.sty inputs pgfmanual.code.tex, which in turn inputs
% pgfmanual.prettyprinter.code.tex and pgfmanual.pdflinks.code.tex.
% All the files are in the same dir as this file.
\usepackage{pgfmanual}

\usepackage{calc} % NEEDED by pgfmanual-en-macros
\input{pgfmanual-en-macros}
\newcommand{\options}[1][options]{\opt{\oarg{#1}}}
\newcommand{\sillymacro}[2][]{
\node [shade, top color = black, bottom color = green, %
text = white, thick, rounded corners, font=\bfseries, #1] {#2};
}
\begin{document}
\begin{command}{\sillymacro\options\marg{contents}}
Defining a command via the command environment is supposed to automatically index it, isn't it?
In fact, an entry is correctly generated in the index.
Howeverm I would expect |\sillymacro| to be treated as a link, but it doesn't really work.
\begin{codeexample}[]
\begin{tikzpicture}
\sillymacro{Uh-uhhhh! I am fancy}
\end{tikzpicture}
\end{codeexample}
\end{command}
No linking inside the example, no |\sillymacro| linking outside.
\printindex
\end{document}


I would expect automatic linking to happen, but it doesn't. All the files appear to be in the right place, and I get no warning whatsoever. In pgfmanual.code.tex, the key /pdflinks/codeexample link is set to true. I have also activated /pdflinks/show labels, but I cannot see any difference.

EDIT

Maybe I should make clearer that the example compiles all right, and gives no error, but it does not produce the expected result. The only problem is that the automatic linking of the keywords with their definitions and the consequent highlighting of the keywords in the code examples do not work.

As I wrote in the code example, the command environment takes care of extracting the names of the command and indexing it. Things are working up to this point, in fact the entry is correctly indexed and shown in the index at the end of the document. What I am trying to understand is if there is something that I do that is preventing automatic linking from working, or if there is something that I am supposed to do and didn't.

After Christian brilliantly answered my question below, I actually tried to make it work. Not without surprise, with respect to the code above I discovered that only adding \def\pgfautoxrefs{1} at the beginning of the document would only partially solve the problem. In-text auto-linking using |\sillymacro| would work as expected, while syntax highlighting in the code example would still be broken.

To make it totally work, one must replace the statement

\usepackage{pgfmanual}


with

\makeatletter
\input{pgfmanual.code}
\makeatother


This is quite puzzling, since all my pgfmanual.sty does is:

\input pgfmanual.code.tex


So, in the end, the complete working example is as follows:

\documentclass[a4paper]{ltxdoc}
\def\pgfautoxrefs{1} % !!!!!!
\usepackage[left=2.25cm,right=2.25cm,
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{hyperref}
\hypersetup{%
filecolor=blue,
urlcolor=blue,
citecolor=blue,
pdfborder=0 0 0,
}
\usepackage{tikz}

% pgfmanual.code.tex in turn inputs
% pgfmanual.prettyprinter.code.tex and pgfmanual.pdflinks.code.tex.
% (I am using pgf 2.10 sources)
\makeatletter          % !!!!
\input{pgfmanual.code} % !!!!
\makeatother           % !!!!

\usepackage{calc} % NEEDED by pgfmanual-en-macros
\input{pgfmanual-en-macros}
\newcommand{\options}[1][options]{\opt{\oarg{#1}}}
\newcommand{\sillymacro}[2][]{
\node [shade, top color = black, bottom color = green,%
text = white, thick, rounded corners,%
font=\bfseries, #1] {#2};
}
\begin{document}
\begin{command}{\sillymacro\options\marg{contents}}
Defining a command via the command environment is supposed
to automatically index it, isn't it?

In fact, now it does!
|\sillymacro| is treated as a link, and I can happily
click on it.
\begin{codeexample}[]
\begin{tikzpicture}
\sillymacro{Uh-uhhhh! I am fancy}
\end{tikzpicture}
\end{codeexample}
\end{command}
It also works outside, and |\sillymacro| is also highlighted in
the code listing. Great, thanks!
\printindex
\end{document}


And here is the result:

-
After adding \makeatletter \input{pgfmanual.prettyprinter.code} \input{pgfmanual.pdflinks.code} \makeatother I get ! Package pgfmanual Warning: pgfmanualpdfref{\sillymacro}: target label does no t exist.. Seems that there is no label for it, so the link can't be created. Running makeindex doesn't help either. –  Martin Scharrer Nov 7 '11 at 10:28
I get no Warning whatsoever from pgfmanual. Where did you add \makeatletter? I didn't understand, sorry. –  masterpiga Nov 7 '11 at 10:38
I had a look at the pgfmanual source files to find you how the links are added. I figured that these two files need to be loaded as well. The need to have the @ as letter, so you need to use \makeatletter beforehand if you load them from a document preamble directly. –  Martin Scharrer Nov 7 '11 at 10:41
As I wrote in the example code, pgfmanual.sty is already loading those two files, and it is doing no trick with @. The files that I have included in my project are from pfg 2.10 sources, and I haven't hacked them in any way. –  masterpiga Nov 7 '11 at 10:56
Ah, ok. I thought pgfmanual-en-macros should load them and because I couldn't find them there I loaded them manually. About the \makeatletter: As I wrote, you only need \makeatletter if you load them in a document preamble. It isn't required inside a package because then @ is already a letter. –  Martin Scharrer Nov 7 '11 at 11:04

The reasons for your problem is that pgfmanual-en-macros.tex explicitly disables the syntax highlighting unless it finds a command-line option which enables it.

In your case, the command-line option is not present and the file disables the syntax highlighting.

The syntax highlighting consumes quite some CPU power and is only activated if one uses make dist for the pgfmanual.

The solution for you is to type

\def\pgfautoxrefs{1}


as first statement in your document. If this macro is absent, the code pgfmanual-en-macros.tex:1286 disables it:

\makeatletter
% \pgfautoxrefs will be defined by 'make dist'
\pgfutil@ifundefined{pgfautoxrefs}{%
\def\pgfmanualpdflabel#1#2{#2}% NO-OP
\def\pgfmanualpdfref#1#2{#2}%
\pgfkeys{

@Christian Uh-uuuu, thanks! That was easy, if you knew where to put the hands. The package is already pretty much self-contained, and it is also decently documented. The only obstacle to release it as a package seems to remove some redundancy and devote some effort to documentation. In this case, I was sure that there was some flag to set, but I was confused by lines 39-43, from which you would understand (well, I did at least) that to activate/deactivate highlighting you only had to toggle /pfdlinks/codeexample links. –  masterpiga Nov 7 '11 at 18:27