☰

l3doc 中的 \cs{} 命令不尊重 \DoNotIndex？

tag-icon • tag-icon l3doc
l3doc 中的 \cs{} 命令不尊重 \DoNotIndex？

考虑这个 TeX 文件（是的，我知道不使用 dtx 是非常不寻常的。）

%%! TEX program = lualatex
\documentclass{l3doc}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\fvset{gobble=0,tabsize=4,frame=single,numbers=left,numbersep=3pt}
\usepackage{hyperref}
\usepackage{csquotes}

%\MakeOuterQuote{"}
\begin{document}
\GetFileInfo{\jobname.tex}
 \DoNotIndex{\endlinechar,\newcommand}

\title{\pkg{somenewpackage} --- Description
\thanks{This file describes version \fileversion, last revised \filedate.}
}
\author{user202729%
%\thanks{E-mail: (not set)}
}
\date{Released \filedate}

\maketitle


\section{Motivation}


The braces around \verb+{\data}+ is optional; however, in the unlikely case if \cs{endlinechar} has the \enquote{letter} catcode, it might be absorbed and gives unexpected result.

\cs{mycommand}

    \begin{macrocode}
\newcommand{\dummyMacro}{}
%    \end{macrocode}


\StopEventually{%
  \PrintChanges
  \PrintIndex
}
\Finale
\end{document}

如果没有\DoNotIndex，则\endlinechar、\mycommand（出现在 中\cs{...}）和\newcommand（出现在macrocode块中）将包含在索引中。

随着它，\newcommand消失但\endlinechar仍然存在。

发生了什么事？（不用说我在 l3doc 手册中没有看到这个）&我该怎么办？

（实际上回想起来，\cs{...}应该如此\tn。但无论如何，问题仍然存在）

我可以看到一些选项

  • 使用|\endlinechar|或"\endlinechar"代替来\cs{endlinechar}排版？（......顺便说一下，这似乎是 l3doc 中另一个未记录的东西，它会自动生成|一个"短动词......？）
  • 就这样处理？
  • 还要别的吗？

答案1

据我所知，它根本不受支持。

该命令\DoNotIndex是从doc包继承的，但是（在我看来）文档很容易被误解：

doc 包文档的引用

“这些名称不会显示在索引中”仅适用于“macrocode或macrocode*环境中使用的每个新宏名称”。其他索引条目（例如由命令生成的\index或直接写入索引文件的条目）将不予涵盖。

目前的实施（此版本的 l3doc.dtx）\cs由

\DeclareDocumentCommand \cs  { O{} m }
  { \@@_cmd:no {#1} { \c_backslash_str #2 } }

[...]

\cs_new_protected:Npn \@@_cmd:nn #1#2
  {
    \bool_set_false:N \l_@@_cmd_noindex_bool
    \bool_set_true:N \l_@@_cmd_replace_bool
    \tl_set:Nn \l_@@_cmd_index_tl { \q_no_value }
    \tl_set:Nn \l_@@_cmd_module_tl { \q_no_value }

[...]

% Indexing.
%    \begin{macrocode}
    \bool_if:NT \l_@@_allow_indexing_bool
     {
      \bool_if:NF \l_@@_cmd_noindex_bool
       {
        \quark_if_no_value:NF \l_@@_cmd_index_tl
          {
            \__kernel_tl_set:Nx \l_@@_cmd_tl
              { \c_backslash_str \exp_not:o { \l_@@_cmd_index_tl } }
          }
        \exp_args:No \@@_key_get:n { \l_@@_cmd_tl }
        \quark_if_no_value:NF \l_@@_cmd_module_tl
          {
            \__kernel_tl_set:Nx \l_@@_index_module_tl
              { \tl_to_str:N \l_@@_cmd_module_tl }
          }
        \@@_special_index_module:ooonN
          { \l_@@_index_key_tl }
          { \l_@@_index_macro_tl }
          { \l_@@_index_module_tl }
          { usage }
          \l_@@_index_internal_bool
       }
     }

[...]
     
\cs_new_protected:Npn \@@_special_index_module:nnnnN #1#2#3#4#5
%    \end{macrocode}
% \begin{arguments}
% \item key
% \item macro
% \item module
% \item index `type' (\texttt{main}/\texttt{usage}/\emph{etc.})
% \item boolean whether internal command
% \end{arguments}
%    \begin{macrocode}
  {
    \use:x
      {
        \exp_not:n { \@@_special_index_aux:nnnnnn {#1} {#2} }
          \tl_if_empty:nTF {#3}

[...]

\cs_new_protected:Npn \@@_special_index_aux:nnnnnn #1#2#3#4#5#6
%    \end{macrocode}
% \begin{arguments}
% \item key
% \item macro
% \item index subheading string
% \item index subheading text
% \item index subheading suffix (appended to both arg 3 and 4)
% \item index `type' (\texttt{main}/\texttt{usage}/\emph{etc.})
% \end{arguments}
%    \begin{macrocode}
  {
    \tl_set:Nn \l_@@_index_escaped_key_tl {#1}
    \@@_quote_special_char:N \l_@@_index_escaped_key_tl
    \@@_special_index_set:Nn \l_@@_index_escaped_macro_tl {#2}
    \str_if_eq:onTF { \@currenvir } { macrocode }
      { \@@_index_codeline_hc:nn }
      {
        \str_case:nnF {#6}
          {
            { main }  { \@@_index_codeline_hc:nn }
            { usage } { \@@_index_page_hc:nn }
          }
          { \@@_target: \@@_index_page_hc:nn }
      }
      {
        \tl_if_empty:nF { #3 #4 #5 }
          { #3 #5 \actualchar #4 #5 \levelchar }
        \l_@@_index_escaped_key_tl
        \actualchar
        {

[...]


\cs_new_protected:Npn \@@_index_codeline_hc:nn #1#2
  {
    \immediate\write\@indexfile
      {
        \string \indexentry { #1 \encapchar hdclindex{\the\c@HD@hypercount}{#2} }
          { MMMMV - \filesep \int_use:N \c@CodelineNo - MMMD - \the\c@HD@hypercount - M }
      }
  }

可以看出，索引条目是直接写入的，而无需查阅索引排除列表（请参阅doc包文档的第 3.7 节）。

总之，只需使用|...|即可。在我看来，源代码的语义含义几乎没有损失。（尽管如果你真的想要，你也可以修补\__codedoc_cmd:nn以查阅\index@excludelist列表）

相关内容