Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

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[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry}
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{hyperref}
\hypersetup{%
        colorlinks=true,
        linkcolor=blue,
        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.

EDIT (post-answer)

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,
            top=2.5cm,bottom=2.5cm,nohead]{geometry}
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{hyperref}
\hypersetup{%
        colorlinks=true,
        linkcolor=blue,
        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:

Working example of auto-linked docs generated with tikz documentation macros

share|improve this question
    
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
show 6 more comments

1 Answer

up vote 8 down vote accepted

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{
        /pdflinks/codeexample links=false,% DISABLED.
    }%
}{}
\makeatother

Perhaps it really is time to pack all that stuff into a self-contained package... (if there is some willing to start it, I will assist with advice. I wrote that syntax highlighting module).

share|improve this answer
2  
As you can see, the requests will be coming in now! :) –  Werner Nov 7 '11 at 18:21
    
@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
1  
@Werner did you just volunteer? ;-) –  Christian Feuersänger Nov 7 '11 at 18:29
    
@ChristianFeuersänger: Wasn't there a recent request for this? –  Werner Nov 7 '11 at 18:32
2  
@Werner ah, ok, thanks for the explanation. You are right about more and more package authors asking for this feature. In fact, I received a couple of feature request per mail in the past. Nevertheless, I seem to have a never-ending todo list for my active spare-time projects... and the pgfmanual package would certainly need a couple of weeks (especially its documentation). And much of that stuff needs an extensible UI as well, I guess. That's why no-one has started it until now. Again: if someone wants to do it, I would appreciate it (and I would explain that thing). –  Christian Feuersänger Nov 7 '11 at 18:52
show 5 more comments

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.