1

Consider this TeX file (yes, I know it's highly unusual to not use dtx for this.)

%%! 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}

Without the \DoNotIndex, the \endlinechar, \mycommand (appear in \cs{...}), and \newcommand (appear in macrocode block) is included in the index.

With it, the \newcommand disappear but \endlinechar remains.

What is going on? (needless to say I don't see this in l3doc manual) & what should I do?

(actually that \cs{...} should probably be \tn, in retrospect. Either way, the problem persists)

I can see a few options

  • use |\endlinechar| or "\endlinechar" instead of \cs{endlinechar} to typeset it? (... by the way this appear to be another undocumented thing in l3doc that it automatically make | and " shortverb...?)
  • just deal with it?
  • anything else?
user202729
  • 7,143

1 Answers1

1

As far as I can see, it's simply not supported.

The command \DoNotIndex is inherited from the doc package, but (in my opinion) the documentation can easily be wrongly understood:

quote of doc package documentation

"Those names won't show up in the index" only applies for the "every new macro name used within a macrocode or macrocode* environment". Other index entries e.g. produced by \index command, or directly written to the index file, won't be covered.

The current implementation (in this version of l3doc.dtx) of \cs consist of

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

As can be seen, the index entry is written directly without consulting the index exclude list (refer to section 3.7 of doc package documentation).

In summary, just use |...| then. There's little loss in semantic meaning of the source code in my opinion. (although if you really want you could as well patch the \__codedoc_cmd:nn to consult the \index@excludelist list)

muzimuzhi Z
  • 26,474
user202729
  • 7,143