From 779e1e8aae671dfb73e0c5a19791be243af01cbe Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Sat, 10 Jun 2023 03:04:15 +0000
Subject: CTAN sync 202306100304

---
 macros/latex/base/doc.dtx | 248 ++++++++++++++++++++++++++--------------------
 1 file changed, 139 insertions(+), 109 deletions(-)

(limited to 'macros/latex/base/doc.dtx')

diff --git a/macros/latex/base/doc.dtx b/macros/latex/base/doc.dtx
index d137038d63..75e04cc299 100644
--- a/macros/latex/base/doc.dtx
+++ b/macros/latex/base/doc.dtx
@@ -1,7 +1,7 @@
 % \iffalse meta-comment
 %
-% Copyright 1993-2022
-% The LaTeX3 Project and any individual authors listed elsewhere
+% Copyright (C) 1993-2023
+% The LaTeX Project and any individual authors listed elsewhere
 % in this file.
 %
 % This file is part of the LaTeX base system.
@@ -45,7 +45,7 @@
 %<+package>
 %<+package>\ProvidesPackage{doc}
 %<+shortvrb>\ProvidesPackage{shortvrb}
-%<+package|shortvrb>  [2022/07/03 v3.0k
+%<+package|shortvrb>  [2022/11/13 v3.0m
 %<+package|shortvrb>   Standard LaTeX documentation package V3 (FMi)]
 %\catcode`\<=12
 %
@@ -82,6 +82,8 @@
 %  \changes{v1.9a}{1993/12/02}{Upgrade for LaTeX2e}
 %  \changes{v1.9d}{1993/12/20}{Protected changes entry.}
 %  \changes{v1.0p}{1994/05/21}{Use new error commands}
+%  \changes{v3.0m}{2022/11/13}{Redefinitions of \cs{verb} removed as
+%     no longer needed (gh/953)}
 %
 %
 % \hyphenation{make-index}
@@ -1208,7 +1210,7 @@
 % not to exceed this limit when describing the change. The actual
 % entry consists of the \meta{version}, the |\actualchar|, the current
 % macro name, a colon, the |\levelchar|, and, finally, the \meta{text}.
-% The result is a glossaryentry for the \meta{version}, with the name of
+% The result is a glossary entry for the \meta{version}, with the name of
 % the current macro as subitem.  Outside the |macro| environment, the
 % text |\generalname| is used instead of the macro name.  When
 % referring to macros in change descriptions it is conventional to use
@@ -1216,6 +1218,13 @@
 % and using up valuable characters in the entry with old \prg{makeindex}
 % versions.
 %
+% Note that in the history listing, the entry is shown with the page number
+% that corresponds to its place in the source, e.g., general changes put at the
+% very beginning of the file will show up with page number ``1'', change entries
+% placed elsewhere might have different numbers (not necessarily always
+% very useful unless you are careful).
+%
+%
 % \changes{v1.7a}{1992/02/26}{Description of \cs{RecordChanges} etc.
 % added
 % to interface section.} \DescribeInterfaceMacro\RecordChanges To cause the
@@ -1824,8 +1833,8 @@
 %        July 1989.
 %    \bibitem{art:docstrip} \textsc{Frank Mittelbach, Denys Duchier and
 %         Johannes Braams}.
-%      \newblock \texttt{docstrip.dtx} (to appear).
-%      \newblock The file is part of the DOC package.
+%      \newblock \texttt{docstrip.dtx}.
+%      \newblock The file is part of core \LaTeX{}.
 %    \bibitem{book:Raspe} \textsc{R. E. Raspe} (*1737, \dag 1797).
 %      \newblock Baron Münchhausens narrative of his marvelous
 %                travels and campaigns in Russia.
@@ -2686,12 +2695,16 @@
 %    first lines are copied literally from \texttt{latex.tex}.
 % \changes{v1.7i}{1992/07/12}{Added \cs{@@par} to clear possible
 %                             \cs{parshape}.}
+%  \changes{v3.0m}{2022/11/13}{Redefinitions of \cs{@verbatim} changed
+%     to match the kernel definition (gh/953)}
 %    \begin{macrocode}
-\def\@verbatim{\trivlist \item[]\if@minipage\else\vskip\parskip\fi
-      \leftskip\@totalleftmargin\rightskip\z@
-      \parindent\z@\parfillskip\@flushglue\parskip\z@
-      \@@par
-      \@tempswafalse
+\def\@verbatim{\trivlist \item\relax
+  \if@minipage\else\vskip\parskip\fi
+  \leftskip\@totalleftmargin\rightskip\z@
+  \parindent\z@\parfillskip\@flushglue\parskip\z@
+  \language\l@nohyphenation
+  \@@par
+  \@tempswafalse
 %    \end{macrocode}
 %    |\@verbatim| sets |^^M|, the end of line character, to
 %    be equal to |\par|.  This control sequence is redefined
@@ -2699,8 +2712,13 @@
 %    \changes{v1.7c}{1992/03/24}{Added \cs{interlinepenalty} to
 %                             \cs{par} from verbatim.sty}
 %    \begin{macrocode}
- \def\par{\if@tempswa\hbox{}\fi\@tempswatrue\@@par
-          \penalty\interlinepenalty
+  \def\par{%
+    \if@tempswa
+      \leavevmode \null \@@par\penalty\interlinepenalty
+    \else
+      \@tempswatrue
+      \ifhmode\@@par\penalty\interlinepenalty\fi
+    \fi    
 %    \end{macrocode}
 %    We add a control sequence |\check@percent| to the definition
 %    of |\par| whose task it is to check for a percent character.
@@ -2713,9 +2731,10 @@
 % \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim,
 %                           which handles more ligatures.}
 %    \begin{macrocode}
- \obeylines
- \let\do\do@noligs \verbatim@nolig@list
- \let\do\@makeother \dospecials}
+  \let\do\@makeother \dospecials
+  \obeylines \verbatim@font \@noligs
+  \everypar \expandafter{\the\everypar \unpenalty}%
+}
 %    \end{macrocode}
 % \end{macro}
 %
@@ -2744,83 +2763,12 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{imacro}{\verb}
-% \changes{v1.7a}{1992/02/27}{Now warns about newlines (from
-%                           newdoc with `@noligs added).}
-% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX \cs{verb}}
-% We re-define |\verb| to check for newlines in its argument since a
-% missing delimiter is difficult to detect in \DOC{} source.
-% The code is the same as in \texttt{latex.tex} of September 19, 1993.
-% Perhaps there should be a font-changing
-% hook rather than just using |\ttfamily|, but if so it probably should be
-% different from |\MacroFont| since that normally includes |\small|
-% and would look wrong inline.
-% \changes{v1.7a}{1992/02/28}{Added math mode check (from verbatim.sty)}
-%    \begin{macrocode}
-\def\verb{\relax\ifmmode\hbox\else\leavevmode\null\fi
-  \bgroup \let\do\do@noligs \verbatim@nolig@list
-    \ttfamily \verb@eol@error \let\do\@makeother \dospecials
-    \@ifstar{\@sverb}{\@vobeyspaces \frenchspacing \@sverb}}
-%    \end{macrocode}
-% \end{imacro}
-%
-% \begin{macro}{\verb@balance@group}
-% \begin{macro}{\verb@egroup}
-% \begin{macro}{\verb@eol@error}
-% \changes{v1.8b}{1993/09/21}{Renamed \cs{verb@err} to
-%                   \cs{verb@eol@error}, as in new LaTeX verbatim.}
-%    \begin{macrocode}
-\let\verb@balance@group\@empty
-%    \end{macrocode}
-%
-%    \begin{macrocode}
-\def\verb@egroup{\global\let\verb@balance@group\@empty\egroup}
-%    \end{macrocode}
-%
-%    \begin{macrocode}
-\begingroup
-  \obeylines%
-  \gdef\verb@eol@error{\obeylines%
-    \def^^M{\verb@egroup\@latex@error{%
-            \noexpand\verb command ended by end of line}\@ehc}}%
-\endgroup
-%    \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\@sverb}
-% \changes{v1.7a}{1992/02/27}{Added for \cs{verb} change.}
-% \changes{v1.7a}{1992/02/28}{Now same as in verbatim.sty.}
-% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim,
-%                           which has better error trapping.}
-% See \cite{art:verbatim} for commentary.
-%  \changes{v2.1j}{2019/11/03}{Use the kernel definition, no change needed (gh/205)}
-%    \begin{macrocode}
-%\def\@sverb#1{%
-%  \catcode`#1\active  \lccode`\~`#1%
-%  \gdef\verb@balance@group{\verb@egroup
-%     \@latex@error{Illegal use of \noexpand\verb command}\@ehc}%
-%  \aftergroup\verb@balance@group
-%  \lowercase{\let~\verb@egroup}}
-%    \end{macrocode}
-% \end{macro}
-%
 %
-% \begin{macro}{\verbatim@nolig@list}
-% \begin{macro}{\do@noligs}
-%     These macros replace the old |\@noligs| mechanism by an
-%     extensible version to allow more ligatures to be added.
-%    \begin{macrocode}
-\def\verbatim@nolig@list{\do\`\do\<\do\>\do\,\do\'\do\-}
-\def\do@noligs#1{%
-  \catcode`#1\active
-  \begingroup
-     \lccode`\~=`#1\relax
-     \lowercase{\endgroup\def~{\leavevmode\kern\z@\char`#1}}}
-%    \end{macrocode}
-% \end{macro}
-% \end{macro}
+% In the early versions of the package it also redefined \cs{verb}
+% because that didn't include the useful test for \enquote{newline} in
+% the verbatim text. This is nowadays part of \LaTeX{} so we do not
+% redefine it any longer (the original code is still kept in the file
+% after \cs{endinput} to keep the long history intact).
 %
 % \begin{tcounter}{\macro@cnt}
 %    \label{page:macro} The \env{macro} environment is implemented as
@@ -3147,9 +3095,6 @@
 %
 % \begin{macro}{\short@macro}
 %
-% \fmi{this needs cleaning up too, the results in the index are
-% currently wrong for cases like `\cs{ }' and the like.}
-%
 % \changes{v1.5c}{1989/04/27}{Corrected bad bug by putting the
 %                         scan@allowedfalse macro before printing
 %                         the argument.}
@@ -3164,17 +3109,14 @@
 %    done by the |\ifnot@excluded| macro which assumes that the
 %    macro name is saved in |\macro@namepart|.  The character
 %    mustn't be stored with a special category code or exclusion from
-%    the index won't work, so we employ the case-changing trick used
-%    elsewhere.  Since the argument might be an active character,
-%    |\string| is used to normalize it.
+%    the index won't work, so we we use \cs{string} to normalize it
+%    the same way it is done in \cs{DoNotIndex}, i.e. everything ends up catcode 12
+%    except for the space character.
 % \changes{v2.0e}{1998/12/28}{Correctly use the case-changing trick.}
+% \changes{v3.0l}{2022/11/03}{No longer using the case-changing trick.}
 %    \begin{macrocode}
-\begingroup
-\catcode`\&=12
-\gdef\short@macro#1{\begingroup
-   \uccode`\&=\expandafter`\string#1%
-   \uppercase{\def\x{\def\macro@namepart{&}}}%
-   \expandafter\endgroup\x
+\def\short@macro#1{%
+   \edef\macro@namepart{\string#1}%
 %    \end{macrocode}
 %    Any indexing is then delegated to
 %    |\maybe@index@short@macro|. Depending on the actual character seen,
@@ -3197,7 +3139,6 @@
 %    cross-referencing is globally disabled.
 %    \begin{macrocode}
     \scan@allowedtrue }
-\endgroup
 %    \end{macrocode}
 % \end{macro}
 %
@@ -3441,7 +3382,6 @@
 \def \ShowIndexingState {
   \__doc_trace:x{Show~ doc~ indexing~ state:}
   \seq_show:N  \l__doc_donotindex_seq
-%  \tl_analysis_show:N\l__doc_donotindex_seq
   \prop_show:N \g__doc_idxtype_prop
 }
 %    \end{macrocode}
@@ -3637,10 +3577,12 @@
 %  \begin{macro}{\maybe@index@short@macro}
 %  \begin{macro}{\__doc_maybe_index_short:o}
 %    Single character macros are handled similarly but there the
-%    indexing is done by \cs{SpecialShortIndex}.
+%    indexing is done by \cs{SpecialShortIndex} and it is simpler
+%    because we know that the argument contains a string token not letters.
+% \changes{v3.0l}{2022/11/03}{We know the argument expands to a single string token}
 %    \begin{macrocode}
 \cs_new:Npn \__doc_maybe_index_short:o #1 {
-  \exp_args:Nf \__doc_maybe_index_aux:nN { \tl_to_str:o {#1} }
+  \exp_args:No \__doc_maybe_index_aux:nN #1
                                          \SpecialShortIndex
 }
 \cs_set_eq:NN \maybe@index@short@macro \__doc_maybe_index_short:o
@@ -3715,7 +3657,12 @@
           {\cs_to_str:N \^^M } {\def\reserved@a{ \string \space \actualchar }
                                 \def\reserved@b { \space }
                                 \let\reserved@c \@empty                          }
-          { }                  {\def\reserved@a{ \string \space \actualchar }
+%    \end{macrocode}
+%    With the fix for
+%    \verb*=\ = we now have to look for a real space to handle that command sequence.
+% \changes{v3.0l}{2022/11/03}{look for the right token}
+%    \begin{macrocode}
+          { ~ }                {\def\reserved@a{ \string \space \actualchar }
                                 \def\reserved@b { \space }
                                 \let\reserved@c \@empty                          }
           {\c_left_brace_str} { \def\reserved@a{ \bgroup \actualchar }
@@ -6256,6 +6203,89 @@
 %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \endinput
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+% \section{Code no longer used}
+%
+% \begin{imacro}{\verb}
+% \changes{v1.7a}{1992/02/27}{Now warns about newlines (from
+%                           newdoc with `@noligs added).}
+% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX \cs{verb}}
+% We re-define |\verb| to check for newlines in its argument since a
+% missing delimiter is difficult to detect in \DOC{} source.
+% The code is the same as in \texttt{latex.tex} of September 19, 1993.
+% Perhaps there should be a font-changing
+% hook rather than just using |\ttfamily|, but if so it probably should be
+% different from |\MacroFont| since that normally includes |\small|
+% and would look wrong inline.
+% \changes{v1.7a}{1992/02/28}{Added math mode check (from verbatim.sty)}
+%    \begin{macrocode}
+%\def\verb{\relax\ifmmode\hbox\else\leavevmode\null\fi
+%  \bgroup \let\do\do@noligs \verbatim@nolig@list
+%    \ttfamily \verb@eol@error \let\do\@makeother \dospecials
+%    \@ifstar{\@sverb}{\@vobeyspaces \frenchspacing \@sverb}}
+%    \end{macrocode}
+% \end{imacro}
+%
+% \begin{macro}{\verb@balance@group}
+% \begin{macro}{\verb@egroup}
+% \begin{macro}{\verb@eol@error}
+% \changes{v1.8b}{1993/09/21}{Renamed \cs{verb@err} to
+%                   \cs{verb@eol@error}, as in new LaTeX verbatim.}
+%    \begin{macrocode}
+%\let\verb@balance@group\@empty
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+%\def\verb@egroup{\global\let\verb@balance@group\@empty\egroup}
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+%\begingroup
+%  \obeylines%
+%  \gdef\verb@eol@error{\obeylines%
+%    \def^^M{\verb@egroup\@latex@error{%
+%            \noexpand\verb command ended by end of line}\@ehc}}%
+%\endgroup
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@sverb}
+% \changes{v1.7a}{1992/02/27}{Added for \cs{verb} change.}
+% \changes{v1.7a}{1992/02/28}{Now same as in verbatim.sty.}
+% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim,
+%                           which has better error trapping.}
+% See \cite{art:verbatim} for commentary.
+%  \changes{v2.1j}{2019/11/03}{Use the kernel definition, no change needed (gh/205)}
+%    \begin{macrocode}
+%\def\@sverb#1{%
+%  \catcode`#1\active  \lccode`\~`#1%
+%  \gdef\verb@balance@group{\verb@egroup
+%     \@latex@error{Illegal use of \noexpand\verb command}\@ehc}%
+%  \aftergroup\verb@balance@group
+%  \lowercase{\let~\verb@egroup}}
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\verbatim@nolig@list}
+% \begin{macro}{\do@noligs}
+%     These macros replace the old |\@noligs| mechanism by an
+%     extensible version to allow more ligatures to be added.
+%    \begin{macrocode}
+%\def\verbatim@nolig@list{\do\`\do\<\do\>\do\,\do\'\do\-}
+%\def\do@noligs#1{%
+%  \catcode`#1\active
+%  \begingroup
+%     \lccode`\~`#1\relax
+%     \lowercase{\endgroup\def~{\leavevmode\kern\z@\char`#1}}}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+
 
 ^^A  Needed for emacs
 ^^A
-- 
cgit v1.2.3

