☰

Till Tantau 的“codeexample”中的自动链接（又名代码高亮）

tag-icon • tag-icon tikz-pgf documentation package-writing
Till Tantau 的“codeexample”中的自动链接（又名代码高亮）

我正在为基于 tikz 的包编写文档，并尝试重用 Till Tantau 的codeexample环境来输出源代码及其输出。但是，我无法让语法突出显示（即自动链接关键字）正常工作。

[编辑：事实证明，pdflinks/语法高亮层是 Christian Feuersänger 的作品]

这是一个重现该问题的最小示例：

\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}

我期望自动链接会发生，但事实并非如此。所有文件似乎都在正确的位置，我没有收到任何警告。在 中pgfmanual.code.tex，键/pdflinks/codeexample link设置为 true。我也激活了/pdflinks/show labels，但我看不出有什么区别。

编辑

也许我应该更清楚地说明，该示例可以顺利编译，并且不会出现任何错误，但它不会产生预期的结果。唯一的问题是，代码示例中关键字与其定义的自动链接以及随后的关键字突出显示不起作用。

正如我在代码示例中所写，command环境负责提取命令的名称并对其进行索引。到目前为止，一切都正常，事实上，条目已正确索引并显示在文档末尾的索引中。我想了解的是，我是否做了一些事情，导致自动链接无法正常工作，或者我应该做但没做。

编辑（回答后）

在 Christian 出色地回答了我的以下问题后，我实际上尝试让它工作。令人惊讶的是，对于上面的代码，我发现仅\def\pgfautoxrefs{1}在文档开头添加只能部分解决问题。使用文本自动链接|\sillymacro|可以按预期工作，而代码示例中的语法突出显示仍然会损坏。

为了实现它完全工作，必须更换声明

\usepackage{pgfmanual}

和

\makeatletter
\input{pgfmanual.code}
\makeatother

这很令人困惑，因为我pgfmanual.sty所做的只是：

\input pgfmanual.code.tex

因此，最终完整的工作示例如下：

\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}

结果如下：

使用 tikz 文档宏生成的自动链接文档的工作示例

答案1

导致你出现问题的原因是pgfmanual-en-macros.tex 明确禁用语法高亮显示，除非找到可以启用该功能的命令行选项。

在您的情况下，命令行选项不存在并且文件禁用语法高亮显示。

语法高亮消耗相当多的 CPU 能力，并且只有在使用make distpgfmanual 时才会激活。

您的解决方案是输入

\def\pgfautoxrefs{1}

作为文档中的第一个语句。如果不存在此宏，则代码pgfmanual-en-macros.tex:1286会禁用它：

\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

也许真的是时候将所有这些东西打包成一个独立的包了......（如果有人愿意开始，我会提供建议。我写了那个语法高亮模块）。

相关内容