diff options
author | Norbert Preining <norbert@preining.info> | 2024-02-15 03:01:30 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2024-02-15 03:01:30 +0000 |
commit | 5b6839a58ea5468b40ebd52b579e680b8e62ff13 (patch) | |
tree | 1dfc09f53794115129a07bf566b466cc337606f5 /macros/latex-dev/base/doc.dtx | |
parent | a90336c3069c198b41b7b6eb76e3389610ad5eb7 (diff) |
CTAN sync 202402150301
Diffstat (limited to 'macros/latex-dev/base/doc.dtx')
-rw-r--r-- | macros/latex-dev/base/doc.dtx | 223 |
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 |