☰

禁用 dtx 文件中的索引创建

tag-icon • tag-icon hyperref indexing dtx
禁用 dtx 文件中的索引创建

下面的代码是一个以 .tex 结尾的最小 dtx 代码（仅用于示例）。

我试图了解何时创建索引以及何时不创建索引，以及这如何受到 hyperref 加载的影响，但未能看到 doc.sty 命令的行为与文档所述一致。

% \iffalse
%<*driver>
\ProvidesFile{dtxcode.tex}
%</driver>
%
%<*driver>
\documentclass{ltxdoc}
% \usepackage{hyperref}

% \EnableCrossrefs  % (default) Every new macro name used within a macrocode or
                  % macrocode∗ environment will produce an index entry.
\DisableCrossrefs % turn off this feature
%
% If an index is created is determined by the use of the following
% declarations in the driver file preamble; if neither is used, no index is 
% produced.
% \PageIndex     % all index entries refer to their page number
% \CodelineIndex % index entries produced by \DescribeMacro and \DescribeEnv
               %  refer to page number but those produced by the macro
               %  environment refer to the code lines, 
               % which will be numbered automatically.
% \CodelineNumbered % no index is created, but the code lines are numbered


\RecordChanges
\listfiles

\begin{document}
  \DocInput{dtxcode.tex}
  \PrintIndex
\end{document}
%</driver>
% \fi
%%
% \DescribeMacro{\foobar} Prints out foobar \index{test}
% 
% \Finale
\endinput

在此代码中，索引由\DisableCrossrefs和创建DisableCrossrefs

但是如果我另外加载包 hyperref，无论我激活什么命令，索引都会完全消失。创建的索引文件仍然相同 - 只是没有加载。

并且如果我\CodelineNumbered在加载 hyperref 时使用，索引会再次出现，但根据 doc.sty 的文档，它不应该出现。

对我来说，这看起来像是 ltxdoc/doc.sty 中的一个错误。

编辑：以下是场景及其结果的列表。在所有情况下，idx 文件在执行前都被删除，并且 pdf 是用pdflatex、makeindex.exe -s gind.ist %.idx、pdflatex

（a）无超链接，\EnableCrossrefs 和 \PageIndex

%\usepackage{hyperref}
\EnableCrossrefs
\PageIndex

索引已创建。

（b）无超链接，\DisableCrossrefs 和 \PageIndex

%\usepackage{hyperref}
\DisableCrossrefs
\PageIndex

索引已创建（但不应该创建吗？）

（c）无超链接，\DisableCrossrefs 和 \CodelineNumbered

%\usepackage{hyperref}
\DisableCrossrefs
\CodelineNumbered

未创建索引，idx 文件为空。

（d）无超链接，\EnableCrossrefs 和 \CodelineNumbered

%\usepackage{hyperref}
\EnableCrossrefs
\CodelineNumbered

未创建索引。与文档的描述相反，它似乎无法控制索引\EnableCrossrefs。\DisableCrossrefs

（e）使用 hyperref、\EnableCrossrefs 和 \PageIndex

\usepackage{hyperref}
\EnableCrossrefs
\PageIndex

\indexidx 文件已创建，但仅显示自定义条目。在这种情况下test，但不是foobar，尽管两者都在 idx 文件中，

\indexentry{foobar=\verb!*+\foobar+|usage|hyperpage}{1}
\indexentry{test|hyperpage}{1}

（f）使用 hyperref、\EnableCrossrefs 和 \CodelineNumbered

\usepackage{hyperref}
\EnableCrossrefs
\CodelineNumbered

由于没有 hyperref，因此不会创建 idx 文件。

总结一下：加载 hyperref 不会影响索引文件的创建，但在 pdf 编译过程中不会包含 doc.sty 的索引条目。

答案1

\EnableCrossrefs和\DisableCrossrefs

这些宏控制是否对环境内的命令名称macrocode进行macrocode*索引。从包装文件doc：

2.7 交叉引用所有使用的宏

\DisableCrossrefs，\EnableCrossrefs

如前所述，在macrocode 或macrocode*环境中使用的每个新宏名称都会生成一个索引条目。这样，人们可以轻松找出特定宏的使用位置。由于 TeX 在生成如此大量的索引条目时会变得非常慢，因此可以使用\DisableCrossrefs驱动程序文件中的 来关闭此功能。要再次打开它，只需使用\EnableCrossrefs。

索引生成

与往常一样，索引生成由\makeindex.Macros触发\CodelineIndex，或者\PageIndex也可以调用\makeindex。

病例讨论

我已经扩展dtxcode.tex以显示以下效果\EnableCrossrefs：

%    \begin{macrocode}
\def\foobar{...}
%    \end{macrocode}

（a）否hyperref，\EnableCrossrefs并且\PageIndex：

\indexentry{foobar=\verb!*+\foobar+|usage}{1}
\indexentry{test}{1}
\indexentry{def=\verb!*+\def+}{1}
\indexentry{foobar=\verb!*+\foobar+}{1}

⇒ 基于整页的索引。

（e）与hyperref，\EnableCrossrefs以及\PageIndex：

\indexentry{foobar=\verb!*+\foobar+|usage|hyperpage}{1}
\indexentry{test|hyperpage}{1}
\indexentry{def=\verb!*+\def+|hyperpage}{1}
\indexentry{foobar=\verb!*+\foobar+|hyperpage}{1}

\DescribeMacro⇒ 基于整页的索引，但/的索引条目错误\usage，因为hyperref不直接支持 的索引格式doc。

（b）否hyperref，\DisableCrossrefs并且\PageIndex：

\indexentry{foobar=\verb!*+\foobar+|usage}{1}
\indexentry{test}{1}

\DescribeMacro⇒ 仅为和索引条目\index。

（c）、（d）和（f）无/有hyperref，\DisableCrossrefs/\EnableCrossrefs和\CodelineNumbered：

⇒ 根本没有索引，因为\makeindex或\PageIndex或之一\CodelineIndex缺失。

链接索引条目

包裹hypdoc可以代替使用hyperref：它加载包hyperref，禁用对hyperref包的索引支持（ ），并实现对包的索引命令hyperindex=false的支持。但是，对于普通命令，没有添加，因此需要添加（）。dochyperpage\index\index{test|hyperpage}

% \iffalse
%<*driver>
\ProvidesFile{dtxcode.tex}
%</driver>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{hypdoc}

\EnableCrossrefs

\PageIndex
%\CodelineIndex

\RecordChanges
\listfiles

\begin{document}
  \DocInput{dtxcode.tex}
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \DescribeMacro{\foobar} Prints out foobar \index{test|hyperpage}.
%
%    \begin{macrocode}
\def\foobar{...}
%    \end{macrocode}
%
% \Finale
\endinput

dtxcode.idx然后包含：

\indexentry{foobar=\verb!*+\foobar+|hdclindex{2}{usage}}{1}
\indexentry{test|hyperpage}{1}
\indexentry{def=\verb!*+\def+|hdpindex{}}{1}
\indexentry{foobar=\verb!*+\foobar+|hdpindex{}}{1}

并且所有条目均已链接。

相关内容