summaryrefslogtreecommitdiff
path: root/macros/latex/base/doc.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-06-10 03:04:15 +0000
committerNorbert Preining <norbert@preining.info>2023-06-10 03:04:15 +0000
commit779e1e8aae671dfb73e0c5a19791be243af01cbe (patch)
treea9dba6085be5122eec4a3659d01dd33a5b1c774b /macros/latex/base/doc.dtx
parent33607c11aca40cfb1f454d818091f19aa47ba651 (diff)
CTAN sync 202306100304
Diffstat (limited to 'macros/latex/base/doc.dtx')
-rw-r--r--macros/latex/base/doc.dtx248
1 files changed, 139 insertions, 109 deletions
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