summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/doc.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/doc.dtx')
-rw-r--r--macros/latex-dev/base/doc.dtx223
1 files changed, 98 insertions, 125 deletions
diff --git a/macros/latex-dev/base/doc.dtx b/macros/latex-dev/base/doc.dtx
index 75e04cc299..82eb8dc5b8 100644
--- a/macros/latex-dev/base/doc.dtx
+++ b/macros/latex-dev/base/doc.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2023
+% Copyright (C) 1993-2024
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
@@ -45,7 +45,7 @@
%<+package>
%<+package>\ProvidesPackage{doc}
%<+shortvrb>\ProvidesPackage{shortvrb}
-%<+package|shortvrb> [2022/11/13 v3.0m
+%<+package|shortvrb> [2024/02/08 v3.0o
%<+package|shortvrb> Standard LaTeX documentation package V3 (FMi)]
%\catcode`\<=12
%
@@ -57,7 +57,7 @@
%
%
%% Package `doc' to use with LaTeX 2e
-%% Copyright (C) 1989-2022 Frank Mittelbach, all rights reserved.
+%% Copyright (C) 1989-2023 Frank Mittelbach, all rights reserved.
%
%
% Version: Date: Changes:
@@ -143,8 +143,8 @@
% \MakeShortVerb{\|}
% \setcounter{StandardModuleDepth}{1}
%
-% {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print
-% \gdef\dimenvalue#1pt{$#1$pt}} ^^A a register value with a - sign
+% {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print a
+% \gdef\dimenvalue#1pt{$#1$pt}} ^^A register value with a - sign
%
% \newcommand{\DOC}{\texttt{doc}\xspace}
%
@@ -167,7 +167,7 @@
%\RenewDocElement[macrolike = true ,
% toplevel = false,
% idxtype = ,
-% idxgroup = LaTeX comands\actualchar\LaTeX{} commands ,
+% idxgroup = LaTeX commands\actualchar\LaTeX{} commands ,
% printtype =
% ]{Macro}{macro}
%
@@ -237,7 +237,7 @@
% \changes{v1.9t}{1995/05/11}{Use \cs{GetFileInfo}}
% \GetFileInfo{doc.sty}
%
-% \CheckSum{0} ^^A % keep the checksum in this file but not now :-)
+% \CheckSum{0}
%
% \title{The \DOC{} and \texttt{shortvrb} Packages\thanks
% {This file has version number \fileversion{} dated \filedate{}.}}
@@ -595,7 +595,16 @@
% class file (like \texttt{ltugboat.cls}) use the |\DocstyleParms|
% command described below. Starting with release 2.0a it can now
% be changed directly as long as the redefinition happens before
-% the |\begin{document}|.
+% the |\begin{document}| (if you change it later you might see strange
+% typesetting effects if you are unlucky).
+%
+% |\MacroFont| does not alter the font of
+% |\verb| or |\verb*| because it is often used to make the font size of
+% the code displays smaller, which would look odd if used within a
+% paragraph. If you decide to use a different font family and want to
+% use the same family with
+% |\verb| you need to alter the font setup for |\ttfamily| in addition
+% to |\MacroFont|.
%
% \DescribeEnv{environment}
% For documenting the definition of environments one can use the
@@ -695,6 +704,12 @@
% |\NewDocElement{Env}{environment}|
% though that's not quite what has been done, as we will see later.
%
+% \DescribeInterfaceMacro{\ProvideDocElement}
+% This declaration does nothing when the doc element is already
+% declared, otherwise it works like \cs{NewDocElement}. It can be
+% useful if you have many documentation files that you may want to
+% process individually as well as together.
+%
% \DescribeOption[noprint]{macrolike}
% \DescribeOption[noprint]{envlike}
% \DescribeOption[noprint]{toplevel}
@@ -1367,7 +1382,7 @@
%\RenewDocElement[macrolike = true ,
% toplevel = false,
% idxtype = ,
-% idxgroup = LaTeX comands\actualchar\LaTeX{} commands ,
+% idxgroup = LaTeX commands\actualchar\LaTeX{} commands ,
% printtype =
% ]{Macro}{macro}
%\end{verbatim}
@@ -1515,7 +1530,7 @@
%
% Thirty years is a long time in the life of computer programs, so
% there are a good number of interfaces within \DOC that are really
-% only of historical interest (or when processing equally old sources.
+% only of historical interest (or when processing equally old sources).
% We list them here, but in general we suggest that for new
% documentation they should not be used.
%
@@ -2108,9 +2123,12 @@
% that is, they must be given |\catcode| $12$.
% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim,
% which handles more ligatures.}
+% \changes{v3.0o}{2023/12/30}{Use \cs{@noligs} from the \LaTeX\
+% kernel, so that the \texttt{upquote} package can
+% add its patch (gh/1230)}
% \begin{macrocode}
\obeylines
- \let\do\do@noligs \verbatim@nolig@list
+ \@noligs
\let\do\@makeother \dospecials
% \end{macrocode}
% \changes{v1.5t}{1989/11/07}{Common code added.}
@@ -2183,7 +2201,7 @@
% \changes{v1.7a}{1992/03/13}{Added \cs{reset@font} for NFSS.}
% \changes{v1.8c}{1993/10/25}{NFSS standard}
% \changes{v1.9t}{1995/05/26}{Removed \cs{math@fontsfalse} (different
-% math setup /pr1622}
+% math setup /pr1622)}
% \begin{macrocode}
\@ifundefined{MacroFont}{%
\if@compatibility
@@ -2220,7 +2238,7 @@
% \changes{v1.7m}{1992/10/11}{Use sltt as default.}
% \changes{v1.8c}{1993/10/25}{NFSS standard}
% \changes{v1.9t}{1995/05/26}{Removed \cs{math@fontsfalse} (different
-% math setup /pr1622}
+% math setup /pr1622)}
% Although most of the macro code is set in |\MacroFont| we want to be
% able to switch to indicate module code set in |\AltMacroFont|.
% |\macro@font| keeps track of which one we're using. We can't do the
@@ -2681,7 +2699,7 @@
% \end{macrocode}
%
% \changes{v2.1j}{2019/11/03}{Kernel now sets up \cs{verbvisiblespace} (gh/205)}
-% \changes{v2.1k}{2019/11/10}{Put the definition into the right command :-( (gh/205)}
+% \changes{v2.1k}{2019/11/10}{Put the definition into the right command (gh/205)}
% \begin{macrocode}
\@setupverbvisiblespace
\MacroFont \@vobeyspaces \@sxverbatim}
@@ -2895,32 +2913,32 @@
% following tasks:
% \begin{itemize}
% \parindent4em
-% \item[1)]
+% \item[(1)]
% |\catcode| all characters used in macro names to
-% 11 (i.e.\ `letter').
-% \item[2)]
+% 11 (i.e., `letter').
+% \item[(2)]
% |\catcode| the `|\|' character to 13
-% (i.e.\ `active').
-% \item[3a)]
+% (i.e., `active').
+% \item[(3a)]
% |\let| the `|\|' equal |\scan@macro|
-% (i.e.\ start the macro scanning mechanism) if there is
-% no special escape character (i.e.\ the
+% (i.e., start the macro scanning mechanism) if there is
+% no special escape character (i.e., the
% |\special@escape@char| is `|\|').
-% \item[3b)]
+% \item[(3b)]
% Otherwise |\let| it equal |\bslash|, i.e.\
% produce a printable |\|.
-% \item[4)]
+% \item[(4)]
% Make the \meta{special escape character} active.
-% \item[5)]
+% \item[(5)]
% |\let| the active version of the special escape
% character
-% (i.e.\ the expansion of |\active@escape@char|) equal
+% (i.e., the expansion of |\active@escape@char|) equal
% |\scan@macro|.
% \end{itemize}
% The reader might ask why we bother to |\catcode| the
% `|\|' first to 12 (at the end of |\macro@code|) then
% re-|\catcode| it to 13 in order to produce a $|\|_{12}$
-% in case 3b) above. This is done because we have to ensure that
+% in case (3b) above. This is done because we have to ensure that
% `|\|' has |\catcode| 13 within the \env{macrocode}
% environment. Otherwise the delimiter for the argument of
% |\xmacro@code| would not be found (parameter matching
@@ -2930,14 +2948,14 @@
% \begin{macrocode}
\begingroup \catcode`\|=\z@ \catcode`\\=\active
% \end{macrocode}
-% We carry out tasks 2) and 3b) first.
+% We carry out tasks (2) and (3b) first.
% \SpecialEscapechar\|
% \begin{macrocode}
|gdef|init@crossref{|catcode`|\|active |let\|bslash
% \end{macrocode}
% Because of the popularity of the `|@|' character as a
% `letter' in macros, we normally have to change its
-% |\catcode| here, and thus fulfill task 1). But the macro
+% |\catcode| here, and thus fulfill task (1). But the macro
% designer might use other characters as private letters as well,
% so we use a macro to do the |\catcode| switching.
% \SpecialEscapechar\|
@@ -2945,8 +2963,8 @@
|MakePrivateLetters
% \end{macrocode}
% Now we |\catcode| the special escape character to 13 and
-% |\let| it equal |\scan@macro|, i.e.\ fulfill tasks 4)
-% and 5). Note the use of |\expandafter| to insert the chosen
+% |\let| it equal |\scan@macro|, i.e., fulfill tasks (4)
+% and (5). Note the use of |\expandafter| to insert the chosen
% escape character saved in |\special@escape@char| and
% |\active@escape@char|.
% \SpecialEscapechar\|
@@ -2955,7 +2973,7 @@
|expandafter|let|active@escape@char|scan@macro}
|endgroup
% \end{macrocode}
-% If there is no special escape character, i.e.\ if
+% If there is no special escape character, i.e., if
% |\SpecialEscapechar| is |\\|, the second last line will
% overwrite the previous definition of $|\|_{13}$. In this
% way all tasks are fulfilled.
@@ -3109,9 +3127,9 @@
% 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 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.
+% the index won't work, so 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}
@@ -3254,7 +3272,7 @@
% unnecessarily index within that part of the code. As the sequence
% is local it will revert this setting at the end of the
% environment so that the command is indexed elsewhere (unless it
-% is generally disabled from indexing.
+% is generally disabled from indexing).
%
% \DescribeMacro\g__doc_idxtype_prop
% Global property list that holds for all commands that are special
@@ -3282,7 +3300,7 @@
% \DescribeInterfaceMacro\RecordIndexType
% This command takes two arguments: a command (with escape char)
% and its type (i.e., first mandatory
-% argument of a |\NewDocElement| declaration. If |#1| should not be
+% argument of a |\NewDocElement| declaration). If |#1| should not be
% included from the index, then the data is used to record that
% this command is of this type. The information is then used to
% generate appropriate index entries. Obviously, index entries
@@ -3481,7 +3499,7 @@
% \begin{macro}{\__doc_idxtype_put:nn}
% This internal command takes two arguments: a command name as
% string (no backslash) and its type (i.e., first mandatory
-% argument of a |\NewDocElement| declaration. If |#1| is not in
+% argument of a |\NewDocElement| declaration). If |#1| is not in
% |\l__doc_donotindex_seq| it will add this data to the property
% list |\g__doc_idxtype_prop| using |#1| as key and |#2| as its
% value. If the key already exist its value will be overwritten. If
@@ -3884,7 +3902,8 @@
% \begin{imacro}{\RightBraceIndex}
% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} These
% two macros fix the problems with \prg{makeindex}. Note the
-% `hack' with |\iffalse}\fi| to satisfy both \TeX{} and the
+% `hack' with \iffalse{-to get matching braces\fi |\iffalse}\fi|
+% to satisfy both \TeX{} and the
% \prg{makeindex} program. When this is written to the
% \texttt{.idx} file \TeX{} will see both braces (so we get a
% balanced text). \prg{makeindex} will also see balanced braces
@@ -5539,7 +5558,7 @@
% \begin{macrocode}
\long\def\@doc@env#1#2#3{
% \end{macrocode}
-% The |\endgroup| here closes the scanning of names (using special catcodes.
+% The |\endgroup| here closes the scanning of names (using special catcodes).
% \begin{macrocode}
\endgroup
\clist_map_inline:nn {#3} { \@doc@env@{#1}{#2}{##1} }
@@ -5565,8 +5584,8 @@
% they are technically part of the generated API, only not meant for public
% use.
%
-% \fmi{above docu is no longer right (but code needs further changes
-% anyway}
+% \fmi{above docu is no longer right (but code probably needs further changes
+% anyway)}
%
% |#1| is either \texttt{TT} (for true = macrolike) or \texttt{TF}.
% If true then we drop the first char from |\saved@macroname| and
@@ -5580,7 +5599,7 @@
% If the \DOC element described is macrolike but not a normal
% ``macro'' then its type should be recorded and this is the places
% where this happens. For macros (which should make up the bulk of
-% these items we don't do this and for anything else that looks
+% these items) we don't do this and for anything else that looks
% from an indexing perspective like a macro we don't do that either
% to keep the list of exceptions small. That would be the case if
% the indexing command |\Code|\meta{doc-element}|Index| is
@@ -5635,7 +5654,7 @@
\fi
% \end{macrocode}
% Suppress further |\index| entries when we are within a
-% \texttt{macrolike} environment. (There is no point doing that for
+% \texttt{macrolike} environment. There is no point doing that for
% non-\texttt{macrolike} environments are index entries are only
% generated for items starting with a backslash anyway.
% \fmi{fix}
@@ -5940,6 +5959,16 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\doc@ignoredinfo}
+%
+% \begin{macrocode}
+\def\doc@ignoredinfo#1#2{%
+ \PackageInfo{doc}{Doc element '#1/#2' declaration
+ ignored}%
+}
+% \end{macrocode}
+% \end{macro}
+%
%
% \begin{imacro}{\NewDocElement}
% \oarg{options}\marg{name}\marg{envname}
@@ -5963,6 +5992,30 @@
% \end{macrocode}
% \end{imacro}
%
+% \begin{imacro}{\ProvideDocElement}
+% \oarg{options}\marg{name}\marg{envname}
+% This does nothing unless the doc element could be declared with
+% \cs{NewDocElement}.
+% \begin{macrocode}
+\newcommand\ProvideDocElement[3][]{%
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \@ifundefined{Print#2Name}%
+ {\@ifundefined{PrintDescribe#2}%
+ {\@ifundefined{#3}%
+ {\@ifundefined{end#3}%
+ {\@NewDocElement{#1}}%
+ \doc@ignoredinfo
+ }\doc@ignoredinfo
+ }\doc@ignoredinfo
+ }\doc@ignoredinfo
+ {#2}{#3}%
+}
+% \end{macrocode}
+% \end{imacro}
+%
+%
% \begin{imacro}{\RenewDocElement}
% \oarg{options}\marg{name}\marg{envname}
%
@@ -6098,7 +6151,7 @@
% \end{macrocode}
-% \begin{macro}{SpecialMainIndex}
+% \begin{macro}{\SpecialMainIndex}
%
% In \DOC v2 we had \cs{SpecialMainIndex} and
% \cs{SpecialMainEnvIndex} but now with additional \DOC elements we
@@ -6110,7 +6163,7 @@
% \end{macrocode}
% \end{macro}
-% \begin{macro}{SpecialUsageIndex}
+% \begin{macro}{\SpecialUsageIndex}
% \DOC v2 also had \cs{SpecialUsageIndex} which is now called
% \cs{SpecialMacroIndex} generating the ``usage'' index entry for
% a macro. Again we provide that as an alias via |\def|.
@@ -6206,86 +6259,6 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% \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