diff options
| author | Norbert Preining <norbert@preining.info> | 2022-01-14 03:01:14 +0000 |
|---|---|---|
| committer | Norbert Preining <norbert@preining.info> | 2022-01-14 03:01:14 +0000 |
| commit | 45623da68203ac8d7aa04b779a6ed65c92c3f866 (patch) | |
| tree | 151ca3ede3ee826360d4b32c0029cfc106346ec9 /macros/latex-dev/base | |
| parent | ee3f9ca89b21a2174f7e427d9d48247b1912e130 (diff) | |
CTAN sync 202201140301
Diffstat (limited to 'macros/latex-dev/base')
249 files changed, 7158 insertions, 4231 deletions
diff --git a/macros/latex-dev/base/README.md b/macros/latex-dev/base/README.md index b0c8521876..2d6ce4804c 100644 --- a/macros/latex-dev/base/README.md +++ b/macros/latex-dev/base/README.md @@ -1,7 +1,7 @@ The LaTeX kernel ================ -Release 2022-06-01 pre-release 0 +Release 2022-06-01 pre-release 1 Overview -------- @@ -10,10 +10,15 @@ This bundle provides the core LaTeX kernel. In addition to this bundle, a minimal LaTeX system also needs the files contained in the - LaTeX team documentation (`doc`) +- L3 programming layer (`l3kernel`) +- L3 backend interfaces (`l3backend`) +- L3 unicode support (`unicode-data`) + - Packages which must be available (`required`). These are - Essential tools (`tools`) - Core graphics and color support (`graphics`) - Key mathematics support (`amsmath`) + - First aid for external packages (`firstaid`) This file contains a small set of pointers to other more complete documentation on installing and using a LaTeX system. @@ -36,10 +41,6 @@ the most significant of these files are with one line of information about the contents - `legal.txt` and `lppl.txt` (LaTeX Project Public License) describe the LaTeX copyright, warranty and copying restrictions. -- `texpert.txt` contains information about the system that may still be - useful for TeX experts -- `tex2.txt` contains important information for users of extremely - old versions of TeX (pre 1990) - `bugs.txt` describes how to submit a bug report for LaTeX Other documentation files include files with names of the form: diff --git a/macros/latex-dev/base/alltt.dtx b/macros/latex-dev/base/alltt.dtx index 350229ab40..908fe92400 100644 --- a/macros/latex-dev/base/alltt.dtx +++ b/macros/latex-dev/base/alltt.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -104,7 +104,7 @@ % The glyph at the position of the $ in an italic font: \textit{$}. % \end{alltt} % -% \StopEventually{} +% \MaybeStop{} % % \section{The Implementation} % diff --git a/macros/latex-dev/base/alltt.ins b/macros/latex-dev/base/alltt.ins index 7ce2103207..f46404bcf4 100644 --- a/macros/latex-dev/base/alltt.ins +++ b/macros/latex-dev/base/alltt.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/alltt.pdf b/macros/latex-dev/base/alltt.pdf Binary files differindex 3b72ef7c0e..d6cdbc0fc7 100644 --- a/macros/latex-dev/base/alltt.pdf +++ b/macros/latex-dev/base/alltt.pdf diff --git a/macros/latex-dev/base/cfgguide.pdf b/macros/latex-dev/base/cfgguide.pdf Binary files differindex 92169f5af5..fae9a8bdf1 100644 --- a/macros/latex-dev/base/cfgguide.pdf +++ b/macros/latex-dev/base/cfgguide.pdf diff --git a/macros/latex-dev/base/cfgguide.tex b/macros/latex-dev/base/cfgguide.tex index 66c02e4c33..7694ef9b63 100644 --- a/macros/latex-dev/base/cfgguide.tex +++ b/macros/latex-dev/base/cfgguide.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/changes.txt b/macros/latex-dev/base/changes.txt index d5d2b555d8..8ae1fd7b59 100644 --- a/macros/latex-dev/base/changes.txt +++ b/macros/latex-dev/base/changes.txt @@ -5,12 +5,143 @@ It is provided for convenience only. It therefore makes no claims to completeness or accuracy and it contains some references to files that are not part of the distribution. ================================================================================ +2021-12-30 Ulrike Fischer <Ulrike.Fischer@latex-project.org> + + * ltmeta.dtx: + Adapted bundle name to new name `LaTeX-lab' + +2022-01-06 Joseph Wright <Joseph.Wright-project.org> + + * ltexpl.dtx (section{Document-level command names for expl3 functions}): + Adjust document-level names for \exp_args:Nc and the like + +2021-12-31 Phelype Oleinik <phelype.oleinik@latex-project.org> + + * ltcmd.dtx (subsubsection{Showing the definition of a command}): + Make \ShowCommand stop for interaction with ltcmd (gh/739) + +2021-12-28 Frank Mittelbach <Frank.Mittelbach@latex-project.org> + + * ltexpl.dtx (section{Document-level command names for expl3 functions}): + Added document-level names for \exp_args:Nc and the like + for use with \NewDocumentCommand, etc. (gh/735) + +2021-12-27 Marcel Krüger <Marcel.Krueger@latex-project.org> + + * ltluatex.dtx: + Added \newluacmd and \newprotectedluacmd for easy allocation of Lua command ids. + +2021-12-13 Frank Mittelbach <Frank.Mittelbach@latex-project.org> + + * ltmeta.dtx: + First version of this module added implementing an interface to + \DocumentMetadata. At the moment the actual code is outside the + format and only loaded if the command is called. + +2021-12-13 David Carlisle <David.Carlisle@latex-project.org> + + * utf8ienc.dtx: Use hex 80 not A0 to test for single byte UTF-8 github/730 + +2021-12-12 Frank Mittelbach <Frank.Mittelbach@latex-project.org> + + * ltoutenc.dtx (subsection{Definitions for the TU encoding}): + \DeclareUnicodeAccent now makes the encoding argument implicit + as it is already done for other Unicode encoding commands. + Also added \DeclareUnicodeCommand and \DeclareUnicodeSymbol (gh/253). + +2021-12-12 Frank Mittelbach <Frank.Mittelbach@latex-project.org> + + * doc.dtx (subsection[Dealing with the change history]): + Implement option recordchangedates to show dates in the change log + if that option is used (gh/531). + +2021-12-11 Frank Mittelbach <Frank.Mittelbach@latex-project.org> + + * ltdirchk.dtx (section{Initialization}): + Add comment lines into latex.ltx to indicate temp definitions that + are later overwritten (gh/725). + +2021-12-10 David Carlisle <David.Carlisle@latex-project.org> + + * utf8ienc.dtx: Add inputenc UTF-8 support for for Digraphs U_01C4-U+01CC + +2021-12-09 Frank Mittelbach <Frank.Mittelbach@latex-project.org> + + * proc.dtx (subsection{The page style}): + Support twoside by providing an appropriate footer line (gh/704). + +2021-12-08 Frank Mittelbach <Frank.Mittelbach@latex-project.org> + + * lttextcomp.dtx (section{Sub-encodings}): + Describe correctly (I hope) how sub-encodings work for TS1. + +2021-11-30 Frank Mittelbach <Frank.Mittelbach@latex-project.org> + + * ltexpl.dtx: + Added \fpeval, \inteval, \dimeval, and \skipeval (gh711) + +2021-11-18 Frank Mittelbach <Frank.Mittelbach@latex-project.org> + + * All *.dtx: Replaced \StopEventually by \MaybeStop + +2021-11-30 Joseph Wright <joseph.wright@latex-project.org> + + * ltclasses.dtx + New option handling routine using ltkeys + +2021-11-26 Joseph Wright <joseph.wright@latex-project.org> + + * ltkeys.dtx + New file to integrate keyval option processing into the kernel + +2021-11-17 Marcel Krüger <Marcel.Krueger@latex-project.org> + + * ltluatex.dtx: + Classify [hv]pack_quality callbacks as exclusive + Never pass true to the engine for LuaTeX list callbacks + +2021-11-15 Frank Mittelbach <Frank.Mittelbach@latex-project.org> + + * build.lua (textfiles): + Dropped a few obsolete documentation files (nobody installs manually these + days and the advice given was no longer current). + + * latexchanges.tex: + We no longer maintain this file; instead everything is documented in ltnewsXX + and in the changes.txt files so we zap this file too because the double book + keeping always means one or the other is out of date. + +2021-11-14 Frank Mittelbach <Frank.Mittelbach@latex-project.org> + + * doc.dtx: Replaced doc.dtx with V3 version. + The old doc can be reactivated with \usepackage{doc}[=v2]. + Hyperref usage (on by default) can be turned off with + \usepackage[hyperref=false]{doc}. + New options etc are documented: use texdoc doc + (code documentation only partly done). + +2021-11-12 Frank Mittelbach <Frank.Mittelbach@latex-project.org> + + * ltxdoc.dtx (section{Configuration file}): + Added our default .cfg for extraction. + Added option "nocfg" to bypass a system cfg. + ================================================================================ All changes above are only part of the development branch for the next release. ================================================================================ ######################### +# 2021-11-15 PL1 Release +######################### + +2021-12-02 Joseph Wright <Joseph.Wright@latex-project.org> + + * ltcmd.dtx + Insert correct default values for optional arguments into the end + of environments + +######################### # 2021-11-15 Release ######################### @@ -150,7 +281,7 @@ All changes above are only part of the development branch for the next release. * ltluatex.dtx: Define missing local copy of flush_list in ltluatex.lua found by Michal Vlasák. - + 2021-08-10 Phelype Oleinik <phelype.oleinik@latex-project.org> * ltvers.dtx (section{Version Identification}): diff --git a/macros/latex-dev/base/classes.dtx b/macros/latex-dev/base/classes.dtx index a13053b871..857cfc799e 100644 --- a/macros/latex-dev/base/classes.dtx +++ b/macros/latex-dev/base/classes.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -230,7 +230,7 @@ % \maketitle % \tableofcontents % -% \StopEventually{} ^^A +% \MaybeStop{} ^^A % % \section{The {\sc docstrip} modules} % diff --git a/macros/latex-dev/base/classes.ins b/macros/latex-dev/base/classes.ins index be0dcaf8ff..1f7b331691 100644 --- a/macros/latex-dev/base/classes.ins +++ b/macros/latex-dev/base/classes.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/classes.pdf b/macros/latex-dev/base/classes.pdf Binary files differindex 3bd8c80577..e4e848f690 100644 --- a/macros/latex-dev/base/classes.pdf +++ b/macros/latex-dev/base/classes.pdf diff --git a/macros/latex-dev/base/clsguide.pdf b/macros/latex-dev/base/clsguide.pdf Binary files differindex c3e212d10a..b6d4901363 100644 --- a/macros/latex-dev/base/clsguide.pdf +++ b/macros/latex-dev/base/clsguide.pdf diff --git a/macros/latex-dev/base/clsguide.tex b/macros/latex-dev/base/clsguide.tex index 3667210e5f..6f4d1cf027 100644 --- a/macros/latex-dev/base/clsguide.tex +++ b/macros/latex-dev/base/clsguide.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/cmextra.ins b/macros/latex-dev/base/cmextra.ins index c530e04d0b..a2befb3aef 100644 --- a/macros/latex-dev/base/cmextra.ins +++ b/macros/latex-dev/base/cmextra.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/cmfonts.ins b/macros/latex-dev/base/cmfonts.ins index d54a325f42..55af4759c5 100644 --- a/macros/latex-dev/base/cmfonts.ins +++ b/macros/latex-dev/base/cmfonts.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/cmfonts.pdf b/macros/latex-dev/base/cmfonts.pdf Binary files differindex 90b38f43fd..f147e56c71 100644 --- a/macros/latex-dev/base/cmfonts.pdf +++ b/macros/latex-dev/base/cmfonts.pdf diff --git a/macros/latex-dev/base/cyrguide.pdf b/macros/latex-dev/base/cyrguide.pdf Binary files differindex b3f7d2016b..7483d4a07f 100644 --- a/macros/latex-dev/base/cyrguide.pdf +++ b/macros/latex-dev/base/cyrguide.pdf diff --git a/macros/latex-dev/base/cyrguide.tex b/macros/latex-dev/base/cyrguide.tex index 07d4bc0b3f..3b16687f39 100644 --- a/macros/latex-dev/base/cyrguide.tex +++ b/macros/latex-dev/base/cyrguide.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/doc-2016-02-15.sty b/macros/latex-dev/base/doc-2016-02-15.sty new file mode 100644 index 0000000000..96b6500463 --- /dev/null +++ b/macros/latex-dev/base/doc-2016-02-15.sty @@ -0,0 +1,826 @@ +%% +%% This is file contains the code from 'doc.sty' from around 2017. +%% +%% The original source files were: +%% +%% doc.dtx (with options: `package') +%% +%% +%% Copyright 1993-2016 +%% The LaTeX3 Project and any individual authors listed elsewhere +%% in this file. +%% +%% This file was generated from file(s) of the LaTeX base system. +%% -------------------------------------------------------------- +%% +%% It may be distributed and/or modified under the +%% conditions of the LaTeX Project Public License, either version 1.3c +%% of this license or (at your option) any later version. +%% The latest version of this license is in +%% https://www.latex-project.org/lppl.txt +%% and version 1.3c or later is part of all distributions of LaTeX +%% version 2005/12/01 or later. +%% +%% This file contains the code for an earlier release and is therefore +%% frozen. It is used as part of the current doc.sty when the user +%% requests a rollback. +%% +\NeedsTeXFormat{LaTeX2e}[1994/12/01] + \ProvidesPackage{doc} + [2016/02/15 v2.1g + Standard LaTeX documentation package (FMi)] +%% +%% Package `doc' to use with LaTeX 2e +%% Copyright (C) 1989-1999 Frank Mittelbach, all rights reserved. +\@ifundefined{macro@cnt}{}{\endinput} +\catcode`\^^A=14 +\AtBeginDocument{\catcode`\^^A=14\relax} +\def\macrocode{\macro@code + \frenchspacing \@vobeyspaces + \xmacro@code} +\def\macro@code{% + \topsep \MacrocodeTopsep + \@beginparpenalty \predisplaypenalty + \if@inlabel\leavevmode\fi + \trivlist \parskip \z@ \item[]% + \macro@font + \leftskip\@totalleftmargin \advance\leftskip\MacroIndent + \rightskip\z@ \parindent\z@ \parfillskip\@flushglue + \blank@linefalse \def\par{\ifblank@line + \leavevmode\fi + \blank@linetrue\@@par + \penalty\interlinepenalty} + \obeylines + \let\do\do@noligs \verbatim@nolig@list + \let\do\@makeother \dospecials + \global\@newlistfalse + \global\@minipagefalse + \ifcodeline@index + \everypar{\global\advance\c@CodelineNo\@ne + \llap{\theCodelineNo\ \hskip\@totalleftmargin}% + \check@module}% + \else \everypar{\check@module}% + \fi + \init@crossref} +\newif\ifblank@line +\def\endmacrocode{% + \ifpm@module \endgroup \pm@modulefalse \fi + \everypar{}% + \global\@inlabelfalse + \endtrivlist + \close@crossref} +\@ifundefined{MacroFont}{% + \if@compatibility + \def\MacroFont{\small + \usefont\encodingdefault + \ttdefault + \mddefault + \updefault + }% + \else + \def\MacroFont{\fontencoding\encodingdefault + \fontfamily\ttdefault + \fontseries\mddefault + \fontshape\updefault + \small}% + \fi + }{} +\@ifundefined{AltMacroFont}{% + \if@compatibility + \def\AltMacroFont{\small + \usefont\encodingdefault + \ttdefault + \mddefault + \sldefault + }% + \else + \def\AltMacroFont{\fontencoding\encodingdefault + \fontfamily\ttdefault + \fontseries\mddefault + \fontshape\sldefault + \small + }% + \fi + }{} +\AtBeginDocument{\let\macro@font\MacroFont} +\def\check@module{% + \ifcheck@modules + \ifpm@module \endgroup \pm@modulefalse \fi + \expandafter\futurelet\expandafter\next\expandafter\ch@percent + \fi} +\newif\ifpm@module +\def\DontCheckModules{\check@modulesfalse} +\def\CheckModules{\check@modulestrue} +\newif\ifcheck@modules \check@modulestrue +\def\ch@percent{% + \if \percentchar\next + \expandafter\check@angle + \fi} +\def\check@angle#1{\futurelet\next\ch@angle} +\begingroup +\catcode`\<\active +\gdef\ch@angle{\ifx<\next + \expandafter\ch@plus@etc + \else \percentchar \fi} +\gdef\ch@plus@etc<{\futurelet\next\check@plus@etc} +\gdef\check@plus@etc{% + \if +\next + \let\next\pm@module + \else\if -\next + \let\next\pm@module + \else\if *\next + \let\next\star@module + \else\if /\next + \let\next\slash@module + \else\ifx <\next + \percentchar + \else + \let\next\pm@module + \fi\fi\fi\fi\fi + \next} +\endgroup +\begingroup +\catcode`\~=\active +\lccode`\~=`\> +\lowercase{\gdef\pm@module#1~}{\pm@moduletrue + \Module{#1}\begingroup + \advance\guard@level\@ne + \ifnum\guard@level>\c@StandardModuleDepth\AltMacroFont\fi +} +\lowercase{\gdef\star@module#1~}{% + \Module{#1}% + \global \advance \guard@level\@ne + \ifnum \guard@level>\c@StandardModuleDepth + \global\let\macro@font=\AltMacroFont \macro@font + \fi} +\catcode`\>=\active +\gdef\slash@module#1>{% + \Module{#1}% + \global \advance \guard@level\m@ne + \ifnum \guard@level=\c@StandardModuleDepth + \global\let\macro@font\MacroFont \macro@font + \fi +} +\endgroup +\newcounter{StandardModuleDepth} +\newcount \guard@level +\@ifundefined{Module}{% + \def\Module#1{\mod@math@codes$\langle\mathsf{#1}\rangle$} + }{} +\def\mod@math@codes{\mathcode`\|="226A \mathcode`\&="2026 + \mathcode`\-="702D \mathcode`\+="702B + \mathcode`\:="703A \mathcode`\=="703D } +\newskip\MacrocodeTopsep \MacrocodeTopsep = 3pt plus 1.2pt minus 1pt +\newdimen\MacroIndent +\settowidth\MacroIndent{\rmfamily\scriptsize 00\ } +\@namedef{macrocode*}{\macro@code\sxmacro@code} +\expandafter\let\csname endmacrocode*\endcsname = \endmacrocode +\catcode`\!=\catcode`\% ^^A In this section there must not be + ^^A any exclamation marks. + ^^A +\begingroup +\catcode`\|=\z@ \catcode`\[=\@ne \catcode`\]=\tw@ +\catcode`\{=12 \catcode`\}=12 +\catcode`\%=12 \catcode`\ =\active \catcode`\\=\active +!% \end{macrocode*} +! Next follows the actual definition of |\macro@code|; +! notice the +! use of the new escape character. We manage to get the argument +! surrounded by the string |\end{macrocode}|, but at the end +! however, in spite of the actual characters used during the +! definition of +! this macro, |\end| with the argument |{macrocode}| +! will be executed, to ensure a balanced environment. +! \begin{macrocode*} +|gdef|xmacro@code#1% \end{macrocode}[#1|end[macrocode]] +!% \end{macrocode*} +! \begin{macro}{\sxmacro@code} +! The definition of |\sxmacro@code| is completely analogous, +! only +! here a slightly different terminating string will be used. +! Note that the space is not active in this environment. +! \begin{macrocode} +|catcode`| =12 +|gdef|sxmacro@code#1% \end{macrocode*}[#1|end[macrocode*]] +!% \end{macrocode} +! because the |\catcode| changes have been made local by +! commencing a +! new group, there now follows the matching |\endgroup| +! in a rather +! unusual style of writing. +! \begin{macrocode} +|endgroup +!% \end{macrocode} +\catcode`\!=12 +\def\DescribeMacro{\leavevmode\@bsphack + \begingroup\MakePrivateLetters\Describe@Macro} +\def\Describe@Macro#1{\endgroup + \marginpar{\raggedleft\PrintDescribeMacro{#1}}% + \SpecialUsageIndex{#1}\@esphack\ignorespaces} +\def\DescribeEnv{\leavevmode\@bsphack\begingroup\MakePrivateLetters + \Describe@Env} +\def\Describe@Env#1{\endgroup + \marginpar{\raggedleft\PrintDescribeEnv{#1}}% + \SpecialEnvIndex{#1}\@esphack\ignorespaces} +\reversemarginpar +\setlength\marginparpush{0pt} \setlength\marginparwidth{8pc} +{\catcode`\|=\z@ \catcode`\\=12 +|gdef|bslash{\}} +\def\verbatim{\@beginparpenalty \predisplaypenalty \@verbatim + \MacroFont \frenchspacing \@vobeyspaces \@xverbatim} +\@namedef{verbatim*}{\@beginparpenalty \predisplaypenalty \@verbatim + \MacroFont \@sxverbatim} +\def\@verbatim{\trivlist \item[]\if@minipage\else\vskip\parskip\fi + \leftskip\@totalleftmargin\rightskip\z@ + \parindent\z@\parfillskip\@flushglue\parskip\z@ + \@@par + \@tempswafalse + \def\par{\if@tempswa\hbox{}\fi\@tempswatrue\@@par + \penalty\interlinepenalty + \check@percent}% + \obeylines + \let\do\do@noligs \verbatim@nolig@list + \let\do\@makeother \dospecials} +{\catcode`\%=12 + \long\gdef\check@percent#1{\ifx #1%\let\next\@empty \else + \let\next=#1\fi \next}} +\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}} +\let\verb@balance@group\@empty + +\def\verb@egroup{\global\let\verb@balance@group\@empty\egroup} + +\begingroup + \obeylines% + \gdef\verb@eol@error{\obeylines% + \def^^M{\verb@egroup\@latex@error{% + Text for \noexpand\verb command ended by end of line}\@ehc}}% +\endgroup +\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}} +\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}}} +\newcount\macro@cnt \macro@cnt=0 +\def\macro{\begingroup + \catcode`\\12 + \MakePrivateLetters \m@cro@ \iftrue} +\def\environment{\begingroup + \catcode`\\12 + \MakePrivateLetters \m@cro@ \iffalse} +\long\def\m@cro@#1#2{\endgroup \topsep\MacroTopsep \trivlist + \edef\saved@macroname{\string#2}% + #1 + \let\saved@indexname\saved@macroname + \else + \edef\saved@indexname{\expandafter\@gobble\string#2}% + \fi + \def\makelabel##1{\llap{##1}}% + \if@inlabel + \let\@tempa\@empty \count@\macro@cnt + \loop \ifnum\count@>\z@ + \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne \repeat + \edef\makelabel##1{\llap{\vtop to\baselineskip + {\@tempa\hbox{##1}\vss}}}% + \advance \macro@cnt \@ne + \else \macro@cnt\@ne \fi + \edef\@tempa{\noexpand\item[% + #1% + \noexpand\PrintMacroName + \else + \noexpand\PrintEnvName + \fi + {\string#2}]}% + \@tempa + \global\advance\c@CodelineNo\@ne + #1% + \SpecialMainIndex{#2}\nobreak + \DoNotIndex{#2}% + \else + \SpecialMainEnvIndex{#2}\nobreak + \fi + \global\advance\c@CodelineNo\m@ne + \ignorespaces} +\let\endmacro \endtrivlist +\let\endenvironment\endmacro +\newskip\MacroTopsep \MacroTopsep = 7pt plus 2pt minus 2pt +\@ifundefined{PrintMacroName} + {\def\PrintMacroName#1{\strut \MacroFont \string #1\ }}{} +\@ifundefined{PrintDescribeMacro} + {\def\PrintDescribeMacro#1{\strut \MacroFont \string #1\ }}{} +\@ifundefined{PrintDescribeEnv} + {\def\PrintDescribeEnv#1{\strut \MacroFont #1\ }}{} +\@ifundefined{PrintEnvName} + {\def\PrintEnvName#1{\strut \MacroFont #1\ }}{} +\begingroup +\catcode`\~\active +\gdef\SpecialEscapechar#1{% + \begingroup + \uccode`\~`#1% + \uppercase{\gdef\active@escape@char{~}}% + \escapechar\m@ne \xdef\special@escape@char{\string#1}% + \endgroup} +\endgroup +\begingroup \catcode`\|=\z@ \catcode`\\=\active +|gdef|init@crossref{|catcode`|\|active |let\|bslash + |MakePrivateLetters + |catcode|expandafter`|special@escape@char|active + |expandafter|let|active@escape@char|scan@macro} +|endgroup +\SpecialEscapechar{\\} +\@ifundefined{MakePrivateLetters} + {\let\MakePrivateLetters\makeatletter}{} +\def\close@crossref{\SpecialEscapechar\\} +\def\scan@macro{% + \special@escape@char + \step@checksum + \ifscan@allowed + \let\macro@namepart\@empty + \def\next{\futurelet\next\macro@switch}% + \else \let\next\@empty \fi + \next} +\newif\ifscan@allowed \scan@allowedtrue +\def\DisableCrossrefs{\@bsphack\scan@allowedfalse\@esphack} +\def\EnableCrossrefs{\@bsphack\scan@allowedtrue + \def\DisableCrossrefs{\@bsphack\@esphack}\@esphack} +\def\macro@switch{\ifcat\noexpand\next a% + \let\next\macro@name + \else \let\next\short@macro \fi + \next} +\begingroup +\catcode`\&=12 +\gdef\short@macro#1{\begingroup + \uccode`\&=\expandafter`\string#1% + \uppercase{\def\x{\def\macro@namepart{&}}}% + \expandafter\endgroup\x + \ifnot@excluded + \produce@index{#1}\fi + \scan@allowedfalse#1% + \scan@allowedtrue } +\endgroup +\def\produce@index#1{% + \if\noexpand#1\special@escape@char + \scan@allowedfalse \it@is@a\special@escape@char \else + \if\noexpand#1\bslash \it@is@a\bslash \else + \if\noexpand#1\space \it@is@a\space \else + \ifx#1\par + \it@is@a\space \else + \ifx#1\relax \else + \if\noexpand#1\bgroup \LeftBraceIndex \else + \if\noexpand#1\egroup \RightBraceIndex \else + \if\noexpand#1\percentchar \PercentIndex \else + \it@is@a{\string#1}% + \fi \fi \fi \fi \fi \fi \fi \fi} +\def\macro@name#1{\edef\macro@namepart{\macro@namepart#1}% + \futurelet\next\more@macroname} +\def\more@macroname{\ifcat\noexpand\next a% + \let\next\macro@name + \else \let\next\macro@finish \fi + \next} +\def\macro@finish{% + \macro@namepart + \ifnot@excluded + \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}% + \@tempa \fi} +\def\DoNotIndex{\begingroup \MakePrivateLetters + \catcode`\\12 + \do@not@index} +\long\def\do@not@index#1{% + \endgroup + \addto@hook\index@excludelist{#1,}} +\long\def\addto@hook#1#2{#1\expandafter{\the#1#2}} +\newtoks\index@excludelist +\index@excludelist{} +\begingroup +\catcode`\|=0% +\catcode`\\=12 +|gdef|ifnot@excluded{|expandafter + |expanded@notin|expandafter{|expandafter + \|macro@namepart,}{|the|index@excludelist}} +|endgroup +\def\expanded@notin#1#2{% + \def\in@@##1#1##2##3\in@@{% + \ifx\expanded@notin##2}% + \expandafter\in@@#2#1\expanded@notin\in@@} +\@ifundefined{actualchar}{\def\actualchar{=}}{} +\@ifundefined{quotechar}{\def\quotechar{!}}{} +\@ifundefined{levelchar}{\def\levelchar{>}}{} +\@ifundefined{encapchar}{\def\encapchar{|}}{} +\@ifundefined{verbatimchar}{\def\verbatimchar{+}}{} +\def\SpecialIndex#1{\@bsphack\special@index{\expandafter\@gobble + \string#1\actualchar + \string\verb\quotechar*\verbatimchar\string#1\verbatimchar}% + \@esphack} + +\def\SpecialMainIndex#1{\@bsphack\SpecialIndex@{#1}{\encapchar main}% + \@esphack} +\begingroup + \catcode`\|=0 + \catcode`\\=12 + |gdef|@SpecialIndexHelper@#1#2|@nil{% + |if |noexpand#1\% + |gdef|@gtempa{#2}% + |else + |begingroup + |escapechar|m@ne + |expandafter|gdef|expandafter|@gtempa|expandafter{|string#1#2}% + |endgroup + |fi} +|endgroup +\def\SpecialIndex@#1#2{% + \@SpecialIndexHelper@#1\@nil + \def\@tempb{ }% + \ifcat \@tempb\@gtempa + \special@index{\quotechar\space\actualchar + \string\verb\quotechar*\verbatimchar + \quotechar\bslash\quotechar\space\verbatimchar#2}% + \else + \def\@tempb##1##2\relax{\ifx\relax##2\relax + \def\@tempc{\special@index{\quotechar##1\actualchar + \string\verb\quotechar*\verbatimchar + \quotechar\bslash\quotechar##1\verbatimchar#2}}% + \else + \def\@tempc{\special@index{##1##2\actualchar + \string\verb\quotechar*\verbatimchar + \bslash##1##2\verbatimchar#2}}% + \fi}% + \expandafter\@tempb\@gtempa\relax + \@tempc + \fi} +\def\SpecialMainEnvIndex#1{\@bsphack\special@index{% + #1\actualchar + {\string\ttfamily\space#1} + (environment)% + \encapchar main}% + \special@index{environments:\levelchar#1\actualchar{% + \string\ttfamily\space#1}\encapchar + main}\@esphack} +\def\SpecialUsageIndex#1{\@bsphack + {\let\special@index\index\SpecialIndex@{#1}{\encapchar usage}}% + \@esphack} +\def\SpecialEnvIndex#1{\@bsphack + \index{#1\actualchar{\protect\ttfamily#1} + (environment)\encapchar usage}% + \index{environments:\levelchar#1\actualchar + {\protect\ttfamily#1}\encapchar usage}\@esphack} +\def\SortIndex#1#2{\index{#1\actualchar#2}} +\def\it@is@a#1{\special@index{\quotechar #1\actualchar + \string\verb\quotechar*\verbatimchar + \quotechar\bslash\quotechar#1\verbatimchar}} +\@ifundefined{LeftBraceIndex}{\def\LeftBraceIndex{% + \special@index{\bgroup\actualchar\string\verb\quotechar*\verbatimchar + \quotechar\bslash{\verbatimchar\string\iffalse}\string\fi}}}{} + +\@ifundefined{RightBraceIndex}{\def\RightBraceIndex{% + \special@index{\egroup\actualchar\string\iffalse{\string\fi\string\verb + \quotechar*\verbatimchar\quotechar\bslash}\verbatimchar}}}{} +\@ifundefined{PercentIndex} + {\def\PercentIndex{\it@is@a\percentchar}}{} +\def\OldMakeindex{\def\PercentIndex{% + \special@index{\quotechar\percentchar\actualchar\string\verb + \quotechar*\verbatimchar\quotechar\bslash + \percentchar\percentchar\verbatimchar}}} +{\catcode`\%=12 \gdef\percentchar{%}} +\newif\ifhave@multicol +\IfFileExists{multicol.sty}{\have@multicoltrue + \RequirePackage{multicol}% + }{} + +\newdimen\IndexMin \IndexMin = 80pt +\newcount\c@IndexColumns \c@IndexColumns = 3 +\ifhave@multicol + \renewenvironment{theindex} + {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]% + \IndexParms \let\item\@idxitem \ignorespaces}% + {\end{multicols}} +\else + \typeout{Can't find multicol.sty -- will use normal index layout if + necessary.} + \def\theindex{\@restonecoltrue\if@twocolumn\@restonecolfalse\fi + \columnseprule \z@ \columnsep 35\p@ + \twocolumn[\index@prologue]% + \IndexParms \let\item\@idxitem \ignorespaces} + \def\endtheindex{\if@restonecol\onecolumn\else\clearpage\fi} +\fi +\long\def\IndexPrologue#1{\@bsphack\def\index@prologue{#1}\@esphack} +\@ifundefined{index@prologue} + {\def\index@prologue{\section*{Index}% + \markboth{Index}{Index}% + Numbers written in italic refer to the page + where the corresponding entry is described; + numbers underlined refer to the + \ifcodeline@index + code line of the + \fi + definition; numbers in roman refer to the + \ifcodeline@index + code lines + \else + pages + \fi + where the entry is used. + }}{} +\@ifundefined{IndexParms} + {\def\IndexParms{% + \parindent \z@ + \columnsep 15pt + \parskip 0pt plus 1pt + \rightskip 15pt + \mathsurround \z@ + \parfillskip=-15pt + \small + \def\@idxitem{\par\hangindent 30pt}% + \def\subitem{\@idxitem\hspace*{15pt}}% + \def\subsubitem{\@idxitem\hspace*{25pt}}% + \def\indexspace{\par\vspace{10pt plus 2pt minus 3pt}}% + }}{} +\def\efill{\hfill\nopagebreak}% +\def\dotfill{\leaders\hbox to.6em{\hss .\hss}\hskip\z@ plus 1fill}% +\def\dotfil{\leaders\hbox to.6em{\hss .\hss}\hfil}% +\def\pfill{\unskip~\dotfill\penalty500\strut\nobreak + \dotfil~\ignorespaces}% +\def\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}} +\@ifundefined{main}{\def\main#1{\underline{#1}}}{} +\@ifundefined{usage}{\def\usage#1{\textit{#1}}}{} +\def\PrintIndex{\@input@{\jobname.ind}% + \global\let\PrintIndex\@empty} +\def\changes{\@bsphack\begingroup\@sanitize + \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore + \changes@} +\def\changes@#1#2#3{% + \protected@edef\@tempa{\noexpand\glossary{#1\levelchar + \ifx\saved@macroname\@empty + \space + \actualchar + \generalname + \else + \saved@indexname + \actualchar + \string\verb\quotechar*% + \verbatimchar\saved@macroname + \verbatimchar + \fi + :\levelchar #3}}% + \@tempa\endgroup\@esphack} +\def\saved@macroname{} +\def\saved@indexname{} +\def\generalname{General} +\let\RecordChanges\makeglossary +\newdimen\GlossaryMin \GlossaryMin = 80pt +\newcount\c@GlossaryColumns \c@GlossaryColumns = 2 +\ifhave@multicol + \newenvironment{theglossary}{% + \begin{multicols}\c@GlossaryColumns + [\glossary@prologue][\GlossaryMin]% + \GlossaryParms \let\item\@idxitem \ignorespaces}% + {\end{multicols}} +\else + \newenvironment{theglossary}{% + \@restonecoltrue\if@twocolumn\@restonecolfalse\fi + \columnseprule \z@ \columnsep 35\p@ + \twocolumn[\glossary@prologue]% + \GlossaryParms \let\item\@idxitem \ignorespaces} + {\if@restonecol\onecolumn\else\clearpage\fi} +\fi +\long\def\GlossaryPrologue#1{\@bsphack + \def\glossary@prologue{#1}% + \@esphack} +\@ifundefined{glossary@prologue} + {\def\glossary@prologue{\section*{{Change History}}% + \markboth{{Change History}}{{Change History}}% + }}{} +\@ifundefined{GlossaryParms}{\let\GlossaryParms\IndexParms + \expandafter\def\expandafter\GlossaryParms\expandafter{\GlossaryParms + \rightskip 15pt plus 1fil + \parfillskip -15pt plus -1fil\relax} +}{} +\def\PrintChanges{\@input@{\jobname.gls}% + \global\let\PrintChanges\@empty} +\newcommand\AlsoImplementation{% + \long\def\StopEventually##1{\@bsphack\gdef\Finale{##1% + \check@checksum}% + \init@checksum + \@esphack}% + } +\AlsoImplementation +\def\OnlyDescription{\@bsphack\long\def\StopEventually##1{% + ##1\endinput}\@esphack} +\let\Finale\relax +\ifx\l@nohyphenation\undefined + \newlanguage\l@nohyphenation +\fi +\DeclareRobustCommand\meta[1]{% + \ensuremath\langle + \ifmmode \expandafter \nfss@text \fi + {% + \meta@font@select + \edef\meta@hyphen@restore + {\hyphenchar\the\font\the\hyphenchar\font}% + \hyphenchar\font\m@ne + \language\l@nohyphenation + #1\/% + \meta@hyphen@restore + }\ensuremath\rangle +} +\def\meta@font@select{\itshape} +\def\IndexInput#1{% + \begingroup \macro@code + \frenchspacing \@vobeyspaces + \input{#1}\endmacrocode + \endgroup} +\def\maketitle{\par + \begingroup \def \thefootnote {\fnsymbol {footnote}}% + \setcounter {footnote}\z@ + \def\@makefnmark{\hbox to\z@{$\m@th^{\@thefnmark}$\hss}}% + \long\def\@makefntext##1{\parindent 1em\noindent + \hbox to1.8em{\hss$\m@th^{\@thefnmark}$}##1}% + \if@twocolumn \twocolumn [\@maketitle ]% + \else \newpage \global \@topnum \z@ \@maketitle \fi + \thispagestyle{titlepage}\@thanks \endgroup + \setcounter {footnote}\z@ + \gdef\@date{\today}\gdef\@thanks{}% + \gdef\@author{}\gdef\@title{}} +\@ifundefined{ps@titlepage} + {\let\ps@titlepage=\ps@plain}{} +\def\MakeShortVerb{% + \@ifstar + {\def\@shortvrbdef{\verb*}\@MakeShortVerb}% + {\def\@shortvrbdef{\verb}\@MakeShortVerb}} +\def\@MakeShortVerb#1{% + \expandafter\ifx\csname cc\string#1\endcsname\relax + \@shortvrbinfo{Made }{#1}\@shortvrbdef + \add@special{#1}% + \expandafter + \xdef\csname cc\string#1\endcsname{\the\catcode`#1}% + \begingroup + \catcode`\~\active \lccode`\~`#1% + \lowercase{% + \global\expandafter\let + \csname ac\string#1\endcsname~% + \expandafter\gdef\expandafter~\expandafter{\@shortvrbdef~}}% + \endgroup + \global\catcode`#1\active + \else + \@shortvrbinfo\@empty{#1 already}{\@empty\verb(*)}% + \fi} +\def\DeleteShortVerb#1{% + \expandafter\ifx\csname cc\string#1\endcsname\relax + \@shortvrbinfo\@empty{#1 not}{\@empty\verb(*)}% + \else + \@shortvrbinfo{Deleted }{#1 as}{\@empty\verb(*)}% + \rem@special{#1}% + \global\catcode`#1\csname cc\string#1\endcsname + \global \expandafter\let \csname cc\string#1\endcsname \relax + \ifnum\catcode`#1=\active + \begingroup + \catcode`\~\active \lccode`\~`#1% + \lowercase{% + \global\expandafter\let\expandafter~% + \csname ac\string#1\endcsname}% + \endgroup \fi \fi} +\def\@shortvrbinfo#1#2#3{% + \PackageInfo{doc}{% + #1\expandafter\@gobble\string#2 a short reference + for \expandafter\string#3}} +\def\add@special#1{% + \rem@special{#1}% + \expandafter\gdef\expandafter\dospecials\expandafter + {\dospecials \do #1}% + \expandafter\gdef\expandafter\@sanitize\expandafter + {\@sanitize \@makeother #1}} +\def\rem@special#1{% + \def\do##1{% + \ifnum`#1=`##1 \else \noexpand\do\noexpand##1\fi}% + \xdef\dospecials{\dospecials}% + \begingroup + \def\@makeother##1{% + \ifnum`#1=`##1 \else \noexpand\@makeother\noexpand##1\fi}% + \xdef\@sanitize{\@sanitize}% + \endgroup} +\def\MakeShortverb{\typeout{*** Switch to \noexpand\MakeShortVerb + syntax, this is obsolete ***}\MakeShortVerb} +\def\DeleteShortverb{\typeout{*** Switch to \noexpand\DeleteShortVerb + syntax, this is obsolete ***}\DeleteShortVerb} +\def\init@checksum{\relax + \global\bslash@cnt\z@} +\def\check@checksum{\relax + \ifnum\check@sum>\m@ne + \ifnum\check@sum=\z@ + \typeout{**********************************}% + \typeout{* This macro file has no checksum!}% + \typeout{* The checksum should be \the\bslash@cnt!}% + \typeout{**********************************}% + \else + \ifnum\check@sum=\bslash@cnt + \typeout{*******************}% + \typeout{* Checksum passed *}% + \typeout{*******************}% + \else + \PackageError{doc}{Checksum not passed + (\the\check@sum<>\the\bslash@cnt)}% + {The file currently documented seems to be wrong.^^J% + Try to get a correct version.}% + \fi + \fi + \fi + \global\check@sum\m@ne} +\newcount\check@sum \check@sum = \m@ne +\newcount\bslash@cnt \bslash@cnt = \z@ +\def\CheckSum#1{\@bsphack\global\check@sum#1\relax\@esphack} +\def\step@checksum{\global\advance\bslash@cnt\@ne} +\def\CharacterTable{\begingroup \CharTableChanges \character@table} +\begingroup + \catcode`\~=11 + \gdef\character@table#1{\def\used~table{#1}% + \ifx\used~table\default~table + \typeout{***************************}% + \typeout{* Character table correct *}% + \typeout{***************************}% + \else + \PackageError{doc}{Character table corrupted} + {\the\wrong@table} + \show\default~table + \show\used~table + \fi + \endgroup} + \global\let\CharTableChanges\@empty + \makeatother + \gdef\default~table + {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z + Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z + Digits \0\1\2\3\4\5\6\7\8\9 + Exclamation \! Double quote \" Hash (number) \# + Dollar \$ Percent \% Ampersand \& + Acute accent \' Left paren \( Right paren \) + Asterisk \* Plus \+ Comma \, + Minus \- Point \. Solidus \/ + Colon \: Semicolon \; Less than \< + Equals \= Greater than \> Question mark \? + Commercial at \@ Left bracket \[ Backslash \\ + Right bracket \] Circumflex \^ Underscore \_ + Grave accent \` Left brace \{ Vertical bar \| + Right brace \} Tilde \~} +\endgroup + \newhelp\wrong@table{Some of the ASCII characters are corrupted.^^J + I now \string\show\space you both tables for comparison.} +\newif\ifcodeline@index \codeline@indexfalse +\let\CodelineNumbered\codeline@indextrue +\def\codeline@wrindex#1{\if@filesw + \immediate\write\@indexfile + {\string\indexentry{#1}% + {\number\c@CodelineNo}}\fi} +\let\special@index = \@gobble +\def\CodelineIndex{\makeindex + \codeline@indextrue + \let\special@index\codeline@wrindex} +\def\PageIndex{\makeindex + \codeline@indexfalse + \let\special@index\index} +\newcount\c@CodelineNo \c@CodelineNo\z@ +\@ifundefined{theCodelineNo} + {\ifx\selectfont\undefined + \def\theCodelineNo{\rmfamily\scriptsize\arabic{CodelineNo}}% + \else + \def\theCodelineNo{\reset@font\scriptsize\arabic{CodelineNo}}% + \fi} + {} + \tolerance=1000\relax +{ \catcode`\"=12 + \global\mathcode`\\="705C \global\mathcode`\@="7040 } +\@ifundefined{DocstyleParms}{}{\DocstyleParms} +\let\DocstyleParms\relax +\@ifundefined{AmSTeX} + {\def\AmSTeX{\leavevmode\hbox{$\mathcal A\kern-.2em\lower.376ex% + \hbox{$\mathcal M$}\kern-.2em\mathcal S$-\TeX}}}{} +\@ifundefined{BibTeX} + {\def\BibTeX{{\rmfamily B\kern-.05em% + \textsc{i\kern-.025em b}\kern-.08em% + T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}}{} +\@ifundefined{SliTeX} + {\def\SliTeX{{\rmfamily S\kern-.06emL\kern-.18em\raise.32ex\hbox + {\scshape i}\kern -.03em\TeX}}}{} +\@ifundefined{PlainTeX}{\def\PlainTeX{\textsc{Plain}\kern2pt\TeX}}{} +\@ifundefined{Web}{\def\Web{\textsc{Web}}}{} +\def\MakePercentIgnore{\catcode`\%9\relax} +\def\MakePercentComment{\catcode`\%14\relax} +\def\DocInput#1{\MakePercentIgnore\input{#1}\MakePercentComment} +\def\GetFileInfo#1{% + \def\filename{#1}% + \def\@tempb##1 ##2 ##3\relax##4\relax{% + \def\filedate{##1}% + \def\fileversion{##2}% + \def\fileinfo{##3}}% + \edef\@tempa{\csname ver@#1\endcsname}% + \expandafter\@tempb\@tempa\relax? ? \relax\relax} +\endinput +%% +%% End of file `doc.sty'. diff --git a/macros/latex-dev/base/doc-v3beta.sty b/macros/latex-dev/base/doc-2021-06-01.sty index eeac71568c..444849f2e7 100644 --- a/macros/latex-dev/base/doc-v3beta.sty +++ b/macros/latex-dev/base/doc-2021-06-01.sty @@ -1,10 +1,10 @@ %% -%% This is file `doc-v3beta.sty', +%% This is file `doc.sty', %% generated with the docstrip utility. %% %% The original source files were: %% -%% doc.dtx (with options: `package,beta') +%% doc.dtx (with options: `package') %% %% This is a generated file. %% @@ -13,8 +13,8 @@ %% (but please observe conditions on bug reports sent to that address!) %% %% -%% Copyright 1993-2018 -%% The LaTeX3 Project and any individual authors listed elsewhere +%% Copyright (C) 1993-2021 +%% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% %% This file was generated from file(s) of the LaTeX base system. @@ -26,7 +26,7 @@ %% The latest version of this license is in %% https://www.latex-project.org/lppl.txt %% and version 1.3c or later is part of all distributions of LaTeX -%% version 2005/12/01 or later. +%% version 2008 or later. %% %% This file has the LPPL maintenance status "maintained". %% @@ -42,56 +42,15 @@ %% and covered by LPPL is defined by the unpacking scripts (with %% extension .ins) which are part of the distribution. \NeedsTeXFormat{LaTeX2e}[1994/12/01] - -\providecommand\DeclareRelease[3]{} -\providecommand\DeclareCurrentRelease[2]{} - -\DeclareRelease{v2}{2016-02-15.sty} - {doc-2016-02-15.sty} -\DeclareCurrentRelease{v3}{2018-04-16} - -\ProvidesPackage{doc-v3beta} - [2021/02/07 v3.0e - Standard LaTeX documentation package V3 (FMi)] + \ProvidesPackage{doc} + [2021/05/28 v2.1n + Standard LaTeX documentation package (FMi)] %% %% Package `doc' to use with LaTeX 2e -%% Copyright (C) 1989-2018 Frank Mittelbach, all rights reserved. - - - - - +%% Copyright (C) 1989-2020 Frank Mittelbach, all rights reserved. \@ifundefined{macro@cnt}{}{\endinput} \catcode`\^^A=14 \AtBeginDocument{\catcode`\^^A=14\relax} -\RequirePackage{kvoptions} -\SetupKeyvalOptions{family=doc,prefix=doc@} -\DeclareBoolOption{noprint} -\DeclareBoolOption{noindex} -\DeclareBoolOption[true]{hyperref} -\DeclareBoolOption[true]{multicol} -\DeclareBoolOption[false]{debugshow} -\DeclareBoolOption[true]{toplevel} -\DeclareComplementaryOption{notoplevel}{toplevel} -\DeclareBoolOption{macrolike} -\DeclareComplementaryOption{envlike}{macrolike} -\DeclareStringOption{idxtype} -\DeclareStringOption{idxgroup} -\DeclareStringOption{printtype} -\DeclareBoolOption[false]{outer} -\ProcessKeyvalOptions* -\newif\ifscan@allowed \scan@allowedtrue -\def\SetupDoc#1{% - \setkeys{doc}{#1}% - \edef\doc@noprintdefault{\ifdoc@noprint true\else false\fi}% - \ifdoc@noindex - \def\doc@noindexdefault{true}% - \scan@allowedfalse - \else - \def\doc@noindexdefault{false}% - \fi -} -\SetupDoc{} % just save the default values \def\macrocode{\macro@code \frenchspacing \@vobeyspaces \xmacro@code} @@ -100,6 +59,7 @@ \@beginparpenalty \predisplaypenalty \if@inlabel\leavevmode\fi \trivlist \parskip \z@ \item[]% + \global\setbox\@labels\box\voidb@x \macro@font \leftskip\@totalleftmargin \advance\leftskip\MacroIndent \rightskip\z@ \parindent\z@ \parfillskip\@flushglue @@ -132,13 +92,13 @@ \usefont\encodingdefault \ttdefault \mddefault - \updefault + \shapedefault }% \else \def\MacroFont{\fontencoding\encodingdefault \fontfamily\ttdefault \fontseries\mddefault - \fontshape\updefault + \fontshape\shapedefault \small}% \fi }{} @@ -221,7 +181,6 @@ \endgroup \newcounter{StandardModuleDepth} \newcount \guard@level - \@ifundefined{Module}{% \def\Module#1{\mod@math@codes$\langle\mathsf{#1}\rangle$} }{} @@ -270,16 +229,25 @@ |endgroup !% \end{macrocode} \catcode`\!=12 - +\def\DescribeMacro{\leavevmode\@bsphack + \begingroup\MakePrivateLetters\Describe@Macro} +\def\Describe@Macro#1{\endgroup + \marginpar{\raggedleft\PrintDescribeMacro{#1}}% + \SpecialUsageIndex{#1}\@esphack\ignorespaces} +\def\DescribeEnv{\leavevmode\@bsphack\begingroup\MakePrivateLetters + \Describe@Env} +\def\Describe@Env#1{\endgroup + \marginpar{\raggedleft\PrintDescribeEnv{#1}}% + \SpecialEnvIndex{#1}\@esphack\ignorespaces} \reversemarginpar \setlength\marginparpush{0pt} \setlength\marginparwidth{8pc} -\setlength\marginparsep{\labelsep} {\catcode`\|=\z@ \catcode`\\=12 |gdef|bslash{\}} \def\verbatim{\@beginparpenalty \predisplaypenalty \@verbatim \MacroFont \frenchspacing \@vobeyspaces \@xverbatim} \@namedef{verbatim*}{\@beginparpenalty \predisplaypenalty \@verbatim - \MacroFont \@sxverbatim} + \@setupverbvisiblespace + \MacroFont \@vobeyspaces \@sxverbatim} \def\@verbatim{\trivlist \item[]\if@minipage\else\vskip\parskip\fi \leftskip\@totalleftmargin\rightskip\z@ \parindent\z@\parfillskip\@flushglue\parskip\z@ @@ -306,14 +274,8 @@ \obeylines% \gdef\verb@eol@error{\obeylines% \def^^M{\verb@egroup\@latex@error{% - Text for \noexpand\verb command ended by end of line}\@ehc}}% + \noexpand\verb ended by end of line}\@ehc}}% \endgroup -\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}} \def\verbatim@nolig@list{\do\`\do\<\do\>\do\,\do\'\do\-} \def\do@noligs#1{% \catcode`#1\active @@ -321,7 +283,56 @@ \lccode`\~=`#1\relax \lowercase{\endgroup\def~{\leavevmode\kern\z@\char`#1}}} \newcount\macro@cnt \macro@cnt=0 +\def\macro{\begingroup + \catcode`\\12 + \MakePrivateLetters \m@cro@ \iftrue} +\def\environment{\begingroup + \catcode`\\12 + \MakePrivateLetters \m@cro@ \iffalse} +\long\def\m@cro@#1#2{\endgroup \topsep\MacroTopsep \trivlist + \edef\saved@macroname{\string#2}% + #1 + \let\saved@indexname\saved@macroname + \else + \edef\saved@indexname{\expandafter\@gobble\string#2}% + \fi + \def\makelabel##1{\llap{##1}}% + \if@inlabel + \let\@tempa\@empty \count@\macro@cnt + \loop \ifnum\count@>\z@ + \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne \repeat + \edef\makelabel##1{\llap{\vtop to\baselineskip + {\@tempa\hbox{##1}\vss}}}% + \advance \macro@cnt \@ne + \else \macro@cnt\@ne \fi + \edef\@tempa{\noexpand\item[% + #1% + \noexpand\PrintMacroName + \else + \noexpand\PrintEnvName + \fi + {\string#2}]}% + \@tempa + \global\advance\c@CodelineNo\@ne + #1% + \SpecialMainIndex{#2}\nobreak + \DoNotIndex{#2}% + \else + \SpecialMainEnvIndex{#2}\nobreak + \fi + \global\advance\c@CodelineNo\m@ne + \ignorespaces} +\let\endmacro \endtrivlist +\let\endenvironment\endmacro \newskip\MacroTopsep \MacroTopsep = 7pt plus 2pt minus 2pt +\@ifundefined{PrintMacroName} + {\def\PrintMacroName#1{\strut \MacroFont \string #1\ }}{} +\@ifundefined{PrintDescribeMacro} + {\def\PrintDescribeMacro#1{\strut \MacroFont \string #1\ }}{} +\@ifundefined{PrintDescribeEnv} + {\def\PrintDescribeEnv#1{\strut \MacroFont #1\ }}{} +\@ifundefined{PrintEnvName} + {\def\PrintEnvName#1{\strut \MacroFont #1\ }}{} \begingroup \catcode`\~\active \gdef\SpecialEscapechar#1{% @@ -349,6 +360,7 @@ \def\next{\futurelet\next\macro@switch}% \else \let\next\@empty \fi \next} +\newif\ifscan@allowed \scan@allowedtrue \def\DisableCrossrefs{\@bsphack\scan@allowedfalse\@esphack} \def\EnableCrossrefs{\@bsphack\scan@allowedtrue \def\DisableCrossrefs{\@bsphack\@esphack}\@esphack} @@ -362,10 +374,24 @@ \uccode`\&=\expandafter`\string#1% \uppercase{\def\x{\def\macro@namepart{&}}}% \expandafter\endgroup\x - \maybe@index@short@macro\macro@namepart + \ifnot@excluded + \produce@index{#1}\fi \scan@allowedfalse#1% \scan@allowedtrue } \endgroup +\def\produce@index#1{% + \if\noexpand#1\special@escape@char + \scan@allowedfalse \it@is@a\special@escape@char \else + \if\noexpand#1\bslash \it@is@a\bslash \else + \if\noexpand#1\space \it@is@a\space \else + \ifx#1\par + \it@is@a\space \else + \ifx#1\relax \else + \if\noexpand#1\bgroup \LeftBraceIndex \else + \if\noexpand#1\egroup \RightBraceIndex \else + \if\noexpand#1\percentchar \PercentIndex \else + \it@is@a{\string#1}% + \fi \fi \fi \fi \fi \fi \fi \fi} \def\macro@name#1{\edef\macro@namepart{\macro@namepart#1}% \futurelet\next\more@macroname} \def\more@macroname{\ifcat\noexpand\next a% @@ -374,171 +400,41 @@ \next} \def\macro@finish{% \macro@namepart - \maybe@index@macro \macro@namepart -} - -\RequirePackage{expl3} -\ExplSyntaxOn -\seq_new:N \l__doc_donotindex_seq -\prop_new:N \g__doc_idxtype_prop -\cs_new:Npn\__doc_trace:x { - \ifdoc@debugshow - \expandafter \iow_term:x - \else - \expandafter \use_none:n - \fi -} -\cs_new:Npn \doc_dont_index:n { - \group_begin: - \MakePrivateLetters - \__doc_dont_index:n -} -\cs_new:Npn \__doc_dont_index:n #1 { - \group_end: - \__doc_trace:x{Disable~ indexing~ for~ '\tl_to_str:n{#1}' } - \clist_map_function:nN {#1} \__doc_dont_index_aux:n -} -\cs_new:Npn \__doc_dont_index_aux:n #1 { - \seq_put_right:Nx \l__doc_donotindex_seq {\expandafter\@gobble \string#1} -} -\cs_set_eq:NN \DoNotIndex \doc_dont_index:n -\def \ShowIndexingState { - \__doc_trace:x{Show~ doc~ indexing~ state:} - \seq_show:N \l__doc_donotindex_seq - \prop_show:N \g__doc_idxtype_prop -} - -\cs_new:Npn \__doc_idxtype_put:Nn #1#2 { - \exp_args:Nx \__doc_idxtype_put:nn { \cs_to_str:N #1 }{#2} - \protected@write\@auxout{} - {\string\RecordIndexTypeAux {\string#1 }{#2} } -} -\cs_new:Npn \RecordIndexTypeAux #1#2 { - \exp_args:Nx \__doc_idxtype_put:nn { \cs_to_str:N #1 }{#2} -} -\AtEndDocument{ - \cs_set_eq:NN \RecordIndexTypeAux \use_none:nn -} -\cs_set_eq:NN \RecordIndexType \__doc_idxtype_put:Nn -\cs_new:Npn \__doc_idxtype_put_scan:nn #1#2 { - \exp_args:Nf \__doc_idxtype_put:nn { \tl_to_str:n {#1} }{#2} - \protected@write\@auxout{} - {\string\RecordIndexTypeAux {\bslash #1 }{#2} } -} -\cs_generate_variant:Nn \__doc_idxtype_put_scan:nn {o} -\cs_set_eq:NN \record@index@type@save \__doc_idxtype_put_scan:on -\cs_new:Npn \__doc_idxtype_put:nn #1#2 { - \exp_args:NNf - \seq_if_in:NnTF \l__doc_donotindex_seq {\tl_to_str:n{#1}} - { - \__doc_trace:x{Not~ recording~ index~ type~ for~ '\bslash #1' } - } - { - \__doc_trace:x{Recording~ index~ type~ for~ '\bslash #1' ~ as~ #2 } - \prop_gput:Nnn \g__doc_idxtype_prop {#1}{#2} - } -} -\cs_new:Npn \exp_args:co #1#2 - { \cs:w #1 \exp_after:wN \cs_end:\exp_after:wN {#2} } -\cs_generate_variant:Nn \tl_to_str:n {o} - -\cs_new:Npn \__doc_maybe_index:o #1 { - \exp_args:Nf \__doc_maybe_index_aux:nN { \tl_to_str:o {#1} } - \SpecialIndex -} -\cs_set_eq:NN \maybe@index@macro \__doc_maybe_index:o -\cs_new:Npn \__doc_maybe_index_short:o #1 { - \exp_args:Nf \__doc_maybe_index_aux:nN { \tl_to_str:o {#1} } - \SpecialShortIndex -} -\cs_set_eq:NN \maybe@index@short@macro \__doc_maybe_index_short:o -\cs_new:Npn \__doc_maybe_index_aux:nN #1#2 { - \__doc_trace:x{Searching~ for~ '\bslash #1'} - \seq_if_in:NnTF \l__doc_donotindex_seq {#1} - { - \__doc_trace:x{Not~ indexing~ '\bslash #1' } - } - { - \prop_get:NnNTF \g__doc_idxtype_prop {#1} \l__doc_idxtype_tl - { - \exp_args:Ncno \__doc_maybe_index_aux:Nnn - { Code \tl_use:N \l__doc_idxtype_tl Index } - {code} {\bslash #1} - } - { - \__doc_trace:x{Indexing~ '\bslash #1'\space (\string #2)} - \exp_args:No #2 {\bslash #1} - } - } -} -\cs_new:Npn \SpecialShortIndex #1 { - \@SpecialIndexHelper@ #1\@nil - \@bsphack - \ifdoc@noindex \else - \str_case_e:nnF {\@gtempa } - { - {\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 } - \def\reserved@b { \space } - \let\reserved@c \@empty } - {\c_left_brace_str} { \def\reserved@a{ \bgroup \actualchar } - \def\reserved@b { \c_left_brace_str } - \def\reserved@c { \noexpand\iffalse - \c_right_brace_str - \noexpand\fi } } - {\c_right_brace_str} { \def\reserved@a{ \egroup \actualchar - \noexpand\iffalse - \c_left_brace_str - \noexpand\fi } - \def\reserved@b { \c_right_brace_str } - \let\reserved@c \@empty } - {\verbatimchar} { \def\reserved@a{ \quotechar\verbatimchar - \actualchar } - \let\reserved@b \@empty - \def\reserved@c - { \string\texttt{\string\string\verbatimchar} } } - } - { \def\reserved@a {\quotechar \@gtempa \actualchar } - \def\reserved@b {\quotechar \@gtempa } - \let\reserved@c \@empty } - \special@index { - \reserved@a - \string\verb - \quotechar *\verbatimchar \quotechar \bslash - \reserved@b - \verbatimchar - \reserved@c - \encapchar code} - \fi - \@esphack -} - -\cs_new:Npn \__doc_maybe_index_aux:Nnn #1#2#3 { - \cs_if_exist:NTF #1 - { - \__doc_trace:x{Indexing~ '#3'\space as~ - \tl_use:N \l__doc_idxtype_tl } - #1{#2}{#3} - } - { - \PackageError{doc}{Doc~ element~ - '\tl_use:N \l__doc_idxtype_tl'~ unknown}% - - {When~ using~ '\string\RecordIndexType'~ the~ type~ must~ - be~ known~\MessageBreak - to~ the~ system,~ i.e.,~ declared~ via~ - '\string\NewDocElement'\MessageBreak - before~ it~ can~ be~ used~ in~ indexing.} - } -} -\ExplSyntaxOff + \ifnot@excluded + \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}% + \@tempa \fi} +\def\DoNotIndex{\begingroup \MakePrivateLetters + \catcode`\\12 + \do@not@index} +\long\def\do@not@index#1{% + \endgroup + \addto@hook\index@excludelist{#1,}} +\long\def\addto@hook#1#2{#1\expandafter{\the#1#2}} +\newtoks\index@excludelist +\index@excludelist{} +\begingroup +\catcode`\|=0% +\catcode`\\=12 +|gdef|ifnot@excluded{|expandafter + |expanded@notin|expandafter{|expandafter + \|macro@namepart,}{|the|index@excludelist}} +|endgroup +\def\expanded@notin#1#2{% + \def\in@@##1#1##2##3\in@@{% + \ifx\expanded@notin##2}% + \expandafter\in@@#2#1\expanded@notin\in@@} \@ifundefined{actualchar}{\def\actualchar{=}}{} \@ifundefined{quotechar}{\def\quotechar{!}}{} \@ifundefined{levelchar}{\def\levelchar{>}}{} \@ifundefined{encapchar}{\def\encapchar{|}}{} \@ifundefined{verbatimchar}{\def\verbatimchar{+}}{} +\def\SpecialIndex#1{\@bsphack\special@index{\expandafter\@gobble + \string#1\actualchar + \string\verb\quotechar*\verbatimchar\string#1\verbatimchar}% + \@esphack} + +\def\SpecialMainIndex#1{\@bsphack\SpecialIndex@{#1}{\encapchar main}% + \@esphack} \begingroup \catcode`\|=0 \catcode`\\=12 @@ -552,43 +448,75 @@ |endgroup |fi} |endgroup -\def\SortIndex#1#2{% - \ifdoc@noindex\else - \index{#1\actualchar#2}% - \fi -} +\def\SpecialIndex@#1#2{% + \@SpecialIndexHelper@#1\@nil + \def\@tempb{ }% + \ifcat \@tempb\@gtempa + \special@index{\quotechar\space\actualchar + \string\verb\quotechar*\verbatimchar + \quotechar\bslash\quotechar\space\verbatimchar#2}% + \else + \def\@tempb##1##2\relax{\ifx\relax##2\relax + \def\@tempc{\special@index{\quotechar##1\actualchar + \string\verb\quotechar*\verbatimchar + \quotechar\bslash\quotechar##1\verbatimchar#2}}% + \else + \def\@tempc{\special@index{##1##2\actualchar + \string\verb\quotechar*\verbatimchar + \bslash##1##2\verbatimchar#2}}% + \fi}% + \expandafter\@tempb\@gtempa\relax + \@tempc + \fi} +\def\SpecialMainEnvIndex#1{\@bsphack\special@index{% + #1\actualchar + {\string\ttfamily\space#1} + (environment)% + \encapchar main}% + \special@index{environments:\levelchar#1\actualchar{% + \string\ttfamily\space#1}\encapchar + main}\@esphack} +\def\SpecialUsageIndex#1{\@bsphack + {\let\special@index\index\SpecialIndex@{#1}{\encapchar usage}}% + \@esphack} +\def\SpecialEnvIndex#1{\@bsphack + \index{#1\actualchar{\protect\ttfamily#1} + (environment)\encapchar usage}% + \index{environments:\levelchar#1\actualchar + {\protect\ttfamily#1}\encapchar usage}\@esphack} +\def\SortIndex#1#2{\index{#1\actualchar#2}} +\def\it@is@a#1{\special@index{\quotechar #1\actualchar + \string\verb\quotechar*\verbatimchar + \quotechar\bslash\quotechar#1\verbatimchar}} \@ifundefined{LeftBraceIndex}{\def\LeftBraceIndex{% - \special@index{\bgroup\actualchar - \string\verb% % to fool emacs highlighting - \quotechar*\verbatimchar - \quotechar\bslash{\verbatimchar\string\iffalse}\string\fi}}}{} + \special@index{\bgroup\actualchar\string\verb\quotechar*\verbatimchar + \quotechar\bslash{\verbatimchar\string\iffalse}\string\fi}}}{} \@ifundefined{RightBraceIndex}{\def\RightBraceIndex{% - \special@index{\egroup\actualchar\string\iffalse{\string\fi - \string\verb% % to fool emacs highlighting + \special@index{\egroup\actualchar\string\iffalse{\string\fi\string\verb \quotechar*\verbatimchar\quotechar\bslash}\verbatimchar}}}{} \@ifundefined{PercentIndex} {\def\PercentIndex{\it@is@a\percentchar}}{} \def\OldMakeindex{\def\PercentIndex{% - \special@index{\quotechar\percentchar\actualchar - \string\verb% % to fool emacs highlighting + \special@index{\quotechar\percentchar\actualchar\string\verb \quotechar*\verbatimchar\quotechar\bslash \percentchar\percentchar\verbatimchar}}} {\catcode`\%=12 \gdef\percentchar{%}} -\def\it@is@a#1{\special@index{\quotechar #1\actualchar - \string\verb% % to fool emacs highlighting - \quotechar*\verbatimchar - \quotechar\bslash\quotechar#1\verbatimchar}} +\newif\ifhave@multicol +\IfFileExists{multicol.sty}{\have@multicoltrue + \RequirePackage{multicol}% + }{} \newdimen\IndexMin \IndexMin = 80pt \newcount\c@IndexColumns \c@IndexColumns = 3 -\ifdoc@multicol - \RequirePackage{multicol} +\ifhave@multicol \renewenvironment{theindex} {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]% \IndexParms \let\item\@idxitem \ignorespaces}% {\end{multicols}} \else + \typeout{Can't find multicol.sty -- will use normal index layout if + necessary.} \def\theindex{\@restonecoltrue\if@twocolumn\@restonecolfalse\fi \columnseprule \z@ \columnsep 35\p@ \twocolumn[\index@prologue]% @@ -628,15 +556,13 @@ \def\indexspace{\par\vspace{10pt plus 2pt minus 3pt}}% }}{} \def\efill{\hfill\nopagebreak}% -\def\pfill{\unskip~% - \leaders\hbox to.6em{\hss .\hss}\hfill - \penalty500\strut\nobreak - \leaders\hbox to.6em{\hss .\hss}\hfil - ~\ignorespaces}% +\def\dotfill{\leaders\hbox to.6em{\hss .\hss}\hskip\z@ plus 1fill\kern\z@}% +\def\dotfil{\leaders\hbox to.6em{\hss .\hss}\hfil\kern\z@}% +\def\pfill{\unskip~\dotfill\penalty500\strut\nobreak + \dotfil~\ignorespaces}% \def\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}} \@ifundefined{main}{\def\main#1{\underline{#1}}}{} \@ifundefined{usage}{\def\usage#1{\textit{#1}}}{} -\@ifundefined{code}{\def\code#1{#1}}{} \def\PrintIndex{\@input@{\jobname.ind}% \global\let\PrintIndex\@empty} \def\changes{\@bsphack\begingroup\@sanitize @@ -644,19 +570,18 @@ \changes@} \def\changes@#1#2#3{% \protected@edef\@tempa{\noexpand\glossary{#1\levelchar - \ifx\saved@macroname\@empty - \quotechar!% - \actualchar - \generalname - \else - \saved@indexname - \actualchar - \string\verb% % to fool emacs highlighting - \quotechar*% - \verbatimchar\saved@macroname - \verbatimchar - \fi - :\levelchar #3}}% + \ifx\saved@macroname\@empty + \space + \actualchar + \generalname + \else + \saved@indexname + \actualchar + \string\verb\quotechar*% + \verbatimchar\saved@macroname + \verbatimchar + \fi + :\levelchar #3}}% \@tempa\endgroup\@esphack} \def\saved@macroname{} \def\saved@indexname{} @@ -664,7 +589,7 @@ \let\RecordChanges\makeglossary \newdimen\GlossaryMin \GlossaryMin = 80pt \newcount\c@GlossaryColumns \c@GlossaryColumns = 2 -\ifdoc@multicol +\ifhave@multicol \newenvironment{theglossary}{% \begin{multicols}\c@GlossaryColumns [\glossary@prologue][\GlossaryMin]% @@ -693,16 +618,15 @@ \def\PrintChanges{\@input@{\jobname.gls}% \global\let\PrintChanges\@empty} \newcommand\AlsoImplementation{% - \long\def\MaybeStopHere##1{\@bsphack\gdef\Finale{##1% + \long\def\StopEventually##1{\@bsphack\gdef\Finale{##1% \check@checksum}% \init@checksum \@esphack}% } \AlsoImplementation -\def\OnlyDescription{\@bsphack\long\def\MaybeStopHere##1{% +\def\OnlyDescription{\@bsphack\long\def\StopEventually##1{% ##1\endinput}\@esphack} \let\Finale\relax -\def\StopEventually{\MaybeStopHere} \ifx\l@nohyphenation\undefined \newlanguage\l@nohyphenation \fi @@ -758,20 +682,13 @@ \endgroup \global\catcode`#1\active \else - \@shortvrbinfo\@empty{#1 already}% - {\@empty\verb% % to fool emacs highlighting - (*)}% + \@shortvrbinfo\@empty{#1 already}{\@empty\verb(*)}% \fi} \def\DeleteShortVerb#1{% \expandafter\ifx\csname cc\string#1\endcsname\relax - \@shortvrbinfo\@empty{#1 not}% - {\@empty\verb% % to fool emacs highlighting - (*)}% + \@shortvrbinfo\@empty{#1 not}{\@empty\verb(*)}% \else - \@shortvrbinfo{Deleted }{#1 as}% - {\@empty\verb% % to fool emacs - % highlighting - (*)}% + \@shortvrbinfo{Deleted }{#1 as}{\@empty\verb(*)}% \rem@special{#1}% \global\catcode`#1\csname cc\string#1\endcsname \global \expandafter\let \csname cc\string#1\endcsname \relax @@ -801,6 +718,10 @@ \ifnum`#1=`##1 \else \noexpand\@makeother\noexpand##1\fi}% \xdef\@sanitize{\@sanitize}% \endgroup} +\def\MakeShortverb{\typeout{*** Switch to \noexpand\MakeShortVerb + syntax, this is obsolete ***}\MakeShortVerb} +\def\DeleteShortverb{\typeout{*** Switch to \noexpand\DeleteShortVerb + syntax, this is obsolete ***}\DeleteShortVerb} \def\init@checksum{\relax \global\bslash@cnt\z@} \def\check@checksum{\relax @@ -866,13 +787,9 @@ \newif\ifcodeline@index \codeline@indexfalse \let\CodelineNumbered\codeline@indextrue \def\codeline@wrindex#1{\if@filesw - \begingroup - \set@display@protect \immediate\write\@indexfile {\string\indexentry{#1}% - {\number\c@CodelineNo}}% - \endgroup - \fi} + {\number\c@CodelineNo}}\fi} \let\special@index = \@gobble \def\CodelineIndex{\makeindex \codeline@indextrue @@ -916,326 +833,6 @@ \def\fileinfo{##3}}% \edef\@tempa{\csname ver@#1\endcsname}% \expandafter\@tempb\@tempa\relax? ? \relax\relax} - -\ifdoc@hyperref - \let\PrintDescribeMacro \@empty - \let\PrintDescribeEnv \@empty - \let\PrintMacroName \@empty - \let\PrintEnvName \@empty - \let\SpecialUsageIndex \@empty - \let\SpecialEnvIndex \@empty - \expandafter\let\expandafter\doc@eoph@@k\csname doc.sty-h@@k\endcsname - \RequirePackage{hypdoc} - \expandafter\let\csname doc.sty-h@@k\endcsname\doc@eoph@@k - \let\PrintDescribeMacro \relax - \let\PrintDescribeEnv \relax - \let\PrintMacroName \relax - \let\PrintEnvName \relax - \def\doc@providetarget{\HD@target} - \def\doc@handleencap#1{\encapchar hdclindex{\the\c@HD@hypercount}{#1}} -\else - \let\doc@providetarget\@empty - \def\doc@handleencap#1{\encapchar #1} - \def\hdclindex#1#2{\ifx\@nil#2\@nil\else\csname #2\expandafter\endcsname\fi} - \def\hdpindex #1{\ifx\@nil#1\@nil\else\csname #1\expandafter\endcsname\fi} -\fi - - -\ExplSyntaxOn - -\long\def\@doc@env#1#2#3{ - \endgroup - \clist_map_inline:nn {#3} { \@doc@env@{#1}{#2}{##1} } -} - -\ExplSyntaxOff -\long\def\@doc@env@#1#2#3{% - \topsep\MacroTopsep - \trivlist - \edef\saved@macroname{\string#3}% - \if #1% - \edef\saved@indexname{\expandafter\@gobble\saved@macroname}% - \expandafter\ifx - \csname Code#2Index\endcsname - \CodeMacroIndex - \else - \record@index@type@save - {\saved@indexname}{#2}% - \fi - \else - \let\saved@indexname\saved@macroname - \fi - \def\makelabel##1{\llap{##1}}% - \if@inlabel - \let\@tempa\@empty - \count@\macro@cnt - \loop\ifnum\count@>\z@ - \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne - \repeat - \edef\makelabel##1{\llap{\vtop to\baselineskip{\@tempa\hbox{##1}\vss}}}% - \advance\macro@cnt\@ne - \else - \macro@cnt\@ne - \fi - \ifdoc@noprint - \item - \else - \edef\@tempa{% - \noexpand\item[% - \noexpand\doc@providetarget - \noexpand\strut - \noexpand\@nameuse{Print#2Name}{\saved@macroname}]}% - \@tempa - \fi - \ifdoc@noindex\else - \global\advance\c@CodelineNo\@ne - \csname SpecialMain#2Index\expandafter\endcsname - \expandafter{\saved@macroname}\nobreak - \global\advance\c@CodelineNo\m@ne - \fi - \if#1\expandafter\DoNotIndex \expandafter {\saved@macroname}\fi - \ignorespaces} - -\def\doc@env#1#2[#3]{% - \@nameuse{doc@noprint\doc@noprintdefault}% - \@nameuse{doc@noindex\doc@noindexdefault}% - \setkeys{doc}{#3}% - \begingroup - \ifdoc@outer - \catcode`\\12 - \fi - \MakePrivateLetters - \@doc@env{#1}{#2}% -} - -\def\@doc@describe#1#2{% - \ifdoc@noprint\else - \marginpar{\raggedleft - \strut - \doc@providetarget - \@nameuse{PrintDescribe#1}{#2}}% - \fi - \ifdoc@noindex\else - \@nameuse{Special#1Index}{#2}% - \fi - \@esphack - \endgroup - \ignorespaces} -\def\doc@describe#1[#2]{% - \leavevmode\@bsphack - \setkeys{doc}{#2}% - \@doc@describe{#1}} -\@ifundefined{temptokenb}{\newtoks\@temptokenb}{} -\def\doc@createspecialindexes#1#2#3{% - \@temptokena{\space (#2)}% - \@temptokenb{#3:}% - \@nameedef{SpecialMain#1Index}##1{% - \noexpand\@bsphack - \ifdoc@toplevel - \noexpand\special@index{##1\noexpand\actualchar - {\string\ttfamily\space##1}% - \ifx\@nil#2\@nil\else \the\@temptokena \fi - \noexpand\encapchar main}% - \fi - \ifx\@nil#3\@nil\else - \noexpand\special@index{\the\@temptokenb\noexpand\levelchar - ##1\noexpand\actualchar{\string\ttfamily\space##1}% - \noexpand\encapchar main}% - \fi - \noexpand\@esphack}% - \@nameedef{Special#1Index}##1{% - \noexpand\@bsphack - \ifdoc@toplevel - \noexpand\doc@providetarget - \noexpand\index{##1\noexpand\actualchar{\string\ttfamily\space##1}% - \ifx\@nil#2\@nil\else \the\@temptokena \fi - \noexpand\doc@handleencap{usage}}% - \fi - \ifx\@nil#3\@nil\else - \noexpand\index{\the\@temptokenb\noexpand\levelchar - ##1\noexpand\actualchar{\string\ttfamily\space##1}% - \noexpand\doc@handleencap{usage}}% - \fi - \noexpand\@esphack}} -\def\doc@createspecialmacrolikeindexes#1#2#3{% - \@temptokena{\space (#2)}% - \@temptokenb{#3:}% - \@nameedef{Code#1Index}##1##2{% - \noexpand\@SpecialIndexHelper@##2\noexpand\@nil - \noexpand\@bsphack - \noexpand\ifdoc@noindex\noexpand\else - \ifdoc@toplevel - \noexpand\special@index{\noexpand\@gtempa\noexpand\actualchar -\string\verb% % to fool emacs highlighting -\noexpand\quotechar*\noexpand\verbatimchar -\noexpand\bslash\noexpand\@gtempa\noexpand\verbatimchar -\ifx\@nil#2\@nil\else \the\@temptokena \fi -\noexpand\encapchar ##1}% - \fi - \ifx\@nil#3\@nil\else - \noexpand\special@index{\the\@temptokenb\noexpand\levelchar -\noexpand\@gtempa\noexpand\actualchar -\string\verb% % to fool emacs highlighting -\noexpand\quotechar*\noexpand\verbatimchar -\noexpand\bslash\noexpand\@gtempa\noexpand\verbatimchar -\noexpand\encapchar ##1}% - \fi - \noexpand\fi - \noexpand\@esphack}% - \@nameedef{SpecialMain#1Index}##1{% - \expandafter\noexpand\csname Code#1Index\endcsname - {main}{##1}}% - \@nameedef{Special#1Index}##1{% - \noexpand\@SpecialIndexHelper@##1\noexpand\@nil - \noexpand\@bsphack - \noexpand\ifdoc@noindex\noexpand\else - \ifdoc@toplevel - \noexpand\doc@providetarget - \noexpand\index{\noexpand\@gtempa\noexpand\actualchar -\string\verb% % to fool emacs highlighting -\noexpand\quotechar*\noexpand\verbatimchar -\noexpand\bslash\noexpand\@gtempa\noexpand\verbatimchar -\ifx\@nil#2\@nil\else \the\@temptokena \fi -\noexpand\doc@handleencap{usage}}% - \fi - \ifx\@nil#3\@nil\else - \noexpand\index{\the\@temptokenb\noexpand\levelchar -\noexpand\@gtempa\noexpand\actualchar -\string\verb% % to fool emacs highlighting -\noexpand\quotechar*\noexpand\verbatimchar -\noexpand\bslash\noexpand\@gtempa\noexpand\verbatimchar -\noexpand\doc@handleencap{usage}}% - \fi - \noexpand\fi - \noexpand\@esphack}} - -\def\doc@createdescribe#1{% - \@namedef{Describe#1}{% - \begingroup - \MakePrivateLetters - \@ifnextchar[%] - {\doc@describe{#1}}{\doc@describe{#1}[]}}} -\def\doc@createenv#1#2#3{% - \@namedef{#3}{% - \@ifnextchar[%] - {\doc@env{#1}{#2}}{\doc@env{#1}{#2}[]}}% - \@namedef{end#3}{\endtrivlist}% -} - -\def\@nameedef#1{\expandafter\edef\csname #1\endcsname} - - -\def\doc@declareerror#1#2{% - \PackageError{doc}{Doc element '#1/#2' already defined?\@gobble}% - {There is already a definition for - '\string\Print#1Name',\MessageBreak - '\string\PrintDescribe#1' - or the environment '#2'.\MessageBreak - Maybe you are overwriting something by mistake!\MessageBreak - Otherwise use '\string\RenewDocElement' instead.}% -} - -\def\doc@notdeclarederror#1#2{% - \PackageError{doc}{Doc element '#1/#2' unknown}% - {I expected an existing definition for - '\string\Print#1Name',\MessageBreak - '\string\PrintDescribe#1' and - the environment '#2' but\MessageBreak - not all of them are defined.\MessageBreak - Maybe you wanted to use - '\string\NewDocElement'?}% -} -\newcommand\NewDocElement[3][]{% - \@ifundefined{Print#2Name}% - {\@ifundefined{PrintDescribe#2}% - {\@ifundefined{#3}% - {\@ifundefined{end#3}% - {\@NewDocElement{#1}}% - \doc@declareerror - }\doc@declareerror - }\doc@declareerror - }\doc@declareerror - {#2}{#3}% -} -\newcommand\RenewDocElement[3][]{% - \@ifundefined{Print#2Name}\doc@notdeclarederror - {\@ifundefined{PrintDescribe#2}\doc@notdeclarederror - {\@ifundefined{#3}\doc@notdeclarederror - {\@ifundefined{end#3}\doc@notdeclarederror - {\@NewDocElement{#1}}% - }% - }% - }% - {#2}{#3}% -} -\def\@NewDocElement#1#2#3{% - \doc@macrolikefalse - \doc@topleveltrue - \def\doc@idxtype{#3}% - \def\doc@idxgroup{#3s}% - \let\doc@printtype\@empty - \setkeys{doc}{#1}% - \ifx\doc@printtype\@empty - \@temptokena{}% - \else - \@temptokena\expandafter{\expandafter - \textnormal\expandafter{\expandafter - \space\expandafter - (\doc@printtype)}}% - \fi - \@nameedef{Print#2Name}##1{% - {\noexpand\MacroFont - \ifdoc@macrolike - \noexpand\string - \fi - ##1% - \the\@temptokena - }}% - \expandafter\let\csname PrintDescribe#2\expandafter\endcsname - \csname Print#2Name\endcsname - \edef\doc@expr{% - \ifdoc@macrolike - \noexpand\doc@createspecialmacrolikeindexes - \else - \noexpand\doc@createspecialindexes - \fi - {#2}% - }% - \expandafter\expandafter\expandafter - \doc@expr - \expandafter\expandafter\expandafter - {\expandafter\doc@idxtype\expandafter}\expandafter - {\doc@idxgroup}% - \doc@createdescribe{#2}% - \ifdoc@macrolike - \doc@createenv{TT}{#2}{#3}% - \else - \doc@createenv{TF}{#2}{#3}% - \fi -} - - -\NewDocElement[macrolike = true , - idxtype = , - idxgroup = , - printtype = - ]{Macro}{macro} - -\def\SpecialMainIndex{\SpecialMainMacroIndex} - -\def\SpecialUsageIndex{\SpecialMacroIndex} - -\def\SpecialIndex {\CodeMacroIndex{code}} - -\NewDocElement[macrolike = false , - idxtype = env. , - idxgroup = environments , - printtype = \textit{env.} - ]{Env}{environment} - - -\DeclareRobustCommand\cs[1]{\texttt{\bslash #1}} - \endinput %% -%% End of file `doc-v3beta.sty'. +%% End of file `doc.sty'. diff --git a/macros/latex-dev/base/doc-code.pdf b/macros/latex-dev/base/doc-code.pdf Binary files differnew file mode 100644 index 0000000000..a27820aee9 --- /dev/null +++ b/macros/latex-dev/base/doc-code.pdf diff --git a/macros/latex-dev/base/doc-code.tex b/macros/latex-dev/base/doc-code.tex new file mode 100644 index 0000000000..6457d22e03 --- /dev/null +++ b/macros/latex-dev/base/doc-code.tex @@ -0,0 +1,4 @@ +% this will typeset documentation + code + +\AtBeginDocument{\AlsoImplementation} +\input{doc.dtx} diff --git a/macros/latex-dev/base/doc.dtx b/macros/latex-dev/base/doc.dtx index 41bc073315..e6b0e2cf92 100644 --- a/macros/latex-dev/base/doc.dtx +++ b/macros/latex-dev/base/doc.dtx @@ -1,7 +1,7 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 -% The LaTeX Project and any individual authors listed elsewhere +% Copyright 1993-2022 +% The LaTeX3 Project and any individual authors listed elsewhere % in this file. % % This file is part of the LaTeX base system. @@ -33,10 +33,23 @@ % ^^A category for `<' %\catcode`\<=14 %<+package|shortvrb>\NeedsTeXFormat{LaTeX2e}[1994/12/01] -%<+package> \ProvidesPackage{doc} +%<+package> +%<+package>\providecommand\DeclareRelease[3]{} +%<+package>\providecommand\DeclareCurrentRelease[2]{} +%<+package> +%<+package>\DeclareRelease{v2.1g}{2016-02-15} +%<+package> {doc-2016-02-15.sty} +%<+package>\DeclareRelease{v2}{2021-06-01} +%<+package> {doc-2021-06-01.sty} +%<+package>\DeclareCurrentRelease{v3}{2022-06-01} +%<+package> +%<*package> +%<-beta>\ProvidesPackage{doc} +%<+beta>\ProvidesPackage{doc-v3beta} +%</package> %<+shortvrb>\ProvidesPackage{shortvrb} -%<+package|shortvrb> [2021/10/04 v2.1n -%<+package|shortvrb> Standard LaTeX documentation package (FMi)] +%<+package|shortvrb> [2022/06/01 v3.0g +%<+package|shortvrb> Standard LaTeX documentation package V3 (FMi)] %\catcode`\<=12 % %% @@ -47,7 +60,7 @@ % % %% Package `doc' to use with LaTeX 2e -%% Copyright (C) 1989-2020 Frank Mittelbach, all rights reserved. +%% Copyright (C) 1989-2022 Frank Mittelbach, all rights reserved. % % % Version: Date: Changes: @@ -128,18 +141,103 @@ % \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault} % \DoNotIndex{\bfdefault} % -% \MakeShortVerb{\"} +% \MakeShortVerb{\|} % \setcounter{StandardModuleDepth}{1} % % {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print -% \gdef\dimenvalue#1pt{$#1$pt}} ^^A register values with a - sign +% \gdef\dimenvalue#1pt{$#1$pt}} ^^A a register value with a - sign +% +% \newcommand{\DOC}{\texttt{doc}\xspace} +% +% \newcommand\env{\texttt} +% \newcommand\opt{\texttt} +% \newcommand\cls{\texttt} +% \newcommand\pkg{\texttt} +% \newcommand\prg{\textsf} +% +% \newcommand\DOX{\env{DoX}\xspace} +% \newcommand\api{\textsc{api}\xspace} +% +% \newcommand\fmi[1]{\par\textbf{TODO: }\textit{#1}\par} +% +% \newcommand\NewIn[1]{\leavevmode +% \marginpar{\hfill\fbox{\fbox{New in #1}}\hspace*{1em}}\ignorespaces} +% +% +%\RenewDocElement[macrolike = true , +% toplevel = false, +% idxtype = , +% idxgroup = LaTeX comands\actualchar\LaTeX{} commands , +% printtype = +% ]{Macro}{macro} +% +%\RenewDocElement[macrolike = false , +% toplevel = false, +% idxtype = env. , +% idxgroup = Package environments, +% printtype = \textit{env.} +% ]{Env}{environment} +% +% +%\NewDocElement[macrolike = true , +% toplevel = false, +% idxtype = , +% idxgroup = Package commands, +% printtype = +% ]{InterfaceMacro}{imacro} +% +%\NewDocElement[macrolike = true , +% toplevel = false, +% idxtype = , +% idxgroup = Package commands (obsolete), +% printtype = +% ]{ObsoleteInterfaceMacro}{omacro} +% +%\NewDocElement[macrolike = false , +% toplevel = false, +% idxtype = counter , +% idxgroup = LaTeX counters\actualchar \LaTeX{} counters , +% printtype = \textit{counter} +% ]{LaTeXCounter}{lcounter} +% +%\NewDocElement[macrolike = true , +% toplevel = false, +% idxtype = counter , +% idxgroup = TeX counters\actualchar \protect\TeX{} counters , +% printtype = \textit{counter} +% ]{TeXCounter}{tcounter} +% +% +%\NewDocElement[macrolike = true , +% toplevel = false, +% idxtype = skip , +% idxgroup = LaTeX length\actualchar \LaTeX{} length (skip) , +% printtype = \textit{skip} +% ]{LaTeXSkip}{lskip} +% +%\NewDocElement[macrolike = true , +% toplevel = false, +% idxtype = dimen , +% idxgroup = LaTeX length\actualchar \LaTeX{} length (dimen) , +% printtype = \textit{dimen} +% ]{LaTeXDimen}{ldimen} +% +%\NewDocElement[macrolike = false , +% toplevel = false, +% idxtype = option , +% idxgroup = Package options , +% printtype = \textit{option} +% ]{Option}{option} +% +% \renewcommand\code[1]{\mbox{$\ell$-#1}} +% \renewcommand\main[1]{\underline{\mbox{$\ell$-#1}}} +% \setcounter{IndexColumns}{2} % -% \newcommand{\DOC}{\texttt{doc}} % % \changes{v1.9t}{1995/05/11}{Use \cs{GetFileInfo}} % \GetFileInfo{doc.sty} % -% \CheckSum{2213} ^^A % keep the checksum in this file +% \CheckSum{0} ^^A % keep the checksum in this file but not now :-) % % \title{The \DOC{} and \texttt{shortvrb} Packages\thanks % {This file has version number \fileversion{} dated \filedate{}.}} @@ -149,190 +247,77 @@ % provided by Andrew Mills; fairly substantial additions, % particularly from \texttt{newdoc}, and % documentation of post-v1.5q features added at v1.7a by Dave -% Love (SERC Daresbury Lab). Extraction of \texttt{shortvrb} -% package added by Joachim Schrod (TU~Darmstadt).}} +% Love (SERC Daresbury Lab).}~\thanks +% {Extraction of \texttt{shortvrb} +% package added by Joachim Schrod (TU~Darmstadt).}~\thanks +% {Version~3 now integrates code from Didier Verna's +% \DOX package and some of his documentation was +% reused (a.k.a.\ stolen).}} +% \date{Printed \today} % % \MaintainedByLaTeXTeam{latex} +% % \maketitle % % \begin{abstract} -% This package contains the definitions that are necessary to -% format the documentation of package files. The package was -% developed in Mainz in cooperation with the Royal Military College -% of Science. This is an update which documents various changes -% and new features in \DOC{} and integrates the features of -% \textsf{newdoc}. +% Roughly 30 years ago (version 1.0 was dated 1988/05/05) I wrote +% the first version of the \DOC package, a package to provide code +% documentation for \TeX{} code. Since then it has be used all over +% the place to document the \LaTeX{} kernel and most of the +% packages that are nowadays available. The core code of version 2 +% (which is the current version) exists since 1998, i.e., for 20 +% years. +% +% If I would restart from scratch I would do a lot of things +% differently these days and in fact several other people have +% tried to come up with better solutions. However, as the saying +% goes, a bad standard is better than none, \DOC has prevailed and +% changing it now in incompatible ways is probably not really +% helpful. +% +% So this is version 3 of the package with some smaller extensions +% that are upwards compatible but hopefully serve well. Most +% important modifications are the integration of the +% \pkg{hypdoc} package to enable links within the document (in +% particular from the index) is so desired. Also integrated are the +% ideas from the \DOX package by Didier Verna (although I +% offer a different interface that imho fits better with the rest +% of \DOC's interfaces). Finally I updated a few odds and ends. % \end{abstract} % -% \newif\ifmulticols -% \IfFileExists{multicol.sty}{\multicolstrue}{} % -% \ifmulticols +% \newpage +% % \addtocontents{toc}{\protect\begin{multicols}{2}} -% \fi % -% {\parskip 0pt ^^A We have to reset \parskip +% ^^A{\parskip 0pt ^^A We have to reset \parskip % ^^A (bug in \LaTeX) % \tableofcontents -% } +% ^^A} % % \changes{v1.7a}{1992/02/25}{Miscellaneous small changes to the text} +% \changes{v3.0a}{2018/03/04}{Integrated DoX package} +% \changes{v3.0a}{2018/03/04}{Interfaced hypdoc package} % -% \ifmulticols -% \begin{multicols}{2}[\section*{Preface to version 1.7}] -% \else \section*{Preface to version 1.7} \fi -% -% This version of \texttt{doc.dtx} documents changes which have occurred -% since the last published version \cite{art:doc} but which have been -% present in distributed versions of \texttt{doc.sty} for some time. It -% also integrates the (undocumented) features of the distributed -% \texttt{newdoc.sty}. -% -% The following changes and additions have been made to the user -% interface since the published version~\cite{art:doc}. See -% \S\ref{sec:interface} for more details. -% \begin{description} -% \item[Driver mechanism] "\DocInput" is now used in the driver file -% to input possibly multiple independent \DOC{} files and \DOC{} no -% longer has to be the last package. "\IndexListing" is replaced -% by "\IndexInput"; -% \item[Indexing] is controlled by "\PageIndex" and "\CodelineIndex", -% one of which must be specified to produce an index---there is no -% longer a "\makeindex" in the default "\DocstyleParms"; -% \item[The \texttt{macro} environment] now takes as argument the -% macro name {\em with\/} the backslash; -% \item[Verbatim text] Newlines are now forbidden inside "\verb" and -% commands "\MakeShortVerb" and "\DeleteShortVerb" are provided for -% verbatim shorthand; -% \item[\texttt{\bslash par}] can now be used in "\DoNotIndex"; -% \item[Checksum/character table support] for ensuring the integrity -% of distributions is added; -% \item[\texttt{\bslash printindex}] becomes "\PrintIndex"; -% \item[\texttt{multicol.sty}] is no longer necessary to use \DOC{} or -% print the documentation (although it is recommended); -% \item[`Docstrip' modules] are recognised and formatted specially. -% \end{description} % -% As well as adding some completely new stuff, -% the opportunity has been taken to add some commentary to the code -% formerly in \texttt{newdoc.sty} and that added after version 1.5k of -% \texttt{doc.sty}. Since (as noted in the sections concerned) this -% commentary wasn't written by Frank Mittelbach but the code was, it is -% probably {\em not\/} true in this case that ``if the code and -% comments disagree both are probably wrong''! % -% \subsection*{Bugs} -% -% There are some known bugs in this version: -% \begin{itemize} -% \item The "\DoNotIndex" command doesn't work for some single -% character commands most noticeable "\%". -% \item The `General changes' glossary entry would come out after -% macro names with a leading "!" and possibly a leading |"|; -% \item If you have an old version of \textsf{makeindex} long "\changes" -% entries will come out strangely and you may find the section -% header amalgamated with the first changes entry. Try to get an -% up-to-date one (see p.~\pageref{makeindex:version}); -% \item Because the accompanying \textsf{makeindex} style files support -% the inconsistent attribute specifications of older and newer -% versions \textsf{makeindex} always complains about three `unknown -% specifier's when sorting the index and changes entries. -% \item If "\MakeShortVerb" and "\DeleteShortVerb" are used with -% single character arguments, e.g., "{|}" instead of "{\|}" chaos -% may happen. -% \end{itemize} -% (Some `features' are documented below.) -% -% \subsection*{Wish list} -% -% \begin{itemize} -% \item Hooks to allow "\DescribeMacro" and "\DescribeEnv" to write -% out to a special file information about the package's `exported' -% definitions which they describe. This could subsequently be -% included in the \texttt{docstrip}ped \texttt{.sty} file in a -% suitable form for use by smart editors in command completion, -% spelling checking etc., based on the packages used in a document. -% This would need agreement on a `suitable form'. \item Indexing of -% the modules used in \texttt{docstrip}'s "%<" directives. I'm not -% sure how to index directives containing module combinations; \item -% Writing out bibliographic information about the package; \item Allow -% turning off use of the special font for, say, the next guarded -% block. -% \end{itemize} -% -% \ifmulticols -% \end{multicols} -% -% \begin{multicols}{2}[\medskip \rule{\textwidth}{.3pt} -% \section{Introduction}] -% \else % \section{Introduction} -% \fi -% -% The \TeX{} macros which are described here allow definitions and -% documentation to be held in one and the same file. This has the -% advantage that normally very complicated instructions are made -% simpler to understand by comments inside the definition. In addition -% to this, updates are easier and only one source file needs to be -% changed. On the other hand, because of this, the package files are -% considerably longer: thus \TeX{} takes longer to load them. If this -% is a problem, there is an easy remedy: one needs only to run the -% \texttt{docstrip.tex} program that removes nearly all lines that begin -% with a -% percent sign. % -% The idea of integrated documentation was born with the development -% of the \TeX{} program; it was crystallized in Pascal with the \Web{} -% system. The advantages of this method are plain to see (it's easy -% to make comparisons \cite{art:Knuthliterat}). Since this -% development, systems similar to \Web{} have been developed for other -% programming languages. But for one of the most complicated -% programming languages (\TeX) the documentation has however been -% neglected. The \TeX{} world seems to be divided between:--- -% \begin{itemize} \item a couple of ``wizards'', who produce many -% lines of completely unreadable code ``off the cuff'', and \item many -% users who are amazed that it works just how they want it to do. Or -% rather, who despair that certain macros refuse to do what is -% expected of them.\end{itemize} -% -% I do not think that the \Web{} system is {\em the\/} reference work; -% on the contrary, it is a prototype which suffices for the -% development of programs within the \TeX{} world. It is sufficient, -% but not totally sufficient.\footnote{I know that this will be seen -% differently by a few people, but this product should not be seen as -% the finished product, at least as far as applications concerning -% \TeX{} are concerned. The long-standing debate over `multiple -% change files' shows this well.} As a result of \Web, new programming -% perspectives have been demonstrated; unfortunately, though, they -% haven't been developed further for other programming languages. -% -% The method of documentation of \TeX{} macros which I have introduced -% here should also only be taken as a first sketch. It is designed -% explicitly to run under \LaTeX{} alone. Not because I was of the -% opinion that this was the best starting point, but because from this -% starting point it was the quickest to develop.\footnote{This -% argument is a bad one, however, it is all too often trotted out.} As -% a result of this design decision, I had to move away from the -% concept of modularization; this was certainly a step backward. -% -% I would be happy if this article could spark off discussion over -% \TeX\ documentation. I can only advise anyone who thinks that they -% can cope without documentation to ``Stop Time'' until he or she -% completely understands the \AmSTeX{} source code. +% This is a new version of the \DOC package, written roughly 30 years +% after the initial release. As the package has been used for so long +% (and largely unchanged) +% it is absolutely important to preserve existing interfaces, even if +% we can agree that they could have been done better. % +% So this is a light-weight change, basically adding hyperlink support +% and adding a way to provide generally \DOC elements (not just macros +% and environments) and try to do this properly (which wasn't the case +% for environments either in the past). The ideas for this have been +% stolen from the \DOX package by Didier Verna even though I +% didn't keep his interfaces. % -% -% -% -% \subsection{Using the \DOC{} package} -% -% Just like any other package, invoke it by requesting it with a -% |\usepackage| command in the preamble. \textsf{Doc}'s use of -% |\reversemarginpars| may make it incompatible with some classes. -% \changes{v1.7a}{1992/02/25}{Altered usage info} -% -% -% \ifmulticols\end{multicols}\fi +% Most of the documentation below is from the earlier release which +% accounts for some inconsistencies in presentation, mea culpa. % % % \section{The User Interface}\label{sec:interface} @@ -342,36 +327,38 @@ % package one has to prepare a special driver file which produces the % formatted document. This driver file has the following % characteristics: -% -% \noindent |\documentclass[|\meta{options}]^^A -% |{|\meta{document-class}|}|\\[1pt] +% \begin{quote} +% \noindent |\documentclass|\oarg{options}^^A +% \marg{document-class}\\[1pt] % |\usepackage{doc}|\\[3pt] % \hspace*{10pt}\meta{preamble}\\[3pt] % |\begin{document}|\\[3pt] % \hspace*{10pt}\meta{special input commands}\\[3pt] % |\end{document}| -% -% The \meta{document-class} might be any document class, I normally +% \end{quote} +% The \meta{document-class} might be any document class, I usually % use \texttt{article}. % % In the \meta{preamble} one should place declarations which % manipulate the behavior of the \DOC{} package like % |\DisableCrossrefs| or |\OnlyDescription|. % -% \DescribeMacro\DocInput \DescribeMacro\IndexInput -% Finally the \meta{special input commands} part should contain one or -% more |\DocInput|\meta{file name} and/or -% |\IndexInput|\meta{file name} commands. The +% +% \DescribeInterfaceMacro\DocInput \DescribeInterfaceMacro\IndexInput +% Finally +% the \meta{special input commands} part should contain one or +% more |\DocInput|\marg{file name} and/or +% |\IndexInput|\marg{file name} commands. The % |\DocInput| command is used for files prepared for the % \DOC{} package whereas |\IndexInput| can be used for all kinds of % macro files. See page \pageref{..Input} for more details of -% "\IndexInput". Multiple "\DocInput"s can be used with a +% |\IndexInput|. Multiple |\DocInput|s can be used with a % number of included files which are each self-contained % self-documenting packages---for instance, each containing -% "\maketitle". +% |\maketitle|. % % As an example, the driver file for the \DOC{} package itself is -% the following text surrounded by "%<*driver>" and "%</driver>". +% the following text surrounded by |%<*driver>| and |%</driver>|. % To produce the documentation you can simply run the \texttt{.dtx} % file through \LaTeX{} in which case this code will be executed % (loading the document class \texttt{ltxdoc}, etc.) or you can @@ -379,7 +366,7 @@ % the \texttt{docstrip} program. % The line numbers below are added by % \DOC{}'s formatting. -% Note that the class \textsf{ltxdoc} has the \DOC{} package +% Note that the class \cls{ltxdoc} has the \DOC{} package % preloaded. % \changes{v1.7a}{1992/03/06}{Added % docstrip-derivable driver file as example.} @@ -387,20 +374,83 @@ % \begin{macrocode} %<*driver> \documentclass{ltxdoc} + +\usepackage[T1]{fontenc} +\usepackage{xspace} + +\OnlyDescription + \EnableCrossrefs - %\DisableCrossrefs % Say \DisableCrossrefs if index is ready + %\DisableCrossrefs % Say \DisableCrossrefs if index is ready \CodelineIndex -\RecordChanges % Gather update information - %\OnlyDescription % comment out for implementation details - %\OldMakeindex % use if your MakeIndex is pre-v2.9 -\setlength\hfuzz{15pt} % dont make so many -\hbadness=7000 % over and under full box warnings +\RecordChanges % Gather update information +\SetupDoc{reportchangedates} + %\OnlyDescription % comment out for implementation details +\setlength\hfuzz{15pt} % don't show so many +\hbadness=7000 % over- and underfull box warnings \begin{document} \DocInput{doc.dtx} \end{document} %</driver> % \end{macrocode} % +% \RecordIndexType{\CodelineIndex}{InterfaceMacro} +% \RecordIndexType{\DisableCrossrefs}{InterfaceMacro} +% \RecordIndexType{\DocInput}{InterfaceMacro} +% \RecordIndexType{\EnableCrossrefs}{InterfaceMacro} +% \RecordIndexType{\OnlyDescription}{InterfaceMacro} +% \RecordIndexType{\RecordChanges}{InterfaceMacro} +% \RecordIndexType{\hbadness}{TeXCounter} +% \RecordIndexType{\hfuzz}{LaTeXDimen} +% +% +% \subsection{Package options} +% +% \NewIn{v3} +% Starting with version~3 the \DOC package now offers a small number +% of package options to modify its overall behavior. These are: +% \DescribeOption[noprint]{multicol} +% \DescribeOption[noprint]{nomulticol} +% \DescribeOption[noprint]{hyperref} +% \DescribeOption[noprint]{nohyperref} +% \DescribeOption[noprint]{debugshow} +% \DescribeOption[noprint]{noindex} +% \DescribeOption[noprint]{noprint} +% \DescribeOption[noprint]{reportchangedates} +% \begin{description} +% \item[\opt{hyperref}, \opt{nohyperref}] Boolean (default \texttt{true}). Load the +% \pkg{hyperref} package and make index references to code lines +% and pages and other items clickable links. \opt{nohyperref} is +% the complementary key. +% +% \item[\opt{multicol}, \opt{nomulticol}] Boolean (default \texttt{true}). Load the +% \pkg{multicol} package for use in typesetting the index and the +% list of changes. \opt{nomulticol} is +% the complementary key. +% +% \item[\opt{debugshow}] Boolean (default \texttt{false}). Provide +% various tracing information at the terminal and in the transcript +% file. In particular show which elements are indexed. +% +% \item[\opt{noindex}] Boolean (default \texttt{false}). If set, all +% automatic indexing is suppressed. This option can also be used on +% individual elements as described below. +% +% \item[\opt{noprint}] Boolean (default \texttt{false}). If set, then +% printing of element names in the margin will be suppressed. This +% option can also be used on individual elements as described +% below. +% \item[\opt{reportchangedates}] Boolean (default \texttt{false}). If +% set, then change entries list the date after the version number in +% the change log. +% \end{description} +% +% \DescribeInterfaceMacro{\SetupDoc} Instead of providing options to the \DOC +% package you can call \cs{SetupDoc} and provide them there. This +% allows, for example, to change default values in case \DOC was already +% loaded earlier. +% +% % % \subsection{General conventions} % @@ -413,10 +463,18 @@ % \LaTeX{} commands except that the character `|%|' cannot be % used as a comment character. % \SortIndex{\string^\string^A}{\string\verb\verbatimchar -% \string^\string^A\verbatimchar \encapchar usage} To allow user -% comments, the |^^A| character is defined as a comment character -% later on. Such `metacomments' may be also be included simply by -% surrounding them with "\iffalse" \ldots~"\fi". +% \string^\string^A\verbatimchar \encapchar usage}^^A +% \SortIndex{\string^\string^X}{\string\verb\verbatimchar +% \string^\string^X\verbatimchar \encapchar usage} +% To allow user +% comments, the characters |^^A| and |^^X| are both defined as a comment character +% later on.\footnote{In version 2 it was only +% \texttt{\string^\string^A}, but many keyboards combine +% \texttt{\string^} and \texttt{A} and automatically turn it into +% ``Ä''; so \texttt{\string^\string^X} was added as an +% alternative in version 3.} +% Such `metacomments' may be also be included simply by +% surrounding them with |\iffalse| \ldots~|\fi|. % % All other parts of the file are called `definition parts'. They % contain fractions of the macros described in the `documentation @@ -430,13 +488,17 @@ % \DescribeEnv{macrocode} % On the other hand, if the documentation of these macros is to be % produced, the `definition parts' should be typeset verbatim. To -% achieve this, these parts are surrounded by the \textsf{macrocode} +% achieve this, these parts are surrounded by the \env{macrocode} % environment. % More exactly: before a `definition part' there should be a line -% containing\\ -% \hspace*{\MacroIndent}\verb*+% \begin{macrocode}+\\ -% and after this part a line\\ -% \hspace*{\MacroIndent}\verb*+% \end{macrocode}+\\ +% containing +% \begin{flushleft} +% \hspace*{\MacroIndent}\verb*+% \begin{macrocode}+ +% \end{flushleft} +% and after this part a line +% \begin{flushleft} +% \hspace*{\MacroIndent}\verb*+% \end{macrocode}+ +% \end{flushleft} % There must be {\em exactly\/} four spaces between the |%| % and |\end{macrocode}| --- \TeX{} is looking for this string % and not for the macro while processing a `definition part'. @@ -444,16 +506,16 @@ % Inside a `definition part' all \TeX{} commands are allowed; even the % percent sign could be used to suppress unwanted spaces etc. % -% \DescribeEnv{macrocode*} Instead of the \textsf{macrocode} -% environment one can also use the \textsf{macrocode$*$} environment +% \DescribeEnv{macrocode*} Instead of the \env{macrocode} +% environment one can also use the \env{macrocode$*$} environment % which produces the same results except that spaces are printed as % \nopagebreak\verb*+ + characters. % % % -% \subsection{Describing the usage of new macros} +% \subsection{Describing the usage of macros and environments} % -% \DescribeMacro\DescribeMacro +% \DescribeInterfaceMacro\DescribeMacro % When you describe a new macro you may use |\DescribeMacro| to % indicate that at this point the usage of a specific macro is % explained. It takes one argument which will be printed in the margin @@ -461,35 +523,38 @@ % |\DescribeMacro{\DescribeMacro}| to make clear that this is the % point where the usage of |\DescribeMacro| is explained. % -% \DescribeMacro\DescribeEnv -% An analogous macro |\DescribeEnv| should be used to indicate -% that a \LaTeX{} environment is explained. It will produce a somewhat -% different index entry. Below I used |\DescribeEnv{verbatim}|. +% As the argument to |\DescribeMacro| is a command name, many people +% got used to using the (incorrect) short form, i.e., omitting the +% braces around the argument as in |\DescribeMacro\foo|. This does +% work as long as the macro name consists only of ``letters''. +% However, if the name contains special characters that are normally +% not of type ``letter'' (such as |@|, or in case of \pkg{expl3} |_| +% and |:|) this will fail dramatically. |\DescribeMacro| would then +% receive only a partial command name (up to the first ``non-letter'') +% e.g., |\DescribeMacro\foo@bar| would be equivalent to +% |\DescribeMacro{\foo} @bar| and you can guess that this can +% resulting in both incorrect output and possibly low-level error +% messages. +% +% \DescribeInterfaceMacro\DescribeEnv +% An analogous macro |\DescribeEnv| should be used to indicate that a +% \LaTeX{} environment is explained. It will produce a somewhat +% different index entry and a slightly different display in the +% margin. Below I used |\DescribeEnv{verbatim}|. % -% \DescribeEnv{verbatim} -% It is often a good idea to include examples of the usage of new macros -% in the text. Because of the |%| sign in the first column of every -% row, the \textsf{verbatim} environment is slightly altered to suppress -% those -% characters.\footnote{These macros were written by Rainer -% Sch\"opf~\cite{art:verbatim}. He also -% provided a new \textsf{verbatim} environment -% which can be used inside of other macros.} -% \DescribeEnv{verbatim*} -% The \textsf{verbatim$*$} environment is changed in the same way. -% \changes{v1.7a}{1992/02/26}{Documented \cs{verb} change.} -% \DescribeMacro\verb -% The "\verb" command is re-implemented to give an error report if a -% newline appears in its argument. -% The \textsf{verbatim} and \textsf{verbatim$*$} environments set text -% in the style defined by "\MacroFont"~(\S\ref{sec:macrofont}). % +% \NewIn{v3} +% Starting with version~3 the \cs{Describe...} commands accept an +% optional argument in which you can specify either \opt{noindex} +% or \opt{noprint} to suppress indexing or printing for that +% particular instance. Using both would be possible too, but pointless +% as then the commands wouldn't do anything any more. % % -% \subsection{Describing the definition of new macros} +% \subsection{Describing the definition of macros and environments} % % \DescribeEnv{macro} -% To describe the definition of a new macro we use the \textsf{macro} +% To describe the definition of a (new) macro we use the \env{macro} % environment. It has one argument: the name of the new % macro.\footnote{This is a change to the style design I described in % ^^A \TUB ^^A removed in case ltugboat.sty not used @@ -505,20 +570,26 @@ % labels in the margin are placed under each other. % \changes{v1.7a}{1992/02/26}{Note on need for some text in macro env.} % There should be some text---even if it's just an empty -% "\mbox{}"---in this environment before "\begin{macrocode}" or the +% |\mbox{}|---in this environment before |\begin{macrocode}| or the % marginal label won't print in the right place. % -% \DescribeMacro\MacrocodeTopsep -% \DescribeMacro\MacroTopsep +% \NewIn{v3} +% In fact it is now allowed to specify several macros in the argument, +% separated by commas. This is a short form for starting several +% \env{macro} environments in direct succession. Of course, you +% should then have also only one matching |\end{macro}|. +% +% \DescribeLaTeXSkip\MacrocodeTopsep +% \DescribeLaTeXSkip\MacroTopsep % There also exist four style parameters: |\MacrocodeTopsep| and % |\MacroTopsep| are used to control the vertical spacing above -% and below the \textsf{macrocode} and the \textsf{macro} -% \DescribeMacro\MacroIndent +% and below the \env{macrocode} and the \env{macro} +% \DescribeLaTeXDimen\MacroIndent % environment, |\MacroIndent| is used to indent the lines of code % and -% \DescribeMacro\MacroFont \label{sec:macrofont} +% \DescribeInterfaceMacro\MacroFont \label{sec:macrofont} % |\MacroFont| holds the font and a possible size change command -% for the code lines, the "verbatim"["*"] environment and the macro +% for the code lines, the |verbatim|[|*|] environment and the macro % names printed in the margin. If you want % to change their default values in a % class file (like \texttt{ltugboat.cls}) use the |\DocstyleParms| @@ -526,17 +597,34 @@ % be changed directly as long as the redefinition happens before % the |\begin{document}|. % +% \DescribeEnv{environment} +% For documenting the definition of environments one can use the +% environment \texttt{environment} which works like the \texttt{macro} +% environment, except that it expects an \meta{env-name} +% (without a backslash) +% as its argument and internally provides different index +% entries suitable for environments. +% Nowadays you can alternatively specify a comma-separated list of environments. +% +% \NewIn{v3} +% Starting with version~3 these environments accept an optional +% argument in which you can specify \opt{noindex} or \opt{noprint} or +% both to suppress indexing or printing for that particular +% instance. If any such setting is made on the environment level it +% overwrites whatever default was given when the \DOC element was +% defined or when the package was loaded. +% % % % -% \subsection{Formatting the margins} +% \subsection{Formatting names in the margin} % -% \DescribeMacro\PrintDescribeMacro -% \DescribeMacro\PrintDescribeEnv -% \DescribeMacro\PrintMacroName -% \DescribeMacro\PrintEnvName -% As mentioned earlier, some macros and the \textsf{macro} environment -% print their arguments in the margin. This is actually done by four +% \DescribeInterfaceMacro\PrintDescribeMacro +% \DescribeInterfaceMacro\PrintDescribeEnv +% \DescribeInterfaceMacro\PrintMacroName +% \DescribeInterfaceMacro\PrintEnvName +% As mentioned earlier, some macros and environment +% print their arguments in the margin. The actual formatting is done by four % macros which are user % definable.\footnote{You may place the changed definitions in a % separate package @@ -544,33 +632,157 @@ % file. % For example, if you don't like any names in the % margin -% but want a fine index you can simply -% \texttt{\bslash let} -% these macros equal \texttt{\bslash @gobble}. -% The doc package won't redefine any existing -% definitions of these macros.} -% They are named |\PrintDescribeMacro|, |\PrintDescribeEnv|, -% |\PrintMacroName| (called by the \textsf{macro} environment) and -% |\PrintEnvName| (called by the \textsf{environment} environment). +% but want a fine index you can simply redefine them +% accept their argument and do nothing with it.} +% They are named |\PrintDescribeMacro| and |\PrintDescribeEnv| (defining +% how |\DescribeMacro| and |\DescribeEnv| behave) and +% |\PrintMacroName| and +% |\PrintEnvName| (called by the \env{macro} and \env{environment} +% environments, respectively). +% +% +% \subsection{Providing further documentation items} +% +% Out of the box the \DOC package offers the above commands and +% environments to document macros and environments. +% \NewIn{v3} +% With version 3 +% this has now been extended in a generic fashion so that you can +% easily provide your own items, such as counters, length register, +% options etc. +% +% \DescribeInterfaceMacro{\NewDocElement} +% The general syntax for providing a new \DOC element is +% \begin{quote} +% \cs{NewDocElement}\oarg{options}\marg{element-name}\marg{env-name} +% \end{quote} +% By convention the \meta{element-name} has the first letter +% uppercased as in \texttt{Env} or \texttt{Macro}. +% +% Such a declaration will define for you +% \begin{itemize} +% \item the command |\Describe|\meta{element-name} which has the +% syntax +% \begin{quote} +% |\Describe|\meta{element-name}\oarg{options}\marg{element} +% \end{quote} +% +% \item the environment \meta{env-name} which has the syntax +% \begin{quote} +% \cs{begin}\marg{env-name}\oarg{options}\marg{element} +% \end{quote} +% +% \item the display command |\PrintDescribe|\meta{element-name} with +% the syntax +% \begin{quote} +% |\PrintDescribe|\meta{element-name}\marg{element} +% \end{quote} +% +% \item and the +% |\Print|\meta{element-name}|Name| display command for the +% environment. +% \end{itemize} +% If any of the commands or the environment is already defined (which +% especially with the \meta{env-name} is a danger) then you will +% receive an error telling you so. +% +% \DescribeInterfaceMacro{\RenewDocElement} +% If you want to modify an existing \DOC element use +% |\RenewDocElement| instead. +% +% For example, the already provided ``\texttt{Env}'' \DOC element could have been +% defined simply by making the declaration +% |\NewDocElement{Env}{environment}| +% though that's not quite what has been done, as we will see later. +% +% \DescribeOption[noprint]{macrolike} +% \DescribeOption[noprint]{envlike} +% \DescribeOption[noprint]{toplevel} +% \DescribeOption[noprint]{notoplevel} +% \DescribeOption[noprint]{idxtype} +% \DescribeOption[noprint]{printtype} +% \DescribeOption[noprint]{idxgroup} +% The \meta{options} are keyword/value and define further details on +% how that \DOC element should behave. They are: +% \begin{description} +% \item[\opt{macrolike}] Boolean (default \opt{false}). Does this \DOC +% element starts with a backslash? +% +% \item[\opt{envlike}] Boolean. Complementary option to +% \opt{macrolike}. +% +% \item[\opt{toplevel}] Boolean (default \opt{true}). Should all +% a top-level index entry be made? If set to \texttt{false} then +% either no index entries are produced or only grouped index entries +% (see \opt{idxgroup} for details). +% +% \item[\opt{notoplevel}] Boolean. Complementary option to +% \opt{toplevel}. +% +% \item[\opt{idxtype}] String (default \meta{env-name}). What to put +% (in parentheses if non-empty) at the end of a top-level index entry. +% +% \item[\opt{printtype}] String (default \meta{env-name}). What to put +% (in parentheses if non-empty) after an element name in the margin. +% +% \item[\opt{idxgroup}] String (default +% \meta{env-name}\texttt{s}). Name of the top-level index entry if +% entries are grouped. They are only grouped if this option is +% non-empty. +% +% \item[\opt{noindex}] Boolean (default \texttt{false}). If set this +% will suppress indexing for elements of this type. This setting +% overwrite any global setting of \opt{noindex}. % +% \item[\opt{noprint}] Boolean (default \texttt{false}). If set this +% will suppress printing the element name in the margin. This setting +% overwrite any global setting of \opt{noprint}. +% \end{description} +% As usual giving a boolean option without a value sets it to +% \texttt{true}. + + + + +% \subsection{Displaying sample code verbatim} % +% \DescribeEnv{verbatim} +% It is often a good idea to include examples of the usage of new macros +% in the text. Because of the |%| sign in the first column of every +% row, the \env{verbatim} environment is slightly altered to suppress +% those +% characters.\footnote{These macros were written by Rainer +% Schöpf~\cite{art:verbatim}. He also +% provided a new \env{verbatim} environment +% which can be used inside of other macros.} +% \DescribeEnv{verbatim*} +% The \env{verbatim$*$} environment is changed in the same way. +% \changes{v1.7a}{1992/02/26}{Documented \cs{verb} change.} +% \DescribeInterfaceMacro\verb +% The |\verb| command is re-implemented to give an error report if a +% newline appears in its argument. +% The \env{verbatim} and \env{verbatim$*$} environments set text +% in the style defined by |\MacroFont|~(\S\ref{sec:macrofont}). +% +% + % \subsection{Using a special escape character} % -% \DescribeMacro\SpecialEscapechar +% \DescribeInterfaceMacro\SpecialEscapechar % If one defines complicated macros it is sometimes necessary to % introduce a new escape character because the `|\|' has got a % special |\catcode|. In this case one can use % |\SpecialEscapechar| to indicate which character is actually % used to play the r\^ole of the `|\|'. A scheme like this is -% needed because the \textsf{macrocode} environment and its counterpart -% \textsf{macrocode$*$} produce an index entry for every occurrence of a +% needed because the \env{macrocode} environment and its counterpart +% \env{macrocode$*$} produce an index entry for every occurrence of a % macro name. They would be very confused if you didn't tell them that % you'd changed |\catcode|$\,$s. The argument to % |\SpecialEscapechar| is a single-letter control sequence, that -% is, one has to use "\|" for example to denote that `\verb+|+' +% is, one has to use \verb=\|= for example to denote that `\verb+|+' % is used as an escape character. |\SpecialEscapechar| only -% changes the behavior of the next \textsf{macrocode} or -% \textsf{macrocode$*$} environment. +% changes the behavior of the next \env{macrocode} or +% \env{macrocode$*$} environment. % % The actual index entries created will all be printed with |\| % rather than \verb+|+, but this probably reflects their usage, if not @@ -582,20 +794,24 @@ % % \subsection{Cross-referencing all macros used} % -% \DescribeMacro\DisableCrossrefs \DescribeMacro\EnableCrossrefs As -% already mentioned, every new macro name used within a -% \textsf{macrocode} or \textsf{macrocode$*$} environment will produce -% an index entry. In this way one can easily find out where a specific -% macro is used. Since \TeX{} is considerably slower when it has to -% produce such a bulk of index entries one can turn off this feature -% by using |\DisableCrossrefs| in the driver file. To turn it on again -% just use |\EnableCrossrefs|.\footnote{Actually, \texttt{\bslash -% EnableCrossrefs} changes things more drastically; any following -% \texttt{\bslash DisableCrossrefs} which might be present in the -% source will be ignored.} -% -% -% \DescribeMacro\DoNotIndex +% \DescribeInterfaceMacro\DisableCrossrefs \DescribeInterfaceMacro\EnableCrossrefs As +% already mentioned, every macro name used within a +% \env{macrocode} or \env{macrocode$*$} environment will produce an +% index entry. In this way one can easily find out where a specific +% macro is used. Since \TeX{} is considerably slower\footnote{This +% comment was written about 30 years ago. \TeX{} is still considerably +% slower but while it took minutes to process a large document (such +% as the \LaTeX{} kernel documentation) it takes seconds or less these +% days. Thus \cs{DisableCrossrefs} isn't really that necessary these +% days.} when it has to produce such a bulk of index entries one can +% turn off this feature by using |\DisableCrossrefs| in the driver +% file. To turn it on again just use +% |\EnableCrossrefs|.\footnote{Actually, \cs{EnableCrossrefs} changes +% things more drastically; any following call to \cs{DisableCrossrefs} +% which might be present in the source will be ignored.} +% +% +% \DescribeInterfaceMacro\DoNotIndex % But also finer control is provided. The |\DoNotIndex| macro % takes a list of macro names separated by commas. Those names won't % show up in the index. You might use several |\DoNotIndex| @@ -605,26 +821,28 @@ % % All three above declarations are local to the current group. % -% Production (or not) of the index (via the "\makeindex" commend) is +% Production (or not) of the index (via the |\makeindex| commend) is % controlled by using or omitting the following declarations in the % driver file preamble; if neither is used, no index is produced. -% \DescribeMacro\PageIndex Using "\PageIndex" makes all index +% \DescribeInterfaceMacro\PageIndex Using |\PageIndex| makes all index % entries refer to their page number; with -% \DescribeMacro\CodelineIndex "\CodelineIndex", index entries -% produced by "\DescribeMacro" and "\DescribeEnv" refer to page number -% but those produced by the \textsf{macro} environment refer to the +% \DescribeInterfaceMacro\CodelineIndex |\CodelineIndex|, index entries +% produced by |\DescribeMacro| and |\DescribeEnv| and possibly further +% |\Describe...| commands refer to a page number +% but those produced by the \env{macro} environment (or other \DOC +% element environments) refer to the % code lines, which will be numbered automatically.\footnote{The line % number is actually that of the first line of the first -% \textsf{macrocode} environment in the \textsf{macro} environment.} -% \DescribeMacro\theCodelineNo +% \env{macrocode} environment in the \env{macro} environment.} +% \DescribeInterfaceMacro\theCodelineNo % The style of this numbering can be controlled by defining the macro -% "\theCodelineNo". Its default definition is to use scriptsize +% |\theCodelineNo|. Its default definition is to use scriptsize % arabic numerals; a user-supplied definition won't be overwritten. % -% \DescribeMacro\CodelineNumbered +% \DescribeInterfaceMacro\CodelineNumbered % When you don't wish to get an index but want your code lines -% numbered use "\CodelineNumbered" instead of "\CodelineIndex". This -% prevents the generation of an unnecessary ".idx" file. +% numbered use |\CodelineNumbered| instead of |\CodelineIndex|. This +% prevents the generation of an unnecessary |.idx| file. % % % \subsection{Producing the actual index entries} @@ -632,7 +850,7 @@ % Several of the aforementioned macros will produce some sort of index % entries. These entries have to be sorted by an external % program---the current implementation assumes that the -% \textsf{makeindex} program by Chen~\cite{art:Chen} is used. +% \prg{makeindex} program by Chen~\cite{art:Chen} is used. % % But this isn't built in: one has only to redefine some of the % following macros to be able to use any other index program. All @@ -644,25 +862,25 @@ % % To allow the user to change the specific characters recognized by % his or her index program all characters which have special meaning -% in the \textsf{makeindex} program are given symbolic +% in the \prg{makeindex} program are given symbolic % names.\footnote{I don't know if there exists a program which needs % more command characters, but I hope not.} % However, all characters used should be of |\catcode| other than % `letter' (11). % -% \DescribeMacro{\actualchar} +% \DescribeInterfaceMacro{\actualchar} % The |\actualchar| is used to separate the `key' and the actual % index entry. -% \DescribeMacro{\quotechar} +% \DescribeInterfaceMacro{\quotechar} % The |\quotechar| is used before a special index program % character to suppress its special meaning. -% \DescribeMacro{\encapchar} +% \DescribeInterfaceMacro{\encapchar} % The |\encapchar| separates the indexing information from a -% letter string which \textsf{makeindex} uses as a \TeX{} command to +% letter string which \prg{makeindex} uses as a \TeX{} command to % format the page number associated with a special entry. It is used % in this package to apply the |\main| and the |\usage| % commands. -% \DescribeMacro{\levelchar} +% \DescribeInterfaceMacro{\levelchar} % Additionally |\levelchar| is used to separate `item', % `subitem' and `subsubitem' entries. % @@ -670,33 +888,54 @@ % which index program is used. In this way your files will be % portable. % -% \DescribeMacro\SpecialMainIndex -% \DescribeMacro\SpecialMainEnvIndex +% \fmi{describe old \cs{SpecialMainIndex} and \cs{SpecialUsageIndex}} +% +% \DescribeInterfaceMacro\SpecialMainMacroIndex +% \DescribeInterfaceMacro\SpecialMainEnvIndex % To produce a main index entry for a macro the -% |\SpecialMainIndex| macro\footnote{This macro is called by the -% \textsf{macro} environment.} may be used. It is called `special' +% |\SpecialMainMacroIndex| macro\footnote{This macro is called by the +% \env{macro} environment.} may be used. It is called `special' % because it has to print its argument verbatim. % A similar macro, called |\SpecialMainEnvIndex| is used for indexing % the main definition point of an % environment.\footnote{This macro is called by the -% \textsf{environment} environment.} -% \DescribeMacro\SpecialIndex -% If you want a normal index entry for a macro name -% |\SpecialIndex| might be used.\footnote{This macro is called -% within the \textsf{macrocode} environment when encountering a macro -% name.} -% \DescribeMacro\SpecialUsageIndex -% \DescribeMacro\SpecialEnvIndex +% \env{environment} environment.} +% +% \DescribeInterfaceMacro\SpecialMacroIndex +% \DescribeInterfaceMacro\SpecialEnvIndex % To index the usage of a macro or an environment -% |\SpecialUsageIndex| and |\SpecialEnvIndex| may be used. -% \DescribeMacro\SortIndex -% Additionally a |\SortIndex| command is provided. It takes two -% arguments---the sort key and the actual index entry. +% |\SpecialMacroIndex| and |\SpecialEnvIndex| may be used. % % All these macros are normally used by other macros; you will need % them only in an emergency. % -% \DescribeMacro\verbatimchar +% \NewIn{v3} +% If further code elements are declared with +% |\NewDocElement|\marg{name}\texttt{...} then this sets up +% additional indexing commands, e.g., +% \cs{SpecialMain\meta{name}Index}. +% +% \DescribeInterfaceMacro\SpecialIndex +% The \env{macrocode} environment is automatically indexing macros +% (normally by code line number). You can (with care) also do this +% manually by +% |\SpecialIndex|. However, note that if |\CodelineIndex| is used +% this will generate an entry referring to the last code line which is +% usually not what you want. It does, however, make some sense if you +% always refer to pages only, i.e., if you use |\PageIndex|. +% +% \DescribeInterfaceMacro\SpecialShortIndex +% \NewIn{v3} +% For single character macros, e.g., |\{|, doesn't always work +% correctly. +% For this reason there is now also +% a special variant the can produce correct index entries for them. +% +% \DescribeInterfaceMacro\SortIndex +% Additionally a |\SortIndex| command is provided. It takes two +% arguments---the sort key and the actual index entry. +% +% \DescribeInterfaceMacro\verbatimchar % But there is one characteristic worth mentioning: all macro names in % the index are typeset with the |\verb*| command. Therefore one % special character is needed to act as a delimiter for this command. @@ -704,12 +943,14 @@ % referenced indirectly, by the macro |\verbatimchar|. It expands % by default to \verb?+? but if your code lines contain macros with % `\texttt{+}' characters in their names (e.g.\ when you use \verb?\+?) -% you will end up with an index entry containing \verb?\verb+\++? -% which will be typeset as `\verb+\++' and not as `\verb?\+?'. In this -% case you should redefine |\verbatimchar| globally or locally to -% overcome this problem. -% -% \DescribeMacro\* +% then that caused a problem because you ended up with an +% index entry containing \verb?\verb+\++? +% which will be typeset as `\verb+\++' and not as `\verb?\+?'. +% \NewIn{v3} +% In version 3 this is now automatically taken care of (with the help +% of the |\SpecialShortIndex| command). +% +% \DescribeInterfaceMacro\* % We also provide a |\*| macro. This is intended to be used for % index entries like % \begin{quote} @@ -721,49 +962,39 @@ % \index{index entries\levelchar Special macros for \*} %\end{verbatim} % -% \DescribeMacro\OldMakeindex -% Versions of \textsf{makeindex} prior to 2.9 had some bugs affecting -% \DOC{}. One of these, -% pertaining to the "%" character doesn't have a work-around -% appropriate for versions with and without the -% bug.\label{makeindex:version} If -% you have an old version, invoke "\OldMakeindex" in a -% package file or the driver file to prevent problems with index entries -% such as "\%", although you'll probably normally want to turn off -% indexing of "\%" anyway. Try to get an up-to-date \textsf{makeindex} -% from one of the \TeX{} repositories. -% % % \subsection{Setting the index entries} % % \changes{v1.7a}{1992/03/11}{Usage note on gind.ist.} After the first % formatting pass through the \texttt{.dtx} file you need to sort the % index entries written to the \texttt{.idx} file using -% \textsf{makeindex} or your favourite alternative. You need a -% suitable style file for \textsf{makeindex} (specified by the +% \prg{makeindex} or your favorite alternative. You need a +% suitable style file for \prg{makeindex} (specified by the % \texttt{-s} switch). A suitable one is supplied with \DOC{}, % called \texttt{gind.ist}. % -% \DescribeMacro\PrintIndex +% \DescribeInterfaceMacro\PrintIndex % To read in and print the sorted index, just put the % |\PrintIndex| command as the last (commented-out, and thus % executed during the documentation pass through the file) command % in your package file. Precede it by any bibliography commands % necessary for your citations. % Alternatively, it may be more convenient to put all such calls -% amongt the arguments of the |\StopEventually| macro, in +% amongst the arguments of the |\MaybeStop| macro, in % which case a |\Finale| command should appear at the end of % your file. % % \DescribeEnv{theindex} % Contrary to standard \LaTeX, the index is typeset in three columns -% by default. This is controlled by the \LaTeX{} counter +% by default. +% \DescribeLaTeXCounter{IndexColumns} +% This is controlled by the \LaTeX{} counter % `\textsf{IndexColumns}' and can therefore be changed with a % |\setcounter| declaration. Additionally one doesn't want to -% start a new page unnecessarily. Therefore the \textsf{theindex} +% start a new page unnecessarily. Therefore the \env{theindex} % environment is redefined. -% \DescribeMacro\IndexMin -% When the \textsf{theindex} environment starts it will measure how much +% \DescribeLaTeXDimen\IndexMin +% When the \env{theindex} environment starts it will measure how much % space is left on the current page. If this is more than % |\IndexMin| then the index will start on this page. Otherwise % |\newpage| is called. @@ -771,23 +1002,23 @@ % Then a short introduction about the meaning of several index entries % is typeset (still in onecolumn mode). Afterwards the actual index % entries follow in multi-column mode. -% \DescribeMacro\IndexPrologue +% \DescribeInterfaceMacro\IndexPrologue % You can change this prologue with the help of the % |\IndexPrologue| macro. Actually the section heading is also % produced in this way, so you'd better write something like: % \begin{verbatim} % \IndexPrologue{\section*{Index} The index entries underlined ...} %\end{verbatim} -% When the \textsf{theindex} environment is finished the last page will +% When the \env{theindex} environment is finished the last page will % be reformatted to produce balanced columns. This improves the layout % and allows the next article to start on the same page. -% \DescribeMacro\IndexParms +% \DescribeInterfaceMacro\IndexParms % Formatting of the index columns (values for |\columnssep| % etc.)\ is controlled by the |\IndexParms| macro. It assigns the % following values: -% \SpecialUsageIndex{\parindent}\SpecialUsageIndex{\columnsep}^^A -% \SpecialUsageIndex{\parskip}\SpecialUsageIndex{\rightskip}^^A -% \SpecialUsageIndex{\mathsurround}\SpecialUsageIndex{\parfillskip} +% \SpecialLaTeXDimenIndex{\parindent}\SpecialLaTeXDimenIndex{\columnsep}^^A +% \SpecialLaTeXSkipIndex{\parskip}\SpecialLaTeXSkipIndex{\rightskip}^^A +% \SpecialLaTeXDimenIndex{\mathsurround}\SpecialLaTeXSkipIndex{\parfillskip} % \begin{center} % \begin{tabular}{l@{\,=\,}ll@{\,=\,}l} % |\parindent| & \IndexParms \the\parindent & @@ -800,24 +1031,27 @@ % \expandafter\dimenvalue\the\parfillskip % \end{tabular} % \end{center} -% \DescribeMacro{\@idxitem} +% \DescribeInterfaceMacro{\@idxitem} % Additionally it defines |\@idxitem| (which will be used when an % |\item| command is encountered) and selects |\small| size. % If you want to change any of these values you have to define them % all. % -% \DescribeMacro\main -% \DescribeMacro\usage +% \DescribeInterfaceMacro\main +% \DescribeInterfaceMacro\usage +% \DescribeInterfaceMacro\code % The page numbers for main index entries are encapsulated by the % |\main| macro (underlining its argument) and the numbers % denoting the description are encapsulated by the |\usage| macro -% (which produces {\em italics}). As usual these commands are user +% (which produces \textit{italics}). |\code| encapsulates page or code +% line numbers in entries generated by parsing the code inside +% \env{macrocode} environments. As usual these commands are user % definable. % % % \subsection{Changing the default values of style parameters} % -% \DescribeMacro\DocstyleParms If you want to overwrite some default +% \DescribeInterfaceMacro\DocstyleParms If you want to overwrite some default % settings made by the \DOC{} package, you can either put your % declarations in the driver file (that is after \texttt{doc.sty} is % read in) or use a separate package file for doing this work. In the @@ -828,10 +1062,13 @@ % % The doc package currently assigns values to the following % registers: -% \SpecialUsageIndex{\IndexMin}\SpecialUsageIndex{\MacrocodeTopsep}^^A -% \SpecialUsageIndex{\MacroTopsep}^^A -% \SpecialUsageIndex{\MacroIndent}\SpecialUsageIndex{\marginparpush}^^A -% \SpecialUsageIndex{\marginparwidth}\SpecialUsageIndex{\tolerance} +% \SpecialLaTeXDimenIndex{\IndexMin}^^A +% \SpecialLaTeXSkipIndex{\MacrocodeTopsep}^^A +% \SpecialLaTeXSkipIndex{\MacroTopsep}^^A +% \SpecialLaTeXDimenIndex{\MacroIndent}^^A +% \SpecialLaTeXDimenIndex{\marginparpush}^^A +% \SpecialLaTeXDimenIndex{\marginparwidth}^^A +% \SpecialTeXCounterIndex{\tolerance} % \begin{center} % \begin{tabular}{l@{\,=\,}ll@{\,=\,}l} % |\IndexMin| & \the\IndexMin & @@ -847,34 +1084,34 @@ % % \subsection{Short input of verbatim text pieces} % -% \DescribeMacro\MakeShortVerb -% \DescribeMacro{\MakeShortVerb*} \DescribeMacro\DeleteShortVerb It is -% awkward to have to type, say, "\verb|"\ldots"|" continually when +% \DescribeInterfaceMacro\MakeShortVerb +% \DescribeInterfaceMacro{\MakeShortVerb*} \DescribeInterfaceMacro\DeleteShortVerb It is +% awkward to have to type, say, \verb"\verb|"\ldots\verb"|" continually when % quoting % verbatim bits (like macro names) in the text, so an abbreviation % mechanism is provided. Pick a character \meta{c}---one which % normally has catcode `other' unless you have very good reason not % to---which you don't envisage using in the text, or not using often. -% (I like |"|, but you may prefer "|" if you have |"| active to do +% (I like |"|, but you may prefer \verb"|" if you have |"| active to do % umlauts, for instance.) Then if you say -% "\MakeShortVerb{\"\meta{c}"}" you can subsequently use +% |\MakeShortVerb{\|\meta{c}|}| you can subsequently use % \meta{c}\meta{text}\meta{c} as the equivalent of -% "\verb"\meta{c}\meta{text}\meta{c}; analogously, the "*"-form -% "\MakeShortVerb*{\"\meta{c}"}" gives you the equivalent of -% "\verb*"\meta{c}\meta{text}\meta{c}. Use -% "\DeleteShortVerb{\"\meta{c}"}" if you subsequently want \meta{c} to +% |\verb|\meta{c}\meta{text}\meta{c}; analogously, the |*|-form +% |\MakeShortVerb*{\|\meta{c}|}| gives you the equivalent of +% |\verb*|\meta{c}\meta{text}\meta{c}. Use +% |\DeleteShortVerb{\|\meta{c}|}| if you subsequently want \meta{c} to % revert to its previous meaning---you can always turn it on again % after the unusual section. The `short verb' commands make global -% changes. The abbreviated "\verb" may not appear in the argument of -% another command just like "\verb". However the `short verb' -% character may be used freely in the \textsf{verbatim} and -% \textsf{macrocode} environments without ill effect. -% "\DeleteShortVerb" is silently ignored if its argument does not +% changes. The abbreviated |\verb| may not appear in the argument of +% another command just like |\verb|. However the `short verb' +% character may be used freely in the \env{verbatim} and +% \env{macrocode} environments without ill effect. +% |\DeleteShortVerb| is silently ignored if its argument does not % currently represent a short verb character. Both commands type a % message to tell you the meaning of the character is being changed. % -% Please remember that the command "\verb" cannot be used in arguments -% of other commands. Therefore abbreviation characters for "\verb" +% Please remember that the command |\verb| cannot be used in arguments +% of other commands. Therefore abbreviation characters for |\verb| % cannot be used there either. % % This feature is also available as a sole package, \texttt{shortvrb}. @@ -885,24 +1122,33 @@ % We provide macros for logos such as \Web, \AmSTeX, \BibTeX, % \SliTeX{} and \PlainTeX. Just type |\Web|, |\AmSTeX|, % |\BibTeX|, |\SliTeX| or |\PlainTeX|, respectively. -% \LaTeX{} and \TeX{} are already defined in the \LaTeX{} format. +% \LaTeX{} and \TeX{} are already defined in \texttt{latex.tex}. % -% \DescribeMacro\meta +% \DescribeInterfaceMacro\meta % Another useful macro is |\meta| which has one argument and % produces something like \meta{dimen parameter}. % -% \DescribeMacro\OnlyDescription -% \DescribeMacro\StopEventually +% \DescribeInterfaceMacro\OnlyDescription +% \DescribeInterfaceMacro\MaybeStop +% \DescribeObsoleteInterfaceMacro\StopEventually % You can use the |\OnlyDescription| declaration in the driver % file to suppress the last part of your document (which presumably % exhibits the code). To make this work -% you have to place the command |\StopEventually| at a suitable -% point in your file. This macro has one argument in which you put +% \NewIn{v3} +% you have to place the command |\MaybeStop| at a suitable +% point in your file. This macro\footnote{For about 30 years this +% macro was called \cs{StopEventually} which was due to a ``false +% friend'' misunderstanding. In the German language the word +% ``eventuell'' mean roughly ``perhaps'' which isn't quite the same +% as ``eventually''. But given that this is now used for so long +% and all over the place we can't drop the old name. So it is still +% there to allow processing all the existing documentation.} +% has one argument in which you put % all information you want to see printed if your document ends at % this point (for example a bibliography which is normally printed at % the very end). When the |\OnlyDescription| declaration is -% missing the |\StopEventually| -% \DescribeMacro\Finale +% missing the |\MaybeStop| +% \DescribeInterfaceMacro\Finale % macro saves its argument in a macro called |\Finale| which can % afterwards be used to get things back (usually at the very end). % Such a scheme makes changes in two places unnecessary. @@ -910,17 +1156,17 @@ % Thus you can use this feature to produce a local guide for the % \TeX{} users which describes only the usage of macros (most of them % won't be interested in your definitions anyway). For the same -% reason the |\maketitle| \DescribeMacro\maketitle command is slightly +% reason the |\maketitle| \DescribeInterfaceMacro\maketitle command is slightly % changed to allow multiple titles in one document. So you can make % one driver file reading in several articles at once. -% \DescribeMacro{\ps@titlepage} To avoid an unwanted +% \DescribeInterfaceMacro{\ps@titlepage} To avoid an unwanted % \textsf{pagestyle} on the title page the |\maketitle| command issues % a |\thispagestyle{titlepage}| declaration which produces a % \textsf{plain} page if the \textsf{titlepage} page style is -% undefined. This allows class files like \textsf{ltugboat.cls} to +% undefined. This allows class files like \cls{ltugboat.cls} to % define their own page styles for title pages. % -% \DescribeMacro\AlsoImplementation +% \DescribeInterfaceMacro\AlsoImplementation % Typesetting the whole document is the default. However, this default % can also be explicitly selected using the declaration % |\AlsoImplementation|. This overwrites any previous @@ -933,24 +1179,23 @@ % \end{quote} % to make sure that all documents will show the code part. % -% \DescribeMacro\IndexInput \label{..Input} Last but not least I +% \DescribeInterfaceMacro\IndexInput \label{..Input} Last but not least I % defined an |\IndexInput| macro which takes a file name as an % argument and produces a verbatim listing of the file, indexing every % command as it goes along. This might be handy, if you want to learn % something about macros without enough documentation. I used this -% feature to cross-reference \texttt{latex.tex} (these days -% called \texttt{latex.ltx}) getting a verbatim +% feature to cross-reference \texttt{latex.tex} getting a verbatim % copy with about 15 pages index.\footnote{It took quite a long time % and the resulting \texttt{.idx} file was longer than the % \texttt{.dvi} file. Actually too long to be handled by the -% \textsf{makeindex} program directly (on our MicroVAX) but the final +% \prg{makeindex} program directly (on our MicroVAX) but the final % result was worth the trouble.} % % \changes{v2.1d}{2006/02/02}{Corrected description of \cs{changes} % macro.} -% \DescribeMacro\changes +% \DescribeInterfaceMacro\changes % To maintain a change history within the file, the |\changes| -% command may be placed amongt the description part of the changed +% command may be placed amongst the description part of the changed % code. It takes three arguments, thus: % \begin{quote} % |\changes{|\meta{version}|}{|\meta{date}|}{|^^A @@ -960,7 +1205,7 @@ % |\glossary| mechanism is used for this) which may be printed % after suitable formatting. The |\changes| macro generates the % printed entry in such a change history; because old -% versions\footnote{Before 2.6.} of the \textsf{makeindex} +% versions\footnote{Before 2.6.} of the \prg{makeindex} % program limit such fields to 64 characters, care should be taken % not to exceed this limit when describing the change. The actual % entry consists of the \meta{version}, the |\actualchar|, the current @@ -970,101 +1215,38 @@ % text |\generalname| is used instead of the macro name. When % referring to macros in change descriptions it is conventional to use % |\cs{|\meta{macroname}|}| rather than attempting to format it properly -% and using up valuable characters in the entry with old \textsf{makeindex} +% and using up valuable characters in the entry with old \prg{makeindex} % versions. % % \changes{v1.7a}{1992/02/26}{Description of \cs{RecordChanges} etc. % added -% to interface section.} \DescribeMacro\RecordChanges To cause the -% change information to be written out, include "\RecordChanges" in -% the driver file. \DescribeMacro\PrintChanges To read in and print +% to interface section.} \DescribeInterfaceMacro\RecordChanges To cause the +% change information to be written out, include |\RecordChanges| in +% the driver file. \DescribeInterfaceMacro\PrintChanges To read in and print % the sorted change history (in two columns), just put the % |\PrintChanges| command as the last (commented-out, and thus % executed during the documentation pass through the file) command in % your package file. Alternatively, this command may form one of the -% arguments of the |\StopEventually| command, although a change +% arguments of the |\MaybeStop| command, although a change % history is probably {\em not\/} required if only the description is -% being printed. The command assumes that \textsf{makeindex} or some +% being printed. The command assumes that \prg{makeindex} or some % other program has processed the \texttt{.glo} file to generate a -% sorted \texttt{.gls} file. You need a special \textsf{makeindex} +% sorted \texttt{.gls} file. You need a special \prg{makeindex} % style file; a suitable one is supplied with \DOC{}, called -% \texttt{gglo.ist}. \DescribeMacro\GlossaryMin -% \DescribeMacro\GlossaryPrologue \DescribeMacro\GlossaryParms The -% "\GlossaryMin", "\GlossaryPrologue" and "\GlossaryParms" macros are -% analogous to the "\Index"\ldots\ versions. (The \LaTeX{} `glossary' +% \texttt{gglo.ist}. +% +% \DescribeLaTeXDimen\GlossaryMin +% \DescribeInterfaceMacro\GlossaryPrologue +% \DescribeInterfaceMacro\GlossaryParms +% \DescribeLaTeXCounter{GlossaryColumns} +% The +% |\GlossaryMin|, |\GlossaryPrologue| and |\GlossaryParms| macros and +% the counter \texttt{GlossaryColumns} are +% analogous to the |\Index|\ldots\ versions. (The \LaTeX{} `glossary' % mechanism is used for the change entries.) % -% \label{sec:checksum} -% \DescribeMacro\CharacterTable -% \DescribeMacro\CheckSum -% To overcome some of the problems of sending files over the networks -% we developed two macros which should detect corrupted files. If one -% places the lines -% \begin{flushleft} -% \small\ttfamily ^^A \ttfamily to get the blanks between "..."s -% ^^A right -%"%%\CharacterTable"\\ -%"%% {Upper-case " -%"\A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z"\\ -%"%% Lower-case " -%"\a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z"\\ -%"%% Digits \0\1\2\3\4\5\6\7\8\9"\\ -%"%% Exclamation \! Double quote "\verb=\"= -%" Hash (number) \#"\\ -%"%% Dollar \$ Percent \% Ampersand \&"\\ -%"%% Acute accent \' Left paren \( Right paren \)"\\ -%"%% Asterisk \* Plus \+ Comma \,"\\ -%"%% Minus \- Point \. Solidus \/"\\ -%"%% Colon \: Semicolon \; Less than \<"\\ -%"%% Equals \= Greater than \> Question mark \?"\\ -%"%% Commercial at \@ Left bracket \[ Backslash \\"\\ -%"%% Right bracket \] Circumflex \^ Underscore \_"\\ -%"%% Grave accent \` Left brace \{ Vertical bar \|"\\ -%"%% Right brace \} Tilde \~}"\\ -%"%%" -%\end{flushleft} -% at the beginning of the file then character translation failures -% will be detected, provided of course, that the used \DOC{} -% package has a correct default table. The percent -% signs\footnote{There are two percent signs in each line. This has -% the effect that these lines are not removed by the -% \texttt{docstrip.tex} program.} at the beginning of the lines should -% be typed in, since only the \DOC{} package should look at this -% command. -% -% -% Another problem of mailing files is possible truncation. To detect -% these sort of errors we provide a |\CheckSum| macro. The check-sum -% of a file is simply the number of backslashes in the code, i.e.\ all -% lines between the \textsf{macrocode} environments. But don't be -% afraid: you don't have count the code-lines yourself; this is done -% by the \DOC{} package for you. You simply have add -% \begin{quote} -% |% \CheckSum{0}| -% \end{quote} -% near the beginning of the file and -% use -% the |\StopEventually| (which starts looking for backslashes) and the -% |\Finale| command. The latter will inform you either that your file -% has no check-sum (telling you the right number) or that your number -% is incorrect if you put in anything other than zero but guessed wrong (this time -% telling you both the correct and the -% incorrect one). Then you go to the top of your file again and change the -% line to the right number, i.e. -% line -% \begin{quote} -% |% \CheckSum{|\meta{number}|}| -% \end{quote} -% and that's all. -% -% While |\CharacterTable| and |\CheckSum| have been important features -% in the early days of the public internet when \DOC{} was written as -% the mail gateways back then were rather unreliable and often mangled -% files they are these days more a nuisance than any help. They are -% therefore now fully optional and no longer recommended for use with new files. -% % -% \DescribeMacro\bslash +% \DescribeInterfaceMacro\bslash % From time to time, it is necessary to print a |\| without % being able to use the |\verb| command because the % |\catcode|$\,$s of the symbols are already firmly @@ -1072,53 +1254,55 @@ % |\bslash| presupposing, of course, that the actual font in % use at this point contains a `backslash' as a symbol. Note that % this definition of |\bslash| is expandable; it inserts a -% $"\"_{12}$. This means that you have to |\protect| +% $|\|_{12}$. This means that you have to |\protect| % it if it is used in `moving arguments'. % -% \DescribeMacro\MakePrivateLetters +% \DescribeInterfaceMacro\MakePrivateLetters % \changes{v1.7a}{1992/02/26}{Documented \cs{MakePrivateLetters} in % interface section}^^A -% If your macros "\catcode" anything other than "@" to `letter', you -% should redefine "\MakePrivateLetters" so that it also makes the +% If your macros |\catcode| anything other than |@| to `letter', you +% should redefine |\MakePrivateLetters| so that it also makes the % relevant characters `letters' for the benefit of the indexing. The -% default definition is just "\makeatletter". +% default definition is just |\makeatletter|. % -% \DescribeMacro\DontCheckModules \DescribeMacro\CheckModules -% \DescribeMacro\Module \DescribeMacro\AltMacroFont The `module' -% directives of the \textsf{docstrip} system \cite{art:docstrip} are -% normally recognised and invoke special formatting. This can be +% \DescribeInterfaceMacro\DontCheckModules \DescribeInterfaceMacro\CheckModules +% \DescribeInterfaceMacro\Module \DescribeInterfaceMacro\AltMacroFont The `module' +% directives of the \prg{docstrip} system \cite{art:docstrip} are +% normally recognized and invoke special formatting. This can be % turned on and off in the \texttt{.dtx} file or the driver file using -% "\CheckModules" and "\DontCheckModules". If checking for module +% |\CheckModules| and |\DontCheckModules|. If checking for module % directives is on (the default) then code in the scope of the -% directives is set as determined by the hook "\AltMacroFont", which +% directives is set as determined by the hook |\AltMacroFont|, which % gives {\small\ttfamily\itshape small italic type\-writer\/} by % default in the New Font Selection Scheme but just ordinary % {\small\ttfamily small type\-writer} in the old one, where a font % such as italic typewriter can't be used portably (plug for NFSS); % you will need to override this if you don't have the italic % typewriter font available. Code is in such a scope if it's on a -% line beginning with "%<" or is between lines starting with -% "%<*"\meta{name list}">" and "%</"\meta{name list}">". The -% directive is formatted by the macro "\Module" whose single argument +% line beginning with |%<| or is between lines starting with +% |%<*|\meta{name list}|>| and |%</|\meta{name list}|>|. The +% directive is formatted by the macro |\Module| whose single argument % is the text of the directive between, but not including, the angle % brackets; this macro may be re-defined in the driver or package file % and by default produces results like \Module{+foo\string|bar} with no % following space. % -% \DescribeMacro{StandardModuleDepth} Sometimes (as in this file) the +% \DescribeLaTeXCounter{StandardModuleDepth} Sometimes (as in this file) the % whole code is surrounded by modules to produce several files from a % single source. In this case it is clearly not appropriate to format -% all code lines in a special "\AltMacroFont". For this reason a -% counter "StandardModuleDepth" is provided which defines the level of +% all code lines in a special |\AltMacroFont|. For this reason a +% counter |StandardModuleDepth| is provided which defines the level of % module nesting which is still supposed to be formatted in -% "\MacroFont" rather then "\AltMacroFont". The default setting is -% "0", for this documentation it was set to +% |\MacroFont| rather then |\AltMacroFont|. The default setting is +% |0|, for this documentation it was set to %\begin{verbatim} % \setcounter{StandardModuleDepth}{1} %\end{verbatim} % at the beginning of the file. % % +% \section{Examples and basic usage summary} +% % \subsection{Basic usage summary} % \changes{v1.7a}{1992/03/11}{Added basic usage summary to spell % it out.} @@ -1126,26 +1310,482 @@ % To sum up, the basic structure of a \texttt{.dtx} file without any % refinements is like this: % \begin{verse}\small -% "% "\meta{waffle}\ldots\\ +% |% |\meta{waffle}\ldots\\ % \quad\ldots \\ -% "% \DescribeMacro{\fred}"\\ -% "% "\meta{description of fred's use}\\ +% |% \DescribeMacro{\fred}|\\ +% |% |\meta{description of fred's use}\\ % \quad\ldots\\ -% "% \StopEventually{"\meta{finale code}"}"\\ +% |% \MaybeStop{|\meta{finale code}|}|\\ % \quad\ldots\\ -% "% \begin{macro}{\fred}"\\ -% "% "\meta{commentary on macro fred}\\ +% |% \begin{macro}{\fred}|\\ +% |% |\meta{commentary on macro fred}\\ % \verb*+% \begin{macrocode}+\\ % \meta{code for macro fred}\\ % \verb*+% \end{macrocode}+\\ -% "% \end{macro}"\\ +% |% \end{macro}|\\ % \quad\ldots\\ -% "% \Finale \PrintIndex \PrintChanges" +% |% \Finale \PrintIndex \PrintChanges| % \end{verse} -% For examples of the use of most---if not all---of the features -% described above consult the \texttt{doc.dtx} source itself. +% For further examples of the use of most---if not all---of the features +% described above, consult the \texttt{doc.dtx} source itself. +% +% +% +% \subsection{Examples} +% +% The default setup includes definitions for the \DOC elements +% ``macro'' and ``environment''. They correspond to the following +% declarations: +%\begin{verbatim} +% \NewDocElement[macrolike = true , +% idxtype = , +% idxgroup = , +% printtype = +% ]{Macro}{macro} +% +% \NewDocElement[macrolike = false , +% idxtype = env. , +% idxgroup = environments , +% printtype = \textit{env.} +% ]{Env}{environment} +%\end{verbatim} +% +% To showcase the new features of \DOC version 3 to some extend, the +% current documentation is done by redefining these declarations and +% also adding a few additional declarations on top. +% +% For any internal command we document we use \texttt{Macro} and put +% all of them under the heading ``\LaTeX{} commands'' (note the use of \cs{actualchar}): +%\begin{verbatim} +%\RenewDocElement[macrolike = true , +% toplevel = false, +% idxtype = , +% idxgroup = LaTeX comands\actualchar\LaTeX{} commands , +% printtype = +% ]{Macro}{macro} +%\end{verbatim} +% +% We only have package environments so we use \texttt{Env} for those +% and group them as well: +%\begin{verbatim} +%\RenewDocElement[macrolike = false , +% toplevel = false, +% idxtype = env. , +% idxgroup = Package environments, +% printtype = \textit{env.} +% ]{Env}{environment} +%\end{verbatim} +% +% +% All the interface commands are also grouped together under the label +% ``Package commands'', we use \texttt{InterfaceMacro} for them: +%\begin{verbatim} +%\NewDocElement[macrolike = true , +% toplevel = false, +% idxtype = , +% idxgroup = Package commands, +% printtype = +% ]{InterfaceMacro}{imacro} +%\end{verbatim} +% +% And since we also have a few obsolete interfaces we add yet another category: +%\begin{verbatim} +%\NewDocElement[macrolike = true , +% toplevel = false, +% idxtype = , +% idxgroup = Package commands (obsolete), +% printtype = +% ]{ObsoleteInterfaceMacro}{omacro} +%\end{verbatim} +% +% Another type of category are the package keys: +%\begin{verbatim} +%\NewDocElement[macrolike = false , +% toplevel = false, +% idxtype = key , +% idxgroup = Package keys , +% printtype = \textit{key} +% ]{Key}{key} +%\end{verbatim} +% +% Finally we have \TeX{} counters (with a backslash in front) and +% \LaTeX{} counters (no backslash) and the two types of \LaTeX{} +% length registers: +%\begin{verbatim} +%\NewDocElement[macrolike = true , +% toplevel = false, +% idxtype = counter , +% idxgroup = TeX counters\actualchar \protect\TeX{} counters , +% printtype = \textit{counter} +% ]{TeXCounter}{tcounter} +% +%\NewDocElement[macrolike = false , +% toplevel = false, +% idxtype = counter , +% idxgroup = LaTeX counters\actualchar \LaTeX{} counters , +% printtype = \textit{counter} +% ]{LaTeXCounter}{lcounter} +% +%\NewDocElement[macrolike = true , +% toplevel = false, +% idxtype = skip , +% idxgroup = LaTeX length\actualchar \LaTeX{} length (skip) , +% printtype = \textit{skip} +% ]{LaTeXSkip}{lskip} +% +%\NewDocElement[macrolike = true , +% toplevel = false, +% idxtype = dimen , +% idxgroup = LaTeX length\actualchar \LaTeX{} length (dimen) , +% printtype = \textit{dimen} +% ]{LaTeXDimen}{ldimen} +% +%\end{verbatim} +% +% And we modify the appearance of the index: just 2 columns not 3 and +% all the code-line entries get prefixed with an ``$\ell$'' (for line) +% so that they can easily be distinguished from page index entries. +%\begin{verbatim} +% \renewcommand\code[1]{\mbox{$\ell$-#1}} +% \renewcommand\main[1]{\underline{\mbox{$\ell$-#1}}} +% \setcounter{IndexColumns}{2} +%\end{verbatim} +% +% +% +% \section{Incompatibilities between version 2 and 3} +% +% The basic approach when developing version~3 was to provide a very +% high level of compatibility with version~2 so that nearly all +% older documents should work out of the box without the need for +% any adjustments. +% +% But as with any change there are situations where that change can +% result in some sort of incompatibility, e.g., if a newly introduce +% command name was already been defined in the user document then +% there will be a conflict that is nearly impossible to avoid +% 100\%. +% +% As mentioned earlier, \DOC now supports options on several commands +% and environments and as a result it is necessary to use braces +% around the argument for \cs{DescribeMaro} if the ``macro to be +% described'' uses private letters such as |@| or |_| as part of its +% name. That was always the official syntax but in the past you could +% get away with leaving out the braces more often than you can now. +% +% The old \DOC documentation also claimed that redefinitions of things +% like \cs{PrintDescribeMacro} could be done before loading the +% package (and not only afterwards) and \DOC would in that case not +% change those commands. As the setup mechanisms are now much more +% powerful and general such an approach is not really good. So with +% \DOC version~3 modifications have to be done after the \DOC package +% got loaded and the last modification will always win. +% +% I'm temped to drop compatibility with \LaTeX~2.09 (but so far I +% have left it in). +% +% In the past it was possible to use macros declared with \cs{outer} +% in the argument of \verb=\begin{macro}= or \cs{DoNotIndex} even +% though \cs{outer} is not a concept supported in \LaTeX{}. This is no +% longer possible. More exactly, it is no longer possible to prevent +% them from being indexed (as \cs{DoNotIndex} can't be used), but you +% can pass them to the \env{macro} environment as follows: +%\begin{verbatim} +% \begin{macro}[outer]{\foo} +%\end{verbatim} +% if \cs{foo} is a macro declared with \cs{outer}. The technical +% reason for this change is that in the past various other commands, +% such as |\{| or |\}| did not work properly in these arguments when +% they where passed as ``strings'' and not as single macro tokens. But +% by switching to macro tokens we can't have \cs{outer} macros because +% their feature is to be not allowed in arguments. So what happens +% above when you use \texttt{[outer]} is that the argument is read as +% a string with four character tokens so that it is not recognized as +% being \cs{outer}. +% +% +% \section{Old interfaces no longer really needed} +% +% 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. +% We list them here, but in general we suggest that for new +% documentation they should not be used. +% +% +% \subsection{\prg{makeindex} bugs} +% +% \DescribeObsoleteInterfaceMacro\OldMakeindex +% Versions of \prg{makeindex} prior to 2.9 had some bugs affecting +% \DOC{}. One of these, +% pertaining to the |%| character doesn't have a work-around +% appropriate for versions with and without the +% bug.\label{makeindex:version} If +% you really still have an old version, invoke |\OldMakeindex| in a +% package file or the driver file to prevent problems with index entries +% such as |\%|, although you'll probably normally want to turn off +% indexing of |\%| anyway. Try to get an up-to-date \prg{makeindex} +% from one of the \TeX{} repositories. +% +% \subsection{File transmission issues} +% +% In the early days of the Internet file transmission issues have been +% a serious problem. There was a famous gateway in Rochester, UK that +% handled the traffic from the European continent to the UK and that +% consisted of two IBM machines running with different codepages (that +% had non-reversible differences). As a result ``strange'' \TeX{} +% characters got replaced with something else with the result that the +% files became unusable. +% +% To guard against this problem (or rather to detect it if something +% got broken in transfer I added code to \DOC to check a static +% character table and also to have a very simple checksum feature +% (counting backslashes). +% +% These days the \cs{CheckSum} is of little value (and a lot of pain +% for the developer) and character scrambling doesn't happen any more +% so the \cs{CharacterTable} is essentially useless. Thus neither +% should be used in new developments. +% +% \label{sec:checksum} +% \DescribeObsoleteInterfaceMacro\CharacterTable +% \DescribeObsoleteInterfaceMacro\CheckSum +% To overcome some of the problems of sending files over the networks +% we developed two macros which should detect corrupted files. If one +% places the lines +% \begin{flushleft} +% \small\ttfamily ^^A \ttfamily to get the blanks between "..."s +% ^^A right +%|%%\CharacterTable|\\ +%|%% {Upper-case | +%|\A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z|\\ +%|%% Lower-case | +%|\a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z|\\ +%|%% Digits \0\1\2\3\4\5\6\7\8\9|\\ +%|%% Exclamation \! Double quote "| +%| Hash (number) \#|\\ +%|%% Dollar \$ Percent \% Ampersand \&|\\ +%|%% Acute accent \' Left paren \( Right paren \)|\\ +%|%% Asterisk \* Plus \+ Comma \,|\\ +%|%% Minus \- Point \. Solidus \/|\\ +%|%% Colon \: Semicolon \; Less than \<|\\ +%|%% Equals \= Greater than \> Question mark \?|\\ +%|%% Commercial at \@ Left bracket \[ Backslash \\|\\ +%|%% Right bracket \] Circumflex \^ Underscore \_|\\ +%|%% Grave accent \` Left brace \{ Vertical bar |\verb=|=\\ +%|%% Right brace \} Tilde \~}|\\ +%|%%| +%\end{flushleft} +% at the beginning of the file then character translation failures +% will be detected, provided of course, that the used \DOC{} +% package has a correct default table. The percent +% signs\footnote{There are two percent signs in each line. This has +% the effect that these lines are not removed by the +% \texttt{docstrip.tex} program.} at the beginning of the lines should +% be typed in, since only the \DOC{} package should look at this +% command. +% +% +% Another problem of mailing files is possible truncation. To detect +% these sort of errors we provide a |\CheckSum| macro. The check-sum +% of a file is simply the number of backslashes in the code, i.e.\ all +% lines between the \env{macrocode} environments. But don't be +% afraid: you don't have count the code-lines yourself; this is done +% by the \DOC{} package for you. You simply have add +% \begin{quote} +% |% \CheckSum{0}| +% \end{quote} +% near the beginning of the file and use the |\MaybeStop| (which +% starts looking for backslashes) and the |\Finale| command. The +% latter will inform you either that your file has no check-sum +% (telling you the right number) or that your number is incorrect if +% you put in anything other than zero but guessed wrong (this time +% telling you both the correct and the incorrect one). Then you go to +% the top of your file again and change the line to the right number, +% i.e., line +% \begin{quote} +% |% \CheckSum{|\meta{number}|}| +% \end{quote} +% and that's all. +% +% While |\CharacterTable| and |\CheckSum| have been important features +% in the early days of the public internet when \DOC{} was written as +% the mail gateways back then were rather unreliable and often mangled +% files they are these days more a nuisance than any help. They are +% therefore now fully optional and no longer recommended for use with +% new files. +% +% + + + +% ^^A ============================================================= + + + +% \begin{multicols}{2}[\medskip \noindent\rule{\textwidth}{.3pt} +% \section{Introduction to previous releases}] +% +% \begin{quote} +% \textbf{Original abstract:} +% This package contains the definitions that are necessary to +% format the documentation of package files. The package was +% developed in Mainz in cooperation with the Royal Military College +% of Science. This is an update which documents various changes +% and new features in \DOC{} and integrates the features of +% \env{newdoc}. +% \end{quote} +% +% The \TeX{} macros which are described here allow definitions and +% documentation to be held in one and the same file. This has the +% advantage that normally very complicated instructions are made +% simpler to understand by comments inside the definition. In addition +% to this, updates are easier and only one source file needs to be +% changed. On the other hand, because of this, the package files are +% considerably longer: thus \TeX{} takes longer to load them. If this +% is a problem, there is an easy remedy: one needs only to run the +% \texttt{docstrip.tex} program that removes nearly all lines that begin +% with a +% percent sign. +% +% The idea of integrated documentation was born with the development +% of the \TeX{} program; it was crystallized in Pascal with the \Web{} +% system. The advantages of this method are plain to see (it's easy +% to make comparisons \cite{art:Knuthliterat}). Since this +% development, systems similar to \Web{} have been developed for other +% programming languages. But for one of the most complicated +% programming languages (\TeX) the documentation has however been +% neglected. The \TeX{} world seems to be divided between:--- +% \begin{itemize} \item a couple of ``wizards'', who produce many +% lines of completely unreadable code ``off the cuff'', and \item many +% users who are amazed that it works just how they want it to do. Or +% rather, who despair that certain macros refuse to do what is +% expected of them.\end{itemize} +% +% I do not think that the \Web{} system is {\em the\/} reference work; +% on the contrary, it is a prototype which suffices for the +% development of programs within the \TeX{} world. It is sufficient, +% but not totally sufficient.\footnote{I know that this will be seen +% differently by a few people, but this product should not be seen as +% the finished product, at least as far as applications concerning +% \TeX{} are concerned. The long-standing debate over `multiple +% change files' shows this well.} As a result of \Web, new programming +% perspectives have been demonstrated; unfortunately, though, they +% haven't been developed further for other programming languages. +% +% The method of documentation of \TeX{} macros which I have introduced +% here should also only be taken as a first sketch. It is designed +% explicitly to run under \LaTeX{} alone. Not because I was of the +% opinion that this was the best starting point, but because from this +% starting point it was the quickest to develop.\footnote{This +% argument is a bad one, however, it is all too often trotted out.} As +% a result of this design decision, I had to move away from the +% concept of modularization; this was certainly a step backward. +% +% I would be happy if this article could spark off discussion over +% \TeX\ documentation. I can only advise anyone who thinks that they +% can cope without documentation to ``Stop Time'' until he or she +% completely understands the \AmSTeX{} source code. +% +% \subsection*{Using the \DOC{} package} +% +% Just like any other package, invoke it by requesting it with a +% |\usepackage| command in the preamble. \DOC's use of +% |\reversemarginpars| may make it incompatible with some classes. +% \changes{v1.7a}{1992/02/25}{Altered usage info} +% +% +% \end{multicols} +% +% +% +% +% \begin{multicols}{2}[\subsection*{Preface to version 1.7 (from +% around 1992)}] +% +% This version of \texttt{doc.dtx} documents changes which have occurred +% since the last published version \cite{art:doc} but which have been +% present in distributed versions of \texttt{doc.sty} for some time. It +% also integrates the (undocumented) features of the distributed +% \texttt{newdoc.sty}. +% +% The following changes and additions have been made to the user +% interface since the published version~\cite{art:doc}. See +% \S\ref{sec:interface} for more details. +% \begin{description} +% \item[Driver mechanism] |\DocInput| is now used in the driver file +% to input possibly multiple independent \DOC{} files and \DOC{} no +% longer has to be the last package. |\IndexListing| is replaced +% by |\IndexInput|; +% \item[Indexing] is controlled by |\PageIndex| and |\CodelineIndex|, +% one of which must be specified to produce an index---there is no +% longer a |\makeindex| in the default |\DocstyleParms|; +% \item[The \texttt{macro} environment] now takes as argument the +% macro name {\em with\/} the backslash; +% \item[Verbatim text] Newlines are now forbidden inside |\verb| and +% commands |\MakeShortVerb| and |\DeleteShortVerb| are provided for +% verbatim shorthand; +% \item[\texttt{\bslash par}] can now be used in |\DoNotIndex|; +% \item[Checksum/character table support] for ensuring the integrity +% of distributions is added; +% \item[\texttt{\bslash printindex}] becomes |\PrintIndex|; +% \item[\texttt{multicol.sty}] is no longer necessary to use \DOC{} or +% print the documentation (although it is recommended); +% \item[`Docstrip' modules] are recognized and formatted specially. +% \end{description} +% +% As well as adding some completely new stuff, +% the opportunity has been taken to add some commentary to the code +% formerly in \pkg{newdoc} and that added after version 1.5k of +% \DOC. Since (as noted in the sections concerned) this +% commentary wasn't written by Frank Mittelbach but the code was, it is +% probably {\em not\/} true in this case that ``if the code and +% comments disagree both are probably wrong''! +% +% \subsubsection*{Bugs} +% +% There are some known bugs in this version: +% \begin{itemize} +% \item The |\DoNotIndex| command doesn't work for some single +% character commands most noticeable |\%|. +% \item The `General changes' glossary entry would come out after +% macro names with a leading |!| and possibly a leading |"|; +% \item If you have an old version of \prg{makeindex} long |\changes| +% entries will come out strangely and you may find the section +% header amalgamated with the first changes entry. Try to get an +% up-to-date one (see p.~\pageref{makeindex:version}); +% \item Because the accompanying \prg{makeindex} style files support +% the inconsistent attribute specifications of older and newer +% versions \prg{makeindex} always complains about three `unknown +% specifier's when sorting the index and changes entries. +% \item If |\MakeShortVerb| and |\DeleteShortVerb| are used with +% single character arguments, e.g., \verb"{|}" instead of \verb"{\|}" chaos +% may happen. +% \end{itemize} +% (Some `features' are documented below.) +% +% \subsubsection*{Wish list} +% +% \begin{itemize} +% \item Hooks to allow |\DescribeMacro| and |\DescribeEnv| to write +% out to a special file information about the package's `exported' +% definitions which they describe. This could subsequently be +% included in the \texttt{docstrip}ped \texttt{.sty} file in a +% suitable form for use by smart editors in command completion, +% spelling checking etc., based on the packages used in a document. +% This would need agreement on a `suitable form'. \item Indexing of +% the modules used in \texttt{docstrip}'s |%<| directives. I'm not +% sure how to index directives containing module combinations; \item +% Writing out bibliographic information about the package; \item Allow +% turning off use of the special font for, say, the next guarded +% block. +% \end{itemize} % -% \subsection{Acknowledgements} +% +% \end{multicols} + + +% \subsection*{Acknowledgements} % % I would like to thank all folks at Mainz and at the Royal Military % College of Science for their help in this project. Especially Brian @@ -1158,14 +1798,14 @@ % \texttt{doc.dtx} after its publication in \textsl{TUGboat\/} have % been never properly described. Beside this splendid work he kindly % provided additional code (like ``docstrip'' module formatting) which -% I think every \textsf{doc.dtx} user will be grateful for. +% I think every \DOC user will be grateful for. % % -% \StopEventually{ +% \MaybeStop{ % \begin{thebibliography}{1} % \bibitem{book:Buerger} \textsc{G. A. B\"urger}. -% \newblock Wunderbare Reisen zu Wasser und zu Lande, Feldz\"uge -% und lustige Abenteuer des Freyherrn v.\ M\"unchhausen. +% \newblock Wunderbare Reisen zu Wasser und zu Lande, Feldzüge +% und lustige Abenteuer des Freyherrn v.\ Münchhausen. % \newblock London, 1786 \& 1788. % \bibitem{art:Knuthliterat} \textsc{D. E. Knuth}. % \newblock Literate Programming. @@ -1189,20 +1829,20 @@ % \newblock \texttt{docstrip.dtx} (to appear). % \newblock The file is part of the DOC package. % \bibitem{book:Raspe} \textsc{R. E. Raspe} (*1737, \dag 1797). -% \newblock Baron M\"unchhausens narrative of his marvellous +% \newblock Baron Münchhausens narrative of his marvelous % travels and campaigns in Russia. % \newblock Oxford, 1785. -% \bibitem{art:verbatim} \textsc{Rainer Sch\"opf}. +% \bibitem{art:verbatim} \textsc{Rainer Schöpf}. % \newblock A New Implementation of \LaTeX's \texttt{verbatim} and % \texttt{verbatim*} Environments. % \newblock File \texttt{verbatim.doc}, version 1.4i. % \end{thebibliography} % -% \ifmulticols % \addtocontents{toc}{\protect\end{multicols}} -% \fi % -% } ^^A end \StopEventually +% \PrintIndex +% +% } ^^A end \MaybeStop % % % \section{The Description of Macros} @@ -1228,50 +1868,206 @@ \@ifundefined{macro@cnt}{}{\endinput} % \end{macrocode} % -% \DescribeMacro\fileversion -% \DescribeMacro\filedate -% \DescribeMacro\docdate +% \DescribeObsoleteInterfaceMacro\fileversion +% \DescribeObsoleteInterfaceMacro\filedate +% \DescribeObsoleteInterfaceMacro\docdate % As you can see I used macros like |\fileversion| to denote the % version number and the date. They are defined at the very beginning -% of the package file (without a surrounding \textsf{macrocode} +% of the package file (without a surrounding \env{macrocode} % environment), so I don't have to search for this place here when I % change the version number. You can see their actual outcome in a % footnote to the title. % % -% The first thing that we do next is to get ourselves a new comment -% sign. Because all sensible signs are already occupied, we will -% choose one that can only be entered indirectly: +% The first thing that we do next is to get ourselves two alternative comment +% signs. Because all sensible signs are already occupied, we will +% choose some that can only be entered indirectly: % {\DoNotIndex{\^}^^A avoid misinterpretation !!!!! VERIFY % \begin{macrocode} \catcode`\^^A=14 +\catcode`\^^X=14 % \end{macrocode} % We repeat this statement at the beginning of the document in case % the \texttt{inputenc} package is used disabling it again. % \changes{v2.0b}{1998/05/19}{Init docs private comment char at begin % of document again (pr2581)} % \begin{macrocode} -\AtBeginDocument{\catcode`\^^A=14\relax} +\AtBeginDocument{\catcode`\^^A=14\relax\catcode`\^^X=14\relax} % \end{macrocode} % \SortIndex{\string^\string^A}{\string\verb\verbatimchar % \string^\string^A\verbatimchar +% \encapchar main}^^A +% \SortIndex{\string^\string^X}{\string\verb\verbatimchar +% \string^\string^X\verbatimchar % \encapchar main} % } % % -% \subsection{Options supported by \DOC{}} +% \subsection{Keys supported by \DOC{}} +% +% In the past this used \pkg{kvoptions} but this will be +% replaced by using \texttt{l3keys} at some point in the future. +% Right now this is only a lightweight shift---the code could and +% should be altered further. +% \fmi{cleanup replacement of kvoptions} +% +% \begin{macrocode} +\RequirePackage{l3keys2e} +\ExplSyntaxOn +% \end{macrocode} +% Some keys are available as options for use in \cs{usepackage} some are +% for the generated item \api's: +% \fmi{cleanup documentation (and code once the new key interface is there)} +% \begin{macrocode} +\newif \ifdoc@noprint +\newif \ifdoc@noindex +\newif \ifdoc@hyperref \doc@hyperreftrue +\newif \ifdoc@multicol \doc@multicoltrue +\newif \ifdoc@debugshow +\newif \ifdoc@reportchangedates +\keys_define:nn {doc} + { + noprint .choice:, + noprint / true .code:n = { \legacy_if_set_true:n { doc@noprint } }, + noprint / false .code:n = { \legacy_if_set_false:n { doc@noprint } }, + noprint .default:n = { true }, + noindex .choice:, + noindex / true .code:n = { \legacy_if_set_true:n { doc@noindex } }, + noindex / false .code:n = { \legacy_if_set_false:n { doc@noindex } }, + noindex .default:n = { true }, + hyperref .choice:, + hyperref / true .code:n = { \legacy_if_set_true:n { doc@hyperref } }, + hyperref / false .code:n = { \legacy_if_set_false:n { doc@hyperref } }, + hyperref .default:n = { true }, + hyperref .choice:, + nohyperref / true .code:n = { \legacy_if_set_false:n { doc@hyperref } }, + nohyperref / false .code:n = { \legacy_if_set_true:n { doc@hyperref } }, + nohyperref .default:n = { true }, + multicol .choice:, + multicol / true .code:n = { \legacy_if_set_true:n { doc@multicol } }, + multicol / false .code:n = { \legacy_if_set_false:n { doc@multicol } }, + multicol .default:n = { true }, + nomulticol .choice:, + nomulticol / true .code:n = { \legacy_if_set_false:n { doc@multicol } }, + nomulticol / false .code:n = { \legacy_if_set_true:n { doc@multicol } }, + multicol .default:n = { true }, + debugshow .choice:, + debugshow / true .code:n = { \legacy_if_set_true:n { doc@debugshow } }, + debugshow / false .code:n = { \legacy_if_set_false:n { doc@debugshow } }, + debugshow .default:n = { true }, + reportchangedates .choice:, + reportchangedates / true .code:n = { \legacy_if_set_true:n { doc@reportchangedates } }, + reportchangedates / false .code:n = { \legacy_if_set_false:n { doc@reportchangedates } }, + reportchangedates .default:n = { true }, + } +% \end{macrocode} +% This one is for \cs{usepackage} and \cs{NewDocElement}: +% \begin{macrocode} +\newif \ifdoc@toplevel \doc@topleveltrue +\keys_define:nn {doc} + { + toplevel .choice:, + toplevel / true .code:n = { \legacy_if_set_true:n { doc@toplevel } }, + toplevel / false .code:n = { \legacy_if_set_false:n { doc@toplevel } }, + toplevel .default:n = { true }, + notoplevel .choice:, + notoplevel / true .code:n = { \legacy_if_set_false:n { doc@toplevel } }, + notoplevel / false .code:n = { \legacy_if_set_true:n { doc@toplevel } }, + notoplevel .default:n = { true } + } +% \end{macrocode} +% These are for \cs{NewDocElement}: +% \begin{macrocode} +\newif \ifdoc@macrolike +\keys_define:nn {doc} + { + macrolike .choice:, + macrolike / true .code:n = { \legacy_if_set_true:n { doc@macrolike } }, + macrolike / false .code:n = { \legacy_if_set_false:n { doc@macrolike } }, + macrolike .default:n = { true }, + envlike .choice:, + envlike / true .code:n = { \legacy_if_set_false:n { doc@macrolike } }, + envlike / false .code:n = { \legacy_if_set_true:n { doc@macrolike } }, + envlike .default:n = { true } + } + +\keys_define:nn { doc } + { + idxtype .tl_set:N = \doc@idxtype, + idxgroup .tl_set:N = \doc@idxgroup, + printtype .tl_set:N = \doc@printtype + } +% \end{macrocode} +% And this one only for instances of doc elements in the document, it +% covers the case where you want to document a macro which is +% declared to be \cs{outer}. This is not a concept officially +% supported by \LaTeX{} but there are cases when it gets used. +% \begin{macrocode} +\newif\ifdoc@outer +\keys_define:nn {doc} + { + outer .choice:, + outer / true .code:n = { \legacy_if_set_true:n { doc@outer } }, + outer / false .code:n = { \legacy_if_set_false:n { doc@outer } }, + outer .default:n = { true }, + } +\ExplSyntaxOff +% \end{macrocode} +% +% \subsection{Processing the package keys} +% +% \begin{macrocode} +\ProcessKeysOptions {doc} +% \end{macrocode} % -% Not options available at the moment % +% \begin{macro}{\ifscan@allowed} +% \begin{macro}{\scan@allowedtrue} +% \begin{macro}{\scan@allowedfalse} +% |\ifscan@allowed| is the switch used to determine if +% the |\active@escape@char|\SpecialIndex{\active@escape@char} +% should start the macro scanning mechanism. % \begin{macrocode} +\newif\ifscan@allowed \scan@allowedtrue % \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{imacro}{\SetupDoc} +% +% We need to save the default value for some options because \DOC elements +% can locally set them. +% \fmi{Use 2e interface for \cs{keys\_set:nn} when available} +% \begin{macrocode} +\def\SetupDoc#1{% + \csname keys_set:nn\endcsname{doc}{#1}% + \edef\doc@noprintdefault{\ifdoc@noprint true\else false\fi}% + \ifdoc@noindex +% \end{macrocode} +% If we do not index by default then we should also turn off +% \cs{scan@allowed}. +% \begin{macrocode} + \def\doc@noindexdefault{true}% + \scan@allowedfalse + \else + \def\doc@noindexdefault{false}% + \fi +} +% \end{macrocode} +% \end{imacro} +% +% \begin{macrocode} +\SetupDoc{} % just save the default values +% \end{macrocode} +% % % % \subsection{Macros surrounding the `definition parts'} % % \begin{environment}{macrocode} % Parts of the macro definition will be surrounded by the -% environment \textsf{macrocode}. Put more precisely, they will be +% environment \env{macrocode}. Put more precisely, they will be % enclosed by a macro whose argument (the text to be set % `verbatim') is terminated by the string % \verb*+% \end{macrocode}+. Carefully note the number of spaces. @@ -1307,7 +2103,7 @@ % \begin{macrocode} \def\macro@code{% % \end{macrocode} -% In theory it should consist of a \textsf{trivlist} environment, but +% In theory it should consist of a \env{trivlist} environment, but % the empty space before and after the environment should not be % too large. % \begin{macrocode} @@ -1384,7 +2180,7 @@ % indexing by code lines is switched on the line number is incremented % and set appropriately. We also check whether the start of the next % line indicates a \texttt{docstrip} module directive and process it -% appropriately if so using "\check@module". +% appropriately if so using |\check@module|. % \begin{macrocode} \global\@newlistfalse \global\@minipagefalse @@ -1408,9 +2204,9 @@ % \begin{macro}{\blank@linetrue} % \begin{macro}{\blank@linefalse} % |\ifblank@line| is the switch used in the definition above. -% In the original \textsf{verbatim} environment the |\if@tempswa| +% In the original \env{verbatim} environment the |\if@tempswa| % switch is used. This is dangerous because its value may change -% while processing lines in the \textsf{macrocode} environment. +% while processing lines in the \env{macrocode} environment. % \begin{macrocode} \newif\ifblank@line % \end{macrocode} @@ -1419,10 +2215,10 @@ % \end{macro} % % \begin{macro}{\endmacrocode} -% Because we have begun a \textsf{trivlist} environment in the -% \textsf{macrocode} environment, we must also end it. We must -% also act on the value of the "pm@module" flag (see below) and -% empty "\everypar". +% Because we have begun a \env{trivlist} environment in the +% \env{macrocode} environment, we must also end it. We must +% also act on the value of the |pm@module| flag (see below) and +% empty |\everypar|. % \changes{v1.5r}{1989/11/04}{Support for code line no. (Undoc)} % \begin{macrocode} \def\endmacrocode{% @@ -1439,7 +2235,7 @@ % \end{macro} % % -% \begin{macro}{\MacroFont} +% \begin{imacro}{\MacroFont} % Here is the default definition for the |\MacroFont| macro. % With the new math font handling in NFSS2 it isn't any longer % correct to suppress the math font setup since this is now handled @@ -1459,7 +2255,7 @@ % bothered since doc-sources should be up-to-date but since the % request came from someone called David Carlisle \ldots :-) % \changes{v1.9y}{1996/01/26}{Support compat mode} -% \changes{v2.1l}{2019/12/16}{Use \cs{shapedefault} not +% \changes{v2.1l}{2019/12/16}{Use \cs{shapedefault} not % \cs{updefault} for extended NFSS} % \begin{macrocode} \def\MacroFont{\small @@ -1477,9 +2273,9 @@ \fi }{} % \end{macrocode} -% \end{macro} +% \end{imacro} % -% \begin{macro}{\AltMacroFont} +% \begin{imacro}{\AltMacroFont} % \begin{macro}{\macro@font} % \changes{v1.7a}{1992/03/12}{Added to support distinction of modules.} % \changes{v1.7c}{1992/03/26}{Altered font change for OFSS.} @@ -1487,9 +2283,9 @@ % \changes{v1.8c}{1993/10/25}{NFSS standard} % \changes{v1.9t}{1995/05/26}{Removed \cs{math@fontsfalse} (different % 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 +% 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 % same thing sensibly in OFSS as in NFSS. % \begin{macrocode} \@ifundefined{AltMacroFont}{% @@ -1514,8 +2310,8 @@ \fi }{} % \end{macrocode} -% To allow changing the "\MacroFont" in the preamble we defer -% defining the internally used "\macro@font" until after the +% To allow changing the |\MacroFont| in the preamble we defer +% defining the internally used |\macro@font| until after the % preamble. % \changes{v2.0a}{1998/05/16}{Support changing \cs{MacroFont} in % preamble} @@ -1523,23 +2319,23 @@ \AtBeginDocument{\let\macro@font\MacroFont} % \end{macrocode} % \end{macro} -% \end{macro} +% \end{imacro} % % \begin{macro}{\check@module} % \begin{macro}{\ifpm@module} % \changes{v1.7a}{1992/03/12}{Added.} -% This is inserted by "\everypar" at the start of each macrocode line to +% This is inserted by |\everypar| at the start of each macrocode line to % check whether it starts with module information. (Such information is -% of the form "%<"\meta{switch}">", where the "%" must be at the +% of the form |%<|\meta{switch}|>|, where the |%| must be at the % start of the line and \meta{switch} comprises names with various -% possible separators and a possible leading "+", "-", "*" or "/" +% possible separators and a possible leading |+|, |-|, |*| or |/| % \cite{art:docstrip}. All that concerns us here is what the first -% character of \meta{switch} is.) First it checks the "pm@module" +% character of \meta{switch} is.) First it checks the |pm@module| % flag in case the previous line had a non-block module -% directive i.e., not "%<*" or "%</"; if it did we need to close the -% group it started and unset the flag. "\check@module" looks ahead at -% the next token and then calls "\ch@percent" to take action depending -% on whether or not it's a "%"; we don't want to expand the token at +% directive i.e., not |%<*| or |%</|; if it did we need to close the +% group it started and unset the flag. |\check@module| looks ahead at +% the next token and then calls |\ch@percent| to take action depending +% on whether or not it's a |%|; we don't want to expand the token at % this stage. This is all done conditionally so it can be turned off % if it causes problems with code that wasn't designed to be % \texttt{docstrip}ped. @@ -1553,25 +2349,27 @@ % \end{macrocode} % \end{macro} % \end{macro} -% \begin{macro}{\DontCheckModules} -% \begin{macro}{\CheckModules} +% \begin{imacro}{\DontCheckModules} +% \begin{imacro}{\CheckModules} % \changes{v1.7a}{1992/03/12}{Added.} % \begin{macro}{\ifcheck@modules} % Here are two driver-file interface macros for turning the module -% checking on and off using the "check@modules" switch. +% checking on and off using the |check@modules| switch. % \begin{macrocode} \def\DontCheckModules{\check@modulesfalse} \def\CheckModules{\check@modulestrue} \newif\ifcheck@modules \check@modulestrue % \end{macrocode} % \end{macro} -% \end{macro} -% \end{macro} +% \end{imacro} +% \end{imacro} +% +% % \begin{macro}{\ch@percent} % \changes{v1.7a}{1992/03/12}{Added.} -% If the lookahead token in "\next" is $"%"_{12}$ we go on to check -% whether the following one is "<" and otherwise do nothing. Note the -% "\expandafter" to get past the "\fi". +% If the lookahead token in |\next| is $|%|_{12}$ we go on to check +% whether the following one is |<| and otherwise do nothing. Note the +% |\expandafter| to get past the |\fi|. % \begin{macrocode} \def\ch@percent{% \if \percentchar\next @@ -1582,7 +2380,7 @@ % % \begin{macro}{\check@angle} % \changes{v1.7a}{1992/03/12}{Added.} -% Before looking ahead for the "<" the "%" is gobbled by the +% Before looking ahead for the |<| the |%| is gobbled by the % argument here. % \begin{macrocode} \def\check@angle#1{\futurelet\next\ch@angle} @@ -1591,9 +2389,9 @@ % \begin{macro}{\ch@angle} % \changes{v1.7a}{1992/03/12}{Added.} % \changes{v1.9k}{1994/02/22}{Have \texttt{<} active} -% If the current lookahead token is "<" we are defined to be -% processing a module directive can go on to look for "+" etc.; -% otherwise we must put back the gobbled "%". With \LaTeXe{} +% If the current lookahead token is |<| we are defined to be +% processing a module directive can go on to look for |+| etc.; +% otherwise we must put back the gobbled |%|. With \LaTeXe{} % \texttt{<} is active so we have to be a bit careful. % \begin{macrocode} \begingroup @@ -1644,13 +2442,13 @@ % \end{macro} % \begin{macro}{\pm@module} % If we're not dealing with a block -% directive ("*" or "/") i.e., it's a single special line, we set -% everything up to the next ">" appropriately and then change to the +% directive (|*| or |/|) i.e., it's a single special line, we set +% everything up to the next |>| appropriately and then change to the % special macro font inside a group which will be ended at the start % of the next line. If the apparent module directive is missing the -% terminating ">" this will lose, but then so will the \texttt{docstrip} +% terminating |>| this will lose, but then so will the \texttt{docstrip} % implementation. An alternative strategy would be to have -% "\pm@module" make ">" active and clear a flag set here to indicate +% |\pm@module| make |>| active and clear a flag set here to indicate % processing the directive. Appropriate action could then be taken if % the flag was found still to be set when processing the next line. % \changes{v1.7a}{1992/03/12}{Added.} @@ -1663,8 +2461,8 @@ \Module{#1}\begingroup % \end{macrocode} % We switch to a special font as soon the nesting is higher than -% the current value of "\c@StandardModuleDepth". We do a local -% update to the "\guard@level" here which will be restored after +% the current value of |\c@StandardModuleDepth|. We do a local +% update to the |\guard@level| here which will be restored after % the current input line. % \begin{macrocode} \advance\guard@level\@ne @@ -1706,8 +2504,7 @@ % \end{macro} % \end{macro} % -% -% \begin{macro}{\c@StandardModuleDepth} +% \begin{lcounter}{StandardModuleDepth} % \changes{v1.7i}{1992/07/11}{Counter added.} % Counter defining up to which level modules are considered part of % the main code. If, for example, the whole code is surrounded by @@ -1716,38 +2513,39 @@ % \begin{macrocode} \newcounter{StandardModuleDepth} % \end{macrocode} -% \end{macro} +% \end{lcounter} % % -% \begin{macro}{\guard@level} +% \begin{tcounter}{\guard@level} % \changes{v1.7f}{1992/05/16}{Added.} % We need a counter to keep track of the guard nesting. % \begin{macrocode} \newcount \guard@level % \end{macrocode} -% \end{macro} +% \end{tcounter} + % \begin{macro}{\Module} % \changes{v1.7a}{1992/03/12}{Added.} % \changes{v1.7d}{1992/04/25}{Use sans font for modules.} % This provides a hook to determine the way the module directive is % set. It gets as argument everything between the angle brackets. % The default is to set the contents in sans serif text between -% $\langle\,\rangle$ with the special characters suitably "\mathcode"d -% by "\mod@math@codes". (You can't just set it in a sans text font -% because normally "|" will print as an em-dash.) This is done +% $\langle\,\rangle$ with the special characters suitably |\mathcode|d +% by |\mod@math@codes|. (You can't just set it in a sans text font +% because normally \verb"|" will print as an em-dash.) This is done % differently depending on whether we have the NFSS or the old one. In -% the latter case we can easily change "\fam" appropriately. +% the latter case we can easily change |\fam| appropriately. % \changes{v1.8c}{1993/10/25}{NFSS standard} % \begin{macrocode} \@ifundefined{Module}{% % \end{macrocode} % With NFSS what we probably {\em should\/} do is change to a new -% "\mathversion" but I (Dave Love) haven't spotted an easy way to +% |\mathversion| but I (Dave Love) haven't spotted an easy way to % do so correctly if the document uses a version other than -% "normal". (We need to know in what font to set the other +% |normal|. (We need to know in what font to set the other % groups.) This uses a new math alphabet rather than version and % consequently has to worry about whether we're using -% \textsf{oldlfnt} or not. I expect there's a better +% \env{oldlfnt} or not. I expect there's a better % way\ldots % \begin{macrocode} \def\Module#1{\mod@math@codes$\langle\mathsf{#1}\rangle$} @@ -1759,11 +2557,11 @@ % \changes{v1.7c}{1992/03/26}{Added.} % \changes{v2.1e}{2010/02/04}{Added mathcodes for +,-,:, and = (pr/4096)} % As well as `words', the module -% directive text might contain any of the characters "*/+-,&|!()" -% for the current version of \textsf{docstrip}. We only need +% directive text might contain any of the characters \verb"*/+-,&|!()" +% for the current version of \prg{docstrip}. We only need % special action for two of them in the math code changing required -% above: "|" is changed to a "\mathop" (it's normally |"026A|) and -% "&" is also made a "\mathop", but in family 0. Remember that "&" +% above: \verb"|" is changed to a |\mathop| (it's normally |"026A|) and +% |&| is also made a |\mathop|, but in family 0. Remember that |&| % will not have a special catcode when it's encountered. % \begin{macrocode} \def\mod@math@codes{\mathcode`\|="226A \mathcode`\&="2026 @@ -1772,27 +2570,9 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\mathsf} -% \changes{v1.7c}{1992/03/26}{Added.} -% \changes{v1.7d}{1992/04/25}{Use sans font for modules.} -% \changes{v1.7n}{1993/02/21}{\cs{sfmath} Renamed to \cs{mathsf}.} -% \changes{v1.8c}{1993/10/25}{NFSS standard} -% If NFSS is in use we need a new math alphabet which uses a sans serif -% font. To support both the release one and two of NFSS the alphabet -% was renamed to "\mathsf" which is defined in NFSS2. -% \begin{macrocode} -%\ifx\selectfont\undefined -%\else -% \ifx\mathsf\undefined -% \newmathalphabet*{\mathsf}{\sfdefault}{m}{n}\fi -%\fi -% \end{macrocode} -% \end{macro} -% % -% -% \begin{macro}{\MacrocodeTopsep} -% \begin{macro}{\MacroIndent} +% \begin{lskip}{\MacrocodeTopsep} +% \begin{ldimen}{\MacroIndent} % In the code above, we have used two registers. Therefore we have % to allocate them. The default values might be overwritten with % the help of the |\DocstyleParms| macro. @@ -1805,22 +2585,22 @@ \newdimen\MacroIndent \settowidth\MacroIndent{\rmfamily\scriptsize 00\ } % \end{macrocode} -% \end{macro} -% \end{macro} +% \end{ldimen} +% \end{lskip} % % % % % \begin{environment}{macrocode*} % \begin{macro}{\endmacrocode*} -% Just as in the \textsf{verbatim} environment, there is also a -% `star' variant of the \textsf{macrocode} environment in which a +% Just as in the \env{verbatim} environment, there is also a +% `star' variant of the \env{macrocode} environment in which a % space is shown by the symbol \verb*+ +. Until this moment, I % have not yet used it (it will be used in the description of the % definition of |\xmacro@code| below) but it's exactly on this one -% occasion {\em here\/} that you can't use it (cf.\ M\"unchhausens +% occasion {\em here\/} that you can't use it (cf.\ Münchhausens % Marsh problem)\footnote{Karl Friedrich Hieronymus Frhr.\ v.\ -% M\"unchhausen (*1720, \dag1797). Several books were written +% Münchhausen (*1720, \dag1797). Several books were written % about fantastic adventures supposedly told by him (see % \cite{book:Raspe} or \cite{book:Buerger}). In one story he % escaped from the marsh by pulling himself out by his hair.} @@ -1865,7 +2645,7 @@ % \end{macrocode*} % Additionally, we need to ensure that the symbols in the above % string contain the |\catcode|$\,$s which are available -% within the \textsf{macrocode} environment. +% within the \env{macrocode} environment. % \begin{macrocode*} \catcode`\{=12 \catcode`\}=12 \catcode`\%=12 \catcode`\ =\active \catcode`\\=\active @@ -1908,65 +2688,7 @@ % \subsection{Macros for the `documentation parts'} % % -% \begin{macro}{\DescribeMacro} -% \begin{macro}{\Describe@Macro} -% \changes{v1.5v}{1990/01/28}{Macro added.} -% \changes{v1.5j}{1989/06/09}{\cs{ignorespaces} added as a temporary -% fix} -% \begin{macro}{\DescribeEnv} -% \begin{macro}{\Describe@Env} -% \changes{v1.5v}{1990/01/28}{Macro added.} -% \changes{v1.5j}{1989/06/09}{\cs{ignorespaces} added as a temporary -% fix} -% The |\DescribeMacro| and |\DescribeEnv| macros should -% print their arguments in the margin and produce an index entry. -% We simply use |\marginpar| to get the desired result. This -% is however not the best solution because the labels might be -% slightly misplaced. One also might get a lot of `marginpar moved' -% messages which are hard-wired into the \LaTeX{} output -% routine.\footnote{It might be better to change these macros into -% environments like the \textsf{macro} environment.} First we change -% to horizontal mode if necessary. The \LaTeX{} macros -% |\@bsphack| and |\@esphack| are used to make those -% commands invisible (i.e.\ to normalize the surrounding space and -% to make the |\spacefactor| transparent). -% \changes{v1.5v}{1990/01/28}{\cs{MakePrivateLetters} added.} -% \begin{macrocode} -\def\DescribeMacro{\leavevmode\@bsphack -% \end{macrocode} -% When documenting the code for the \texttt{amstex.sty} option we -% encountered a bug: the |\catcode| of |@| was active and -% therefore couldn't be used in command names. So we first have to -% make sure that we get all |\catcode|s right by calling -% |\MakePrivateLetters| inside a group. Then we call -% |\Describe@Macro| to do the work. -% \changes{v2.0g}{1999/03/22}{Parse backslash as letter in argument -% to \cs{DescribeMacro}.} -% \changes{v2.0h}{1999/03/25}{Correct errors introduced in v2.0g.} -% \begin{macrocode} - \begingroup\MakePrivateLetters\Describe@Macro} -\def\Describe@Macro#1{\endgroup - \marginpar{\raggedleft\PrintDescribeMacro{#1}}% -% \end{macrocode} -% Note the use of |\raggedleft| to place the output flushed -% right. Finally we call a macro which produces the actual index -% entry and finish with |\@esphack| to leave no -% trace.\footnote{The whole mechanism won't work because -% of the \texttt{\bslash leavevmode} in front. -% As a temporary change \texttt{\bslash ignorespaces} -% is added.} -% \begin{macrocode} - \SpecialUsageIndex{#1}\@esphack\ignorespaces} -% \end{macrocode} -% The |\DescribeEnv| macro is completely analogous. -% \changes{v1.5v}{1990/01/28}{\cs{MakePrivateLetters} added.} -% \begin{macrocode} -\def\DescribeEnv{\leavevmode\@bsphack\begingroup\MakePrivateLetters - \Describe@Env} -\def\Describe@Env#1{\endgroup - \marginpar{\raggedleft\PrintDescribeEnv{#1}}% - \SpecialEnvIndex{#1}\@esphack\ignorespaces} -% \end{macrocode} + % To put the labels in the left margin we have to use the % |\reversemarginpar| declaration. (This means that the % \texttt{doc.sty} can't be used with all classes or packages.) @@ -1978,12 +2700,12 @@ \reversemarginpar \setlength\marginparpush{0pt} \setlength\marginparwidth{8pc} % \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} % -% \begin{macro}{\bslash} +% \begin{macrocode} +\setlength\marginparsep{\labelsep} +% \end{macrocode} +% +% \begin{imacro}{\bslash} % \changes{v1.7a}{1992/02/26}{Moved \cs{bslash} documentation to `user % interface' part} % We start a new group in which to hide the alteration of @@ -2000,14 +2722,14 @@ % \begin{macrocode} |gdef|bslash{\}} % \end{macrocode} -% \end{macro} +% \end{imacro} % % % % \begin{environment}{verbatim} % \begin{environment}{verbatim*} % \changes{v1.7i}{1992/07/12}{Added changed definition for verbatim!*.} -% The \textsf{verbatim} environment holds no secrets; it consists of +% The \env{verbatim} environment holds no secrets; it consists of % the normal \LaTeX{} environment. We also set the % |\@beginparpenalty| and change to the font given by % |\MacroFont|. @@ -2032,7 +2754,7 @@ % \begin{macro}{\@verbatim} % Additionally we redefine the |\@verbatim| macro so that it % suppresses |%| characters at the beginning of the line. The -% first lines are copied literally from the \LaTeX{} format. +% first lines are copied literally from \texttt{latex.tex}. % \changes{v1.7i}{1992/07/12}{Added \cs{@@par} to clear possible % \cs{parshape}.} % \begin{macrocode} @@ -2056,7 +2778,7 @@ % \begin{macrocode} \check@percent}% % \end{macrocode} -% The rest is again copied literally from the \LaTeX{} format (less +% The rest is again copied literally from \texttt{latex.tex} (less % "\tt"). % \changes{v1.7a}{1992/02/26}{Removed redundant \cs{tt}.} % \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim, @@ -2074,7 +2796,7 @@ % percent's |\catcode| so that it is seen by \TeX. The definition % itself is nearly trivial: grab the following character, check if % it is a |%|, and insert it again if not. At the end of the -% \textsf{verbatim} environment this macro will peek at the next +% \env{verbatim} environment this macro will peek at the next % input line. In that case the argument to |\check@percent| might % be a |\par| or a macro with arguments. Therefore we make the % definition |\long| (|\par| allowed) and use the normal |\next| @@ -2093,16 +2815,16 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\verb} +% \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 +% 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" +% 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} @@ -2111,24 +2833,27 @@ \ttfamily \verb@eol@error \let\do\@makeother \dospecials \@ifstar{\@sverb}{\@vobeyspaces \frenchspacing \@sverb}} % \end{macrocode} -% \end{macro} +% \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.} -% \changes{v2.1n}{2021/05/28}{Use same error message text as in format} % \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 ended by end of line}\@ehc}}% + \noexpand\verb command ended by end of line}\@ehc}}% \endgroup % \end{macrocode} % \end{macro} @@ -2155,7 +2880,7 @@ % % \begin{macro}{\verbatim@nolig@list} % \begin{macro}{\do@noligs} -% These macros replace the old "\@noligs" mechanism by an +% 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\-} @@ -2168,240 +2893,29 @@ % \end{macro} % \end{macro} % -% -% \begin{macro}{\macro} -% \begin{macro}{\m@cro@} -% \changes{v1.5v}{1990/01/28}{\cs{macro@} renamed to \cs{m@cro@} -% since AmSTeX -% defines another macro of the same name.} -% \begin{macro}{\macro@cnt} -% \label{page:macro} The \textsf{macro} environment is implemented as -% a \textsf{trivlist} environment, whereby in order that the macro +% \begin{tcounter}{\macro@cnt} +% \label{page:macro} The \env{macro} environment is implemented as +% a \env{trivlist} environment, whereby in order that the macro % names can be placed under one another in the margin % (corresponding to the macro's nesting depth), the macro % |\makelabel| must be altered. In order to store the nesting % depth, we use a counter. We also need a counter to count the -% number of nested \textsf{macro} environments. +% number of nested \env{macro} environments. % \changes{v1.5k}{1989/08/17}{Fix for save stack problem.} % \changes{v1.9k}{1994/02/22}{Fix probably no longer necessary} % \begin{macrocode} \newcount\macro@cnt \macro@cnt=0 % \end{macrocode} -% The environment takes an argument---the macro name to be -% described. Since this name may contain special `letters' we have -% to re-|\catcode| them before scanning the argument. This is done -% by the |\MakePrivateLetters| macro. -% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.} -% \changes{v1.7a}{1992/02/26}{Catcode backslash to other (from newdoc).} -% \changes{v1.9k}{1994/02/22}{Don't omit extra group} -% \begin{macrocode} -\def\macro{\begingroup - \catcode`\\12 - \MakePrivateLetters \m@cro@ \iftrue} -% \end{macrocode} -% -% \begin{environment}{environment} -% \changes{v1.8c}{1993/10/25}{Environment added} -% The ``environment'' environment will be implemented just like the -% ``macro'' environment flagging any differences in the code by -% passing |\iffalse| or |\iftrue| to the |\m@cro@| environment -% doing the actual work. -% \begin{macrocode} -\def\environment{\begingroup - \catcode`\\12 - \MakePrivateLetters \m@cro@ \iffalse} -% \end{macrocode} -% \end{environment} +% \end{tcounter} % -% After scanning the argument we close the group to get the normal -% |\catcode|$\,$s back. Then we assign a special value to -% |\topsep| and start a \textsf{trivlist} environment. -% \changes{v1.5f}{1989/05/07}{MacroTopsep parameter added.} -% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.} -% \changes{v1.8c}{1993/10/25}{Support ``environment'' env} -% \changes{v1.9k}{1994/02/22}{Remove \cs{macro@level}} -% \begin{macrocode} -\long\def\m@cro@#1#2{\endgroup \topsep\MacroTopsep \trivlist -% \end{macrocode} -% We also save the name being described in |\saved@macroname| for -% use in conjunction with the |\changes| macro. -% \begin{macrocode} - \edef\saved@macroname{\string#2}% - #1 -% \end{macrocode} -% If documenting an environment we put is name in |\saved@indexname| -% otherwise the name without the backslash. -% \changes{v2.1g}{2016/02/15}{Use \cs{saved@indexname}} -% \begin{macrocode} - \let\saved@indexname\saved@macroname - \else - \edef\saved@indexname{\expandafter\@gobble\string#2}% - \fi -% \end{macrocode} -% Now there follows a variation of |\makelabel| which is used -% should the environment not be nested, or should it lie between -% two successive |\begin{macro}| instructions or explanatory -% text. One can recognize this with the switch |\if@inlabel| -% which will be |true| in the case of successive |\item| -% commands. -% \begin{macrocode} - \def\makelabel##1{\llap{##1}}% -% \end{macrocode} -% If |@inlabel| is |true| and if $\verb=\macro@cnt= > 0$ -% then the above definition needs to be changed, because in this -% case \LaTeX{} would otherwise put the labels all on the same line -% and this would lead to them being overprinted on top of each -% other. Because of this |\makelabel| needs to be redefined -% in this case. -% \begin{macrocode} - \if@inlabel -% \end{macrocode} -% If |\macro@cnt| has the value $1$, then we redefine -% |\makelabel| so that the label will be positioned in the -% second line of the margin. As a result of this, two macro names -% appear correctly, one under the other. It's important whilst -% doing this that the generated label box is not allowed to have -% more depth than a normal line since otherwise the distance -% between the first two text lines of \TeX{} will be incorrectly -% calculated. The definition should then look like: -%\begin{verbatim} -% \def\makelabel##1{\llap{\vtop to \baselineskip -% {\hbox{\strut}\hbox{##1}\vss}}} -%\end{verbatim} -% Completely analogous to this is the case where labels need to be -% placed one under the other. The lines above are only an example -% typeset with the \textsf{verbatim} environment. To produce the real -% definition we save the value of |\macro@cnt| in -% |\count@| and empty the temp macro |\@tempa| for later -% use. -% \begin{macrocode} - \let\@tempa\@empty \count@\macro@cnt -% \end{macrocode} -% In the following loop we append for every already typeset label -% an |\hbox{\strut}| to the definition of |\@tempa|. -% \begin{macrocode} - \loop \ifnum\count@>\z@ - \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne \repeat -% \end{macrocode} -% Now be put the definition of |\makelabel| together. -% \changes{v1.5b}{1989/04/27}{vbox to vtop changed in makelabel (test)} -% \changes{v1.5e}{1989/04/28}{ht strutbox changed to baselineskip -% (test)} -% \begin{macrocode} - \edef\makelabel##1{\llap{\vtop to\baselineskip - {\@tempa\hbox{##1}\vss}}}% -% \end{macrocode} -% Next we increment the value of the nesting depth counter. This -% value inside the \textsf{macro} environment is always at least one -% after this point, but its toplevel definition is zero. Provided -% this environment has been used correctly, $|\macro@cnt|=0$ -% should not occur when |@inlabel|=\textsf{true}. It is -% however possible if this environment is used within other list -% environments (but this would have little point). -% \begin{macrocode} - \advance \macro@cnt \@ne -% \end{macrocode} -% If |@inlabel| is false we reset |\macro@cnt| assuming -% that there is enough room to print the macro name without -% shifting. -% \begin{macrocode} - \else \macro@cnt\@ne \fi -% \end{macrocode} -% Now the label will be produced using |\item|. The following -% line is only a hack saving the day until a better solution is -% implemented. We have to face two problems: the argument might be -% a |\par| which is forbidden in the argument of other macros -% if they are not defined as |\long|, or it is something like -% |\iffalse| or |\else|, i.e.\ something which will be -% misinterpreted when \TeX{} is skipping conditional text. In both -% cases |\item| will bomb, so we protect the argument by using -% |\string|. -% \begin{macrocode} - \edef\@tempa{\noexpand\item[% -% \end{macrocode} -% Depending on whether we are inside a ``macro'' or ``environment'' -% environment we use |\PrintMacroName| or |\PrintEnvName| to -% display the name. -% \begin{macrocode} - #1% - \noexpand\PrintMacroName - \else - \noexpand\PrintEnvName - \fi - {\string#2}]}% - \@tempa -% \end{macrocode} -% At this point we also produce an index entry. Because it is not -% known which index sorting program will be used, we do not use the -% command |\index|, but rather a command -% |\SpecialMainIndex| after advancing the counter for indexing -% by line number. This may be redefined by the user in -% order to generate an index entry which will be understood by the -% index program in use (note the definition of -% |\SpecialMainIndex| for our installation). -% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} -% \changes{v1.9u}{1995/08/06}{Removed brace group which -% killed \cs{DoNotIndex}} -% We advance the current codeline number and after producing an -% index entry revert to the original value -% \begin{macrocode} - \global\advance\c@CodelineNo\@ne -% \end{macrocode} -% Again the macro to call depends on the environment we are -% actually in. -% \begin{macrocode} - #1% - \SpecialMainIndex{#2}\nobreak - \DoNotIndex{#2}% - \else - \SpecialMainEnvIndex{#2}\nobreak - \fi - \global\advance\c@CodelineNo\m@ne -% \end{macrocode} -% The |\nobreak| is needed to prevent a page break after the -% |\write| produced by the |\SpecialMainIndex| macro. We -% exclude the new macro in the cross-referencing feature, to -% prevent spurious non-main entry references. Regarding possibly -% problematic arguments, the implementation takes -% care of |\par| and the conditionals are uncritical. -% \changes{v1.7a}{1992/03/02}{Removed redundant code checking for -% \cs{par}.}^^A % -% Because the space symbol should be ignored between the -% |\begin{macro}{...}| and the following text we must take -% care of this with |\ignorespaces|. -% \begin{macrocode} - \ignorespaces} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% -% -% -% \begin{macro}{\endmacro} -% \begin{macro}{\endenvironment} -% Older releases of this environment omit the |\endgroup| token, -% when being nested. This was done to avoid unnecessary stack usage. -% However it does not work if \textsf{macro} and -% \textsf{environment} environments are mixed, therefore we now -% use a simpler approach. -% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.} -% \changes{v1.9k}{1994/02/22}{Don't checkfor nesting} -% \begin{macrocode} -\let\endmacro \endtrivlist -\let\endenvironment\endmacro -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\MacroTopsep} +% \begin{lskip}{\MacroTopsep} % Here is the default value for the |\MacroTopsep| parameter % used above. % \begin{macrocode} \newskip\MacroTopsep \MacroTopsep = 7pt plus 2pt minus 2pt % \end{macrocode} -% \end{macro} +% \end{lskip} % % % @@ -2413,49 +2927,15 @@ % Therefore we define those macros only if they have not already % been defined. % -% \begin{macro}{\PrintMacroName} -% \begin{macro}{\PrintEnvName} -% \begin{macro}{\PrintDescribeMacro} -% \begin{macro}{\PrintDescribeEnv} -% The formatting of the macro name in the left margin is done by -% these macros. We first set a |\strut| to get the height and -% depth of the normal lines. Then we change to the -% |\MacroFont| using |\string| to |\catcode| the -% argument to other (assuming that it is a macro name). Finally we -% print a space. The font change remains local since this macro -% will be called inside an |\hbox|. -% \begin{macrocode} -\@ifundefined{PrintMacroName} - {\def\PrintMacroName#1{\strut \MacroFont \string #1\ }}{} -% \end{macrocode} -% We use the same formatting conventions when describing a macro. -% \begin{macrocode} -\@ifundefined{PrintDescribeMacro} - {\def\PrintDescribeMacro#1{\strut \MacroFont \string #1\ }}{} -% \end{macrocode} -% To format the name of a new environment there is no need to use -% |\string|. -% \begin{macrocode} -\@ifundefined{PrintDescribeEnv} - {\def\PrintDescribeEnv#1{\strut \MacroFont #1\ }}{} -\@ifundefined{PrintEnvName} - {\def\PrintEnvName#1{\strut \MacroFont #1\ }}{} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% -% % % \subsection{Creating index entries by scanning `macrocode'} % % The following macros ensure that index entries are created for each % occurrence of a \TeX-like command (something starting with -% `|\|') providing indexing has been turned on with "\PageIndex" -% or "\CodelineIndex". With the default definitions of -% |\SpecialMainIndex|, etc., the index file generated is -% intended to be processed by Chen's \textsf{makeindex} program +% `|\|') providing indexing has been turned on with |\PageIndex| +% or |\CodelineIndex|. With the default definitions of +% |\specialMainMacroIndex|, etc., the index file generated is +% intended to be processed by Chen's \prg{makeindex} program % \cite{art:Chen}. % % @@ -2464,15 +2944,15 @@ % introduce command names at places where |\| has to belong to % some other category. Therefore, we may also need to recognize % \verb+|+ as the introducer for a command when setting the text -% inside the \textsf{macrocode} environment. Other users may have the +% inside the \env{macrocode} environment. Other users may have the % need to make similar reassignments for their macros. % % -% \begin{macro}{\SpecialEscapechar}\label{sect:specialescapechar} +% \begin{imacro}{\SpecialEscapechar}\label{sect:specialescapechar} % \begin{macro}{\active@escape@char} % \begin{macro}{\special@escape@char} % The macro |\SpecialEscapechar| is used to denote a special escape -% character for the next \textsf{macrocode} environment. It has one +% character for the next \env{macrocode} environment. It has one % argument---the new escape character given as a `single-letter' % control sequence. Its main purpose is defining % |\special@escape@char| to produce the chosen escape character @@ -2528,7 +3008,7 @@ % \end{macrocode} % \end{macro} % \end{macro} -% \end{macro} +% \end{imacro} % % % @@ -2564,7 +3044,7 @@ % `|\|' 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 -% `|\|' has |\catcode| 13 within the \textsf{macrocode} +% `|\|' has |\catcode| 13 within the \env{macrocode} % environment. Otherwise the delimiter for the argument of % |\xmacro@code| would not be found (parameter matching % depends on |\catcode|$\,$s). @@ -2574,7 +3054,7 @@ \begingroup \catcode`\|=\z@ \catcode`\\=\active % \end{macrocode} % We carry out tasks 2) and 3b) first. -% \SpecialEscapechar{\|} +% \SpecialEscapechar\| % \begin{macrocode} |gdef|init@crossref{|catcode`|\|active |let\|bslash % \end{macrocode} @@ -2613,7 +3093,7 @@ % % % -% \begin{macro}{\MakePrivateLetters} +% \begin{imacro}{\MakePrivateLetters} % Here is the default definition of this command, which makes just % the |@| into a letter. The user may change it if he/she % needs more or other characters masquerading as letters. @@ -2621,7 +3101,7 @@ \@ifundefined{MakePrivateLetters} {\let\MakePrivateLetters\makeatletter}{} % \end{macrocode} -% \end{macro} +% \end{imacro} % % \begin{macro}{\close@crossref} % At the end of a cross-referencing part we prepare ourselves for @@ -2642,10 +3122,10 @@ % The |\init@crossref| will have made |\active| our % |\special@escape@char|, so that each % |\active@escape@char| will invoke |\scan@macro| when -% within the \textsf{macrocode} environment. By this means, we can +% within the \env{macrocode} environment. By this means, we can % automatically add index entries for every \TeX-like command which % is met whilst setting (in verbatim) the contents of -% \textsf{macrocode} environments. +% \env{macrocode} environments. % \begin{macrocode} \def\scan@macro{% % \end{macrocode} @@ -2658,7 +3138,7 @@ \special@escape@char \step@checksum % \end{macrocode} -% If the \textsf{macrocode} environment contains, for example, the +% If the \env{macrocode} environment contains, for example, the % command |\\|, the second |\| should not start the % scanning mechanism. Therefore we use a switch to decide if % scanning of macro names is allowed. @@ -2689,22 +3169,9 @@ % \end{macro} % % -% \begin{macro}{\ifscan@allowed} -% \begin{macro}{\scan@allowedtrue} -% \begin{macro}{\scan@allowedfalse} -% |\ifscan@allowed| is the switch used above to determine if -% the |\active@escape@char|\SpecialIndex{\active@escape@char} -% should start the macro scanning mechanism. -% \begin{macrocode} -\newif\ifscan@allowed \scan@allowedtrue -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% % -% \begin{macro}{\EnableCrossrefs} -% \begin{macro}{\DisableCrossrefs} +% \begin{imacro}{\EnableCrossrefs} +% \begin{imacro}{\DisableCrossrefs} % At this point we might define two macros which allow the user to % disable or enable the cross-referencing mechanism. Processing of % files will be faster if only main index entries are generated @@ -2718,8 +3185,8 @@ \def\EnableCrossrefs{\@bsphack\scan@allowedtrue \def\DisableCrossrefs{\@bsphack\@esphack}\@esphack} % \end{macrocode} -% \end{macro} -% \end{macro} +% \end{imacro} +% \end{imacro} % % % @@ -2750,6 +3217,10 @@ % % % \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.} @@ -2757,7 +3228,7 @@ % \cs{macro@namepart} as `letter' so index exclusion works.} % This macro will be invoked (with a single character as parameter) % when a single-character macro name has been spotted whilst -% scanning within the \textsf{macrocode} environment. +% scanning within the \env{macrocode} environment. % % First we take a look at the |\index@excludelist| to see % whether this macro name should produce an index entry. This is @@ -2775,14 +3246,14 @@ \uccode`\&=\expandafter`\string#1% \uppercase{\def\x{\def\macro@namepart{&}}}% \expandafter\endgroup\x - \ifnot@excluded % \end{macrocode} -% If necessary the index entry is produced by the macro -% |\produce@index|. Depending on the actual character seen, -% this macro has to do different things, so we pass the character -% as an argument. +% Any indexing is then delegated to +% |\maybe@index@short@macro|. Depending on the actual character seen, +% this macro has to do different things, which is why we keep it separate from +% |\maybe@index@macro| to avoid the special tests in the more +% common case of a multi-letter macro name. % \begin{macrocode} - \produce@index{#1}\fi + \maybe@index@short@macro\macro@namepart % \end{macrocode} % Then we disable the cross-referencing mechanism with % |\scan@allowedfalse| and print the actual character. The @@ -2803,104 +3274,6 @@ % % % -% \begin{macro}{\produce@index} -% \changes{v1.4s}{1989/04/23}{Added noexpand to all -% \cs{if} tests -% to avoid garbage produced by new active chars} -% \changes{v1.4s}{1989/04/23}{Used \texttt{\protect\bslash string} for -% the same reason.} -% \changes{v1.5c}{1989/04/27}{Corrected bad bug by placing the -% scan@allowedfalse macro into short@macro} -% This macro is supposed to generate a suitable |\SortIndex| -% command for a given single-letter control sequence. We test -% first for the cases which involve active characters (i.e.\ the -% backslash, the special escape character (if any), the space and -% the |^^M|). Using the |\if| test (testing for -% character codes), we have to ensure that the argument isn't -% expanded. -% \begin{macrocode} -\def\produce@index#1{% - \if\noexpand#1\special@escape@char -% \end{macrocode} -% If the character is the special escape character (or the -% `|\|' in case there was none) the |\it@is@a| macro is -% used to produce the actual |\SortIndex| call. -% \begin{macrocode} - \scan@allowedfalse \it@is@a\special@escape@char \else -% \end{macrocode} -% Next comes the test for a `|\|' which must be the -% $|\|_{13}$ expanding to |\bslash|. -% \begin{macrocode} - \if\noexpand#1\bslash \it@is@a\bslash \else -% \end{macrocode} -% Another possibility is \verb*+ +$_{13}$. Recall that |\space| -% produces a \verb*+ +$_{10}$. -% \begin{macrocode} - \if\noexpand#1\space \it@is@a\space \else -% \end{macrocode} -% The last\footnote{Well, it isn't the last active character after -% all. I added \texttt{\bslash @noligs} some days ago and now -% \texttt{`} too is active. So we have to make sure that such -% characters don't get expanded in the index.} possibility of an -% active character is |^^M|\@. In this case we don't test for -% character codes, since it is easier to look if the character is -% equal to |\par|. (We are inside the \textsf{macrocode} -% environment.) -% \begin{macrocode} - \ifx#1\par -% \end{macrocode} -% If we end up here we have just scanned a |\^^M| or something -% similar. Since this will be treated like \verb*+\ + by \TeX{} we -% produce a corresponding index entry. -% \begin{macrocode} - \it@is@a\space \else -% \end{macrocode} -% If it is the token |\relax| we do nothing. This can't happen -% when the `doc' package is used in the way described here, but was -% added to allow extensions like the \texttt{idxverb} option. -% \changes{v1.5t}{1989/11/14}{Added \cs{relax} as a possible token to -% allow extensions.} -% \begin{macrocode} - \ifx#1\relax \else -% \end{macrocode} -% The next three branches are needed because of bugs in -% our \textsf{makeindex} program. You can't produce unbalanced index -% entries\footnote{This is possible for \TeX{} if you use -% \texttt{\string{$_{12}$ \rmfamily or -% \ttfamily\string}$_{12}$}, -% but \textsf{makeindex} will complain.} -% and you have to double a percent character. To get around these -% restrictions we use special macros to produce the |\index| -% calls.\footnote{Brian \textsc{Hamilton Kelly} has written fixes for -% all three -% bugs. When they've found their way through all -% installations, -% the lines above will be removed. See -% page~\pageref{bug:fixes} if you already have them. -% (I'm not sure which versions incorporate these, but -% 2.11 is OK. See also -% \pageref{makeindex:version}.)} -% \begin{macrocode} - \if\noexpand#1\bgroup \LeftBraceIndex \else - \if\noexpand#1\egroup \RightBraceIndex \else - \if\noexpand#1\percentchar \PercentIndex \else -% \end{macrocode} -% All remaining characters are used directly to produce their index -% entries. This is possible even for the characters which have -% special meanings in the index program, provided we quote the -% characters. (This is correctly done in |\it@is@a|.) -% \begin{macrocode} - \it@is@a{\string#1}% -% \end{macrocode} -% We now need a whole pile of |\fi|$\,$s to match up with -% the |\if|$\,$s. -% \begin{macrocode} - \fi \fi \fi \fi \fi \fi \fi \fi} -% \end{macrocode} -% \end{macro} -% -% -% % \begin{macro}{\macro@name} % We now come to the macro which assembles command names which % consist of one or more `letters' (which might well include @@ -2968,9 +3341,11 @@ % routine. At this time \texttt{\bslash macro@namepart} might have a % new value.} % \begin{macrocode} - \ifnot@excluded - \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}% - \@tempa \fi} +% \ifnot@excluded +% \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}% +% \@tempa \fi + \maybe@index@macro \macro@namepart +} % \end{macrocode} % \end{macro} % @@ -2980,155 +3355,525 @@ % % \subsection[The index exclude list]{The index exclude % list\footnotemark} -% \footnotetext{Warning: the incomplete commentary on +% \footnotetext{Info: the incomplete commentary on % \texttt{\bslash DoNotIndex} and the macros it calls % was written by Dave Love.} % -% The internal form of the index exclude list is -% \begin{quote} -% \meta{macro name}|,|\meta{macro name}|,| -% \ldots|,| -% \end{quote} -% where \meta{macro name} is a macro name like -% $"\"_{12}"p"{_{11}}"@"_{11}$ or $"\"_{12}"$"_{11}$. Note that the "\" -% has category `other' and the other characters in the name are all -% `letter', regardless of their normal category. % -% \begin{macro}{\DoNotIndex} -% This macro is used to suppress macro names in the index. It -% starts off with a new group because we have to change the -% |\catcode|$\,$s of all characters which belong to `letters' -% while macros are defined. +% + +% \def\MakePrivateLetters{% +% \makeatletter +% \catcode`\_11 +% \catcode`\:11} +% +% +% The following part of the code is a new implementation using the +% \LaTeX3 programming layer as the constructs and types +% provided therein are making programming much easier. Over time I +% will probably replace the rest of that \DOC code too. % \begin{macrocode} -\def\DoNotIndex{\begingroup \MakePrivateLetters - \catcode`\\12 +\ExplSyntaxOn % \end{macrocode} -% Then we call the macro which actually reads the argument given by -% the user. +% +% +% \DescribeMacro\l__doc_donotindex_seq +% Local sequence that holds names (as strings) of commands that +% should not be indexed. Within a \DOC element environment that +% element is placed into the sequence so that it isn't +% 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. +% +% \DescribeMacro\g__doc_idxtype_prop +% Global property list that holds for all commands that are special +% \DOC elements the type of the element. The key is the command +% name without backslash and the value is \DOC element type +% identifier, e.g., |\texttt{Length}| for length registers if that +% type has been set up. \DOC only indexes commands, that is things +% starting with an escape character, i.e., a backslash (by +% default). \DOC elements that do not start with an escape +% character, e.g., environments are not identified when parsing +% code so that aren't indexed automatically inside. Thus for them +% there is no point in keeping them in that property list. +% +% \DescribeMacro{\doc_dont_index:n} +% \DescribeInterfaceMacro{\DoNotIndex} +% Takes a clist of commands (with backslash) as input and exclude +% all of them from the index. User facing we make this available as +% |\DoNotIndex|. +% +% +% \DescribeInterfaceMacro\ShowIndexingState +% Displays the current list of the exclude index list in a fairly +% low-level form. +% +% \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 +% 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 +% generated earlier will be listing the wrong type. Therefore this +% information is also placed into the \texttt{.aux} file so that it +% will be available at the beginning of further runs. +% +% This command is internally executed as part of any \DOC element +% environment so it only needs to be explicitly given if for some +% reason a command with a special type has no corresponding environment. +% +% +% +% +% \begin{macro}{\l__doc_donotindex_seq} +% \begin{macro}{\g__doc_idxtype_prop} +% Declarations. % \begin{macrocode} - \do@not@index} +\seq_new:N \l__doc_donotindex_seq +\prop_new:N \g__doc_idxtype_prop % \end{macrocode} -% \end{macro} +% \end{macro} +% \end{macro} % +% ^^A -------------------------------------------------- % % -% \begin{macro}{\do@not@index} -% We make the |\do@not@index| macro |\long| -% since the user might want to exclude the |\par| -% macro. +% \begin{macro}{\__doc_trace:x} +% A helper for tracing\ldots % \begin{macrocode} -\long\def\do@not@index#1{% +\cs_new:Npn\__doc_trace:x { + \legacy_if:nTF{ doc@debugshow }{ \iow_term:x } { \use_none:n } +} % \end{macrocode} -% It just adds to a token list after finishing the group in which -% the catcodes were changed. -% \changes{v1.7a}{1992/02/26}{Replaced with newdoc version.} +% \end{macro} +% +% +% ^^A -------------------------------------------------- +% +% \begin{macro}{\doc_dont_index:n} +% \begin{macro}{\__doc_dont_index:n} +% \begin{macro}{\__doc_dont_index_aux:n} +% +% Parses the argument a clist of commands with +% |\MakePrivateLetters| in force (so that special characters are +% recognized as being part of command names) and puts each command +% without is backslash as a string into the sequence +% |\l__doc_donotindex_seq|. % \begin{macrocode} - \endgroup - \addto@hook\index@excludelist{#1,}} +\cs_new:Npn \doc_dont_index:n { + \group_begin: + \MakePrivateLetters + \__doc_dont_index:n +} % \end{macrocode} -% \end{macro} % -% \begin{macro}{\addto@hook} -% The code for adding tokens (the second argument) to a token list -% (the first argument) is taken from~\cite{art:verbatim}, but it needs -% to be "\long" in case "\par" is amongt the tokens. % \begin{macrocode} -\long\def\addto@hook#1#2{#1\expandafter{\the#1#2}} +\cs_new:Npn \__doc_dont_index:n #1 { + \group_end: % \end{macrocode} -% \end{macro} % -% \begin{macro}{\index@excludelist} -% We need an initially-empty register for the excluded list. % \begin{macrocode} -\newtoks\index@excludelist -\index@excludelist{} + \__doc_trace:x{Disable~ indexing~ for~ '\tl_to_str:n{#1}' } % \end{macrocode} -% \end{macro} +% Adding the commands to the |\l__doc_donotindex_seq| sequence is +% done by mapping the function |\__doc_dont_index_aux:n| on each +% element in the clist. +% \begin{macrocode} + \clist_map_function:nN {#1} \__doc_dont_index_aux:n +} +% \end{macrocode} +% We record each command by using its name as a string. +% This means more tokens in the sequence but it allows +% to compare names not ``action'' which is important as different +% commands may have the same meaning (e.g., they may not be defined +% at all), +% \begin{macrocode} +\cs_new:Npn \__doc_dont_index_aux:n #1 { + \seq_put_right:Nx \l__doc_donotindex_seq {\expandafter\@gobble \string#1} +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} % -% \begin{macro}{\ifnot@excluded} -% \changes{v1.7a}{1992/02/26}{Replaced with newdoc version.} -% \begin{macro}{\expanded@notin} -% Now we take a look at the |\index@excludelist| to see -% whether a macro name saved in |\macro@namepart| should -% produce an index entry. This macro is a pseudo |\if|; it -% should expand to |\iftrue| or |\iffalse| depending on -% the contents of |\index@excludelist|. +% \begin{macro}{\DoNotIndex} +% The document-level interface % \begin{macrocode} -\begingroup +\cs_set_eq:NN \DoNotIndex \doc_dont_index:n % \end{macrocode} -% First we change "\catcode"s so that "\" is `other' and "|" a -% temporary for the escape character. This is necessary since our -% macro names are stored that way in the "\index@excludelist". +% \end{macro} +% +% +% \begin{macro}{\ShowIndexingState} +% Some tracing information that may be helpful. % \begin{macrocode} -\catcode`\|=0% -\catcode`\\=12 +\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} -% Then we define "\ifnot@excluded" to call "\expanded@notin" with -% two arguments: the first is the string "\" followed by the -% contents of "\macro@namepart" followed by a "," and the second is -% "\the" followed by "\index@excludelist". To achieve the expansion -% of "\macro@namepart", i.e.\ to pass its contents, we need a -% suitable number of "\expandafter"s. -% \SpecialEscapechar{\|} +% \end{macro} + + + +% ^^A -------------------------------------------------- +% +% +% \begin{macro}{\__doc_idxtype_put:Nn} +% \begin{imacro}{\RecordIndexType} +% \fmi{Change name of interface command!} +% \begin{macro}{\RecordIndexTypeAux} +% This is the internal form for |\RecordIndexType|. The first +% argument is turned into a string and the rest of the processing +% is then done by |\__doc_idxtype_put:nn| +% \begin{macrocode} +\cs_new:Npn \__doc_idxtype_put:Nn #1#2 { + \exp_args:Nx \__doc_idxtype_put:nn { \cs_to_str:N #1 }{#2} +% \end{macrocode} +% We also make an entry in the \texttt{.aux} file so that this +% declaration becomes immediately available in the next +% run. However, for this we aren't reusing |\__doc_idxtype_put:N| +% (a.k.a.\ |\RecordIndexType|) since that would result in doubling +% such lines each time the document is run. Instead we use +% |\RecordIndexTypeAux| which is only updating the data structures +% without writing to the \texttt{.aux} file. +% \begin{macrocode} + \protected@write\@auxout{} + {\string\RecordIndexTypeAux {\string#1 }{#2} } +} +% \end{macrocode} +% When we execute this code from the \texttt{.aux} we better not +% generate a new line in the \texttt{.aux}. Otherwise those would +% cumulate over time. % \begin{macrocode} -|gdef|ifnot@excluded{|expandafter - |expanded@notin|expandafter{|expandafter - \|macro@namepart,}{|the|index@excludelist}} -|endgroup +\cs_new:Npn \RecordIndexTypeAux #1#2 { + \exp_args:Nx \__doc_idxtype_put:nn { \cs_to_str:N #1 }{#2} +} +% \end{macrocode} +% Similarly, when the \texttt{.aux} is read at the end of the run we +% should disable that command to avoid unnecessary processing. +% \begin{macrocode} +\AtEndDocument{ + \cs_set_eq:NN \RecordIndexTypeAux \use_none:nn +} +% \end{macrocode} +% Finally, we provide the user-level interface +% \begin{macrocode} +\cs_set_eq:NN \RecordIndexType \__doc_idxtype_put:Nn +% \end{macrocode} +% \end{macro} +% \end{imacro} +% \end{macro} +% +% +% \begin{macro}{\__doc_idxtype_put_scan:nn} +% When we want to record an index type for a scanned name we can't +% turn that into a csname and then call |\__doc_idxtype_put:Nn| +% because turning it into a csname may change the meaning of the +% name from ``undefined'' to |\relax|. Got bitten by that when +% processing the kernel sources containing |\@undefined| within the +% code: suddenly that wasn't undefined any longer. +% So here is another version that works only on characters as +% input. As we don't know whether or not they are proper strings +% already we first make sure that this is the case. +% \begin{macrocode} +\cs_new:Npn \__doc_idxtype_put_scan:nn #1#2 { + \exp_args:Nf \__doc_idxtype_put:nn { \tl_to_str:n {#1} }{#2} +% \end{macrocode} +% In this case we also have to append a backslash when writing to +% the \texttt{.aux} file. +% \begin{macrocode} + \protected@write\@auxout{} + {\string\RecordIndexTypeAux {\bslash #1 }{#2} } +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\__doc_idxtype_put_scan:on} +% And here is the one we really need since the characters are +% stored in some macro. +% \begin{macrocode} +\cs_generate_variant:Nn \__doc_idxtype_put_scan:nn {o} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\record@index@type@save} +% And here is the interface to the rest of the code: +% \begin{macrocode} +\cs_set_eq:NN \record@index@type@save \__doc_idxtype_put_scan:on +% \end{macrocode} +% \end{macro} +% +% +% \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 +% |\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 +% the command is later marked for exclusion from the index the +% property list setting remains unchanged but as long as no index +% is produced for the command it will not be consulted. +% +% Note: the command assumes that |#1| is already in string form +% \begin{macrocode} +\cs_new:Npn \__doc_idxtype_put:nn #1#2 { +% \end{macrocode} +% No mystery here: if the command is not marked for exclusion from +% the index add the property. The extra |\tl_to_str:n| is a safety +% measure in case the input wasn't already in that form (should +% only be the case with broken input but \ldots) +% \begin{macrocode} + \exp_args:NNf + \seq_if_in:NnTF \l__doc_donotindex_seq {\tl_to_str:n{#1}} +% \end{macrocode} +% Some tracing info \ldots{} +% \begin{macrocode} + { + \__doc_trace:x{Not~ recording~ index~ type~ for~ '\bslash #1' } + } + { + \__doc_trace:x{Recording~ index~ type~ for~ '\bslash #1' ~ as~ #2 } +% \end{macrocode} +% Stick the data into the property list: +% \begin{macrocode} + \prop_gput:Nnn \g__doc_idxtype_prop {#1}{#2} + } +} +% \end{macrocode} +% \end{macro} +% +% ^^A -------------------------------------------------- +% +% +% \begin{macro}{\exp_args:co} +% A helper: construct a function and call it with its first argument +% expanded once: +% \begin{macrocode} +\cs_new:Npn \exp_args:co #1#2 + { \cs:w #1 \exp_after:wN \cs_end:\exp_after:wN {#2} } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\tl_to_str:o} +% Another helper: take some token list variable, expand it and turn +% it into a string. +% \begin{macrocode} +\cs_generate_variant:Nn \tl_to_str:n {o} +% \end{macrocode} +% \end{macro} +% +% +% +% ^^A -------------------------------------------------- +% +% +% +% \DescribeMacro\maybe@index@macro +% +% This takes a macro name (without backslash) as parsed within a +% \env{macrocode} environment and checks if it should get indexed +% (i.e., is not on the exclude list) and if so how (i.e., gets it +% index type property and makes the right choice depending on that. +% + + +% \begin{macro}{\maybe@index@macro} +% \begin{macro}{\__doc_maybe_index:o} +% We first make sure that the argument is really a string (so that +% we have a defined situation) and then +% pass it on to |\__doc_maybe_index_aux:nN| to do the work. +% The second argument defines the indexing operation +% \cs{SpecialIndex} for multi-letter macros and below +% \cs{SpecialShortIndex} for single character macros. +% \begin{macrocode} +\cs_new:Npn \__doc_maybe_index:o #1 { + \exp_args:Nf \__doc_maybe_index_aux:nN { \tl_to_str:o {#1} } + \SpecialIndex +} +% \end{macrocode} +% And here is what we call it in the older non-expl3 code: +% \begin{macrocode} +\cs_set_eq:NN \maybe@index@macro \__doc_maybe_index:o +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \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}. +% \begin{macrocode} +\cs_new:Npn \__doc_maybe_index_short:o #1 { + \exp_args:Nf \__doc_maybe_index_aux:nN { \tl_to_str:o {#1} } + \SpecialShortIndex +} +\cs_set_eq:NN \maybe@index@short@macro \__doc_maybe_index_short:o +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% \begin{macro}{\__doc_maybe_index_aux:nN} +% Take a string (representing a macro without backslash) and make +% the right choices with respect to indexing. +% \begin{macrocode} +\cs_new:Npn \__doc_maybe_index_aux:nN #1#2 { +% \end{macrocode} +% A bit of tracing: +% \begin{macrocode} + \__doc_trace:x{Searching~ for~ '\bslash #1'} +% \end{macrocode} +% If the name is on the exclude list do nothing. +% \begin{macrocode} + \seq_if_in:NnTF \l__doc_donotindex_seq {#1} % \end{macrocode} -% The macro "\expanded@notin" now does the dirty work. It first -% defines a macro "\in@@" with a very special parameter text. If -% you look closely "\in@@" has three arguments, the first one is -% delimited by the first argument of "\expanded@notin" (i.e.\ by -% the string starting with a "\" and ending with a "," above), the -% second is undelimited (which means that it will get the next -% token after our string, and the third is delimited again and will -% get the rest up to the token "\in@@". In other words the token -% "\in@@" is also used as a delimiter. -% \begin{macrocode} -\def\expanded@notin#1#2{% - \def\in@@##1#1##2##3\in@@{% -% \end{macrocode} -% Now the replacement text simply compares the second argument -% (i.e.\ the undelimited one after our string) to the token -% "\expanded@notin". This is an unclosed "\ifx" statement which -% means that this macro behaves similar to a normal \TeX{} -% conditional. -% \begin{macrocode} - \ifx\expanded@notin##2}% -% \end{macrocode} -% After all these preparations we call "\in@@". First we expand the -% token after "\in@@" (which is "\the" from the second argument to -% "\expanded@notin"). As a result we get the contents of the -% "\index@excludelist" inserted after "\in@@". After this contents -% we add once more the string we are looking for, then the token -% "\expanded@notin" and finally the token "\in@@". -% \begin{macrocode} - \expandafter\in@@#2#1\expanded@notin\in@@} -% \end{macrocode} -% Now what happens when the macro "\in@@" above gets called? The -% first argument to "\in@@" is delimited by our string. In other -% words it will get everything from the contents of -% "\index@excludelist" before this string. If the string is not in -% "\index@excludelist" then it gets the whole contents, since after -% it we had inserted the string one more. In this case the next -% token is "\expanded@notin" which gets assigned to the second -% argument and the third argument will be empty. If, on the other -% hand, the string was inside "\index@excludelist" then the second -% argument will not be the token "\expanded@notin" and the third -% argument will be all the garbage up to "\in@@". Therefore testing -% the seconded argument, as done in the definition of "\in@@" will -% tell us whether or not the string is in "\index@includelist" and -% this was exactly what we wanted. (Deep breath.) You got -% that?\footnote{\TeX{}book page 125. The code described above is -% originally due to Michael Spivak who used a similar method within -% the \AmSTeX{} macros.} -% \end{macro} -% \end{macro} % +% \begin{macrocode} + { + \__doc_trace:x{Not~ indexing~ '\bslash #1' } + } +% \end{macrocode} +% Otherwise check if this name has an index type property attached +% to it. +% \begin{macrocode} + { + \prop_get:NnNTF \g__doc_idxtype_prop {#1} \l__doc_idxtype_tl +% \end{macrocode} +% If so construct and execute +% |\Code|\meta{idxtype}|Index|\footnote{I guess this should really +% be an internal name not a user-level one.} which is done inside +% |\__doc_maybe_index_aux| +% \begin{macrocode} + { + \exp_args:Ncno \__doc_maybe_index_aux:Nnn + { Code \tl_use:N \l__doc_idxtype_tl Index } + {code} {\bslash #1} + } +% \end{macrocode} +% Otherwise execute |\SpecialIndex| which is a short form for +% |\CodeMacroIndex{code}| or execute \cs{SpecialShortIndex} which +% deals with some special cases for single letter macros. +% \begin{macrocode} + { + \__doc_trace:x{Indexing~ '\bslash #1'\space (\string #2)} + \exp_args:No #2 {\bslash #1} + } + } +} +% \end{macrocode} +% \end{macro} % % % +% \begin{macro}{\SpecialShortIndex} +% \fmi{to be documented; also needs cleaning up as it is a mix of +% old and new right now} +% \begin{macrocode} +\cs_new:Npn \SpecialShortIndex #1 { + \@SpecialIndexHelper@ #1\@nil + \@bsphack + \ifdoc@noindex \else + \str_case_e:nnF {\@gtempa } + { + {\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 } + \def\reserved@b { \space } + \let\reserved@c \@empty } + {\c_left_brace_str} { \def\reserved@a{ \bgroup \actualchar } + \def\reserved@b { \c_left_brace_str } + \def\reserved@c { \noexpand\iffalse + \c_right_brace_str + \noexpand\fi } } + {\c_right_brace_str} { \def\reserved@a{ \egroup \actualchar + \noexpand\iffalse + \c_left_brace_str + \noexpand\fi } + \def\reserved@b { \c_right_brace_str } + \let\reserved@c \@empty } +% \end{macrocode} +% The case of \cs{verbatimchar} is tricky. We can't stick it into +% the normal \cs{verb} because we would then get something like +% \verb=\verb+\++= which would comes out as ``\verb+\++'' instead +% of \verb=\+=. So we use the \cs{verb} to only generate the +% backslash and then use \cs{texttt} on the \cs{verbatimchar} +% itself. However, that is not enough if we are unlucky and +% somebody (like Will :-)) has used something like \verb=&= with a +% special catcode for the \cs{verbatimchar}. We therefore also +% apply \cs{string} to it when we read it back. +% \begin{macrocode} + {\verbatimchar} { \def\reserved@a{ \quotechar\verbatimchar + \actualchar } + \let\reserved@b \@empty + \def\reserved@c + { \string\texttt{\string\string\verbatimchar} } } + } + { \def\reserved@a {\quotechar \@gtempa \actualchar } + \def\reserved@b {\quotechar \@gtempa } + \let\reserved@c \@empty } + \special@index { + \reserved@a + \string\verb + \quotechar *\verbatimchar \quotechar \bslash + \reserved@b + \verbatimchar + \reserved@c + \encapchar code} + \fi + \@esphack +} +% \end{macrocode} +% \end{macro} + + + + + +% \begin{macro}{\__doc_maybe_index_aux:Nnn} +% Execute the function passed on as first argument taking argument +% 2 and 3 as input. +% \begin{macrocode} +\cs_new:Npn \__doc_maybe_index_aux:Nnn #1#2#3 { +% \end{macrocode} +% We have to be a little careful: as that function name is +% constructed it may not actually exist (as constructions generate +% |\relax| in \TeX{} in that case). In that case we raise an error, +% otherwise we execute (with a little bit of tracing info): +% \begin{macrocode} + \cs_if_exist:NTF #1 + { + \__doc_trace:x{Indexing~ '#3'\space as~ + \tl_use:N \l__doc_idxtype_tl } + #1{#2}{#3} + } + { + \PackageError{doc}{Doc~ element~ + '\tl_use:N \l__doc_idxtype_tl'~ unknown}% + + {When~ using~ '\string\RecordIndexType'~ the~ type~ must~ + be~ known~\MessageBreak + to~ the~ system,~ i.e.,~ declared~ via~ + '\string\NewDocElement'\MessageBreak + before~ it~ can~ be~ used~ in~ indexing.} + } +} +% \end{macrocode} +% \end{macro} +% +% +% Back to old style coding \ldots +% \begin{macrocode} +\ExplSyntaxOff +% \end{macrocode} % % % @@ -3138,20 +3883,20 @@ % index entries; these are either invoked explicitly, or automatically % by |\scan@macro|. As already mentioned, the definitions given % here presuppose that the |.idx| file will be processed by -% Chen's \textsf{makeindex} program --- they may be redefined for use -% with the user's favourite such program. +% Chen's \prg{makeindex} program --- they may be redefined for use +% with the user's favorite such program. % % To assist the reader in locating items in the index, all such % entries are sorted alphabetically {\em ignoring\/} the initial % `|\|'; this is achieved by issuing an |\index| command which -% contains the `actual' operator for \textsf{makeindex}. The default +% contains the `actual' operator for \prg{makeindex}. The default % value for the latter operator is `|@|', but the latter character is % so popular in \LaTeX\ package files that it is necessary to substitute -% another character. This is indicated to \textsf{makeindex} by means +% another character. This is indicated to \prg{makeindex} by means % of an `index style file'; the character selected for this function % is |=|, and therefore this character too must be specially treated % when it is met in a \TeX\ command. A suitable index style file is -% provided amongt the supporting files for this style file in +% provided amongst the supporting files for this style file in % \texttt{gind.ist} and is generated from this source by processing % with \texttt{docstrip} to extract the module \textbf{gind}. A % similar style file \texttt{gglo.ist} is supplied for sorting the @@ -3172,12 +3917,12 @@ %<+gind|gglo> % \end{macrocode} % -% \begin{macro}{\actualchar} -% \begin{macro}{\quotechar} -% \begin{macro}{\levelchar} +% \begin{imacro}{\actualchar} +% \begin{imacro}{\quotechar} +% \begin{imacro}{\levelchar} % First come the definitions of |\actualchar|, % |\quotechar| and |\levelchar|. Note, that our defaults -% are not the ones used by the \textsf{makeindex} program without a +% are not the ones used by the \prg{makeindex} program without a % style file. % \begin{macrocode} %<*package> @@ -3190,85 +3935,39 @@ %<+gind|gglo>level '>' %<*package> % \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} +% \end{imacro} +% \end{imacro} +% \end{imacro} % % -% \begin{macro}{\encapchar} -% The \textsf{makeindex} default for the |\encapchar| isn't +% \begin{imacro}{\encapchar} +% The \prg{makeindex} default for the |\encapchar| isn't % changed. % \begin{macrocode} \@ifundefined{encapchar}{\def\encapchar{|}}{} % \end{macrocode} -% \end{macro} +% \end{imacro} % % -% \begin{macro}{\verbatimchar} +% \begin{imacro}{\verbatimchar} % We also need a special character to be used as a delimiter for % the |\verb*| command used in the definitions below. % \begin{macrocode} \@ifundefined{verbatimchar}{\def\verbatimchar{+}}{} % \end{macrocode} -% \end{macro} +% \end{imacro} % % -% \begin{macro}{\SpecialIndex} -% The |\SpecialIndex| command creates index entries for -% macros. If the argument is |\|$xyz$, the command produces -% \verb|\indexentry{|$xyz$\verb|=\verb!*+\|$xyz$\verb|+}{|$n$\verb|}| -% given the above defined defaults for |\actualchar|, -% |\quotechar| and |\verbatimchar|. We first remove the -% initial `|\|' to get a better index. -% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} -% \begin{macrocode} -\def\SpecialIndex#1{\@bsphack\special@index{\expandafter\@gobble - \string#1\actualchar -% \end{macrocode} -% Then follows the actual entry. A |\quotechar| is placed -% before the |*| to allow its use as a special \textsf{makeindex} -% character. Again |\@bsphack| and |\@esphack| are used -% to make the macros invisible. -% \begin{macrocode} - \string\verb\quotechar*\verbatimchar\string#1\verbatimchar}% - \@esphack} -% \end{macrocode} -% \end{macro} - -% \begin{macro}{\SpecialMainIndex} -% \begin{macro}{\SpecialMainEnvIndex} -% \begin{macro}{\SpecialUsageIndex} -% The |\SpecialMainIndex| macro is used to cross-reference the -% names introduced by the \textsf{macro} environment. The action is -% as for |\SpecialIndex|, except that \textsf{makeindex} is -% instructed to `encap'sulate the entry with the string -% \verb=|main= to cause it to generate a call of the |\main| -% macro. -% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} -% \changes{v2.0c}{1998/08/22}{Correctly handle single character -% control sequences like \cs{<}.} -% -% |\SpecialMainIndex| passes the macro name to be indexed on to the -% macro |\SpecialIndex@|. -% \begin{macrocode} -\def\SpecialMainIndex#1{\@bsphack\SpecialIndex@{#1}{\encapchar main}% - \@esphack} -% \end{macrocode} % -% \begin{macro}{\SpecialIndex@} -% \changes{v2.0c}{1998/08/22}{Macro added.} -% \changes{v2.0f}{1999/02/27}{Temp fix to allow strange code in arg 1 -% (PR 2968)} -% The macro |\SpecialIndex@| does the real work for |\SpecialMainIndex| -% and |\SpecialUsageIndex|. It takes two arguments: the macro to be -% indexed (as a control sequence or list of character tokens) and the -% additional text for the index. -% \changes{v2.0g}{1999/03/22}{Correct so-called temp fix. I'm not going to -% explain this.} +% \begin{macro}{\@SpecialIndexHelper@} +% \fmi{doc or drop} % \begin{macrocode} \begingroup \catcode`\|=0 \catcode`\\=12 +% \end{macrocode} +% \SpecialEscapechar\| +% \begin{macrocode} |gdef|@SpecialIndexHelper@#1#2|@nil{% |if |noexpand#1\% |gdef|@gtempa{#2}% @@ -3279,137 +3978,13 @@ |endgroup |fi} |endgroup -\def\SpecialIndex@#1#2{% -% \end{macrocode} -% The first thing it does is to convert the macro into a list of -% characters. Note that a character token list remains (mostly) unchanged. -% \begin{macrocode} - \@SpecialIndexHelper@#1\@nil % \end{macrocode} -% The macro name \verb*|\ | has to handled in a special way. The reason -% is that the space token is skipped when \TeX\ is scanning macro -% parameters, so that the trick used below will not work. -% So, we check whether the replacement text of |\@tempa| starts with -% a space token and write the appropriate index entry. -% \begin{macrocode} - \def\@tempb{ }% - \ifcat \@tempb\@gtempa - \special@index{\quotechar\space\actualchar - \string\verb\quotechar*\verbatimchar - \quotechar\bslash\quotechar\space\verbatimchar#2}% - \else -% \end{macrocode} -% Having handled this special case we have to distinguish control -% sequences consisting of one or more -% letters and those that consists of exactly one nonletter. As character -% tokens in the replacement text of the macro |\@gtempa| have all -% category code $12$ (other), this is difficult. For simplicity, we treat -% all single character control sequences alike, irregardless of whether -% the character is a letter or not. This has the advantage that it works -% even for strange settings of the category codes. % -% We define a utility macro |\@tempb| with two arguments, the second -% delimited by |\relax|. -% It will be called later so that the first argument is the first character -% of the macro name, and the second argument receives the rest of the -% characters. So we distinguish the two cases above by checking whether -% the second argument is empty. -% \begin{macrocode} - \def\@tempb##1##2\relax{\ifx\relax##2\relax -% \end{macrocode} -% If so, we define the helper macro |\@tempc| in a way that it -% adds quotechars in critical places. -% \begin{macrocode} - \def\@tempc{\special@index{\quotechar##1\actualchar - \string\verb\quotechar*\verbatimchar - \quotechar\bslash\quotechar##1\verbatimchar#2}}% -% \end{macrocode} -% Otherwise we write the characters as in |\SpecialIndex|. -% \begin{macrocode} - \else - \def\@tempc{\special@index{##1##2\actualchar - \string\verb\quotechar*\verbatimchar - \bslash##1##2\verbatimchar#2}}% - \fi}% -% \end{macrocode} -% Now pass the list of characters to \@tempb and call \@tempc to do the -% work. -% \begin{macrocode} - \expandafter\@tempb\@gtempa\relax - \@tempc - \fi} -% \end{macrocode} -% \end{macro} -% -% Slightly simpler is the main entry for environments -% \changes{v1.9e}{1994/02/03}{use \cs{ttfamily} with \cs{string}} -% \changes{v1.9f}{1994/02/07}{should have used \cs{noexpand}, sigh} -% \changes{v1.9i}{1994/02/11}{should have used \cs{protect}} -% \changes{v1.9j}{1994/02/16}{Back to string:-)} -% \changes{v1.9s}{1994/10/14}{Added missing percent and changed to -% \cs{ttfamily}} -% \changes{v2.0d}{1998/12/20}{Correctly handle second index entry -% by using \cs{special@index} not \cs{index} (PR/2928).} -% \changes{v2.0e}{1998/12/28}{Use \cs{string}, not \cs{protect} in argument to -% \cs{special@index}.} -% \changes{v2.1c}{2004/07/23}{environment names incorrectly sorted in -% index (pr/3615)} -% \begin{macrocode} -\def\SpecialMainEnvIndex#1{\@bsphack\special@index{% - #1\actualchar - {\string\ttfamily\space#1} - (environment)% - \encapchar main}% - \special@index{environments:\levelchar#1\actualchar{% - \string\ttfamily\space#1}\encapchar - main}\@esphack} -% \end{macrocode} -% The |\SpecialUsageIndex| is similar to |\SpecialMainIndex|, except -% that it uses the standard |\index| command. -% \texttt{usage} instead of \texttt{main}. -% \begin{macrocode} -\def\SpecialUsageIndex#1{\@bsphack - {\let\special@index\index\SpecialIndex@{#1}{\encapchar usage}}% - \@esphack} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% -% -% -% -% \begin{macro}{\SpecialEnvIndex} -% Indexing environments is done a little bit differently; we produce -% two index entries with the |\SpecialEnvIndex| macro: -% \changes{v1.9e}{1994/02/03}{The index needs protecting} -% \changes{v1.9g}{1994/02/08}{should have used \cs{noexpand}, sigh} -% \changes{v1.9i}{1994/02/11}{should have used \cs{protect}} -% \begin{macrocode} -\def\SpecialEnvIndex#1{\@bsphack -% \end{macrocode} -% First we sort the environment under its own name stating in the -% actual entry that this is an environment. -% \begin{macrocode} - \index{#1\actualchar{\protect\ttfamily#1} - (environment)\encapchar usage}% -% \end{macrocode} -% The second entry is sorted as a subitem under the key -% `environments:'. -% \changes{v2.1b}{2004/02/09}{environment names incorrectly sorted in -% index (pr/3615)} -% \begin{macrocode} - \index{environments:\levelchar#1\actualchar - {\protect\ttfamily#1}\encapchar usage}\@esphack} -% \end{macrocode} -% Because both entries correspond to `descriptions' of the -% environment, we encapsulate the page numbers with the -% |\usage| macro. % \end{macro} % % % -% \begin{macro}{\SortIndex} +% \begin{imacro}{\SortIndex} % This macro is used to generate the index entries for any % single-character command that |\scan@macro| encounters. The % first parameter specifies the lexical order for the character, @@ -3417,76 +3992,87 @@ % the entry. It can also be used directly to generate index entries % which differ in sort key and actual entry. % \begin{macrocode} -\def\SortIndex#1#2{\index{#1\actualchar#2}} +\def\SortIndex#1#2{% + \ifdoc@noindex\else + \index{#1\actualchar#2}% + \fi +} % \end{macrocode} -% \end{macro} +% \end{imacro} % % % -% \begin{macro}{\it@is@a} -% This macro is supposed to produce a correct |\SortIndex| -% entry for a given character. Since this character might be -% recognised as a `command' character by the index program used, -% all characters are quoted with the |\quotechar|. -% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} -% \begin{macrocode} -\def\it@is@a#1{\special@index{\quotechar #1\actualchar - \string\verb\quotechar*\verbatimchar - \quotechar\bslash\quotechar#1\verbatimchar}} -% \end{macrocode} -% \end{macro} -% % -% -% \begin{macro}{\LeftBraceIndex} +% \begin{imacro}{\LeftBraceIndex} % \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} -% \begin{macro}{\RightBraceIndex} +% \begin{imacro}{\RightBraceIndex} % \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} These -% two macros fix the problems with \textsf{makeindex}. Note the +% two macros fix the problems with \prg{makeindex}. Note the % `hack' with |\iffalse}\fi| to satisfy both \TeX{} and the -% \textsf{makeindex} program. When this is written to the +% \prg{makeindex} program. When this is written to the % \texttt{.idx} file \TeX{} will see both braces (so we get a -% balanced text). \textsf{makeindex} will also see balanced braces +% balanced text). \prg{makeindex} will also see balanced braces % but when the actual index entry is again processed by \TeX{} the % brace in between |\iffalse| |\fi| will vanish. % \begin{macrocode} \@ifundefined{LeftBraceIndex}{\def\LeftBraceIndex{% - \special@index{\bgroup\actualchar\string\verb\quotechar*\verbatimchar - \quotechar\bslash{\verbatimchar\string\iffalse}\string\fi}}}{} + \special@index{\bgroup\actualchar + \string\verb% % to fool emacs highlighting + \quotechar*\verbatimchar + \quotechar\bslash{\verbatimchar\string\iffalse}\string\fi}}}{} \@ifundefined{RightBraceIndex}{\def\RightBraceIndex{% - \special@index{\egroup\actualchar\string\iffalse{\string\fi\string\verb + \special@index{\egroup\actualchar\string\iffalse{\string\fi + \string\verb% % to fool emacs highlighting \quotechar*\verbatimchar\quotechar\bslash}\verbatimchar}}}{} % \end{macrocode} -% \end{macro} -% \end{macro} +% \end{imacro} +% \end{imacro} % % -% \begin{macro}{\PercentIndex} +% \begin{imacro}{\PercentIndex} % \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} % \changes{v1.7c}{1992/03/25}{Default now for bug-fixed makeindex} -% By default we assume a version of \textsf{makeindex} without the +% By default we assume a version of \prg{makeindex} without the % percent bug is being used. % \begin{macrocode} \@ifundefined{PercentIndex} {\def\PercentIndex{\it@is@a\percentchar}}{} % \end{macrocode} -% \end{macro} -% \begin{macro}{\OldMakeindex} +% \end{imacro} +% +% +% \begin{omacro}{\OldMakeindex} % \changes{v1.7c}{1992/03/26}{Replaced \cs{NewMakeIndex}.} -% \begin{macro}{\percentchar} -% Here is one solution for the percent bug in \textsf{makeindex}. +% \begin{imacro}{\percentchar} +% Here is one solution for the percent bug in \prg{makeindex}. % The macro |\percentchar| denotes a |%|$_{12}$. Calling this from % a package or the driver file sets things up % appropriately.\label{bug:fixes} % \begin{macrocode} \def\OldMakeindex{\def\PercentIndex{% - \special@index{\quotechar\percentchar\actualchar\string\verb + \special@index{\quotechar\percentchar\actualchar + \string\verb% % to fool emacs highlighting \quotechar*\verbatimchar\quotechar\bslash \percentchar\percentchar\verbatimchar}}} {\catcode`\%=12 \gdef\percentchar{%}} % \end{macrocode} -% \end{macro} +% \end{imacro} +% \end{omacro} +% +% +% \begin{macro}{\it@is@a} +% This macro is supposed to produce a correct |\SortIndex| +% entry for a given character. Since this character might be +% recognized as a `command' character by the index program used, +% all characters are quoted with the |\quotechar|. +% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} +% \begin{macrocode} +\def\it@is@a#1{\special@index{\quotechar #1\actualchar + \string\verb% % to fool emacs highlighting + \quotechar*\verbatimchar + \quotechar\bslash\quotechar#1\verbatimchar}} +% \end{macrocode} % \end{macro} % % @@ -3494,7 +4080,7 @@ % % % -% \subsection{Redefining the \textsf{index} environment} +% \subsection{Redefining the \env{index} environment} % %\changes{v1.4r}{1989/04/22}{twocols env. placed into separate file} %\changes{v1.4?}{1989/04/19}{use DEK's algorithm and implement @@ -3502,34 +4088,10 @@ %\changes{v1.4?}{1989/04/16}{changes to the index env.} %\changes{v1.5a}{1989/04/26}{Now input multicol.sty instead of % multcols.sty} -% \begin{macro}{\ifhave@multicol} -% \changes{v1.7a}{1992/03/04}{Added to support avoiding multicol.sty} By -% default the index is set in three columns, and will start on the -% same page as, and underneath, the last part of the text of the -% documented package file, if possible. The last page will be -% reformatted with balanced columns. This requires the -% \textsf{multicols} environment which is described elsewhere. So -% that \DOC{} can be run independently of -% \texttt{multicol.sty} we first check for its existence and set -% the "have@multicol" flag appropriately for use below. -% \changes{v1.9a}{1993/12/02}{Use \cs{IfFileExists}} -% \changes{v1.9m}{1994/04/28}{Use \cs{RequirePackage} to load multicol} -% \begin{macrocode} -\newif\ifhave@multicol -% \end{macrocode} -% If we found \texttt{multicol.sty} we use it. It would be nice to -% delay this (and the re-definition of "theindex") until we knew -% whether an index was actually required \ldots -% \begin{macrocode} -\IfFileExists{multicol.sty}{\have@multicoltrue - \RequirePackage{multicol}% - }{} -% \end{macrocode} -% \end{macro} % -% \begin{macro}{\IndexMin} -% \begin{macro}{\c@IndexColumns} +% \begin{ldimen}{\IndexMin} +% \begin{lcounter}{IndexColumns} % \changes{v1.4t}{1989/04/24}{Counter added.} % If \texttt{multicol} is in use, % when the index is started we compute the remaining space on the @@ -3542,8 +4104,9 @@ \newdimen\IndexMin \IndexMin = 80pt \newcount\c@IndexColumns \c@IndexColumns = 3 % \end{macrocode} -% \end{macro} -% \end{macro} +% \end{lcounter} +% \end{ldimen} +% % % % \begin{environment}{theindex} @@ -3557,7 +4120,14 @@ % \changes{v1.6e}{1991/04/03}{Turned into env definition.} % \changes{v1.7a}{1992/03/04}{Include test for multicols.} % \begin{macrocode} -\ifhave@multicol +\ifdoc@multicol +% \end{macrocode} +% +% \begin{macrocode} + \RequirePackage{multicol} +% \end{macrocode} +% +% \begin{macrocode} \renewenvironment{theindex} {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]% % \end{macrocode} @@ -3570,17 +4140,15 @@ % % \begin{macro}{\endtheindex} % \changes{v1.4t}{1989/04/24}{Incorporated new multicols env.} -% At the end of the index, we have only to end the \textsf{multicols} +% At the end of the index, we have only to end the \env{multicols} % environment. % \begin{macrocode} {\end{multicols}} % \end{macrocode} -% If we can't use \textsf{multicols} we warn the user and use an +% If we can't use \env{multicols} we warn the user and use an % environment that's basically the one from \texttt{article.sty}. % \begin{macrocode} \else - \typeout{Can't find multicol.sty -- will use normal index layout if - necessary.} \def\theindex{\@restonecoltrue\if@twocolumn\@restonecolfalse\fi \columnseprule \z@ \columnsep 35\p@ \twocolumn[\index@prologue]% @@ -3591,8 +4159,8 @@ % \end{macro} % \end{environment} % -% Here are the necessary \textsf{makeindex} declarations. We disable -% scanning of macro names inside the index with "\scan@allowedfalse\n" +% Here are the necessary \prg{makeindex} declarations. We disable +% scanning of macro names inside the index with |\scan@allowedfalse\n| % to avoid recursion. % \begin{macrocode} %</package> @@ -3604,7 +4172,7 @@ % \end{macrocode} % % -% \begin{macro}{\IndexPrologue} +% \begin{imacro}{\IndexPrologue} % \begin{macro}{\index@prologue} % \changes{v1.9w}{1995/12/27}{Text changed} % \changes{v1.9x}{1996/01/11}{Text depends on code lines used} @@ -3639,11 +4207,11 @@ }}{} % \end{macrocode} % \end{macro} -% \end{macro} +% \end{imacro} % % % -% \begin{macro}{\IndexParms} +% \begin{imacro}{\IndexParms} % These are some last-minute assignments for formatting the index % entries. They are defined in a separate macro so that a user can % substitute different definitions. We start by defining the @@ -3678,7 +4246,7 @@ \def\subsubitem{\@idxitem\hspace*{25pt}}% % \end{macrocode} % \begin{macro}{\indexspace} -% The \textsf{makeindex} program generates an |\indexspace| +% The \prg{makeindex} program generates an |\indexspace| % before each new alphabetic section commences. After this final % definition we end the |\@ifundefined| and the definition of % |\IndexParms|. @@ -3690,10 +4258,10 @@ % \end{macro} % \end{macro} % \end{macro} -% \end{macro} +% \end{imacro} % % -% \begin{macro}{\efill} +% \begin{imacro}{\efill} % This definition of |\efill| is intended to be used after index % items which have no following text (for example, ``\textit{ % see\/}'' entries). It just ensures that the current line is @@ -3706,104 +4274,96 @@ %<+gind>item_x2 "\\efill \n \\subsubitem " %<*package> % \end{macrocode} -% \end{macro} +% \end{imacro} % % % -% \begin{macro}{\pfill} -% \begin{macro}{\dotfil} -% \begin{macro}{\dotfill} +% \begin{imacro}{\pfill} % The following definitions provide the |\pfill| command; if -% this is specified in the index style file to \textsf{makeindex} as +% this is specified in the index style file to \prg{makeindex} as % the delimiter to appear after index items, then the intervening % space before the referenced page numbers will be filled with % dots, with a little white space interpolated at each end of the % dots. If the line is broken the dots will show up on both lines. -% \changes{v2.1i}{2018/09/25}{Guard against following \cs{unskip} (git/23)} % \begin{macrocode} -\def\dotfill{\leaders\hbox to.6em{\hss .\hss}\hskip\z@ plus 1fill\kern\z@}% -\def\dotfil{\leaders\hbox to.6em{\hss .\hss}\hfil\kern\z@}% -\def\pfill{\unskip~\dotfill\penalty500\strut\nobreak - \dotfil~\ignorespaces}% +\def\pfill{\unskip~% + \leaders\hbox to.6em{\hss .\hss}\hfill + \penalty500\strut\nobreak + \leaders\hbox to.6em{\hss .\hss}\hfil + ~\ignorespaces}% %</package> %<+gind|gglo>delim_0 "\\pfill " %<+gind|gglo>delim_1 "\\pfill " %<+gind|gglo>delim_2 "\\pfill " %<*package> % \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} +% \end{imacro} % % % -% \begin{macro}{\*} +% \begin{imacro}{\*} % Here is the definition for the |\*| macro. It isn't used in % this set of macros. % \begin{macrocode} \def\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}} % \end{macrocode} -% \end{macro} +% \end{imacro} % % -% \begin{macro}{\main} +% \begin{imacro}{\main} % The \textit{defining\/} entry for a macro name is flagged with % the string \texttt{\encapchar main}\footnote{With the current % definition of \texttt{\bslash encapchar} substituted for -% \texttt{\encapchar}} in the |\index| command; \textsf{makeindex} +% \texttt{\encapchar}} in the |\index| command; \prg{makeindex} % processes this so that the |\main| macro will be invoked to % underline the page number(s) on which the {\em definition\/} of % the macro will be found. % \begin{macrocode} \@ifundefined{main}{\def\main#1{\underline{#1}}}{} % \end{macrocode} -% \end{macro} +% \end{imacro} % -% \begin{macro}{\usage} +% \begin{imacro}{\usage} % The |\usage| macro is used to indicate entries describing % the usage of a macro. The corresponding page number(s) will be % set in \textit{italics}. % \begin{macrocode} \@ifundefined{usage}{\def\usage#1{\textit{#1}}}{} % \end{macrocode} -% \end{macro} +% \end{imacro} % +% \begin{imacro}{\code} +% The |\code| macro is used to indicate index entries to code lines +% that aren't main entries. +% By default we do nothing special with them +% the usage of a macro. +% \begin{macrocode} +\@ifundefined{code}{\def\code#1{#1}}{} +% \end{macrocode} +% \end{imacro} % -% \begin{macro}{\PrintIndex} +% +% \begin{imacro}{\PrintIndex} % \changes{v1.5k}{1989/09/04}{\cs{printindex} changed to % \cs{PrintIndex}} % \changes{v1.7a}{1992/02/26}{Documentation moved to interface section.} % \changes{v1.9h}{1994/02/10}{Use \cs{@input@} instead of \cs{@input}.} % \changes{v1.9w}{1995/12/29}{Turn the cmd into a noop after use.} -% This is the same as "\printindex" in the \textsf{makeidx} package. +% This is the same as |\printindex| in the \pkg{makeidx} package. % \begin{macrocode} \def\PrintIndex{\@input@{\jobname.ind}% \global\let\PrintIndex\@empty} % \end{macrocode} -% \end{macro} +% \end{imacro} % -% \begin{macro}{\printindex} -% Since the above macro was called |\printindex| in older versions -% of \texttt{doc.sty} the following definition was provided up to -% version 1.9y. -% \changes{v1.9z}{1996/04/17}{Commented out} -% \begin{macrocode} -%\def\printindex{\typeout{\string\printindex\space is obsolete!}% -% \typeout{Please use \string\PrintIndex\space -% if you are a macro implementor^^J -% or get a newer version of the documented -% software if you are a user}% -% \PrintIndex} -% \end{macrocode} -% \end{macro} % % We want headings in the index (and changes list) according to the % initial character of the next block of entries and have to instruct -% \textsf{makeindex} appropriately. Unfortunately the specification +% \prg{makeindex} appropriately. Unfortunately the specification % for this changed sometime between versions 2.4 and 2.11 of -% \textsf{makeindex}. We provide both ways of doing it but +% \prg{makeindex}. We provide both ways of doing it but % unfortunately this will always produce a warning message from -% \textsf{makeindex}. This is for older versions: +% \prg{makeindex}. This is for older versions: % \changes{v1.7h}{1992/07/01}{Turn off headings in gls file} % \begin{macrocode} %</package> @@ -3839,13 +4399,13 @@ % is otherwise ignored, but the others are written out and may be used % to generate a history of changes, to be printed at the end of the % document. However, note that older versions of Chen's standard -% \textsf{makeindex} +% \prg{makeindex} % program limit any textual field to just 64 characters; therefore, % is important that the number of characters in the second and third % parameters should not exceed 61 altogether (to allow for the % parentheses placed around the date). % -% \begin{macro}{\changes} +% \begin{imacro}{\changes} % \changes{BHK}{1989/04/26}{Documented \texttt{\protect\bslash changes} % command.} % \changes{BHK}{1989/04/26}{Changed definition of @@ -3855,9 +4415,9 @@ % change in \LaTeX{} 2.09 changed the command name in the % \texttt{.glo} file from \texttt{\bslash indexentry} to % \texttt{\bslash glossaryentry}. It is therefore necessary to -% have a special \textsf{makeindex} style file called +% have a special \prg{makeindex} style file called % \texttt{gglo.ist} to process this file correctly.} Thus -% \textsf{makeindex} or a similar program can be used to process +% \prg{makeindex} or a similar program can be used to process % the output into a sorted ``glossary''. The |\changes| command % commences by taking the usual measures to hide its spacing, and % then redefines |\protect| for use within the argument of the @@ -3880,42 +4440,57 @@ \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore \changes@} \def\changes@#1#2#3{% - \protected@edef\@tempa{\noexpand\glossary{#1\levelchar + \protected@edef\@tempa{\noexpand\glossary{#1% +% \end{macrocode} +% If asked for we also show the date of in the change log (after +% the version). +% \changes{v3.0g}{2022/06/01}{Show change dates if asked for (gh/531)} +% \begin{macrocode} + \ifdoc@reportchangedates + \space -- #2\fi + \levelchar % \end{macrocode} % \changes{v1.9u}{1995/08/06}{Use value of \cs{saved@macroname} to % find out about change entries at outer level} -% If the macro "\saved@macroname" doesn't contain any macro name +% If the macro |\saved@macroname| doesn't contain any macro name % (ie is empty) the current changes entry was done at top-level. -% In this case we precede it by "\generalname". +% In this case we precede it by |\generalname|. % \begin{macrocode} - \ifx\saved@macroname\@empty - \space - \actualchar - \generalname - \else + \ifx\saved@macroname\@empty +% \end{macrocode} +% Putting a |!| at the beginning of the entry hopefully moves this +% entry to the very beginning during sorting. +% \begin{macrocode} + \quotechar!% + \actualchar + \generalname + \else % \end{macrocode} % \changes{v2.1g}{2016/02/15}{Use \cs{saved@indexname}} % \begin{macrocode} - \saved@indexname - \actualchar - \string\verb\quotechar*% - \verbatimchar\saved@macroname - \verbatimchar - \fi - :\levelchar #3}}% + \saved@indexname + \actualchar + \string\verb% % to fool emacs highlighting + \quotechar*% + \verbatimchar\saved@macroname + \verbatimchar + \fi + :\levelchar #3}}% \@tempa\endgroup\@esphack} % \end{macrocode} +% \end{imacro} +% % % \begin{macro}{\saved@macroname} -% \changes{BHK}{1989/04/26}{Provided for sorting outside \textsf{macro} +% \changes{BHK}{1989/04/26}{Provided for sorting outside \env{macro} % environment} The entries are sorted for convenience by the name % of the most recently introduced macroname (i.e., that in the most % recent |\begin{macro}| command). We therefore provide % |\saved@macroname| to record that argument, and provide a default -% definition in case |\changes| is used outside a \textsf{macro} +% definition in case |\changes| is used outside a \env{macro} % environment. (This is a {\em wicked\/} hack to get such entries % at the beginning of the sorted list! It works providing no macro -% names start with "!" or |"|.) \changes{v1.7a}{1992/03/02}{Changed +% names start with |!| or |"|.) \changes{v1.7a}{1992/03/02}{Changed % string used for better sorting.} % \changes{v1.9u}{1995/08/06}{Now empty by default} % \begin{macrocode} @@ -3932,17 +4507,17 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\generalname} +% \begin{imacro}{\generalname} % \changes{v1.9u}{1995/08/06}{Macro added} % This macro holds the string placed before changes entries on % top-level. % \begin{macrocode} \def\generalname{General} % \end{macrocode} -% \end{macro} +% \end{imacro} % % -% \begin{macro}{\RecordChanges} +% \begin{imacro}{\RecordChanges} % \changes{BHK}{1989/04/26}{Renames former \texttt{\protect\bslash % PrintChanges} command.} % To cause the changes to be written (to a \texttt{.glo}) file, we @@ -3951,17 +4526,16 @@ % \begin{macrocode} \let\RecordChanges\makeglossary % \end{macrocode} -% \end{macro} -% \end{macro} +% \end{imacro} % % -% \begin{macro}{\GlossaryMin} +% \begin{ldimen}{\GlossaryMin} % \changes{BHK}{1989/04/26}{Added to support % \texttt{\protect\bslash changes}.} -% \begin{macro}{\c@GlossaryColumns} +% \begin{lcounter}{GlossaryColumns} % \changes{BHK}{1989/04/26}{Added to support \texttt{\protect\bslash % changes}.} The remaining macros are all analogues of those used -% for the \textsf{theindex} environment. When the glossary is +% for the \env{theindex} environment. When the glossary is % started we compute the space which remains at the bottom of the % current page; if this is greater than |\GlossaryMin| then the % first part of the glossary will be placed in the available space. @@ -3972,8 +4546,8 @@ \newdimen\GlossaryMin \GlossaryMin = 80pt \newcount\c@GlossaryColumns \c@GlossaryColumns = 2 % \end{macrocode} -% \end{macro} -% \end{macro} +% \end{lcounter} +% \end{ldimen} % % % \begin{environment}{theglossary} @@ -3983,13 +4557,12 @@ % \changes{v1.6e}{1991/04/03}{Turned into env definition.} % \changes{v1.7a}{1992/03/10}{Changed to work without multicols if % necessary.} -% \begin{macro}{\endglossary} % \changes{BHK}{1989/04/26}{Added to support % \texttt{\protect\bslash changes}.} -% The environment \textsf{theglossary} is defined in the same manner -% as the \textsf{theindex} environment. +% The environment \env{theglossary} is defined in the same manner +% as the \env{theindex} environment. % \begin{macrocode} -\ifhave@multicol +\ifdoc@multicol \newenvironment{theglossary}{% \begin{multicols}\c@GlossaryColumns [\glossary@prologue][\GlossaryMin]% @@ -4004,10 +4577,9 @@ {\if@restonecol\onecolumn\else\clearpage\fi} \fi % \end{macrocode} -% \end{macro} % \end{environment} % -% Here are the necessary \textsf{makeindex} declarations with scanning +% Here are the necessary \prg{makeindex} declarations with scanning % disabled as for the index. % \begin{macrocode} %</package> @@ -4025,7 +4597,7 @@ % \end{macrocode} % % -% \begin{macro}{\GlossaryPrologue} +% \begin{imacro}{\GlossaryPrologue} % \changes{BHK}{1989/04/26}{Added to support % \texttt{\protect\bslash changes}.} % \begin{macro}{\glossary@prologue} @@ -4050,9 +4622,9 @@ }}{} % \end{macrocode} % \end{macro} -% \end{macro} +% \end{imacro} % -% \begin{macro}{\GlossaryParms} +% \begin{imacro}{\GlossaryParms} % \changes{BHK}{1989/04/26}{Added to support % \texttt{\protect\bslash changes}.} % Unless the user specifies otherwise, we set the change history @@ -4067,19 +4639,20 @@ \parfillskip -15pt plus -1fil\relax} }{} % \end{macrocode} -% \end{macro} -% \begin{macro}{\PrintChanges} +% \end{imacro} +% +% \begin{imacro}{\PrintChanges} % \changes{BHK}{1989/04/26}{Added to support % \texttt{\protect\bslash changes}.} % To read in and print the sorted change history, just put the % |\PrintChanges| command as the last (commented-out, and thus % executed during the documentation pass through the file) command % in your package file. Alternatively, this command may form one of -% the arguments of the |\StopEventually| command, although a +% the arguments of the |\MaybeStop| command, although a % change history is probably {\em not\/} required if only the % description is being printed. % -% The command assumes that \textsf{makeindex} or some other program +% The command assumes that \prg{makeindex} or some other program % has processed the \texttt{.glo} file to generate a sorted % \texttt{.gls} file. % \changes{v1.9h}{1994/02/10}{Use \cs{@input@} instead of \cs{@input}.} @@ -4088,7 +4661,7 @@ \def\PrintChanges{\@input@{\jobname.gls}% \global\let\PrintChanges\@empty} % \end{macrocode} -% \end{macro} +% \end{imacro} % % % @@ -4096,25 +4669,25 @@ % % \subsection{Bells and whistles} % -% \begin{macro}{\StopEventually} +% \begin{imacro}{\MaybeStop} % \changes{v1.5k}{1989/09/04}{Support for checksum.} -% \begin{macro}{\Finale} +% \begin{imacro}{\Finale} % \changes{v1.5k}{1989/09/04}{Support for checksum.} % \changes{v1.5z}{1990/04/22}{Define \cs{Finale} globally.} -% \begin{macro}{\AlsoImplementation} +% \begin{imacro}{\AlsoImplementation} % \changes{v1.9w}{1995/12/27}{Macro added} -% \begin{macro}{\OnlyDescription} +% \begin{imacro}{\OnlyDescription} % If |\AlsoImplementation| is in force the whole documentation % including the code part will be typeset. This is the default. % \begin{macrocode} \newcommand\AlsoImplementation{% % \end{macrocode} % To make this happen we have to define -% |\StopEventually| in a way that its argument is typeset at the +% |\MaybeStop| in a way that its argument is typeset at the % very end or more exactly at |\Finale|. For this we % save its argument in the macro |\Finale|. % \begin{macrocode} - \long\def\StopEventually##1{\@bsphack\gdef\Finale{##1% + \long\def\MaybeStop##1{\@bsphack\gdef\Finale{##1% % \end{macrocode} % But |\Finale| will be called at the very end of a file. This % is exactly the point were we want to know if the file is @@ -4123,7 +4696,7 @@ % \begin{macrocode} \check@checksum}% % \end{macrocode} -% On the other hand: |\StopEventually| is more or less a +% On the other hand: |\MaybeStop| is more or less a % dividing point between description and code. So we start to look % for the check-sum of the documented file by calling % |\init@checksum|. @@ -4134,35 +4707,44 @@ % \end{macrocode} % % Since |\AlsoImplementation| should be the default we execute it -% and thus |\StopEventually| gets the desired meaning. +% and thus |\MaybeStop| gets the desired meaning. % \begin{macrocode} \AlsoImplementation % \end{macrocode} % When the user places an |\OnlyDescription| declaration in % the driver file the document should only be typeset up to -% |\StopEventually|. We therefore have to redefine this macro. +% |\MaybeStop|. We therefore have to redefine this macro. % \begin{macrocode} -\def\OnlyDescription{\@bsphack\long\def\StopEventually##1{% +\def\OnlyDescription{\@bsphack\long\def\MaybeStop##1{% % \end{macrocode} -% In this case the argument of |\StopEventually| should be set +% In this case the argument of |\MaybeStop| should be set % and afterwards \TeX{} should stop reading from this file. % Therefore we finish this macro with % \begin{macrocode} ##1\endinput}\@esphack} % \end{macrocode} -% If no |\StopEventually| command is given we silently ignore a +% If no |\MaybeStop| command is given we silently ignore a % |\Finale| issued. % \changes{v1.9n}{1994/04/28}{Ignore \cs{Finale} if no -% \cs{StopEventually} is given} +% \cs{MaybeStop} is given} % \begin{macrocode} \let\Finale\relax % \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} +% \end{imacro} +% \end{imacro} +% \end{imacro} +% \end{imacro} +% % -% \begin{macro}{\meta} +% \begin{omacro}{\StopEventually} +% The old wrong name for |\MaybeStop|. We need to use |\def| +% (i.e., expansion) as |\MaybeStop| gets redefined once in a while. +% \begin{macrocode} +\def\StopEventually{\MaybeStop} +% \end{macrocode} +% \end{omacro} +% +% \begin{imacro}{\meta} % \changes{v1.4t}{1989/04/24}{Macro added.} % \changes{v1.5w}{1990/02/03}{Breaks at space allowed.} % \changes{v1.6a}{1990/05/24}{Extra space bug corrected.} @@ -4216,7 +4798,7 @@ }\ensuremath\rangle } % \end{macrocode} -% \end{macro} +% \end{imacro} % % % \begin{macro}{\meta@font@select} @@ -4228,7 +4810,7 @@ % \end{macro} % % -% \begin{macro}{\IndexInput} +% \begin{imacro}{\IndexInput} % This next macro may be used to read in a separate file (possibly % a package file that is {\em not\/} documented by this means) and % set it verbatim, whilst scanning for macro names and indexing the @@ -4243,7 +4825,7 @@ % \begin{macrocode} \begingroup \macro@code % \end{macrocode} -% We also make spacing behave as in the \textsf{macrocode} +% We also make spacing behave as in the \env{macrocode} % environment, because otherwise all the spaces will be shown % explicitly. % \begin{macrocode} @@ -4260,10 +4842,10 @@ % \begin{macrocode} \endgroup} % \end{macrocode} -% \end{macro} +% \end{imacro} % % -% \begin{macro}{\maketitle} +% \begin{imacro}{\maketitle} % The macro to generate titles is easily altered in order that it % can be used more than once (an article with many titles). In the % original, diverse macros were concealed after use with @@ -4299,56 +4881,56 @@ \gdef\@date{\today}\gdef\@thanks{}% \gdef\@author{}\gdef\@title{}} % \end{macrocode} -% \end{macro} +% \end{imacro} % % -% \begin{macro}{\ps@titlepage} +% \begin{imacro}{\ps@titlepage} % \changes{v1.5k}{1989/09/04}{Added \texttt{\protect\bslash % ps@titlepage}} When a number of articles are concatenated into a % journal, for example, it is not usual for the title pages of such % documents to be formatted differently. Therefore, a class -% such as \textsf{ltugboat} can define this macro in advance. +% such as \cls{ltugboat} can define this macro in advance. % However, if no such definition exists, we use pagestyle % \texttt{plain} for title pages. % \begin{macrocode} \@ifundefined{ps@titlepage} {\let\ps@titlepage=\ps@plain}{} % \end{macrocode} -% \end{macro} +% \end{imacro} % -% \begin{macro}{\MakeShortVerb} +% \begin{imacro}{\MakeShortVerb} % \changes{v1.7a}{1992/02/27}{Added (from newdoc but now alters % \cs{dospecials}, \cs{@sanitize}).} -% This arranges an abbreviation for "\verb" such that if you say -% "\MakeShortVerb{\"\meta{c}"}" subsequently using +% This arranges an abbreviation for |\verb| such that if you say +% |\MakeShortVerb{\|\meta{c}|}| subsequently using % \meta{c}\meta{text}\meta{c} is equivalent to -% "\verb"\meta{c}\meta{text}\meta{c}.\footnote{Warning: +% |\verb|\meta{c}\meta{text}\meta{c}.\footnote{Warning: % the commentary in the rest of this section was written by Dave % Love.} In addition, the fact % that \meta{c} is made active is recorded for the benefit of the -% \textsf{verbatim} and \textsf{macrocode} environments. +% \env{verbatim} and \env{macrocode} environments. % Note particularly that the definitions below are global. % The first thing we do (it needn't be first) is to record -% the---presumably new---special character in "\dospecials" and -% "\@sanitize" using "\add@special". +% the---presumably new---special character in |\dospecials| and +% |\@sanitize| using |\add@special|. % % \changes{v1.9e.2}{1994/02/07}{-js: Check if \protect\meta{c} is % already an % abbreviation for \cs{verb}.} -% Some unwary user might issue "\MakeShortVerb" for a second time, we +% Some unwary user might issue |\MakeShortVerb| for a second time, we % better protect against this. We assume that this happened if a -% control sequence "\cc\"\meta{c} is bound, the probability that this +% control sequence |\cc\|\meta{c} is bound, the probability that this % name is used by another module is low. We will output a warning % below, so that a possible error might be noticed by the programmer -% if he reads the "LOG" file. (Should have used module internal names, +% if he reads the |LOG| file. (Should have used module internal names, % 'though.) % -% \begin{macro}{\MakeShortVerb*} +% \begin{imacro}{\MakeShortVerb*} % \changes{v2.1a}{2003/12/09}{(HjG) Added \texttt{*} form} -% This arranges an abbreviation for "\verb*" such that if you say -% "\MakeShortVerb*{\"\meta{c}"}" subsequently using +% This arranges an abbreviation for |\verb*| such that if you say +% |\MakeShortVerb*{\|\meta{c}|}| subsequently using % \meta{c}\meta{text}\meta{c} is equivalent to -% "\verb*"\meta{c}\meta{text}\meta{c}. +% |\verb*|\meta{c}\meta{text}\meta{c}. % \begin{macrocode} %</package> %<*package|shortvrb> @@ -4357,7 +4939,10 @@ {\def\@shortvrbdef{\verb*}\@MakeShortVerb}% {\def\@shortvrbdef{\verb}\@MakeShortVerb}} % \end{macrocode} -% \end{macro} +% \end{imacro} +% \end{imacro} +% +% \begin{macro}{\@MakeShortVerb} % \begin{macrocode} \def\@MakeShortVerb#1{% \expandafter\ifx\csname cc\string#1\endcsname\relax @@ -4367,19 +4952,19 @@ \@shortvrbinfo{Made }{#1}\@shortvrbdef \add@special{#1}% % \end{macrocode} -% Then the character's current catcode is stored in "\cc\"\meta{c}. +% Then the character's current catcode is stored in |\cc\|\meta{c}. % \begin{macrocode} \expandafter \xdef\csname cc\string#1\endcsname{\the\catcode`#1}% % \end{macrocode} % The character is spliced into the definition using the same trick as -% used in "\verb" (for instance), having activated "~" in a group. +% used in |\verb| (for instance), having activated |~| in a group. % \begin{macrocode} \begingroup \catcode`\~\active \lccode`\~`#1% \lowercase{% % \end{macrocode} -% The character's old meaning is recorded in "\ac\"\meta{c} prior to +% The character's old meaning is recorded in |\ac\|\meta{c} prior to % assigning it a new one. % \begin{macrocode} \global\expandafter\let @@ -4398,20 +4983,24 @@ % \end{macrocode} % \changes{v1.9v}{1995/11/03}{(DPC) Use \cs{@shortvrbinfo}} % \begin{macrocode} - \@shortvrbinfo\@empty{#1 already}{\@empty\verb(*)}% + \@shortvrbinfo\@empty{#1 already}% + {\@empty\verb% % to fool emacs highlighting + (*)}% \fi} % \end{macrocode} % \end{macro} -% \begin{macro}{\DeleteShortVerb} +% +% +% \begin{imacro}{\DeleteShortVerb} % \changes{v1.7a}{1992/02/27}{Added (from newdoc but now alters % \cs{dospecials}, \cs{@sanitize}).} -% Here's the means of undoing a "\MakeShortVerb", for instance in a +% Here's the means of undoing a |\MakeShortVerb|, for instance in a % region where you need to use the character outside a verbatim -% environment. It arranges for "\dospecials" and "\@sanitize" to be +% environment. It arranges for |\dospecials| and |\@sanitize| to be % altered appropriately, restores the saved catcode and, if necessary, % the character's meaning (as stored by -% "\MakeShortVerb"). If the catcode wasn't stored in -% "\cc\"\meta{c} (by "\MakeShortVerb") the command is silently +% |\MakeShortVerb|). If the catcode wasn't stored in +% |\cc\|\meta{c} (by |\MakeShortVerb|) the command is silently % ignored. % \changes{v1.7a}{1992/02/28}{Check for previous matched % \cs{MakeShortVerb} @@ -4423,19 +5012,24 @@ % \changes{v2.1a}{2003/12/10}{(HjG) Notify user % if it's not a short verb character} % \begin{macrocode} - \@shortvrbinfo\@empty{#1 not}{\@empty\verb(*)}% + \@shortvrbinfo\@empty{#1 not}% + {\@empty\verb% % to fool emacs highlighting + (*)}% \else % \end{macrocode} % \changes{v1.9v}{1995/11/03}{(DPC) Use \cs{@shortvrbinfo}} % \begin{macrocode} - \@shortvrbinfo{Deleted }{#1 as}{\@empty\verb(*)}% + \@shortvrbinfo{Deleted }{#1 as}% + {\@empty\verb% % to fool emacs + % highlighting + (*)}% \rem@special{#1}% \global\catcode`#1\csname cc\string#1\endcsname % \end{macrocode} % \changes{v1.9e.2}{1994/02/07}{-js: Reset `cc`\protect\meta{c} in -% \cs{DeleteShortVerb}} -% We must not forget to reset "\cc\"\meta{c}, otherwise the check in -% "\MakeShortVerb" for a repeated definition will not work. +% in \cs{DeleteShortVerb}} +% We must not forget to reset |\cc\|\meta{c}, otherwise the check in +% |\MakeShortVerb| for a repeated definition will not work. % \begin{macrocode} \global \expandafter\let \csname cc\string#1\endcsname \relax \ifnum\catcode`#1=\active @@ -4446,7 +5040,7 @@ \csname ac\string#1\endcsname}% \endgroup \fi \fi} % \end{macrocode} -% \end{macro} +% \end{imacro} % % \begin{macro}{\@shortvrbinfo} % \changes{v1.9v}{1995/11/03}{(DPC) Macro added} @@ -4465,12 +5059,12 @@ % \begin{macro}{\add@special} % \changes{v1.7a}{1992/02/27}{Added for short verb facility.} % This helper macro adds its argument to the -% "\dospecials" macro which is conventionally used by verbatim macros +% |\dospecials| macro which is conventionally used by verbatim macros % to alter the catcodes of the currently active characters. We need -% to add "\do\"\meta{c} to the expansion of "\dospecials" after +% to add |\do\|\meta{c} to the expansion of |\dospecials| after % removing the character if it was already there to avoid multiple -% copies building up should "\MakeShortVerb" not be balanced by -% "\DeleteShortVerb" (in case anything that uses "\dospecials" cares +% copies building up should |\MakeShortVerb| not be balanced by +% |\DeleteShortVerb| (in case anything that uses |\dospecials| cares % about repetitions). % \begin{macrocode} \def\add@special#1{% @@ -4478,29 +5072,31 @@ \expandafter\gdef\expandafter\dospecials\expandafter {\dospecials \do #1}% % \end{macrocode} -% Similarly we have to add "\@makeother\"\meta{c} to "\@sanitize" -% (which is used in things like "\index" to re-catcode all special +% Similarly we have to add |\@makeother\|\meta{c} to |\@sanitize| +% (which is used in things like |\index| to re-catcode all special % characters except braces). % \begin{macrocode} \expandafter\gdef\expandafter\@sanitize\expandafter {\@sanitize \@makeother #1}} % \end{macrocode} % \end{macro} +% +% % \begin{macro}{\rem@special} % \changes{v1.7a}{1992/02/27}{Added for short verb facility.} -% The inverse of "\add@special" is slightly trickier. "\do" is +% The inverse of |\add@special| is slightly trickier. |\do| is % re-defined to expand to nothing if its argument is the character of % interest, otherwise to expand simply to the argument. We can then -% re-define "\dospecials" to be the expansion of itself. The space -% after "=`##1" prevents an expansion to "\relax"! +% re-define |\dospecials| to be the expansion of itself. The space +% after |=`##1| prevents an expansion to |\relax|! % \begin{macrocode} \def\rem@special#1{% \def\do##1{% \ifnum`#1=`##1 \else \noexpand\do\noexpand##1\fi}% \xdef\dospecials{\dospecials}% % \end{macrocode} -% Fixing "\@sanitize" is the same except that we need to re-define -% "\@makeother" which obviously needs to be done in a group. +% Fixing |\@sanitize| is the same except that we need to re-define +% |\@makeother| which obviously needs to be done in a group. % \begin{macrocode} \begingroup \def\@makeother##1{% @@ -4511,19 +5107,6 @@ %<*package> % \end{macrocode} % \end{macro} -% \begin{macro}{\MakeShortverb} -% \begin{macro}{\DeleteShortverb} -% \changes{v1.7a}{1992/02/27}{Added (from newdoc).} -% These commands from \textsf{newdoc} are now obsolete. -% \begin{macrocode} -\def\MakeShortverb{\typeout{*** Switch to \noexpand\MakeShortVerb - syntax, this is obsolete ***}\MakeShortVerb} -\def\DeleteShortverb{\typeout{*** Switch to \noexpand\DeleteShortVerb - syntax, this is obsolete ***}\DeleteShortVerb} -% \end{macrocode} -% \end{macro} -% \end{macro} -% % % % \subsection[Providing a checksum and character table] @@ -4535,7 +5118,7 @@ % \begin{macro}{\init@checksum} % The checksum mechanism works by counting backslashes in the % macrocode. This initializes the count (when called from -% "\StopEventually"). +% |\MaybeStop|). % \changes{v1.5k}{1989/09/04}{Macro added to support checksum.} % \begin{macrocode} \def\init@checksum{\relax @@ -4546,8 +5129,8 @@ % % \begin{macro}{\check@checksum} % \changes{v1.5k}{1989/09/04}{Macro added to support checksum.} -% This reports the sum compared with the value ("\bslash@cnt") the -% file advertises. It's called from "\Finale" (if that hasn't been +% This reports the sum compared with the value (|\bslash@cnt|) the +% file advertises. It's called from |\Finale| (if that hasn't been % re-defined). % \changes{v2.1f}{2016/02/12}{Suppress \cs{CheckSum} check if no checksum % is specified in the file} @@ -4581,12 +5164,12 @@ % \end{macro} % % -% \begin{macro}{\check@sum} +% \begin{tcounter}{\check@sum} % \changes{v1.5k}{1989/09/04}{Macro added to support checksum.} -% \begin{macro}{\bslash@cnt} +% \begin{tcounter}{\bslash@cnt} % \changes{v1.5k}{1989/09/04}{Macro added to support checksum.} -% We need to define counters, "\bslash@cnt" for the number of -% backslashes counted and "\check@sum" for the value advertised by the +% We need to define counters, |\bslash@cnt| for the number of +% backslashes counted and |\check@sum| for the value advertised by the % file if any. A negative value means there is no checksum checking which is the default. % \changes{v2.1f}{2016/02/12}{Suppress \cs{CheckSum} check if no checksum % is specified in the file} @@ -4594,17 +5177,17 @@ \newcount\check@sum \check@sum = \m@ne \newcount\bslash@cnt \bslash@cnt = \z@ % \end{macrocode} -% \end{macro} -% \end{macro} +% \end{tcounter} +% \end{tcounter} % % -% \begin{macro}{\CheckSum} +% \begin{omacro}{\CheckSum} % \changes{v1.5k}{1989/09/04}{Macro added to support checksum.} -% This is the interface to setting "\check@sum". +% This is the interface to setting |\check@sum|. % \begin{macrocode} \def\CheckSum#1{\@bsphack\global\check@sum#1\relax\@esphack} % \end{macrocode} -% \end{macro} +% \end{omacro} % % % @@ -4617,13 +5200,13 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\CharacterTable} +% \begin{omacro}{\CharacterTable} % The user interface to the character table-checking does some -% "\catcode"ing and then compares the following table with the -% stored version. We need to have "@" of type ``other'' within the +% |\catcode|ing and then compares the following table with the +% stored version. We need to have |@| of type ``other'' within the % table since this is the way it is usually returned when reading % in a normal document. To nevertheless have a private letter we -% use "~" for this purpose. "~" does no harm as a ``letter'' as it +% use |~| for this purpose. |~| does no harm as a ``letter'' as it % comes last in the table and therefore will not gobble following % space. % \changes{v1.5m}{1989/09/20}{Macro added to check character translation @@ -4635,12 +5218,14 @@ % \begin{macrocode} \def\CharacterTable{\begingroup \CharTableChanges \character@table} % \end{macrocode} -% \end{macro} +% \end{omacro} +% % \def\MakePrivateLetters{\catcode`\~=11\makeatletter} +% % \begin{macro}{\character@table} % This does the work of comparing the tables and reporting the result. % Note that the following code is enclosed in a group -% with "~" catcoded to letter. +% with |~| catcoded to letter. % \begin{macrocode} \begingroup \catcode`\~=11 @@ -4659,22 +5244,22 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\CharTableChanges} +% \begin{omacro}{\CharTableChanges} % When the character table is read in we need to scan it with a -% fixed set of "\catcode"s. The reference table below was defined by -% assuming the normal "\catcode"s of \TeX{}, i.e.\ "@" is of type +% fixed set of |\catcode|s. The reference table below was defined by +% assuming the normal |\catcode|s of \TeX{}, i.e.\ |@| is of type % other and the only token of type ``letter'' are the usual letters % of the alphabet. If, for some reason, other characters are made -% ``letters'' then their "\catcode"s need to be restored before +% ``letters'' then their |\catcode|s need to be restored before % checking the table. Otherwise spaces in the table are gobbled and % we get the information that the tables are different, even if -% they are actually equal. For this reason "\CharTableChanges" can -% be set up to locally restore the "\catcode"s of such ``letters'' +% they are actually equal. For this reason |\CharTableChanges| can +% be set up to locally restore the |\catcode|s of such ``letters'' % to ``other''. % \begin{macrocode} \global\let\CharTableChanges\@empty % \end{macrocode} -% \end{macro} +% \end{omacro} % % \begin{macro}{\default~table} % Here's what the table {\em should\/} look like (modulo spaces). @@ -4719,34 +5304,40 @@ % % The code in this section allows index entries to refer to code line % numbers---the number of the first line of macrocode in the -% \textsf{macro} environment. +% \env{macro} environment. % % % \begin{macro}{\codeline@index} -% Indexing by code line is controlled by the "codeline@index" switch. +% Indexing by code line is controlled by the |codeline@index| switch. % \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} % \changes{v1.7a}{1992/02/24}{Documented code line no. support.} -% \begin{macro}{\CodelineNumbered} +% \begin{imacro}{\CodelineNumbered} % \changes{v1.8a}{1993/05/19}{Macro added} % \begin{macrocode} \newif\ifcodeline@index \codeline@indexfalse \let\CodelineNumbered\codeline@indextrue % \end{macrocode} +% \end{imacro} % \end{macro} -% \end{macro} +% % \begin{macro}{\codeline@wrindex} -% The code index entries are written out by "\special@index". If -% indexing is by code line this is "\let" to "\codeline@wrindex"; -% if indexing is by page it is just "\index". However, if -% "\nofiles" is given, we omit writing such an index entry at all. +% The code index entries are written out by |\special@index|. If +% indexing is by code line this is |\let| to |\codeline@wrindex|; +% if indexing is by page it is just |\index|. However, if +% |\nofiles| is given, we omit writing such an index entry at all. % \changes{v1.7j}{1992/08/14}{Added \cs{if@filesw}.} % \begin{macrocode} \def\codeline@wrindex#1{\if@filesw + \begingroup + \set@display@protect \immediate\write\@indexfile {\string\indexentry{#1}% - {\number\c@CodelineNo}}\fi} + {\number\c@CodelineNo}}% + \endgroup + \fi} % \end{macrocode} % \end{macro} +% % \begin{macro}{\special@index} % By default no index entries are written out. % \begin{macrocode} @@ -4756,8 +5347,8 @@ % \begin{macro}{\CodelineIndex} % \changes{v1.5u}{1989/11/14}{Added \cs{PageIndex} and % \cs{CodelineIndex} (Undoc)} -% This switches on use of the index file with "\makeindex", sets the -% switch to indicate code line numbering and defines "\special@index" +% This switches on use of the index file with |\makeindex|, sets the +% switch to indicate code line numbering and defines |\special@index| % appropriately. % \begin{macrocode} \def\CodelineIndex{\makeindex @@ -4765,17 +5356,17 @@ \let\special@index\codeline@wrindex} % \end{macrocode} % \end{macro} -% \begin{macro}{\PageIndex} -% "\PageIndex" is similar. +% \begin{imacro}{\PageIndex} +% |\PageIndex| is similar. % \begin{macrocode} \def\PageIndex{\makeindex \codeline@indexfalse \let\special@index\index} % \end{macrocode} -% \end{macro} +% \end{imacro} % % -% \begin{macro}{\c@CodelineNo} +% \begin{lcounter}{CodelineNo} % \changes{v1.5l}{1989/09/10}{Counter added to support code line % numbers} % \changes{v1.5y}{1990/02/24}{Default changed.} @@ -4785,7 +5376,8 @@ % \begin{macrocode} \newcount\c@CodelineNo \c@CodelineNo\z@ % \end{macrocode} -% \end{macro} +% \end{lcounter} +% % \begin{macro}{\theCodelineNo} % \changes{v1.7a}{1992/02/25}{Existing definition not overwritten.} % \changes{v1.7a}{1992/03/12}{Use \cs{reset@font} for NFSS.} @@ -4817,7 +5409,6 @@ % \end{macrocode} % \end{macro} % -% \DeleteShortVerb{\"} % % The following |\mathcode| definitions allow the characters % `|\|' @@ -4835,9 +5426,9 @@ % \texttt{\bslash mathcode}$\,$s % to work with any family assignments. For an example % see the article about the new font selection scheme.} -% particularly for something like $|\@abc|=1$. +% particularly for something like |\@abc=1|. % -% If an {\em old\/} version of the \textsf{german} package is in +% If an {\em old\/} version of the \pkg{german} package is in % force, then the `|"|' character is active and would upset the % definition of the \meta{16-bit number} quantities below, therefore % we change the |\catcode| of |"| inside a group, and use @@ -4907,8 +5498,8 @@ % % \subsection{Changing the \texttt{\protect\bslash catcode} of \%} % -% \begin{macro}{\MakePercentIgnore} -% \begin{macro}{\MakePercentComment} +% \begin{imacro}{\MakePercentIgnore} +% \begin{imacro}{\MakePercentComment} % And finally the most important bit: we change the |\catcode| % of `|%|' so that it is ignored (which is how we are able to % produce this document!). We provide two commands to do the actual @@ -4919,10 +5510,10 @@ \def\MakePercentIgnore{\catcode`\%9\relax} \def\MakePercentComment{\catcode`\%14\relax} % \end{macrocode} -% \end{macro} -% \end{macro} +% \end{imacro} +% \end{imacro} % -% \begin{macro}{\DocInput} +% \begin{imacro}{\DocInput} % The two macros above are now used to define the |\DocInput| macro % which was introduced in version v1.5l (or so) of the \DOC{} % package. In older versions |\MakePercentIgnore| was placed @@ -4930,7 +5521,7 @@ % \begin{macrocode} \def\DocInput#1{\MakePercentIgnore\input{#1}\MakePercentComment} % \end{macrocode} -% \end{macro} +% \end{imacro} % % \subsection{GetFileInfo} % @@ -4951,6 +5542,779 @@ % \end{macrocode} % \end{macro} % + + + + +% \section{Integrating hypdoc} +% +% If the option \texttt{hyperref} is selected (which is the +% default), then we load the \pkg{hypdoc} package. We do that as +% late as possible so that we don't generate option clashes if it +% is also loaded in the preamble. That package currently changes +% more commands than it should (not knowing about their new +% definitions defined below) so we have to save and restore a few. +% +% Midterm all this code in \pkg{hypdoc} should be directly included +% in \DOC. For now, while they are separate we have to do this +% juggling. +% \begin{macrocode} +\AddToHook{begindocument/before}[doc/hyperref]{% + \ifdoc@hyperref +% \end{macrocode} +% Annoying to code around issue \#22 +% \begin{macrocode} + \expandafter\let\expandafter\doc@eoph@@k\csname doc.sty-h@@k\endcsname +% \end{macrocode} +% We require the package without any option so if it was already +% loaded there is no option clash. +% \begin{macrocode} + \RequirePackage{hypdoc} + \expandafter\let\csname doc.sty-h@@k\endcsname\doc@eoph@@k +% \end{macrocode} +% After \pkg{hypdoc} got loaded we need to undefine those macros +% again so that later on \texttt{Macro} and \texttt{Env} \DOC items +% appear to be undefined. +% \begin{macrocode} + \let\PrintDescribeMacro \@@PrintDescribeMacro + \let\PrintDescribeEnv \@@PrintDescribeEnv + \let\PrintMacroName \@@PrintMacroName + \let\PrintEnvName \@@PrintEnvName + \let\SpecialUsageIndex \@@SpecialUsageIndex + \let\SpecialEnvIndex \@@SpecialEnvIndex + \let\SortIndex \@@SortIndex + \let\DescribeMacro \@@DescribeMacro + \let\DescribeEnv \@@DescribeEnv +% \end{macrocode} +% The package adds new definitions for \cs{special@index} into +% \cs{CodelineIndex} and \cs{PageIndex} but since we are loading it +% very late we are already past them (in the preamble). So we test +% the final state and do it here, if necessary. +% \begin{macrocode} + \ifx\special@index\@gobble % do we write index entries at all? + \else + \ifcodeline@index + \let\special@index\HD@codeline@wrindex + \else + \let\special@index\HD@page@wrindex + \fi + \fi +% \end{macrocode} +% The \pkg{amsmath} documentation uses \cs{env} in headings and +% with \pkg{hyperref} enabled this causes trouble in bookmarks. +% \fmi{fix elsewhere eventually} +% \begin{macrocode} + \AddToHook{class/amsdtx/after}{% + \pdfstringdefDisableCommands{\let\env\@empty }}% +% \end{macrocode} +% That package also adds extra code into |\index| entries but it doesn't +% know about all the stuff that \DOC does (now). So we need to provide +% us with two helpers that handle the |\encapchar| case in some entries. +% \begin{macrocode} + \def\doc@providetarget{\HD@target}% + \def\doc@handleencap#1{\encapchar hdclindex{\the\c@HD@hypercount}{#1}}% +% \end{macrocode} +% If that package is not loaded these helpers do little to nothing. +% \begin{macrocode} + \else + \let\doc@providetarget\@empty + \def\doc@handleencap#1{\encapchar #1}% +% \end{macrocode} +% We define the next commands just in case the user changed the option +% \texttt{hyperref} from \texttt{true} to \texttt{false} without +% removing the auxiliary files. +% \begin{macrocode} + \def\hdclindex#1#2{\ifx\@nil#2\@nil\else\csname #2\expandafter\endcsname\fi}% + \def\hdpindex #1{\ifx\@nil#1\@nil\else\csname #1\expandafter\endcsname\fi}% +\fi +} +% \end{macrocode} +% +% +% +% +% +% \section{Integrating the \DOX package code} +% +% The code in this section is largely taken over from the \DOX package +% by Didier with only minor modifications (so far). This means it is a +% bit back and forth and both the code and the documentation need +% further updates. +% +% \subsection{\DOX environments} + +% \begin{macro}{\@doc@env,\@doc@env@} +% \fmi{original doc -- fix} +% \marg{are-we-macrolike}\marg{item}\marg{indextype}\marg{name}\\ +% In \texttt{doc.sty}, the \texttt{macro} and \texttt{environment} +% environments go through the \cs{m@cro@} macro which implements specific +% parts by testing a boolean condition as its first argument. This mechanism +% is not extensible, so I have to hack away a more generic version that +% would work for any new \texttt{dox} item, only which looks pretty much +% like the original one (with the addition of options management). +% +% First step is to see if we have a comma-separated list of names +% in |#3| and if so we call the macro doing the work individually +% for each +% \begin{macrocode} +\ExplSyntaxOn +% \end{macrocode} +% +% \begin{macrocode} +\long\def\@doc@env#1#2#3{ +% \end{macrocode} +% The |\endgroup| here closes the scanning of names (using special catcodes. +% \begin{macrocode} + \endgroup + \clist_map_inline:nn {#3} { \@doc@env@{#1}{#2}{##1} } +} + +\ExplSyntaxOff +% \end{macrocode} +% +% And here is the payload for each name from the given list: +% \begin{macrocode} +\long\def\@doc@env@#1#2#3{% + \topsep\MacroTopsep + \trivlist + \edef\saved@macroname{\string#3}% +% \end{macrocode} +% Since version 2.1g, \texttt{doc} creates a \cs{saved@indexname} command +% which in used by \cs{changes}. We now support that as well. The expansion of +% this command depends on whether the documented item is macrolike or not, +% which we don't know here (it's only know by \cs{NewDocElement}). That's why we +% need one specific command generating \cs{saved@indexname} the right way for +% every single item. These commands are +% named\cs{@Save\meta{item}IndexName}; +% 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} +% +% |#1| is either \texttt{TT} (for true = macrolike) or \texttt{TF}. +% If true then we drop the first char from |\saved@macroname| and +% store the result in |\saved@indexname| and use the latter for +% sorting in the index. +% \begin{macrocode} + \if #1% + \edef\saved@indexname{\expandafter\@gobble\saved@macroname}% +% +% \end{macrocode} +% 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 +% 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 +% equivalent to \cs{CodeMacroIndex}. +% \begin{macrocode} + \expandafter\ifx + \csname Code#2Index\endcsname + \CodeMacroIndex + \else + \record@index@type@save + {\saved@indexname}{#2}% + \fi + \else + \let\saved@indexname\saved@macroname + \fi +% + \def\makelabel##1{\llap{##1}}% + \if@inlabel + \let\@tempa\@empty + \count@\macro@cnt + \loop\ifnum\count@>\z@ + \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne + \repeat + \edef\makelabel##1{\llap{\vtop to\baselineskip{\@tempa\hbox{##1}\vss}}}% + \advance\macro@cnt\@ne + \else + \macro@cnt\@ne + \fi + \ifdoc@noprint + \item + \else + \edef\@tempa{% + \noexpand\item[% +% \end{macrocode} +% The second notable modification to the original macro involves dynamically +% constructing the name of the print macro: +% \begin{macrocode} + \noexpand\doc@providetarget + \noexpand\strut + \noexpand\@nameuse{Print#2Name}{\saved@macroname}]}% + \@tempa + \fi + \ifdoc@noindex\else + \global\advance\c@CodelineNo\@ne +% \end{macrocode} +% and the third one involves dynamically constructing the name of the index +% macro: +% \begin{macrocode} + \csname SpecialMain#2Index\expandafter\endcsname + \expandafter{\saved@macroname}\nobreak + \global\advance\c@CodelineNo\m@ne + \fi +% \end{macrocode} +% Suppress further |\index| entries when we are within a +% \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} +% \begin{macrocode} + \if#1\expandafter\DoNotIndex \expandafter {\saved@macroname}\fi + \ignorespaces} +% \end{macrocode} +% \end{macro} +% +% +% +% +% +% +% \begin{macro}{\doc@env} +% \marg{true-value}\marg{item}\oarg{options}\\ +% Handle optional arguments and call \cs{@doc@env}. Because environments can +% be nested, we can't rely on grouping for getting options default values. +% Hence, we need to reset the options at every call. +% \fmi{Use 2e interface for \cs{keys\_set:nn} when available} +% \begin{macrocode} +\def\doc@env#1#2[#3]{% + \@nameuse{doc@noprint\doc@noprintdefault}% + \@nameuse{doc@noindex\doc@noindexdefault}% + \csname keys_set:nn\endcsname{doc}{#3}% + \begingroup + \ifdoc@outer + \catcode`\\12 + \fi + \MakePrivateLetters + \@doc@env{#1}{#2}% +} +% \end{macrocode} +% \end{macro} + + + +% \subsection{\DOC descriptions} +% +% \begin{macro}{\@doc@describe} +% \marg{item}\marg{name}\\ +% \begin{macrocode} +\def\@doc@describe#1#2{% + \ifdoc@noprint\else + \marginpar{\raggedleft +% \end{macrocode} +% The hyperref target has to be in horizontal mode (which is the +% case if it is after the \cs{strut}). +% \begin{macrocode} + \strut + \doc@providetarget + \@nameuse{PrintDescribe#1}{#2}}% + \fi + \ifdoc@noindex\else + \@nameuse{Special#1Index}{#2}% + \fi + \@esphack + \endgroup + \ignorespaces} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\doc@describe} +% \marg{item}\oarg{options}\\ +% Handle optional arguments and call \cs{@doc@describe}. +% \fmi{Use 2e interface for \cs{keys\_set:nn} when available} +% \begin{macrocode} +\def\doc@describe#1[#2]{% + \leavevmode\@bsphack + \csname keys_set:nn\endcsname{doc}{#2}% + \@doc@describe{#1}} +% \end{macrocode} +% \end{macro} +% +% +% +% +% \subsection{API construction} +% +% +% \begin{macro}{\@temptokenb} +% A scratch register (which may have been defined elsewhere) +% \begin{macrocode} +\@ifundefined{temptokenb}{\newtoks\@temptokenb}{} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\doc@createspecialmainindex} +% \marg{item}\marg{idxtype}\marg{idxcat} +% \begin{macro}{\doc@createspecialmainmacrolikeindex} +% \marg{item}\marg{idxtype}\marg{idxcat}\\ +% \fmi{original doc -- fix} +% The ``macrolike'' version does something similar to |doc|'s +% \cs{SpecialIndex@} macro, but simplified. Let's just hope nobody will ever +% define \verb*|\ | or nonletter macros as macrolike \DOC elements\ldots +% \begin{macrocode} +\def\doc@createspecialindexes#1#2#3{% +% \end{macrocode} +% +% \begin{macrocode} + \@temptokena{\space (#2)}% + \@temptokenb{#3:}% +% \end{macrocode} +% +% \begin{macrocode} + \@nameedef{SpecialMain#1Index}##1{% + \noexpand\@bsphack + \ifdoc@toplevel + \noexpand\special@index{##1\noexpand\actualchar + {\string\ttfamily\space##1}% + \ifx\@nil#2\@nil\else \the\@temptokena \fi + \noexpand\encapchar main}% + \fi + \ifx\@nil#3\@nil\else + \noexpand\special@index{\the\@temptokenb\noexpand\levelchar + ##1\noexpand\actualchar{\string\ttfamily\space##1}% + \noexpand\encapchar main}% + \fi + \noexpand\@esphack}% +% \end{macrocode} +% +% \begin{macrocode} + \@nameedef{Special#1Index}##1{% + \noexpand\@bsphack + \ifdoc@toplevel + \noexpand\doc@providetarget + \noexpand\index{##1\noexpand\actualchar{\string\ttfamily\space##1}% + \ifx\@nil#2\@nil\else \the\@temptokena \fi + \noexpand\doc@handleencap{usage}}% + \fi + \ifx\@nil#3\@nil\else + \noexpand\index{\the\@temptokenb\noexpand\levelchar + ##1\noexpand\actualchar{\string\ttfamily\space##1}% + \noexpand\doc@handleencap{usage}}% + \fi + \noexpand\@esphack}} +% \end{macrocode} +% +% \begin{macrocode} +\def\doc@createspecialmacrolikeindexes#1#2#3{% +% \end{macrocode} +% +% \begin{macrocode} + \@temptokena{\space (#2)}% + \@temptokenb{#3:}% +% \end{macrocode} +% +% \begin{macrocode} + \@nameedef{Code#1Index}##1##2{% + \noexpand\@SpecialIndexHelper@##2\noexpand\@nil + \noexpand\@bsphack + \noexpand\ifdoc@noindex\noexpand\else + \ifdoc@toplevel + \noexpand\special@index{\noexpand\@gtempa\noexpand\actualchar + \string\verb% % to fool emacs highlighting + \noexpand\quotechar*\noexpand\verbatimchar + \noexpand\bslash\noexpand\@gtempa\noexpand\verbatimchar + \ifx\@nil#2\@nil\else \the\@temptokena \fi + \noexpand\encapchar ##1}% + \fi + \ifx\@nil#3\@nil\else + \noexpand\special@index{\the\@temptokenb\noexpand\levelchar + \noexpand\@gtempa\noexpand\actualchar + \string\verb% % to fool emacs highlighting + \noexpand\quotechar*\noexpand\verbatimchar + \noexpand\bslash\noexpand\@gtempa\noexpand\verbatimchar + \noexpand\encapchar ##1}% + \fi + \noexpand\fi + \noexpand\@esphack}% +% \end{macrocode} +% +% \begin{macrocode} + \@nameedef{SpecialMain#1Index}##1{% + \expandafter\noexpand\csname Code#1Index\endcsname + {main}{##1}}% +% \end{macrocode} +% +% \begin{macrocode} + \@nameedef{Special#1Index}##1{% + \noexpand\@SpecialIndexHelper@##1\noexpand\@nil + \noexpand\@bsphack + \noexpand\ifdoc@noindex\noexpand\else + \ifdoc@toplevel + \noexpand\doc@providetarget + \noexpand\index{\noexpand\@gtempa\noexpand\actualchar + \string\verb% % to fool emacs highlighting + \noexpand\quotechar*\noexpand\verbatimchar + \noexpand\bslash\noexpand\@gtempa\noexpand\verbatimchar + \ifx\@nil#2\@nil\else \the\@temptokena \fi + \noexpand\doc@handleencap{usage}}% + \fi + \ifx\@nil#3\@nil\else + \noexpand\index{\the\@temptokenb\noexpand\levelchar + \noexpand\@gtempa\noexpand\actualchar + \string\verb% % to fool emacs highlighting + \noexpand\quotechar*\noexpand\verbatimchar + \noexpand\bslash\noexpand\@gtempa\noexpand\verbatimchar + \noexpand\doc@handleencap{usage}}% + \fi + \noexpand\fi + \noexpand\@esphack}} +% \end{macrocode} +% \end{macro} +% \end{macro} + + + +% \begin{macro}{\doc@createdescribe} +% \marg{item} +% \begin{macrocode} +\def\doc@createdescribe#1{% + \@namedef{Describe#1}{% +% \end{macrocode} +% Because of the optional argument we have to set +% |\MakePrivateLetters| already before parsing that (fingers +% crossed). Otherwise incorrect but quite common usage, such as +% |\DescribeMacro\foo@bar| will break because the scan for the +% optional argument will tokenize the following input (i.e., |\foo| +% in that case) before the |@| sign becomes a letter. As a result +% |DescribeMacro| would receive only |\foo| as its argument. +% \begin{macrocode} + \begingroup + \MakePrivateLetters + \@ifnextchar[%] + {\doc@describe{#1}}{\doc@describe{#1}[]}}} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\doc@createenv} +% \marg{item}\marg{envname} +% \begin{macrocode} +\def\doc@createenv#1#2#3{% + \@namedef{#3}{% + \@ifnextchar[%] + {\doc@env{#1}{#2}}{\doc@env{#1}{#2}[]}}% +% \end{macrocode} +% Instead of |\let|ting the end of the environment to +% |\endtrivlist| we use one level of expansion. This way any +% possible change in that environment (if that ever happens) is +% properly reflected. +% \begin{macrocode} + \@namedef{end#3}{\endtrivlist}% +% \expandafter\let\csname end#3\endcsname\endtrivlist +} +% \end{macrocode} +% \end{macro} + + +% +% \begin{macro}{\@nameedef} +% +% \begin{macrocode} +\def\@nameedef#1{\expandafter\edef\csname #1\endcsname} +% \end{macrocode} +% \end{macro} + +% +% \subsection{API creation} +% +% The whole user interface is created in one macro call. +% +%\begin{verbatim} +% defaults: +% +% idxtype = #3 +% idxgroup = #3s +% printtype = +%\end{verbatim} + + + +% \begin{macro}{\doc@declareerror} +% +% \begin{macrocode} +\def\doc@declareerror#1#2{% + \PackageError{doc}{Doc element '#1/#2' already defined?\@gobble}% + {There is already a definition for + '\string\Print#1Name',\MessageBreak + '\string\PrintDescribe#1' + or the environment '#2'.\MessageBreak + Maybe you are overwriting something by mistake!\MessageBreak + Otherwise use '\string\RenewDocElement' instead.}% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\doc@notdeclarederror} +% +% \begin{macrocode} +\def\doc@notdeclarederror#1#2{% + \PackageError{doc}{Doc element '#1/#2' unknown}% + {I expected an existing definition for + '\string\Print#1Name',\MessageBreak + '\string\PrintDescribe#1' and + the environment '#2' but\MessageBreak + not all of them are defined.\MessageBreak + Maybe you wanted to use + '\string\NewDocElement'?}% +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{imacro}{\NewDocElement} +% \oarg{options}\marg{name}\marg{envname} +% +% \begin{macrocode} +\newcommand\NewDocElement[3][]{% +% \end{macrocode} +% +% \begin{macrocode} + \@ifundefined{Print#2Name}% + {\@ifundefined{PrintDescribe#2}% + {\@ifundefined{#3}% + {\@ifundefined{end#3}% + {\@NewDocElement{#1}}% + \doc@declareerror + }\doc@declareerror + }\doc@declareerror + }\doc@declareerror + {#2}{#3}% +} +% \end{macrocode} +% \end{imacro} +% +% \begin{imacro}{\RenewDocElement} +% \oarg{options}\marg{name}\marg{envname} +% +% \begin{macrocode} +\newcommand\RenewDocElement[3][]{% +% \end{macrocode} +% +% \begin{macrocode} + \@ifundefined{Print#2Name}\doc@notdeclarederror + {\@ifundefined{PrintDescribe#2}\doc@notdeclarederror + {\@ifundefined{#3}\doc@notdeclarederror + {\@ifundefined{end#3}\doc@notdeclarederror + {\@NewDocElement{#1}}% + }% + }% + }% + {#2}{#3}% +} +% \end{macrocode} +% \end{imacro} +% +% +% \begin{macro}{\@NewDocElement} +% \marg{options}\marg{name}\marg{envname} +% +% \begin{macrocode} +\def\@NewDocElement#1#2#3{% +% \end{macrocode} +% +% \begin{macrocode} + \doc@macrolikefalse + \doc@topleveltrue +% \end{macrocode} +% +% \fmi{Use 2e interface for \cs{keys\_set:nn} when available} +% \begin{macrocode} + \def\doc@idxtype{#3}% + \def\doc@idxgroup{#3s}% + \let\doc@printtype\@empty + \csname keys_set:nn\endcsname{doc}{#1}% +% \end{macrocode} +% \begin{imacro}{\Print...Name} +% \marg{name} +% \fmi{extremely messy this with so many \cs{expandafter}s \ldots{} +% should reimplement in expl3} +% \begin{macrocode} + \ifx\doc@printtype\@empty + \@temptokena{}% + \else + \@temptokena\expandafter{\expandafter + \textnormal\expandafter{\expandafter + \space\expandafter + (\doc@printtype)}}% + \fi + \@nameedef{Print#2Name}##1{% + {\noexpand\MacroFont + \ifdoc@macrolike + \noexpand\string + \fi + ##1% + \the\@temptokena + }}% +% \end{macrocode} +% \end{imacro} +% +% \begin{imacro}{\PrintDescribe...} +% \marg{name} +% \begin{macrocode} + \expandafter\let\csname PrintDescribe#2\expandafter\endcsname + \csname Print#2Name\endcsname +% \end{macrocode} +% \end{imacro} +% +% \begin{imacro}{\SpecialMain...Index} +% \marg{name} +% \begin{imacro}{\Special...Index} +% \marg{name} +% \begin{macrocode} + \edef\doc@expr{% + \ifdoc@macrolike + \noexpand\doc@createspecialmacrolikeindexes + \else + \noexpand\doc@createspecialindexes + \fi + {#2}% + }% + \expandafter\expandafter\expandafter + \doc@expr + \expandafter\expandafter\expandafter + {\expandafter\doc@idxtype\expandafter}\expandafter + {\doc@idxgroup}% +% \end{macrocode} +% \end{imacro} +% \end{imacro} +% +% \begin{imacro}{\Describe...} +% \oarg{options}\marg{name} +% \begin{macrocode} + \doc@createdescribe{#2}% +% \end{macrocode} +% \end{imacro} +% +% \begin{environment}{\meta{DocElement}} +% \fmi{can't have formatting in argument -- fix} +% \oarg{options}\marg{name} +% \begin{macrocode} + \ifdoc@macrolike + \doc@createenv{TT}{#2}{#3}% + \else + \doc@createenv{TF}{#2}{#3}% + \fi +} +% \end{macrocode} +% \end{environment} +% \end{macro} + + + + + +% \subsection{Setting up the default \DOC elements} + +% \subsubsection{Macro facilities} +% +% Macros get only a single index entry (no index group, no index +% type) and they do not get any label either when printing in the margin. +% \begin{macrocode} +\NewDocElement[macrolike = true , + idxtype = , + idxgroup = , + printtype = + ]{Macro}{macro} +% \end{macrocode} + + +% \begin{macro}{SpecialMainIndex} +% +% In \DOC v2 we had \cs{SpecialMainIndex} and +% \cs{SpecialMainEnvIndex} but now with additional \DOC elements we +% always add the element name after ``\texttt{Main}'' so this would +% be \cs{SpecialMainMacroIndex}. We use |\def| not |\let| so any +% redefinition of |\SpecialMainMacroIndex| will be transparent. +% \begin{macrocode} +\def\SpecialMainIndex{\SpecialMainMacroIndex} +% \end{macrocode} +% \end{macro} + +% \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|. +% +% In fact the documentation of \DOC v2 claimed that one can use +% this for both macros and environments but that was never true as +% for environments the result was that the first character was +% dropped in sorting of the index. The correct way is to use +% \cs{SpecialEnvIndex} for this. +% \begin{macrocode} +\def\SpecialUsageIndex{\SpecialMacroIndex} +% \end{macrocode} +% \end{macro} +% + +% \begin{macro}{\SpecialIndex} +% \begin{macrocode} +\def\SpecialIndex {\CodeMacroIndex{code}} +% \end{macrocode} +% \end{macro} + + +% +% \subsubsection{Environment facilities} +% +% Providing documentation support for environments. Here we differ +% from \DOC V2 by marking the environments with ``(\textit{env.})'' +% when printing the name in the margin. +% \begin{macrocode} +\NewDocElement[macrolike = false , + idxtype = env. , + idxgroup = environments , + printtype = \textit{env.} + ]{Env}{environment} +% \end{macrocode} +% +% +% +% To be able to restore the definition after \pkg{hypdoc} is loaded +% we better save them here. We only load the package at the end of +% the preamble, but the user might do this earlier and then chaos +% is ensured. +% \begin{macrocode} + \let\@@PrintDescribeMacro \PrintDescribeMacro + \let\@@PrintDescribeEnv \PrintDescribeEnv + \let\@@PrintMacroName \PrintMacroName + \let\@@PrintEnvName \PrintEnvName + \let\@@SpecialUsageIndex \SpecialUsageIndex + \let\@@SpecialEnvIndex \SpecialEnvIndex + \let\@@SortIndex \SortIndex + \let\@@DescribeMacro \DescribeMacro + \let\@@DescribeEnv \DescribeEnv +% \end{macrocode} +% +% +% \section{Misc additions} + +% \begin{imacro}{\cs} +% \begin{macrocode} +\DeclareRobustCommand\cs[1]{\texttt{\bslash #1}} +% \end{macrocode} +% \cls{amsdtx} has its own definition for \cs{cs} but that now +% gets overwritten because the class loads \pkg{doc} afterwards. So +% for now we reinstall it here. +% \fmi{fix elsewhere} +% \begin{macrocode} +\AddToHook{class/amsdtx/after}{% + \DeclareRobustCommand\cs[1]{% + \@boxorbreak{% + \ntt + \addbslash#1\@empty + \@xp\@xp\@xp\@indexcs\@xp\@nobslash\string#1\@nil + }% + }% + \def\cn{\cs}% +} +% \end{macrocode} +% \end{imacro} + + % We can now finish the \texttt{docstrip} main module. % \begin{macrocode} %</package> @@ -4958,5 +6322,15 @@ % % % \Finale -% \PrintIndex \PrintChanges +% \PrintChanges +% +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \endinput + +^^A Needed for emacs +^^A +^^A Local Variables: +^^A mode: latex +^^A coding: utf-8-unix +^^A End: diff --git a/macros/latex-dev/base/doc.pdf b/macros/latex-dev/base/doc.pdf Binary files differindex f511483c87..8c2a4a18c6 100644 --- a/macros/latex-dev/base/doc.pdf +++ b/macros/latex-dev/base/doc.pdf diff --git a/macros/latex-dev/base/docstrip.dtx b/macros/latex-dev/base/docstrip.dtx index c7480988b4..22c1f69aa0 100644 --- a/macros/latex-dev/base/docstrip.dtx +++ b/macros/latex-dev/base/docstrip.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -935,7 +935,7 @@ % using*strange@programming<language> %\end{verbatim} % -%\StopEventually{% +%\MaybeStop{% %^^A \section{Conclusion} % \PrintIndex % \PrintChanges diff --git a/macros/latex-dev/base/docstrip.ins b/macros/latex-dev/base/docstrip.ins index e34281fc36..e2187594a4 100644 --- a/macros/latex-dev/base/docstrip.ins +++ b/macros/latex-dev/base/docstrip.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -52,7 +52,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. @@ -98,6 +98,7 @@ extension .ins) which are part of the distribution. \generate{\file{ltxdoc.cls}{\from{ltxdoc.dtx}{class}} + \file{ltxdoc.cfg}{\from{ltxdoc.dtx}{cfg}} } \generate{\file{doc.sty}{\from{doc.dtx}{package}} diff --git a/macros/latex-dev/base/docstrip.pdf b/macros/latex-dev/base/docstrip.pdf Binary files differindex 39378c977f..bcfa8a34c7 100644 --- a/macros/latex-dev/base/docstrip.pdf +++ b/macros/latex-dev/base/docstrip.pdf diff --git a/macros/latex-dev/base/ec.ins b/macros/latex-dev/base/ec.ins index 90b7b2e61f..47823e7edf 100644 --- a/macros/latex-dev/base/ec.ins +++ b/macros/latex-dev/base/ec.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/encguide.pdf b/macros/latex-dev/base/encguide.pdf Binary files differindex e55805f1e9..5d16c1d5d9 100644 --- a/macros/latex-dev/base/encguide.pdf +++ b/macros/latex-dev/base/encguide.pdf diff --git a/macros/latex-dev/base/encguide.tex b/macros/latex-dev/base/encguide.tex index d70233eab4..3c95cf30cc 100644 --- a/macros/latex-dev/base/encguide.tex +++ b/macros/latex-dev/base/encguide.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/exscale.dtx b/macros/latex-dev/base/exscale.dtx index ea67cb6fb7..bc884c4db0 100644 --- a/macros/latex-dev/base/exscale.dtx +++ b/macros/latex-dev/base/exscale.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -106,7 +106,7 @@ % they are printed on another installation whereas when using the % package file they would come out the same on both sites. % -% \StopEventually{} +% \MaybeStop{} % % % \section{Implementation} diff --git a/macros/latex-dev/base/exscale.ins b/macros/latex-dev/base/exscale.ins index cfd2c535a7..d202aad7cf 100644 --- a/macros/latex-dev/base/exscale.ins +++ b/macros/latex-dev/base/exscale.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/exscale.pdf b/macros/latex-dev/base/exscale.pdf Binary files differindex 4c60fd71d6..e330165065 100644 --- a/macros/latex-dev/base/exscale.pdf +++ b/macros/latex-dev/base/exscale.pdf diff --git a/macros/latex-dev/base/fix-cm.dtx b/macros/latex-dev/base/fix-cm.dtx index 1be2e16cc0..5f8983ed34 100644 --- a/macros/latex-dev/base/fix-cm.dtx +++ b/macros/latex-dev/base/fix-cm.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -216,7 +216,7 @@ % % % -% \StopEventually{} +% \MaybeStop{} % % \section{Implementation} % diff --git a/macros/latex-dev/base/fix-cm.ins b/macros/latex-dev/base/fix-cm.ins index 95931970f4..b688cd66cf 100644 --- a/macros/latex-dev/base/fix-cm.ins +++ b/macros/latex-dev/base/fix-cm.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/fix-cm.pdf b/macros/latex-dev/base/fix-cm.pdf Binary files differindex 423e1756aa..3d02f33735 100644 --- a/macros/latex-dev/base/fix-cm.pdf +++ b/macros/latex-dev/base/fix-cm.pdf diff --git a/macros/latex-dev/base/fntguide.pdf b/macros/latex-dev/base/fntguide.pdf Binary files differindex a0b79a1b93..2907d5441b 100644 --- a/macros/latex-dev/base/fntguide.pdf +++ b/macros/latex-dev/base/fntguide.pdf diff --git a/macros/latex-dev/base/fntguide.tex b/macros/latex-dev/base/fntguide.tex index a4b872a261..62d3538304 100644 --- a/macros/latex-dev/base/fntguide.tex +++ b/macros/latex-dev/base/fntguide.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % % The LaTeX Project and any individual authors listed elsewhere % in this file. @@ -12,7 +12,7 @@ % conditions of the LaTeX Project Public License, either version 1.3c % of this license or (at your option) any later version. % The latest version of this license is in -% http://www.latex-project.org/lppl.txt +% https://www.latex-project.org/lppl.txt % and version 1.3c or later is part of all distributions of LaTeX % version 2008 or later. % @@ -33,16 +33,21 @@ \documentclass{ltxguide}[1995/11/28] -\usepackage{varioref} + +\setcounter{totalnumber}{8} +\setcounter{topnumber}{8} + +\usepackage[trace]{fewerfloatpages} +\usepackage{booktabs,varioref} \title{\LaTeXe{} font selection} \author{\copyright~Copyright 1995--2021, \LaTeX\ Project Team.\thanks{Thanks to Arash Esbati for documenting the newer NFSS features of 2020}\\ - All rights reserved.} + All rights reserved.} -\date{March 2021} +\date{December 2021} \begin{document} @@ -160,7 +165,7 @@ For more information about \TeX{} and \LaTeX{}, please contact your local \TeX{} Users Group, or the international \TeX{} Users Group. Addresses and other details can be found at: \begin{quote}\small\label{addrs} - \texttt{http://www.tug.org/lugs.html} + \texttt{https://www.tug.org/lugs.html} \end{quote} @@ -288,6 +293,9 @@ naming scheme to allow for sensible default substitutions if necessary, e.g., ``demi-bold'' is normally just another name for ``semi-bold'', so should get |sb| assigned, etc. + +\newpage + \NEWdescription{2020/02/02} The most common values for the font shape are: \begin{center} @@ -343,27 +351,29 @@ box warning, for example: Overfull \hbox (3.80855pt too wide) in paragraph at lines 314--318 []\OT1/cmr/m/n/10 Normally [] and [] will be iden-ti-cal, \end{verbatim} -The author commands for fonts set the five attributes: -\begin{center} - \hspace*{-1em}% - \begin{tabular}{rcl} - \emph{Author command} & \emph{Attribute} +The author commands for fonts set the five attributes as shown in table~\vref{tab:attributes}. +\begin{table}[!tbp] + \centering + \begin{tabular}{@{}r@{\hspace{3pt}}c@{\hspace{1pt}}c@{}} + \toprule + \multicolumn{1}{c}{\emph{Author command}} & \emph{Attribute} & \emph{Value in} |article| \emph{class} \\ + \midrule |\textnormal{..}| or |\normalfont| & family & |cmr| \\ & series & |m| \\ - & shape & |n| \\[1pt] + & shape & |n| \\ \midrule%[2pt] |\textrm{..}| or |\rmfamily| & family & |cmr| \\ |\textsf{..}| or |\sffamily| & family & |cmss| \\ |\texttt{..}| or |\ttfamily| & family & |cmtt| \\ |\textmd{..}| or |\mdseries| & series & |m| \\ - |\textbf{..}| or |\bfseries| & series & |bx| \\[1pt] + |\textbf{..}| or |\bfseries| & series & |bx| \\ \midrule%[2pt] |\textit{..}| or |\itshape| & shape & |it| \\ |\textsl{..}| or |\slshape| & shape & |sl| \\ |\textsc{..}| or |\scshape| & shape & |sc| \\ |\textssc{..}| or |\sscshape| & shape & |ssc| \\ |\textsw{..}| or |\swshape| & shape & |sw| \\ - |\textulc{..}| or |\ulcshape| & shape & |ulc| (virtual) $\to$ |n|, |it|, |sl| or |ssc| \\ - |\textup{..}| or |\upshape| & shape & |up| (virtual) $\to$ |n| or |sc| \\[1pt] + |\textulc{..}| or |\ulcshape| & shape & |ulc| (virtual) $\to$ |n|, |it|, |sl| or |ssc| \\ + |\textup{..}| or |\upshape| & shape & | up| (virtual) $\to$ |n| or |sc |\phantom{, , } \\\midrule%[2pt] |\tiny| & size & |5pt| \\ |\scriptsize| & size & |7pt| \\ |\footnotesize| & size & |8pt| \\ @@ -373,9 +383,11 @@ The author commands for fonts set the five attributes: |\Large| & size & |14.4pt| \\ |\LARGE| & size & |17.28pt| \\ |\huge| & size & |20.74pt| \\ - |\Huge| & size & |24.88pt| + |\Huge| & size & |24.88pt| \\ + \bottomrule \end{tabular} -\end{center} + \caption{Author font commands and their effects (article class)}\label{tab:attributes} +\end{table} The values used by these commands are determined by the document class, using the parameters defined in Section~\ref{Sec:text.param}. @@ -386,16 +398,20 @@ This section does not explain how \LaTeX{} font specifications are turned into \TeX{} font names. This is described in Section~\ref{Sec:install}. + +\newpage + + \subsection{Selection commands} The low-level commands used to select a text font are as follows. \begin{decl} |\fontencoding| \arg{encoding} \\ - |\fontfamily| \arg{family} \\ - |\fontseries| \arg{series} \\ + |\fontfamily| \arg{family} \qquad + |\fontseries| \arg{series} \qquad |\fontshape| \arg{shape} \\ - |\fontsize| \arg{size} \arg{baselineskip} \\ + |\fontsize| \arg{size} \arg{baselineskip} \qquad |\linespread| \arg{factor} \end{decl} @@ -439,14 +455,14 @@ to |\selectfont|. The current values of the font attributes are held in internal macros. \begin{decl} - |\f@encoding| \\ - |\f@family| \\ - |\f@series| \\ - |\f@shape| \\ - |\f@size| \\ + |\f@encoding| \quad + |\f@family| \quad + |\f@series| \quad + |\f@shape| \quad + |\f@size| \quad |\f@baselineskip| \\ - |\tf@size| \\ - |\sf@size| \\ + |\tf@size| \quad + |\sf@size| \quad |\ssf@size| \end{decl} @@ -482,9 +498,9 @@ specifies: \end{verbatim} \begin{decl} - |\encodingdefault| \\ - |\familydefault| \\ - |\seriesdefault| \\ + |\encodingdefault| \qquad + |\familydefault| \qquad + |\seriesdefault| \qquad |\shapedefault| \end{decl} The encoding, family, series and shape of the main body font. By @@ -493,8 +509,8 @@ default family is |\rmdefault|, this means that changing |\rmdefault| will change the main body font of the document. \begin{decl} - |\rmdefault| \\ - |\sfdefault| \\ + |\rmdefault| \qquad + |\sfdefault| \qquad |\ttdefault| \end{decl} The families selected by |\textrm|, |\rmfamily|, |\textsf|, |\sffamily|, @@ -502,7 +518,7 @@ The families selected by |\textrm|, |\rmfamily|, |\textsf|, |\sffamily|, |cmtt|. \begin{decl} - |\bfdefault| \\ + |\bfdefault| \qquad |\mddefault| \end{decl} The series selected by |\textbf|, |\bfseries|, |\textmd| and @@ -516,12 +532,12 @@ the fonts provided by |psnfss|) is to define silent substitutions from and the |ssub| size function, see Section~\ref{sec:sizefunct}. \begin{decl} - |\itdefault| \\ - |\sldefault| \\ - |\scdefault| \\ - |\sscdefault| \\ + |\itdefault| \qquad + |\sldefault| \qquad + |\scdefault| \qquad + |\sscdefault| \qquad |\swdefault| \\ - |\ulcdefault| \\ + |\ulcdefault| \qquad |\updefault| \end{decl} \NEWfeature{2020/02/02} @@ -611,6 +627,8 @@ This declaration is useful for setting up commands like |\rm| to behave as they did in \LaTeX~2.09. We strongly urge you \emph{not} to misuse this declaration to invent new font commands. +\newpage + The following example defines |\it| to produce the italic shape of the main document font if used in text and to switch to the font that would normally be produced by the math alphabet |\mathit| if used in a @@ -714,13 +732,13 @@ selected indirectly through symbol commands like |\oplus|. Section~\ref{Sec:math.commands} explains how to define symbol commands. \begin{decl} - |\mathnormal{<math>}| \\ - |\mathcal{<math>}| \\ - |\mathrm{<math>}| \\ - |\mathbf{<math>}| \\ - |\mathsf{<math>}| \\ + |\mathnormal{<math>}| \quad + |\mathcal{<math>}| \quad + |\mathbf{<math>}| \quad |\mathit{<math>}| \\ - |\mathtt{<math>}| + |\mathrm{<math>}| \qquad + |\mathsf{<math>}| \qquad + |\mathtt{<math>}| \end{decl} Each math alphabet is a command which can only be used inside math mode. For example, |$x + \mathsf{y} + \mathcal{Z}$| produces @@ -799,6 +817,8 @@ Checks that \m{math-alph} has been declared as a math alphabet, \m{version} is a known math version and \m{encoding} is a known encoding scheme. +\newpage + This example defines |\baz| for the `normal' math version only: \begin{verbatim} \SetMathAlphabet{\baz}{normal}{OT1}{cmss}{m}{n} @@ -868,6 +888,8 @@ alphabet with command \m{math-alph} in \emph{all} math versions. Checks that the command \m{math-alph} is either already a math alphabet command or is undefined; and that \m{sym-font} is a symbol font. +\newpage + Example: \begin{verbatim} \DeclareSymbolFontAlphabet{\mathrm}{operators} @@ -928,6 +950,8 @@ Example: \DeclareMathSymbol{\alphld}{\mathalpha}{AMSb}{"0C} \end{verbatim} +\newpage + \begin{decl} |\DeclareMathDelimiter| \arg{cmd} \arg{type} \arg{sym-font-1} \arg{slot-1}\\ @@ -1021,6 +1045,7 @@ Example: This section explains how \LaTeX's font attributes are turned into \TeX{} font specifications. + \subsection{Font definition files} \NEWdescription{1997/12/01} @@ -1043,6 +1068,8 @@ and font substitutions are made. The declarations in the font definition file are responsible for telling \LaTeX{} how to load fonts for that encoding/family combination. + + \subsection{Font definition file commands} \emph{Note}: A font definition file should contain only commands from @@ -1056,7 +1083,11 @@ of a document. |\ProvidesFile{<file-name>}[<release-info>]| \end{decl} The file should announce itself with a |\ProvidesFile| command, as -described in \emph{\clsguide}. For example: +described in \emph{\clsguide}. + +\newpage + +For example: \begin{verbatim} \ProvidesFile{t1ptm.fd}[1994/06/01 Adobe Times font definitions] \end{verbatim} @@ -2017,12 +2048,17 @@ glyphs from the math fonts instead of the current text font (this means they always keep the same shape and do not nicely blend in with the text font). +\newpage + The following tables show the macros available. The next commands are `constructed' accents and are built via \TeX{} macros: \begin{center} \begin{tabular}[t]{@{}ll} \verb*|\capitalcedilla A| & \capitalcedilla A \\ \verb*|\capitalogonek A| & \capitalogonek A \\ + \end{tabular} + \quad + \begin{tabular}[t]{@{}ll} \verb*|\textcircled a| & \textcircled a \end{tabular} \end{center} @@ -2052,12 +2088,21 @@ show the slot number: \end{tabular} \end{center} -Table~\vref{tab:textcomp} contains macros to access text symbols. Again, +Table~\vref{tab:textcomp} +contains the full list of commands to access the text symbols. +% +% Tables~\vrefrange{tab:ts1-subset-always}{tab:ts1-subset-9-disable} +% contain the commands to access the text symbols. +% +Again, the numbers are the slots in the encoding. -\begin{table} -\centering\footnotesize +\iftrue +\begin{table}[!tp] + \centering\footnotesize + \renewcommand\arraystretch{1.07} \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule \verb|\textcapitalcompwordmark| & \textcapitalcompwordmark & 23 \\ \verb|\textascendercompwordmark| & \textascendercompwordmark & 31 \\ \verb|\textquotestraightbase| & \textquotestraightbase & 13 \\ @@ -2112,9 +2157,11 @@ the numbers are the slots in the encoding. \verb|\textbullet| & \textbullet & 136 \\ \verb|\textcelsius| & \textcelsius & 137 \\ \verb|\textdollaroldstyle| & \textdollaroldstyle & 138 \\ - \verb|\textcentoldstyle| & \textcentoldstyle & 139 + \verb|\textcentoldstyle| & \textcentoldstyle & 139 \\ + \bottomrule \end{tabular}\qquad \begin{tabular}[t]{lp{1.5em}l} + \toprule \verb|\textflorin| & \textflorin & 140 \\ \verb|\textcolonmonetary| & \textcolonmonetary & 141 \\ \verb|\textwon| & \textwon & 142 \\ @@ -2168,12 +2215,371 @@ the numbers are the slots in the encoding. \verb|\textthreequarters| & \textthreequarters & 190 \\ \verb|\texteuro| & \texteuro & 191 \\ \verb|\texttimes| & \texttimes & 214 \\ - \verb|\textdiv| & \textdiv & 246 + \verb|\textdiv| & \textdiv & 246 \\ + \null \\ + \bottomrule + \end{tabular} + \caption{Text symbols formerly from the \textsf{textcomp} package} + \label{tab:textcomp} +\end{table} + +\fi + +The |TS1| encoding contains a rich set of symbols which means that +several symbols are only available in a few \TeX{} fonts and some, such +as the capital accents, not available at all but developed as part of +the reference font implementation. In reality, many existing fonts +don't provide a full set of glyphs defined in |TS1| encoding and the +question arises: ``Which glyphs of the |TS1| encoding are implemented by +which font?'' + +\NEWfeature{2021/06/01} +Fonts can be ordered in sub-encodings with the |\DeclareEncodingSubset| +macro: +\begin{decl} + |\DeclareEncodingSubset| \arg{encoding} + \arg{font family} + \arg{subset number} +\end{decl} +The macro takes 3 mandatory arguments: An \m{encoding} for which a +subsetting is wanted (currently only |TS1|), the \m{font family} for +which we declare the subset and finally the \m{subset number} between +|0| (all of the encoding is supported) and |9| (many glyphs are +missing). Hence, it is assumed that some symbols are always available +by all fonts and each sub-encoding defines macros which become +unavailable (i.e., they are not provided in the sub-encoding with that +number and all sub-encodings with higher numbers.) + +\begin{table}[tbp] + \centering\footnotesize + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textquotestraightbase| & \textquotestraightbase & 13 \\ + \verb|\textquotestraightdblbase| & \textquotestraightdblbase & 18 \\ + \verb|\textcapitalcompwordmark| & \textcapitalcompwordmark & 23 \\ + \verb|\textascendercompwordmark| & \textascendercompwordmark & 31 \\ + \verb|\textdollar| & \textdollar & 36 \\ + \verb|\textquotesingle| & \textquotesingle & 39 \\ + \verb|\textasteriskcentered| & \textasteriskcentered & 42 \\ + \verb|\textdagger| & \textdagger & 132 \\ + \verb|\textdaggerdbl| & \textdaggerdbl & 133 \\ + \verb|\textperthousand| & \textperthousand & 135 \\ + \verb|\textbullet| & \textbullet & 136 \\ + \verb|\texttrademark| & \texttrademark & 151 \\ + \verb|\textcent| & \textcent & 162 \\ + \verb|\textsterling| & \textsterling & 163 \\ + \verb|\textyen| & \textyen & 165 \\ + \verb|\textbrokenbar| & \textbrokenbar & 166 \\ + \bottomrule + \end{tabular}\qquad + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textsection| & \textsection & 167 \\ + \verb|\textcopyright| & \textcopyright & 169 \\ + \verb|\textordfeminine| & \textordfeminine & 170 \\ + \verb|\textlnot| & \textlnot & 172 \\ + \verb|\textregistered| & \textregistered & 174 \\ + \verb|\textdegree| & \textdegree & 176 \\ + \verb|\textpm| & \textpm & 177 \\ + \verb|\textparagraph| & \textparagraph & 182 \\ + \verb|\textperiodcentered| & \textperiodcentered & 183 \\ + \verb|\textordmasculine| & \textordmasculine & 186 \\ + \verb|\textonequarter| & \textonequarter & 188 \\ + \verb|\textonehalf| & \textonehalf & 189 \\ + \verb|\textthreequarters| & \textthreequarters & 190 \\ + \verb|\texttimes| & \texttimes & 214 \\ + \verb|\textdiv| & \textdiv & 246 \\ + \null \\ + \bottomrule + \end{tabular} + \caption{Symbols available in all \texttt{TS1} sub-encodings} + \label{tab:ts1-subset-always} +\end{table} + + + +\begin{table}[!tbp] + \centering + \begin{tabular}[t]{@{}lll@{}} + \toprule + \verb*|\textcircled| & \textcircled{} & acc \\ + \bottomrule + \end{tabular} + \caption{Symbol unavailable in \texttt{TS1} sub-encoding \texttt{1} + and higher} + \label{tab:ts1-subset-1-disable} +\end{table} + + + +\begin{table}[!tbp] + \centering\footnotesize + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\capitalcedilla| & \capitalcedilla{} & acc \\ + \verb|\capitalogonek| & \capitalogonek{} & acc \\ + \verb|\capitalgrave| & \capitalgrave{} & 0 \\ + \verb|\capitalacute| & \capitalacute{} & 1 \\ + \verb|\capitalcircumflex| & \capitalcircumflex{} & 2 \\ + \verb|\capitaltilde| & \capitaltilde{} & 3 \\ + \verb|\capitaldieresis| & \capitaldieresis{} & 4 \\ + \verb|\capitalhungarumlaut| & \capitalhungarumlaut{} & 5 \\ + \verb|\capitalring| & \capitalring{} & 6 \\ + \verb|\capitalcaron| & \capitalcaron{} & 7 \\ + \verb|\capitalbreve| & \capitalbreve{} & 8 \\ + \verb|\capitalmacron| & \capitalmacron{} & 9 \\ + \verb|\capitaldotaccent| & \capitaldotaccent{} & 10 \\ + \verb|\capitaltie| & \capitaltie{} & 27 \\ + \verb|\newtie| & \newtie{} & 28 \\ + \verb|\capitalnewtie{}| & \capitalnewtie{} & 29 \\ + \verb|\textdblhyphen| & \textdblhyphen & 45 \\ + \verb|\textzerooldstyle| & \textzerooldstyle & 48 \\ + \verb|\textoneoldstyle| & \textoneoldstyle & 49 \\ + \verb|\texttwooldstyle| & \texttwooldstyle & 50 \\ + \verb|\textthreeoldstyle| & \textthreeoldstyle & 51 \\ + \verb|\textfouroldstyle| & \textfouroldstyle & 52 \\ + \verb|\textfiveoldstyle| & \textfiveoldstyle & 53 \\ + \verb|\textsixoldstyle| & \textsixoldstyle & 54 \\ + \verb|\textsevenoldstyle| & \textsevenoldstyle & 55 \\ + \verb|\texteightoldstyle| & \texteightoldstyle & 56 \\ + \verb|\textnineoldstyle| & \textnineoldstyle & 57 \\ + \verb|\textmho| & \textmho & 77 \\ + \verb|\textbigcircle| & \textbigcircle & 79 \\ + \verb|\textlbrackdbl| & \textlbrackdbl & 91 \\ + \verb|\textrbrackdbl| & \textrbrackdbl & 93 \\ + \verb|\textasciigrave| & \textasciigrave & 96 \\ + \verb|\textborn| & \textborn & 98 \\ + \bottomrule + \end{tabular}\qquad + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textdivorced| & \textdivorced & 99 \\ + \verb|\textdied| & \textdied & 100 \\ + \verb|\textleaf| & \textleaf & 108 \\ + \verb|\textmarried| & \textmarried & 109 \\ + \verb|\textmusicalnote| & \textmusicalnote & 110 \\ + \verb|\texttildelow| & \texttildelow & 126 \\ + \verb|\textdblhyphenchar| & \textdblhyphenchar & 127 \\ + \verb|\textasciibreve| & \textasciibreve & 128 \\ + \verb|\textasciicaron| & \textasciicaron & 129 \\ + \verb|\textacutedbl| & \textacutedbl & 130 \\ + \verb|\textgravedbl| & \textgravedbl & 131 \\ + \verb|\textdollaroldstyle| & \textdollaroldstyle & 138 \\ + \verb|\textcentoldstyle| & \textcentoldstyle & 139 \\ + \verb|\textnaira| & \textnaira & 143 \\ + \verb|\textguarani| & \textguarani & 144 \\ + \verb|\textpeso| & \textpeso & 145 \\ + \verb|\textrecipe| & \textrecipe & 147 \\ + \verb|\textpertenthousand| & \textpertenthousand & 152 \\ + \verb|\textpilcrow| & \textpilcrow & 153 \\ + \verb|\textbaht| & \textbaht & 154 \\ + \verb|\textdiscount| & \textdiscount & 156 \\ + \verb|\textopenbullet| & \textopenbullet & 158 \\ + \verb|\textservicemark| & \textservicemark & 159 \\ + \verb|\textlquill| & \textlquill & 160 \\ + \verb|\textrquill| & \textrquill & 161 \\ + \verb|\textasciidieresis| & \textasciidieresis & 168 \\ + \verb|\textcopyleft| & \textcopyleft & 171 \\ + \verb|\textcircledP| & \textcircledP & 173 \\ + \verb|\textasciimacron| & \textasciimacron & 175 \\ + \verb|\textasciiacute| & \textasciiacute & 180 \\ + \verb|\textreferencemark| & \textreferencemark & 184 \\ + \verb|\textsurd| & \textsurd & 187 \\ + \null \\ + \bottomrule + \end{tabular} + \caption{Symbols unavailable in \texttt{TS1} sub-encoding \texttt{2} + and higher} + \label{tab:ts1-subset-2-disable} +\end{table} + + +\begin{table}[!tbp] + \centering\footnotesize + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|textlangle| & \textlangle & 60 \\ + \bottomrule + \end{tabular}\qquad + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textrangle| & \textrangle & 62 \\ + \bottomrule + \end{tabular} + \caption{Symbols unavailable in \texttt{TS1} sub-encoding \texttt{3} + and higher} + \label{tab:ts1-subset-3-disable} +\end{table} + + +Thus, the symbols that are available in sub-encoding $x$ are the symbols +in table~\ref{tab:ts1-subset-always} (always available) and the symbols +that only become unavailable in sub-encodings $> x$. The tables +\vrefrange{tab:ts1-subset-1-disable}{tab:ts1-subset-9-disable} show the symbols that +become unavailable in the different sub-encodings. Again, the numbers +are the slots in the |TS1| encoding, |acc| indicates a `constructed' +accent. + +\newpage + + + +\begin{table}[!tbp] + \centering\footnotesize + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textleftarrow| & \textleftarrow & 24 \\ + \verb|\textrightarrow| & \textrightarrow & 25 \\ + \verb|\textuparrow| & \textuparrow & 94 \\ + \verb|\textdownarrow| & \textdownarrow & 95 \\ + \bottomrule + \end{tabular}\qquad + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textcolonmonetary| & \textcolonmonetary & 141 \\ + \verb|\textwon| & \textwon & 142 \\ + \verb|\textlira| & \textlira & 146 \\ + \verb|\textdong| & \textdong & 150 \\ + \bottomrule + \end{tabular} + \caption{Symbols unavailable in \texttt{TS1} sub-encoding \texttt{4} + and higher} + \label{tab:ts1-subset-4-disable} +\end{table} + + +\begin{table}[!tbp] + \centering\footnotesize + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textnumero| & \textnumero & 155 \\ + \bottomrule + \end{tabular}\qquad + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textestimated| & \textestimated & 157 \\ + \bottomrule + \end{tabular} + \caption{Symbols unavailable in \texttt{TS1} sub-encoding \texttt{5} + and higher} + \label{tab:ts1-subset-5-disable} +\end{table} + + + +\begin{table}[!tbp] + \centering\footnotesize + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textflorin| & \textflorin & 140 \\ + \bottomrule + \end{tabular}\qquad + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textcurrency| & \textcurrency & 164 \\ + \bottomrule + \end{tabular} + \caption{Symbols unavailable in \texttt{TS1} sub-encoding \texttt{6} + and higher} + \label{tab:ts1-subset-6-disable} +\end{table} + + + +\begin{table}[!tbp] + \centering\footnotesize + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textfractionsolidus| & \textfractionsolidus & 47 \\ + \verb|\textminus| & \textminus & 61 \\ + \bottomrule + \end{tabular}\qquad + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textohm| & \textohm & 87 \\ + \verb|\textmu| & \textmu & 181 \\ + \bottomrule \end{tabular} -\caption{Text symbols formerly from the \textsf{textcomp} package} -\label{tab:textcomp} + \caption{Symbols unavailable in \texttt{TS1} sub-encoding \texttt{7} + and higher} + \label{tab:ts1-subset-7-disable} \end{table} + + +\begin{table}[!tbp] + \centering\footnotesize + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textblank| & \textblank & 32 \\ + \verb|\textinterrobang| & \textinterrobang & 148 \\ + \bottomrule + \end{tabular}\qquad + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\textinterrobangdown| & \textinterrobangdown & 149 \\ + \null \\ + \bottomrule + \end{tabular} + \caption{Symbols unavailable in \texttt{TS1} sub-encoding \texttt{8} + and higher} + \label{tab:ts1-subset-8-disable} +\end{table} + + +\begin{table}[!tbp] + \centering\footnotesize + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\texttwelveudash| & \texttwelveudash & 21 \\ + \verb|\textthreequartersemdash| & \textthreequartersemdash & 22 \\ + \verb|\textbardbl| & \textbardbl & 134 \\ + \verb|\textcelsius| & \textcelsius & 137 \\ + \bottomrule + \end{tabular}\qquad + \begin{tabular}[t]{@{}lp{1.5em}l@{}} + \toprule + \verb|\texttwosuperior| & \texttwosuperior & 178 \\ + \verb|\textthreesuperior| & \textthreesuperior & 179 \\ + \verb|\textonesuperior| & \textonesuperior & 185 \\ + \null \\ + \bottomrule + \end{tabular} + \caption{Symbols unavailable in \texttt{TS1} sub-encoding \texttt{9}} + \label{tab:ts1-subset-9-disable} +\end{table} + + + +As an example, +%\begin{verbatim} + \verb=\DeclareEncodingSubset{TS1}{foo}{5}= +%\end{verbatim} +indicates that the font family |foo| contains the always available +symbols (table~\vref{tab:ts1-subset-always}) and the ones disabled +in sub-encodings 6--9, i.e., +tables~\vrefrange{tab:ts1-subset-6-disable}{tab:ts1-subset-9-disable}. + +As these days many font families are set up to end in |-LF| (lining +figures), |-OsF| (oldstyle figures), etc. the declaration supports a +shortcut: if the \m{font family} name ends in |-*| then the star gets +replaced by these common ending, e.g., +\begin{verbatim} + \DeclareEncodingSubset{TS1}{Alegreya-*}{2} +\end{verbatim} +is the same as writing +\begin{verbatim} + \DeclareEncodingSubset{TS1}{Alegreya-LF} {2} + \DeclareEncodingSubset{TS1}{Alegreya-OsF} {2} + \DeclareEncodingSubset{TS1}{Alegreya-TLF} {2} + \DeclareEncodingSubset{TS1}{Alegreya-TOsF}{2} +\end{verbatim} +If only some are needed then one can define them individually but in +many cases all four are wanted, hence the shortcut. + + + + \section{If you need to know more \ldots} \NEWdescription{1996/06/01} diff --git a/macros/latex-dev/base/fontdef.dtx b/macros/latex-dev/base/fontdef.dtx index 581cfeb789..06af8feefd 100644 --- a/macros/latex-dev/base/fontdef.dtx +++ b/macros/latex-dev/base/fontdef.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -164,7 +164,7 @@ % \end{quote} % % -% \StopEventually{} +% \MaybeStop{} % % \section{The \texttt{docstrip} modules} % diff --git a/macros/latex-dev/base/format.ins b/macros/latex-dev/base/format.ins index eece2f57ef..88d33d3c4e 100644 --- a/macros/latex-dev/base/format.ins +++ b/macros/latex-dev/base/format.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. @@ -88,7 +88,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 2015-2021 +Copyright (C) 2015-2022 The LaTeX Project and any individual authors listed elsewhere in this file. @@ -123,7 +123,7 @@ extension .ins) which are part of the distribution. This is a generated file. -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. @@ -174,6 +174,7 @@ the system are in the document `cfgguide.tex'. \from{lterror.dtx}{2ekernel} \from{ltpar.dtx}{2ekernel} \from{ltpara.dtx}{2ekernel} % L3 layer module + \from{ltmeta.dtx}{2ekernel} % L3 layer module \from{ltspace.dtx}{2ekernel} \from{ltlogos.dtx}{2ekernel} \from{ltfiles.dtx}{2ekernel} @@ -203,6 +204,7 @@ the system are in the document `cfgguide.tex'. \from{ltbibl.dtx}{2ekernel} \from{ltpage.dtx}{2ekernel} \from{ltclass.dtx}{2ekernel,tracerollback} + \from{ltkeys.dtx}{2ekernel} % L3 layer module \from{ltfilehook.dtx}{2ekernel} % L3 layer module \from{ltshipout.dtx}{2ekernel} % L3 layer module \from{ltoutput.dtx}{2ekernel} diff --git a/macros/latex-dev/base/graphpap.dtx b/macros/latex-dev/base/graphpap.dtx index cc9f4da3cb..78bb688f83 100644 --- a/macros/latex-dev/base/graphpap.dtx +++ b/macros/latex-dev/base/graphpap.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -65,7 +65,7 @@ % The default value of \emph{N} is 10. % The arguments must all be integers. % -% \StopEventually +% \MaybeStop % % First, we define three counters. The first two are defined % as raw TeX counters since multiplication and division must be diff --git a/macros/latex-dev/base/graphpap.ins b/macros/latex-dev/base/graphpap.ins index 65156ad917..d82cbd6670 100644 --- a/macros/latex-dev/base/graphpap.ins +++ b/macros/latex-dev/base/graphpap.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/graphpap.pdf b/macros/latex-dev/base/graphpap.pdf Binary files differindex 94407af25e..f0a6a4a89c 100644 --- a/macros/latex-dev/base/graphpap.pdf +++ b/macros/latex-dev/base/graphpap.pdf diff --git a/macros/latex-dev/base/idx.tex b/macros/latex-dev/base/idx.tex index 8257396f81..bc0dd71021 100644 --- a/macros/latex-dev/base/idx.tex +++ b/macros/latex-dev/base/idx.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ifthen.dtx b/macros/latex-dev/base/ifthen.dtx index acb5cf1967..0bf54b619a 100644 --- a/macros/latex-dev/base/ifthen.dtx +++ b/macros/latex-dev/base/ifthen.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -164,7 +164,7 @@ % With \meta{test} as above, repeatedly executes \meta{while clause} % while the test remains true. % -% \StopEventually{} +% \MaybeStop{} % % \section{The Implementation} % diff --git a/macros/latex-dev/base/ifthen.ins b/macros/latex-dev/base/ifthen.ins index 42e1d3f5d9..88047e94f0 100644 --- a/macros/latex-dev/base/ifthen.ins +++ b/macros/latex-dev/base/ifthen.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/ifthen.pdf b/macros/latex-dev/base/ifthen.pdf Binary files differindex 9477b74355..c304cd4801 100644 --- a/macros/latex-dev/base/ifthen.pdf +++ b/macros/latex-dev/base/ifthen.pdf diff --git a/macros/latex-dev/base/inputenc.dtx b/macros/latex-dev/base/inputenc.dtx index 1b8691d30f..e056f8ffd7 100644 --- a/macros/latex-dev/base/inputenc.dtx +++ b/macros/latex-dev/base/inputenc.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -379,8 +379,8 @@ % as these commands haven't been available in \textsf{inputenc} distributed % with older releases of \LaTeX{}. % - -% \StopEventually{} +% +% \MaybeStop{} % % \section{Announcing the files} % diff --git a/macros/latex-dev/base/inputenc.ins b/macros/latex-dev/base/inputenc.ins index 920a585bff..adacf9efce 100644 --- a/macros/latex-dev/base/inputenc.ins +++ b/macros/latex-dev/base/inputenc.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/inputenc.pdf b/macros/latex-dev/base/inputenc.pdf Binary files differindex a358befe3a..96d79b25d6 100644 --- a/macros/latex-dev/base/inputenc.pdf +++ b/macros/latex-dev/base/inputenc.pdf diff --git a/macros/latex-dev/base/lablst.tex b/macros/latex-dev/base/lablst.tex index da2d7dbceb..0821b0e4f0 100644 --- a/macros/latex-dev/base/lablst.tex +++ b/macros/latex-dev/base/lablst.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/lamport-manual.pdf b/macros/latex-dev/base/lamport-manual.pdf Binary files differindex 69f63c0b69..54d2c31952 100644 --- a/macros/latex-dev/base/lamport-manual.pdf +++ b/macros/latex-dev/base/lamport-manual.pdf diff --git a/macros/latex-dev/base/latex209.dtx b/macros/latex-dev/base/latex209.dtx index bf92f8ef1e..768f7237a5 100644 --- a/macros/latex-dev/base/latex209.dtx +++ b/macros/latex-dev/base/latex209.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -166,7 +166,7 @@ % \changes{v0.11}{1994/01/21}{Split package into head and tail.} % \changes{v0.23}{1994/05/11}{Added bezier option.} % -% \StopEventually{} +% \MaybeStop{} % % \section{Driver} % diff --git a/macros/latex-dev/base/latex209.ins b/macros/latex-dev/base/latex209.ins index 33ebc2488c..f530347a3c 100644 --- a/macros/latex-dev/base/latex209.ins +++ b/macros/latex-dev/base/latex209.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/latexchanges.pdf b/macros/latex-dev/base/latexchanges.pdf Binary files differdeleted file mode 100644 index 9787da6ce8..0000000000 --- a/macros/latex-dev/base/latexchanges.pdf +++ /dev/null diff --git a/macros/latex-dev/base/latexchanges.tex b/macros/latex-dev/base/latexchanges.tex deleted file mode 100644 index 933ea48ddb..0000000000 --- a/macros/latex-dev/base/latexchanges.tex +++ /dev/null @@ -1,1025 +0,0 @@ -% \iffalse meta-comment -% -% Copyright (C) 2015-2021 -% The LaTeX Project and any individual authors listed elsewhere -% in this file. -% -% This file is part of the LaTeX base system. -% ------------------------------------------- -% -% It may be distributed and/or modified under the -% conditions of the LaTeX Project Public License, either version 1.3c -% of this license or (at your option) any later version. -% The latest version of this license is in -% http://www.latex-project.org/lppl.txt -% and version 1.3c or later is part of all distributions of LaTeX -% version 2008 or later. -% -% This file has the LPPL maintenance status "maintained". -% -% The list of all files belonging to the LaTeX base distribution is -% given in the file `manifest.txt'. See also `legal.txt' for additional -% information. -% -% The list of derived (unpacked) files belonging to the distribution -% and covered by LPPL is defined by the unpacking scripts (with -% extension .ins) which are part of the distribution. -% -% \fi -% Filename: latexchanges.tex - -\NeedsTeXFormat{LaTeX2e} - -\documentclass{ltxguide} - -\usepackage[T1]{fontenc} - -\usepackage{url} - -\title{Changes to the \LaTeXe{} format} - -\author{\copyright~Copyright 2015--2021, \LaTeX\ Project Team.\\ - All rights reserved.} - -\date{2021-06-08} - -% a few commands from doc -\newcommand\Lpack[1]{\mbox{\textsf{#1}}} -\newcommand\DescribeMacro[1]{\texttt{\string#1}} - -\newcommand\pkg[1]{\texttt{#1}} -\newcommand\cs[1]{\texttt{\textbackslash #1}} - -\makeatletter % -- provide command introduced in new release - % so this typesets with an old format - -\DeclareTextCommandDefault\textcommabelow[1] - {\hmode@bgroup\ooalign{\null#1\crcr\hidewidth\raise-.31ex - \hbox{\check@mathfonts\fontsize\ssf@size\z@ - \math@fontsfalse\selectfont,}\hidewidth}\egroup} - -\makeatother - - - -\ifx\href\undefined - \newcommand\ghissue[1]{github #1} - \newcommand\gnatsissue[1]{gnats #1} - \newcommand\ltnewsissue[1]{\LaTeX\ News~#1} - \newcommand\sxanswer[1]{\url{https://tex.stackexchange.com\slash a\slash #1}} - \newcommand\sxquestion[1]{\url{https://tex.stackexchange.com\slash q\slash #1}} -\else - \newcommand\ghissue[1]{% - \href{https://github.com/latex3/latex2e/issues/#1}{github #1}} - \newcommand\gnatsissue[1]{% - \href{https://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex/#1}{gnats #1}} - \newcommand\ltnewsissue[1]{% - \href{https://www.latex-project.org/news/latex2e-news/ltnews#1.pdf}{\LaTeX\ News~#1}} - \newcommand\sxanswer[1]{% - \url{https://tex.stackexchange.com/a/#1}} - \newcommand\sxquestion[1]{% - \url{https://tex.stackexchange.com/q/#1}} -\fi - - -\setcounter{tocdepth}{1} % don't show subsections - - -\begin{document} - -\maketitle - -\begin{abstract} -This document describes changes that were made to the -\LaTeX\ format since the 2014-05-01 \LaTeX\ releases. - - -As announced in \ltnewsissue{22}, the 2015 \LaTeX{} release adopts a new -policy. Improvements and bug fixes will be made to the format sources, -with the \Lpack{latexrelease} package being available to revert -changes to use definitions from an earlier format. - -As a summary of changes for a main release will always be available in -\LaTeX\ News, detailed changes are not repeated in this document, -but changes in any patch releases will be listed in more -detail here. - -More detailed change logs are available as -\texttt{changes.txt} in the base distribution, and full code - differences may be browsed via the code repository on GitHub -see for example -\url{https://github.com/latex3/latex2e/commits/master}. -\end{abstract} - -\tableofcontents - -\newpage - -%\section{Introduction} - -\section{Changes introduced in 2021-06-01 patch~1} - -A further refinement to the handling of ``raw'' option lists added -in the last release, see \ghissue{508}. - -Fixes an issue with rollback when \pkg{latexrelease} is loaded by some -other package (as done for \texttt{platex} (\ghissue{577}). - -First aid for \pkg{ulem} and \pkg{varwidth} got added to help them -along until they get corrected. \pkg{ulem} has a problem with the -improved definition of \cs{hspace} and \pkg{varwidth} chokes on a -newly introduced glue item in vertical lists, which is needed for -paragraph hook handling (\ghissue{583}). - - -\section{Changes introduced in 2021-06-01} - -The focus of this release is to provide further important building -blocks for the future production of reliable tagged PDF output. Many -other improvements have been made. Please see \ltnewsissue{33} for an -overview of the new features and the change log in -\texttt{changes.txt} for a more detailed list of individual changes. - -\section{Changes introduced in 2020-10-01 patch~4} - -This patch fixed two bugs in the hook management: if debugging for the -L3 programming layer was turned on it reported inconsistent use of -local/global variables. This was a spurious warning but nevertheless -disconcerting (\ghissue{463}). The other bug was more serious, in some -situations a wrong value of \verb=\CurrentFile= inside of file-related hooks -could lead to errors (\ghissue{464}). - -We also added the documentation file \texttt{usrguide3.pdf} which -will become the main home for documenting new features of \LaTeX. At -this point in time it covers the \Lpack{xparse} functionality that has -been added to the kernel. - -\section{Changes introduced in 2020-10-01 patch~3} - -This patch fixed some rollback issues that prevented successful -rollback to other release levels in some cases. It also fixed an issue -with file hooks involving files with explicit paths (\ghissue{422}). - -One important change was to handle hook declarations done in the -document preamble in a special way, e.g., those done with -\verb=\AtBeginDocument=. They are now always executed last and are not -subject to the normal code sorting for hooks, because they are nearly always -needed to overwrite earlier settings made in packages. - -Finally, the NFSS series handling was slightly changed to -automatically drop surplus ``\texttt{m}''s from series specifications -when needed (and warn about them when encountered), e.g., -``\texttt{mc}'' automatically becomes ``\texttt{c}'' which is the -official NFSS name for a \emph{medium compact} series (\ghissue{453}). -This was done to improve the fix in 2020-02-02 PL~5. - -\section{Changes introduced in 2020-10-01 patch~2} - -This patch fixed the passing of options to packages and classes when -they are stored in a special place (denoted by \verb=\input@path=) -instead of their normal location (\ghissue{414}). In that case the -options got lost. - -\section{Changes introduced in 2020-10-01 patch~1} - -This patch fixed a file handling issue: to allow for spaces in file -names quotes were used but this upsets Bib\TeX{} (\ghissue{400}). In -addition, two rollback issues got corrected. - -\section{Changes introduced in 2020-10-01} - -Major enhancements in this release include pre-loading of the -\Lpack{xparse} package for producing document-level commands with more -complicated argument signatures and the new hook management system for -\LaTeX{} documented in \texttt{lthooks-doc.pdf}, -\texttt{ltfilehook-doc.pdf} and \texttt{ltshipout-doc.pdf}. - -In addition there have been many smaller fixes and enhancements. -Please see \ltnewsissue{32} for an overview of the new features and -the change log in \texttt{changes.txt} for a more detailed list of -individual changes. - -\section{Changes introduced in 2020-02-02 patch~5} - -The patch~4 dropped a bit too much in certain situations, e.g., it -changed a series value of \texttt{semibold} (as used by -\texttt{autoinst}) to \texttt{seibold}, rendering it useless. So we -now only correct series values if they are a member of the -following list: \texttt{ulm}, \texttt{elm}, \texttt{lm}, \texttt{slm}, -\texttt{mm}, \texttt{sbm}, \texttt{bm}, \texttt{ebm}, \texttt{ubm}, -\texttt{muc}, \texttt{mec}, \texttt{mc}, \texttt{msc}, \texttt{msx}, -\texttt{mx}, \texttt{mex} or \texttt{mux}. Here we assume that people -intended to follow the NFSS convention but somehow got it wrong. So we -drop one ``m'' and also add a warning that the -\verb=\DeclareFontShape= declaration in question should be updated -(\ghissue{293}). - - -\section{Changes introduced in 2020-02-02 patch~4} - -In some cases the \texttt{filecontents} environment was opening the -file for writing without quoting it, so that files with spaces failed -(\ghissue{284}). - -Ensure that \verb=\DeclareFontShape= drops surplus ``m'' in situations -where an \texttt{.fd} incorrectly specifies \texttt{mc} instead of -\texttt{c}, etc.\ (\ghissue{289}). - -\section{Changes introduced in 2020-02-02 patch~3} - -Support the following scenario: -\begin{verbatim} -\fontfamily{ptm}\selectfont text \textbf{\sffamily bold sans text} -\end{verbatim} -The default bold series for \texttt{ptm} is \texttt{b} so -\verb=\textbf= switches to that. The \verb=\sffamily= then tried to -find \texttt{OT1/cmss/b/n} which doesn't exist instead of first -altering the series default to use \texttt{bx} as needed for Computer -Modern Sans Serif. This has now been corrected (\ghissue{277}). - - -\section{Changes introduced in 2020-02-02 patch~2} - -Correct \verb=\capitalacute=, etc.\ so that they work in -\texttt{tabbing} (\ghissue{271}). Provide \verb=\@defaultfamilyhook= to -support CJK packages (\ghissue{269}). Provide a list of \texttt{fontenc} -loads with their options in \verb=\@fontenc@load@list= so that Babel -can determine the right \verb=\latinencoding= value (\ghissue{273}). - - -\section{Changes introduced in 2020-02-02 patch~1} - -Fixed a misspelled command name that caused trouble (\ghissue{264}). Make -\texttt{textcomp} package issue only info messages about glyph -substitutions (\ghissue{262}) and warn if it attempts to run in an old format (\ghissue{260}). - -\section{Changes introduced in 2020-02-02} - -Major enhancements in this release include pre-loading \Lpack{expl3} -to improve startup times, especially with Lua\TeX\ and Xe\TeX, and -extra features in the font selection mechanism. Please see -\ltnewsissue{31} for an overview of the new features and the change -log in \texttt{changes.txt} for a more detailed list of individual -changes. - - -\section{Changes introduced in 2019-10-01 patch~3} - -Further fixes to the handling of filenames, expand macros (and -\verb|\jobname| \emph{before} removing \verb|"|, not after. - -\section{Changes introduced in 2019-10-01 patch~2} - -Further fixes to the handling of filenames, \ghissue{204}: non-ascii -filenames and filenames with spaces and multiple dots should now work -in \verb|\includegraphics|. - -Reclassify some luatex callbacks. Other fixes for Issues raised: -\ghissue{198}, \ghissue{201}, \ghissue{202}, \ghissue{205}. - -\section{Changes introduced in 2019-10-01 patch~1} - -Adjustments to \verb|\set@curr@file|, and \verb|\@extracolsep|. - -Added missing \verb=\else= branch in \texttt{nfssfont} so that -\verb=\action= is executed if provided. - -\section{Changes introduced in 2019-10-01} - -Introduced \LaTeX\texttt{-dev} formats for pre testing future \LaTeX{} -releases. Now there's a \texttt{latex-base-dev} package on CTAN which -contains a pre-release of the \LaTeXe{} kernel and both \TeX Live and -MiK\TeX{} include the standard \LaTeX{} executables (\texttt{pdflatex}, -\texttt{lualatex}, etc.) with \texttt{-dev} appended, which use the -pre-release format. - -The handling of Unicode characters was improved by making them safe -inside \verb|\ref|s and \verb|\label|s, by using \verb|\ifincsname| -to make these characters safe in these contexts (\ghissue{95}). - -In line with the better handling of Unicode characters, file names -can now contain any Unicode character plus spaces, as these cases -are now correctly handled by the kernel. - -An optional argument was added to the \texttt{filecontents} environment, -to which a comma-separated list of options can be given. The options -include \texttt{overwrite} (or \texttt{force}), \texttt{nosearch}, and -\texttt{noheader} (which has the same effect as the starred form of the -environment). The environment is now allowed anywhere in the document. - -A plethora of \LaTeX{} commands was made robust so that fewer -\verb|\protect| are needed when using some commands in moving arguments. -There are a few border cases where it's tricker to make the command -robust or where it's not worth it to do so, but most reasonable use -cases are covered. The most notable change was \verb|\begin| and -\verb|\end|, which are now robust and won't break when used in moving -arguments. - -An extra \verb|\hskip 1sp| was added to \verb|c|-column table cells to -protect against the presence of an \verb|\unskip| in the table cell -(\ghissue{102}). - -\texttt{U+012F} which is ``i with ogonek'' should produce an -``i'' and not a ``dotless i''. This has been corrected -(\ghissue{122}). - -The Unicode slots \texttt{27E8} and \texttt{27E9} have been mapped to -\verb|textlangle| and \verb|textrangle| which is the recommended mapping -(\ghissue{110}). - -Basic ligatures (ff, fi, fl, ffi, ffl, ft, st) can now be input as a -single unicode character in pdf\TeX, which is useful when copy-pasting -(\ghissue{154}). - -\verb|\InputIfFileExists{foo}{\input{bar}}{}| -did not load the files \texttt{foo.tex} and \texttt{bar.tex} but -would load \texttt{bar.tex} twice. This has been corrected (\ghissue{109}). - -The \textsf{fncylab} and \textsf{varioref} packages changed \LaTeX's internal -counter prefix commands \verb|p@...| so that they would take the counter -value as an argument instead of just acting as a prefix to them. These -packages also provided the \verb|\labelformat| macro to change the prefix -macro and \verb|\Ref| so that using counters defined that way in the -beginning of sentences would have the proper capitalization. These features -were added to the \LaTeXe{} kernel. - -The kernel now says ``Trying to load\ldots'' -instead of ``Try loading \ldots'' in one of its informal -messages to match style of similar messages (\ghissue{107}). - -\verb|\DeclareErrorFont| would change the font size to 10\,pt which, when -used in the wrong place, would make incorrect font settings in the document. -This has now been fixed (\gnatsissue{4399}). - -The default action of the file \texttt{nfssfont.tex} was set to produce a -font table, so that one can simply hit enter instead of having to write -\verb=\table\bye=. - -The \LaTeX{} kernel now provides dummy (empty) definitions for the two -commands \verb|\conditionally@traceoff| and -\verb|\conditionally@traceon| from the \texttt{trace} package so they -can be used by package developers without worrying about them being -defined or not (\ghissue{164}). - - - - - -\section{Changes introduced in 2018-12-01} - -Further additions to the characters supported by default in UTF-8. -The commands \verb|\guillemetleft| and \verb|\guillemetright| are -provided as alias for the names based on the Adobe font names -(\ghissue{65}). - -The use of potrusion in tables of contents is suppressed by default, -see \sxquestion{172785}. - -The handling of visible space in verbatim was adjusted for -\ghissue{69} and \ghissue{70}. - -Spaces are removed from the argument passed to BiBTeX, \ghissue{88}. - -New commands \verb|\Hwithstroke| and \verb|\hwithstroke| added to T1 encoding support. - -The internal box structure for floats is adjusted to preserve box -levels of split hyperlinks, avoiding a fatal pdftex error. \ghissue{94}. - - -\section{Changes introduced in 2018-04-01 patch~5} -Improved support for non ASCII filenames on the command line on -filesystems using legacy encodings. - -Adjusted the new package rollback code so that some edge cases where rollback -can not be guaranteed become a warning not an error. - -\section{Changes introduced in 2018-04-01 patch~4} -No changes to the format, but \texttt{docstrip} adjusted so that non-ASCII -\texttt{.ins} files work with the new UTF-8 defaults. - -\section{Changes introduced in 2018-04-01 patch~3} -Additional adjustments for GitHub issues \ghissue{34} and \ghissue{38}, adjustment to the -location of some documentation files, such as \texttt{source2e.tex} to -be installed in the documentation sources not the default \TeX\ input -tree. - - -\section{Changes introduced in 2018-04-01 patch~2} -Additional adjustments for GitHub issues \ghissue{32} and \ghissue{33}. - -\section{Changes introduced in 2018-04-01 patch~1} -Make \verb|\UseRawInputEncoding| and \Lpack{latexrelease} reset \verb|\inputencodingname| -when disabling the UTF-8 input handling. - -\section{Changes introduced in 2018-04-01} -Further details of changes at this release are given in \ltnewsissue{28}, but in brief -the main changes are as listed below. - -The default encoding for files has been changed to UTF-8. - -A new possibility to refer to older versions of packages has been added. - -New commands previously available in \Lpack{remreset} and -\Lpack{chngcntr} packages for controlling counters have been added. - -The definition of \verb|\@ifundefined| has been refined to use the e-\TeX \verb|\ifcsname| -primitive when available, and to avoid defining the command being tested to be \verb|\relax| -in the case that it was previously undefined. - -\section{Changes introduced in 2017-04-15} -Optionally, \LaTeX{} format and package dates may use ISO style dates with -\texttt{-} rather than \texttt{/}. - -For Unicode \TeX{}s, made further adjustments to the composite accent -code in \texttt{tuenc.def}, and further updates tracking changes in -Lua\TeX, now at 1.04. - -Previously defining an encoding-specific composite with an undeclared -accent (or an accent declared later) gave no error, but did nothing useful. -\LaTeX\ will now detect this and give the accent command a default definition -as an error, allowing the declared composite to work as intended. - -The definition of \verb|\-| is adjusted to match the comments in -\gnatsissue{3855} to accommodate non standard settings of \verb|\hyphenchar|. - -In parboxes and similar settings, \verb|\lineskiplimit| is now -reset (to the existing default value, \verb|\normallineskiplimit|). -See \sxanswer{359934}. - - The code for \verb|\newpage| has been adjusted to add a test on the value of -\verb|\prevdepth| so that the depth of the last line is preserved in -forced page breaks. - -\section{Changes introduced in 2017/01/01 patch~3} -Emergency patch to correct a typo in a change introduced in patch~2. - -\section{Changes introduced in 2017/01/01 patch~2} -More adjustments for TU encoding, allowing for characters missing in -common system fonts. Additional \texttt{fd} files -for Latin Modern variants are included in the documented sources. - -\section{Changes introduced in 2017/01/01 patch~1} -Fixes to TU encoding definitions for Lua\TeX\ and Xe\TeX. - -\section{Changes introduced in 2017/01/01} - -A new test is added during format making that e\TeX\ extensions are -available. As noted in \LaTeX\ news, e\TeX\ will now be required to -build \LaTeX. - -Further updates tracking changes for Lua\TeX~1.0. - -The definition of \verb|\showhyphens| is changed in formats built -with Xe\TeX, as the original version, inherited from plain \TeX\ does -not work with Xe-\TeX. - -Changes to the default encoding used by Lua\TeX\ and Xe\TeX\ formats to -be TU (Unicode) rather than OT1 (7 bit legacy \TeX\ encoding). - -\section{Changes introduced in 2016/03/31 patch~3} -Fixes to \verb|\newinsert| and \verb|\extrafloats|. - -\section{Changes introduced in 2016/03/31 patch~2} -Adjustments to \verb|\c{g}| in OT1 encoding. - -\section{Changes introduced in 2016/03/31 patch~1} -Adjust the upper limit for Character Class allocation in Xe-\TeX\ to -4096 to match a change in Xe-\TeX. - -\section{Changes introduced in 2016/03/31} -Modify picture mode as suggested in latex/4452 to avoid leaders of -almost zero length. - -Modify the checks in \verb|\DeclareMathSymbol| and related commands -so that they do not give errors with new Lua\TeX\ releases. - -\section{Changes introduced in 2016/02/01} -Adjustments to Lua\TeX\ support to match changes to the Lua\TeX\ engine, -and to the character class allocation in Xe\TeX. - -Load Unicode data from new generic \texttt{unicode-data} distribution. - -\section{Changes introduced in 2015/10/01 patch~2} - -This release fixes the behavior of the allocation mechanism if the switch -from the standard to extended pool takes place within a group. - -\section{Changes introduced in 2015/10/01 patch~1} -This release allows \Lpack{latexrelease} to revert the -Lua\TeX{}-specific -changes, in particular fixing an incorrect date in part of the mechanism and -adding a method to disable callback management entirely. - -\section{Changes introduced in \LaTeX\ 2015/10/01} - -\subsection{LuaTeX allocation} -Almost all changes at this release relate to incorporating allocation macros for luatex into the format -as done for etex and xetex in 2015/01/01. For details see |ltluatex.dtx| or \ltnewsissue{22}. -|ltluatex.dtx| now forms a new chapter (N) in the documented sources, |source2e.tex|. - - -\subsection{Increased number of floats} -The default float list has been increased from 18 to 52 registers if -e\TeX\ is available. -The list can be increased further using |\extrafloats| however this -default allocation uses classic registers below 256 so the registers are -also available for |\newinsert| as described below. - -\subsection{Improved \texttt{\textbackslash newinsert}} -The command |\newinsert| has been extended to take registers from the lists of free float -registers once the classic register allocation is used up. This should make it highly unlikely -to get ``no room'' errors on register allocation assuming the format is used with -an e-\TeX\ based \TeX\ engine. - -\subsection{New accent, \texttt{\textbackslash textcommabelow} (pr/4414)} -The command |\textcommabelow| has been added. This is mainly intended for Romanian letters -\textcommabelow{S}\,\textcommabelow{s}\,\textcommabelow{T}\,\textcommabelow{t}. - -\subsection{Unicode 8} -The file |unicode-letters.def| used to initialize character data in -Unicode \TeX\ variants has been regenerated from data files updated -to Unicode~8. - -\section{Changes introduced in 2015/01/01 patch~2} -There were no changes to the format at this release, but the sources were fixed to fix bug latex/4434 -affecting bottom float positioning if the \Lpack{latexrelease} package was used. - -\section{Changes introduced in 2015/01/01 patch~1} -This release re-introduces the ``Patch Level'' scheme for identifying -releases between main ``dated'' releases. Early \LaTeXe\ releases -included a mechanism whereby updates could be provided by a -\emph{patch - file}. This was mainly intended to allow updates to be made without -downloading the full sources again, which was an important -consideration with download speeds and costs at the time. - -The new mechanism incorporates any changes directly into the sources, -but having the patch level identified in the banner allows the -\LaTeX\ release to be identified, even if (as in this case) most of the -changes do not affect the format but affect other base packages such -as \Lpack{latexrelease} and \Lpack{inputenc}. The patch level is shown -in the banner at the start of the job, but does not affect the date -handling of the |\IncludeInRelease| mechanism. - -Apart from re-arranging the version banner, the only change in the -format is that |\newtoks| was accidentally defined twice, using the -old and new allocation scheme described in Section \ref{e@alloc}. -The old definition is now only in the \Lpack{latexrelease} package, -for use when emulating old formats. - - - - -\section -[Changes between \LaTeX\ releases 2014/05/01 and 2015/01/01] -{Changes between \LaTeX\ releases 2014/05/01 and 2015/01/01\footnote{Much of this text -is taken from \Lpack{fixltx2e} package which was formerly used to make such changes available separately.}} - -\subsection{Support for \LaTeX\ version changes} -\DescribeMacro{\includeInRelease}\arg{date}\oarg{date}\arg{label}\arg{message}\arg{code} - -\smallskip - -The |\includeInRelease| command has been added to support backward and -forward compatibility for the \LaTeX\ format. It supports the -declaration of conditional code that can be loaded based on options -given to the \Lpack{latexrelease} package. Its use is described in -detail in the \Lpack{latexrelease} package documentation. - -\subsection{New Allocation Code\label{e@alloc}} -Previously |\newcount| and related commands were based on classic TeX -and only allocated in the range 0--255. This was extended (in -different ways) for e-\TeX\ in the |etex| package and in the -|xelatex.ini| and |lualatex.ini| files used in those formats. Related -to this the number of boxes allocated to store floats was -limited. This was extended to a certain extent in the |morefloats| -package (by Don Hosek and H.-Martin Muench) but the new allocation -incorporates float allocation directly and supports much larger float -lists using the extended registers. - -The new code allocates registers in the full extended range ( -$2^{15}-1$ for etex and xelatex, $2^{16}-1$ for lualatex. -In addition a new command |\extrafloats| is provided. - -\DescribeMacro{\extrafloats}\arg{number} -\smallskip - -This allocates additional registers for the \LaTeX\ float system to -hold figures and tables etc. Similar functionality has been -available via the \Lpack{morefloats} package but this is a different -implementation using extended e-\TeX\ registers when available so -allows many more registers to be reserved for floats as they are -allocated from a pool of 32 or 64 thousand rather than 256 registers, -depending on the engine in use. - -\DescribeMacro{\newmarks}\arg{command} -\smallskip - -e-\TeX\ only, previously available via the \Lpack{etex} package. -Allocates commands to use the extended e-\TeX\ mark mechanism. - -\DescribeMacro{\newXeTeXintercharclass}\arg{command} -\smallskip - -Xe-\TeX\ only, previously in the Xe-\LaTeX\ format, but added via -|xelatex.ini| not part of the core release. -Allocates commands to use the Xe-\TeX\ character class mechanism. - - -\subsection{e-\TeX\ tracing if available} -|\loggingall| (Usually used via |\tracingall|) is extended to enable -additional e-\TeX\ tracing if e-\TeX\ is available. (|\tracingall| -extension has been available as part of the |etex| package previously). - -Also based on code from the |etex| package, a command |\tracingnone| -is added to reverse the effects of |\tracingall| and turn off all primitive -\TeX\ tracing. A new command |\hideoutput| has been added which resets the -tracing parameters set by |\showoutput|. - - - - -\subsection{\texttt{\textbackslash textsubscript} not defined in - latex.ltx (pr/3492)} - -\begin{verbatim} ->>Number: 3492 ->>Category: latex ->>Synopsis: \textsubscript not defined in latex.ltx ->>Arrival-Date: Tue Jan 14 23:01:00 CET 2003 ->>Originator: Ionel Mugurel Ciobica - -I use \textsubscript much more often than \textsuperscript, and -\textsubscript it is not defined in latex.ltx. Could you please -consider including the definition of \textsubscript in the latex.ltx -for the next versions of LaTeX. Thank you. -\end{verbatim} - -\subsection{\texttt{\textbackslash @} discards spaces when moving - (pr/3039)} - -\begin{verbatim} ->>Number: 3039 ->>Category: latex ->>Synopsis: \@ discards spaces when moving ->>Arrival-Date: Sat May 22 09:01:06 1999 ->>Originator: Donald Arseneau ->>Description: -The \@ command expands to \spacefactor\@m in auxiliary files, -which then ignores following spaces when it is reprocessed. -\end{verbatim} - -\subsection{1-col fig can come before earlier 2-col fig - (pr/2346)} - -\begin{verbatim} ->>Number: 2346 ->>Category: latex ->>Synopsis: 2-col: 1-col fig can come before earlier 2-col fig ->>Arrival-Date: Wed Dec 18 15:41:07 1996 ->>Originator: bil kleb ->>Description: -as documented in Lamport's book, p. 198, concerning figure -placement, "a figure will not be printed before an earlier -figure, and a table will not be printed before an earlier -table." however, there is a footnote stating, "However, -in two-column page style, a single-column figure can come before -an earlier double-column figure, and vice versa." - -This twocolumn behavior is undesirable---at least by me and -most professional organizations i publish in. ed snyzter developed -a hack fix for 2.09 several years ago which links the two -counters, but i have not run across a similar "fix" for 2e... -\end{verbatim} - -Originally fixed in package \Lpack{fix2col} which was merged into -this package. Documentation and code from this package have been -merged into this file. - -\subsubsection{Notes on the Implementation Strategy} - -The standard output routine maintains two lists of floats that have -been `deferred' for later consideration. One list for single column -floats, and one for double column floats (which are always -immediately put onto their deferred list). This mechanism means -that \LaTeX\ `knows' which type of float is contained in each box -by the list that it is processing, but having two lists means -that there is no mechanism for preserving the order between the -floats in each list. - -The solution to this problem consists of two small changes to -the output routine. - -Firstly, abandon the `double column float list' |\@dbldeferlist| -and change every command where it is used so that instead the -same |\@deferlist| is used as for single column floats. -That one change ensures that double and single column floats -stay in the same sequence, but as \LaTeX\ no longer `knows' -whether a float is double or single column, it will happily -insert a double float into a single column, overprinting the -other column, or the margin. - -The second change is to provide an alternative mechanism for -recording the two column floats. \LaTeX\ already has a compact -mechanism for recording float information, an integer count register -assigned to each float records information about the `type' of float -`figure', `table' and the position information `htp' etc. - -The type information is stored in the `high' bits, one bit position -(above `32') allocated to each float type. The `low' bits store -information about the allowed positions, one bit each allocated for -|h t b p|. In the \LaTeX2.09 system, the bit corresponding to `16' -formed a `boundary' between these two sets of information, and it -was never actually used by the system. Ed Sznyter's -\Lpack{fixfloats} package not unreasonably used this position to -store the double column information, setting the bit for double -column floats. Then at each point in the output routine at which a -float is committed to a certain region, an additional check must be -made to check that the float is (or is not) double column. If it -spans the wrong number of columns it is deferred rather than being -added. - -Unfortunately the bit `16' is not available in \LaTeXe. It is used -to encode the extra float position possibility `|!|' that was added -in that system. It would be possible to use position `32' and to -move the flags for `table', `figure',\ldots\ up one position, to -start at 64, but this would mean that in principle one less float -type would be supported, and more importantly is likely to break -any other packages that assume anything about the output routine -internals. So here I instead use another mechanism for flagging -double column floats: By default all floats have depth 0pt. -This package arranges that double column ones have depth 1sp. -This information may then be used in the same manner as in -the \Lpack{fixfloats} package, to defer any floats that are not of -the correct column spanning type. - - - -\subsection{Infinite glue found (pr/4023 and pr/2346)} - -The fix for pr/2346 did not work as intended when used in conjunction -with |\enlargethispage| as the latter introduced an infinite negative -glue at the bottom of the page. That in turn make a |\vsplit| -operation to get at the column marks invalid. - -\subsection{Wrong header for twocolumn (pr/2613)} - -\begin{verbatim} ->>Number: 2613 ->>Category: latex ->>Synopsis: wrong headline for twocolumn ->>Arrival-Date: Mon Sep 22 16:41:09 1997 ->>Originator: Daniel Reischert ->>Description: -When setting the document in two columns -the headline shows the top mark of the second column, -but it should show the top mark of the first column. -\end{verbatim} - -Originally fixed in package \Lpack{fix2col} which was merged into -this package. Documentation and code from this package have been -merged into this file. - -\subsubsection{Notes on the Implementation Strategy} - -The standard \LaTeX\ twocolumn system works internally by making -each column a separate `page' that is passed independently to \TeX's -page breaker. (Unlike say the \Lpack{multicol} package, where all -columns are gathered together and then split into columns later, -using |\vsplit|.) This means that the primitive \TeX\ marks that are -normally used for header information, are globally reset after the -first column. By default \LaTeX\ does nothing about this. -A good solution is provided by Piet van Oostrum (building on earlier -work of Joe Pallas) in his \Lpack{fixmarks} package. - -After the first column box has been collected the mark information -for that box is saved, so that any |\firstmark| can be -`artificially' used to set the page-level marks after the second -column has been collected. (The second column |\firstmark| is not -normally required.) Unfortunately \TeX\ does not provide a direct -way of knowing if any marks are in the page, |\firstmark| always has a -value from previous pages, even if there is no mark in this page. -The solution is to make a copy of the box and then |\vsplit| it -so that any marks show up as |\splitfirstmark|. - -The use of |\vsplit| does mean that the output routine will globally -change the value of |\splitfirstmark| and -|\splitbotmark|. The \Lpack{fixmarks} package goes to some trouble -to save and restore these values so that the output routine does -\emph{not} change the values. This part of \Lpack{fixmarks} is not -copied here as it is quite costly (having to be run on every page) and -there is no reason why anyone writing code using |\vsplit| should -allow the output routine to be triggered before the split marks have -been accessed. - - - -\subsection{\texttt{\textbackslash setlength} produces error if - used with registers like \texttt{\textbackslash dimen0} (pr/3066)} - -\begin{verbatim} ->>Number: 3066 ->>Category: latex ->>Synopsis: \setlength{\dimen0}{10pt} ->>Arrival-Date: Tue Jul 6 15:01:06 1999 ->>Originator: Heiko Oberdiek ->>Description: -The current implementation of \setlength causes an error, -because the length specification isn't terminated properly. -More safe: -\def\setlength#1#2{#1=#2\relax} -\end{verbatim} - -\subsection{Fewer fragile commands} - -\begin{verbatim} ->>Number: 3816 ->>Category: latex ->>Synopsis: Argument of \@sect has an extra }. ->>Arrival-Date: Sat Oct 22 23:11:01 +0200 2005 ->>Originator: Susanne Wunsch - -Use of a \raisebox in \section{} produces the error message -mentioned in the subject. - -PR latex/1738 described a similar problem, which has been solved -10 years ago. Protecting the \raisebox with \protect solved my -problem as well, but wouldn't it make sense to have a similar fix -as in the PR? - -It is particularly confusing, that an unprotected \raisebox in a -\section*-environment works fine, while in a \section-environment -produces error. -\end{verbatim} - -While not technically a bug, in this day and age there are few -reasons why commands taking optional arguments should not be robust. - -\subsubsection{Notes on the implementation strategy} - -Rather than changing the kernel macros to be robust, we have decided -to add the macro \DescribeMacro{\MakeRobust}|\MakeRobust| in -\Lpack{fixltx2e} so that users can easily turn fragile macros into -robust ones. A macro |\foo| is made robust by doing the simple -|\MakeRobust{\foo}|. \Lpack{fixltx2e} makes the following kernel -macros robust: |\(|, |\)|, |\[|, |\]|, - |\makebox|, |\savebox|, -|\framebox|, |\parbox|, |\rule| and |\raisebox|. - -\ldots TODO \ldots fleqn vesion of |\[\]| - -\subsection{\texttt{\textbackslash addpenalty} ruins flush-bottom (pr/3073)} - -\begin{verbatim} ->>Number: 3073 ->>Category: latex ->>Synopsis: \addpenalty ruins flush-bottom ->>Arrival-Date: Sat Jul 17 05:11:05 1999 ->>Originator: Donald Arseneau ->>Description: -Just to keep in mind for further development eh? -A page break at an \addpenalty after \vspace does *not* -give a flush-bottom page. (The intent of \addpenalty is -apparently just to preserve the flush bottom by putting -the breakpoint `above' the skip.) -\end{verbatim} - -\subsection{Within counters only reset next level down (pr4393)} - -This is actually implicitly documented behavior in the \LaTeX{} -Manual that states that |\stepcounter| resets all counters marked -``within''. However it means that if, for example, theorems are -numbered within sections and you start a new chapter in a book, the -section counter is reset to zero but the theorem counter is not -until the first section appears. Thus a theorem directly within the -chapter body (without a new section) would show an incremented -number relative to the last theorem of the previous chapter. - - -For this reason we are now resetting all levels of within in one go -even if that means that some of these resets may happen several times -unnecessarily. - - -\subsection{Check the optional arguments of floats} - -By default LaTeX silently ignores unknown letters in the optional -arguments of floats. |\begin{figure}[tB]| the |B| is ignored so it -acts like |\begin{figure}[t]| However |\begin{figure}[B]| does -\emph{not} act like |\begin{figure}[]| as the check for an empty -argument, or unsupplied argument, is earlier. |[]| causes the -default float placement to be used, but |[B]| means that \emph{no} -float area is allowed and so the float will not be placed until the -next |\clearpage| or end of document, no warning is given. - -This package adds a check on each letter, and if it not one of -|!tbhp| then an error is given and the code acts as if |p| had been -used, so that the float may be placed somewhere. - -\subsection{\texttt{\textbackslash DeclareMathSizes} only take pts. - (pr/3693)} - -\begin{verbatim} ->>Number: 3693 ->>Category: latex ->>Synopsis: \DeclareMathSizes only take pts. ->>Arrival-Date: Fri Jun 11 16:21:00 CEST 2004 ->>Originator: Morten Hoegholm - -The last three arguments of \@DeclareMathSizes cannot take a dimension -as argument, making it inconsistent with the rest of the font changing -commands and itself, as the second argument can take a dimension -specification. -\end{verbatim} - -\subsection{No hyphenation in first word after float environment (pr/3498)} - -\begin{verbatim} ->>Number: 3498 ->>Category: latex ->>Synopsis: No hyphenation in first word after float environment ->>Arrival-Date: Thu Jan 30 13:21:00 CET 2003 ->>Originator: Harald Harders - -If a float environment (figure, table) is written within a paragraph, -the first word after the environment is not hyphenated. -\end{verbatim} - -\subsection{\texttt{\textbackslash fnsymbol} should use text symbols - (pr/3400)} - -\begin{verbatim} ->>Number: 3400 ->>Category: latex ->>Synopsis: \fnsymbol should use text symbols if possible ->>Arrival-Date: Fri Jan 04 20:41:00 CET 2002 ->>Originator: Walter Schmidt - -The \fnsymbol command can be used in both text and math -mode. The symbols produced are, however, always taken from -the math fonts. As a result, they may not match the text -fonts, even if the symbols are actually available, for -instance from the TS1 encoding. Since \fnsymbol is -primarily used for footnotes in text, this should be fixed, -IMO. -\end{verbatim} - - - - - -\subsection{\texttt{\textbackslash footnotemark}[x] crashes with fixltx2e.sty - (pr/3752)} - -\begin{verbatim} ->>Number: 3752 ->>Category: tools ->>Synopsis: feature \footnotemark[x] crashes with fixltx2e.sty ->>Arrival-Date: Fri Dec 17 10:11:00 +0100 2004 ->>Originator: Stefan Pofahl - - If I use /fnsymbol together with fixltx2e.sty I can not use - optional parameter [num] - \footnotemark[1] is not showing the mark number 1 but - the mark \value{footnote}. -\end{verbatim} -This bug was related to pr/3400, where |\@fnsymbol| was made robust. - -\subsubsection{Notes on the implementation strategy} - -Pr/3400 made |\@fnsymbol| decide between text-mode and math-mode, -which requires a certain level of robustness somewhere as the -decision between text and math must be made at typesetting time and -not when inside |\protected@edef| or similar commands. One way of -dealing with this is to make sure the value seen by |\@fnsymbol| is -a fully expanded number, which could be handled by code such as -\begin{verbatim} -\def\fnsymbol#1{\expandafter\@fnsymbol - \expandafter{\the\csname c@#1\endcsname}} -\end{verbatim} -This would be a good solution if everybody used the high level -commands only by writing code like |\fnsymbol{footnote}|. Unfortunately -many classes (including the standard classes) and packages use the -internal forms directly as in |\@fnsymbol\c@footnote| so the easy -solution of changing |\fnsymbol| would break code that had worked for -the past 20~years. - -Therefore the implementation here makes |\@fnsymbol| itself a -non-robust command again and instead uses a new robust command -\DescribeMacro{\TextOrMath}|\TextOrMath|, which will take care of -typesetting either the math or the text symbol. In order to do so, -we face an age old problem and unsolvable problem in \TeX: A -reliable test for math mode that doesn't destroy -kerning. Fortunately this problem can be solved when using e\TeX\ so -if you use this as engine for your \LaTeX\ format, as recommended by -the \LaTeX\ Project, you will get a fully functioning |\TextOrMath| -command with no side effects. If you use regular \TeX\ as engine for -your \LaTeX\ format then we have to choose between the lesser of two -evils: 1)~breaking ligatures and preventing kerning or 2)~face the -risk of choosing text-mode at the beginning of an alignment cell, -which was supposed to be math-mode. We have decided upon 1) as is -customary for regular robust commands in \LaTeX. - - - -\end{document} diff --git a/macros/latex-dev/base/latexrelease.dtx b/macros/latex-dev/base/latexrelease.dtx index 7d2290f4d8..efdfa8c418 100644 --- a/macros/latex-dev/base/latexrelease.dtx +++ b/macros/latex-dev/base/latexrelease.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -471,7 +471,7 @@ % % % -% \StopEventually{} +% \MaybeStop{} % % \section{Implementation} % diff --git a/macros/latex-dev/base/latexrelease.ins b/macros/latex-dev/base/latexrelease.ins index 0b65114a2f..42cb588568 100644 --- a/macros/latex-dev/base/latexrelease.ins +++ b/macros/latex-dev/base/latexrelease.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. @@ -101,6 +101,7 @@ extension .ins) which are part of the distribution. \from{lterror.dtx} {latexrelease}% empty \from{ltpar.dtx} {latexrelease}% empty \from{ltpara.dtx} {latexrelease}% empty + \from{ltmeta.dtx} {latexrelease}% L3 layer module \from{ltspace.dtx} {latexrelease}% \from{ltlogos.dtx} {latexrelease}% L3 layer module \from{ltfiles.dtx} {latexrelease}% diff --git a/macros/latex-dev/base/latexrelease.pdf b/macros/latex-dev/base/latexrelease.pdf Binary files differindex 04f911e0d6..630c7cb84a 100644 --- a/macros/latex-dev/base/latexrelease.pdf +++ b/macros/latex-dev/base/latexrelease.pdf diff --git a/macros/latex-dev/base/latexsym.dtx b/macros/latex-dev/base/latexsym.dtx index 7a97aa4318..62fb097c0d 100644 --- a/macros/latex-dev/base/latexsym.dtx +++ b/macros/latex-dev/base/latexsym.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -84,7 +84,7 @@ % |\unrhd|~$\unrhd$ % \end{quote} % -% \StopEventually{} +% \MaybeStop{} % % \section{The \dst{} modules} % diff --git a/macros/latex-dev/base/latexsym.ins b/macros/latex-dev/base/latexsym.ins index 902bbfc9e8..468afddd67 100644 --- a/macros/latex-dev/base/latexsym.ins +++ b/macros/latex-dev/base/latexsym.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. @@ -87,7 +87,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/latexsym.pdf b/macros/latex-dev/base/latexsym.pdf Binary files differindex dc0e9d1344..d4e39b84ed 100644 --- a/macros/latex-dev/base/latexsym.pdf +++ b/macros/latex-dev/base/latexsym.pdf diff --git a/macros/latex-dev/base/lb2.err b/macros/latex-dev/base/lb2.err index 53148e2833..46958ae3a5 100644 --- a/macros/latex-dev/base/lb2.err +++ b/macros/latex-dev/base/lb2.err @@ -419,7 +419,7 @@ Ende der Wettbewerbsperiode & Gewinner \\[4pt] 2006/04 & Jens Mandavid & 121 \\ 2006/10 & Ralf Heckmann & 61 \\ 2008/04 & --- \\ -\ldots & Termin einer weiteren Verlosung offen +\ldots & keine weitere Verlosung %2008/10 & \\ \end{tabular} \end{center} diff --git a/macros/latex-dev/base/lb2.pdf b/macros/latex-dev/base/lb2.pdf Binary files differindex 64acee80bf..3c945696f2 100644 --- a/macros/latex-dev/base/lb2.pdf +++ b/macros/latex-dev/base/lb2.pdf diff --git a/macros/latex-dev/base/letter.dtx b/macros/latex-dev/base/letter.dtx index 6beee81735..4052c260c8 100644 --- a/macros/latex-dev/base/letter.dtx +++ b/macros/latex-dev/base/letter.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -45,7 +45,7 @@ %<*driver> \ProvidesFile{letter.drv} %</driver> - [2021/03/05 v1.3c + [2021/12/07 v1.3c %<+letter> Standard LaTeX document class] % \end{macrocode} % @@ -178,7 +178,7 @@ % \maketitle % \tableofcontents % -% \StopEventually +% \MaybeStop{} % % % \section{Initial Code} diff --git a/macros/latex-dev/base/letter.ins b/macros/latex-dev/base/letter.ins index 44777393eb..c078dc59ce 100644 --- a/macros/latex-dev/base/letter.ins +++ b/macros/latex-dev/base/letter.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/letter.pdf b/macros/latex-dev/base/letter.pdf Binary files differindex 04a83d4385..a4f9c2c4ff 100644 --- a/macros/latex-dev/base/letter.pdf +++ b/macros/latex-dev/base/letter.pdf diff --git a/macros/latex-dev/base/lgc2.err b/macros/latex-dev/base/lgc2.err index 96fd378fe9..45b440a7f4 100644 --- a/macros/latex-dev/base/lgc2.err +++ b/macros/latex-dev/base/lgc2.err @@ -10,7 +10,7 @@ % % The current version of this file can be found at: % -% https://www.latex-project.org/guides/books.html +% https://www.latex-project.org/help/books % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -351,12 +351,12 @@ You can customize this list to only show errata related to the printing you own by changing the configuration in the file \texttt{\jobname.cfg}. \begin{center} - \Large \bfseries To Err is Human --- Bug Contest + \Large \bfseries To Err is Human --- Bug Contest (no longer open) \end{center} Any mistake found and reported is a gain for all readers of our book. -For this reason Addison-Wesley and the authors offer a prize (for 6 -periods) to the eligible person who finds the largest +For this reason Addison-Wesley and the authors offer a prize to the +eligible person who finds the largest number of bugs during that period (in case of a draw a random choice will be made between all those with the largest number of findings). A person can receive at most one prize, ever; errors found by any of @@ -378,7 +378,7 @@ Good luck! Contest period ends & Winner \\[4pt] 2008/05 & Milan Vujtek & 16 suggestions\\ 2010/05 & & \\ -\ldots +\ldots & contest no longer open \end{tabular} \end{center} \end{list} diff --git a/macros/latex-dev/base/lgc2.pdf b/macros/latex-dev/base/lgc2.pdf Binary files differindex 895b91c84d..07902aca25 100644 --- a/macros/latex-dev/base/lgc2.pdf +++ b/macros/latex-dev/base/lgc2.pdf diff --git a/macros/latex-dev/base/lppl.pdf b/macros/latex-dev/base/lppl.pdf Binary files differindex 8ef7144947..c09da611fd 100644 --- a/macros/latex-dev/base/lppl.pdf +++ b/macros/latex-dev/base/lppl.pdf diff --git a/macros/latex-dev/base/ltalloc.dtx b/macros/latex-dev/base/ltalloc.dtx index 59c492836f..4530d4b07b 100644 --- a/macros/latex-dev/base/ltalloc.dtx +++ b/macros/latex-dev/base/ltalloc.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -62,7 +62,7 @@ % % This section deals with counter and other variable allocation. % -% \StopEventually{} +% \MaybeStop{} % % \begin{macrocode} %<*2ekernel> diff --git a/macros/latex-dev/base/ltbibl.dtx b/macros/latex-dev/base/ltbibl.dtx index cda0fa160a..9824ca539f 100644 --- a/macros/latex-dev/base/ltbibl.dtx +++ b/macros/latex-dev/base/ltbibl.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -106,7 +106,7 @@ % |\nocite{*}| is special: it tells \BibTeX{} to put the whole of a % collection of references into the bibliography. % -% \StopEventually{} +% \MaybeStop{} % % % \changes{v1.0a}{1994/03/31}{Initial version of ltidxbib.dtx, diff --git a/macros/latex-dev/base/ltboxes.dtx b/macros/latex-dev/base/ltboxes.dtx index 92d9228a8a..380be09b1f 100644 --- a/macros/latex-dev/base/ltboxes.dtx +++ b/macros/latex-dev/base/ltboxes.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -212,7 +212,7 @@ % \meta{height} \& \meta{depth} = actual height and depth of box in new % position. % -% \StopEventually{} +% \MaybeStop{} % % \changes{v0.1e}{1994/03/02}{Remove need for drv file} % \changes{v0.1e}{1994/03/02}{Add 2ekernel module} diff --git a/macros/latex-dev/base/ltclass.dtx b/macros/latex-dev/base/ltclass.dtx index 06e0f437af..0ff3f71162 100644 --- a/macros/latex-dev/base/ltclass.dtx +++ b/macros/latex-dev/base/ltclass.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -33,7 +33,7 @@ %<*driver> % \fi \ProvidesFile{ltclass.dtx} - [2021/08/25 v1.4f LaTeX Kernel (Class & Package Interface)] + [2021/12/09 v1.5a LaTeX Kernel (Class & Package Interface)] % \iffalse \documentclass{ltxdoc} \GetFileInfo{ltclass.dtx} @@ -338,7 +338,7 @@ % or the old name \cs{@ifpackagelater}. % \DescribeMacro\IfFormatAtLeastTF -% To test the format date use +% To test the format date use % \begin{quote} % |\IfFormatAtLeastTF{|\meta{date}|}{|^^A % \meta{true}|}{|\meta{false}|}| @@ -434,7 +434,7 @@ % standard (and other non-standard) distributions can put informative % strings in this argument. % -% \StopEventually{} +% \MaybeStop{} % % \section{Implementation} % @@ -1833,7 +1833,7 @@ %</2ekernel|latexrelease> %<latexrelease>\EndIncludeInRelease % \end{macrocode} -% +% % \begin{macrocode} %<latexrelease>\IncludeInRelease{0000/00/00}% %<latexrelease> {\RequirePackageWithOptions}{Unused options issue}% @@ -2175,27 +2175,21 @@ % \begin{macrocode} \@ifl@aded\@currext\@currname % \end{macrocode} -% If the package is already loaded, check that there were no option -% clashes: -% \changes{v1.1b}{1998/05/07} -% {Modify help message for latex/2805} -% \begin{macrocode} - {\@if@ptions\@currext{\@currname}{#2}{}% - {\@latex@error - {Option clash for \@cls@pkg\space \@currname}% - {The package \@currname\space has already been loaded - with options:\MessageBreak - \space\space[\@ptionlist{\@currname.\@currext}]\MessageBreak - There has now been an attempt to load it - with options\MessageBreak - \space\space[#2]\MessageBreak - Adding the global options:\MessageBreak - \space\space - \@ptionlist{\@currname.\@currext},#2\MessageBreak - to your \noexpand\documentclass declaration may fix this.% - \MessageBreak - Try typing \space <return> \space to proceed.}}% - \@firstofone}% +% In the current preferred approach, a key family name will exist for +% processing using \pkg{ltkeys}. In that case, we replace the previous +% package options with with the new ones, then call the key handler. +% Otherwise, we use the more classical clash handler. +% \begin{macrocode} + {% + \@ifundefined{opt@fam@\@currname.\@currext} + {\@onefilewithoptions@clashchk{#2}} + {% + \@namedef{opt@\@currname.\@currext}{#2}% + \expandafter\expandafter\expandafter\ProcessKeyPackageOptions + \expandafter\expandafter\expandafter + [\csname opt@fam@\@currname.\@currext\endcsname]% + }% + }% {\makeatletter % \end{macrocode} % The next line seems to be necessary for 2.09 compatibility (the @@ -2298,6 +2292,34 @@ \@reset@ptions} % \end{macrocode} % +% \begin{macro}{\@onefilewithoptions@clashchk} +% If the package is already loaded, check that there were no option +% clashes. +% \changes{v1.1b}{1998/05/07} +% {Modify help message for latex/2805} +% \changes{v1.5a}{2021/11/30} +% {Separated out from \cs{@onefilewithoptions}} +% \begin{macrocode} +\def\@onefilewithoptions@clashchk#1{% + \@if@ptions\@currext{\@currname}{#1}{}% + {\@latex@error + {Option clash for \@cls@pkg\space \@currname}% + {The package \@currname\space has already been loaded + with options:\MessageBreak + \space\space[\@ptionlist{\@currname.\@currext}]\MessageBreak + There has now been an attempt to load it + with options\MessageBreak + \space\space[#1]\MessageBreak + Adding the global options:\MessageBreak + \space\space + \@ptionlist{\@currname.\@currext},#1\MessageBreak + to your \noexpand\documentclass declaration may fix this.% + \MessageBreak + Try typing \space <return> \space to proceed.}}% + \@firstofone} +% \end{macrocode} +% \end{macro} +% % \begin{macrocode} \let\@currpkg@reqd\@empty % \end{macrocode} @@ -2622,7 +2644,7 @@ %<latexrelease>\EndIncludeInRelease %<*2ekernel> % \end{macrocode} -% +% % \begin{macrocode} \@onlypreamble\AtBeginDocument % \end{macrocode} @@ -2826,7 +2848,7 @@ % \end{macrocode} % % \changes{v1.3m}{2020-08-08}{define \cs{q@curr@file} directly as the -% quotes have already been removed (gh/220)} +% quotes have already been removed (gh/220)} % \begin{macrocode} \gdef\filec@ntents#1{% \set@curr@file{\filec@ntents@checkdir#1}% diff --git a/macros/latex-dev/base/ltcmd.dtx b/macros/latex-dev/base/ltcmd.dtx index 04be2abfbf..bf7ae4ea24 100644 --- a/macros/latex-dev/base/ltcmd.dtx +++ b/macros/latex-dev/base/ltcmd.dtx @@ -2,7 +2,7 @@ % % Copyright (C) 1999 Frank Mittelbach, Chris Rowley, David Carlisle % Copyright (C) 2004-2008 Frank Mittelbach, The LaTeX3 Project -% Copyright (C) 2009-2021 +% Copyright (C) 2009-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -34,8 +34,8 @@ %%% From File: ltcmd.dtx % % \begin{macrocode} -\def\ltcmdversion{v1.0h} -\def\ltcmddate{2021-08-30} +\def\ltcmdversion{v1.0j} +\def\ltcmddate{2021-12-31} % \end{macrocode} % %<*driver> @@ -67,7 +67,7 @@ % documentation for \pkg{ltcmd} is provided as part of \texttt{usrguide3}. Here, % additional material aimed at programmers is provided % -% \StopEventually{} +% \MaybeStop{} % % \begin{macrocode} %<@@=cmd> @@ -626,6 +626,8 @@ % \end{macro} % % \begin{macro}{\@@_start_aux:NNnnnn, \@@_start_aux:ccnnnn} +% \changes{v1.0i}{2021/12/02} +% {Correct defaults for optional arguments in end-of-environment code (gh/712)} % This sets up a few variables to minimize the boilerplate code % included in all \pkg{xparse}-defined commands. It then runs the % grabbers~|#4|. Again, the argument specification |#1| is only for @@ -639,8 +641,6 @@ \tl_set:Nn \l_@@_defaults_tl {#5} \tl_set:Nn \l_@@_process_all_tl {#6} #4 - \bool_if:NT \l_@@_environment_bool - { \exp_args:No \@@_set_environment_end:n \l_@@_environment_str } \@@_run_code: } \cs_generate_variant:Nn \@@_start_aux:NNnnnn { cc } @@ -648,6 +648,8 @@ % \end{macro} % % \begin{macro}{\@@_run_code:} +% \changes{v1.0i}{2021/12/02} +% {Correct defaults for optional arguments in end-of-environment code (gh/712)} % After arguments are grabbed, this function is responsible for % inserting default values, running processors, and finally doing % \cs{group_align_safe_end:} as promised, and running the code. @@ -656,6 +658,8 @@ { \tl_if_empty:NF \l_@@_defaults_tl { \@@_defaults: } \tl_if_empty:NF \l_@@_process_all_tl { \@@_args_process: } + \bool_if:NT \l_@@_environment_bool + { \exp_args:No \@@_set_environment_end:n \l_@@_environment_str } \group_align_safe_end: \conditionally@traceon \exp_after:wN \l_@@_fn_code_tl \l_@@_args_tl @@ -2348,15 +2352,17 @@ % Now just print everything in the required format. The auxiliary % \cs{@@_split_signature:n} stores a ready-to-print token list in % \cs{l_@@_tmpa_tl}, so we ust use that here: +% \changes{v1.0j}{2021/13/31} +% {Make \cs{ShowCommand} stop for interaction} % \begin{macrocode} \cs_new_protected:Npn \@@_show_command_aux:nNNn #1 #2 #3 #4 { \@@_split_signature:n {#4} - \iow_term:x + \tl_show:x { - > ~ \token_to_str:N #2 = #1: \iow_newline: + \token_to_str:N #2 = #1: \iow_newline: \tl_use:N \l_@@_tmpa_tl - -> \cs_replacement_spec:N #3 . + -> \cs_replacement_spec:N #3 } } % \end{macrocode} @@ -2367,15 +2373,17 @@ % |\ShowCommand\foo| is used (if |foo| is an environment), we show % |\endfoo| as well, and when |\ShowCommand\endfoo| is used, change % that to |\ShowCommand\foo| and do the same. +% \changes{v1.0j}{2021/13/31} +% {Make \cs{ShowCommand} stop for interaction} % \begin{macrocode} \cs_new_protected:Npn \@@_show_environment:N #1 { \exp_after:wN \@@_show_environment:Nnnw #1 \q_@@ - \iow_term:x + \tl_show:x { - > ~ \token_to_str:N \end { \cs_to_str:N #1 } : \iow_newline: + \token_to_str:N \end { \cs_to_str:N #1 } : \iow_newline: -> \exp_args:Nc \cs_replacement_spec:N - { environment~ \cs_to_str:N #1 ~end~aux~ } . + { environment~ \cs_to_str:N #1 ~end~aux~ } } } \cs_new_protected:Npn \@@_show_environment:Nnnw #1 #2 #3 #4 \q_@@ diff --git a/macros/latex-dev/base/ltcmdhooks-code.pdf b/macros/latex-dev/base/ltcmdhooks-code.pdf Binary files differindex 94418868e1..7ed20af9ff 100644 --- a/macros/latex-dev/base/ltcmdhooks-code.pdf +++ b/macros/latex-dev/base/ltcmdhooks-code.pdf diff --git a/macros/latex-dev/base/ltcmdhooks-doc.pdf b/macros/latex-dev/base/ltcmdhooks-doc.pdf Binary files differindex 623100bb28..6ac9077ecc 100644 --- a/macros/latex-dev/base/ltcmdhooks-doc.pdf +++ b/macros/latex-dev/base/ltcmdhooks-doc.pdf diff --git a/macros/latex-dev/base/ltcmdhooks-doc.tex b/macros/latex-dev/base/ltcmdhooks-doc.tex index 1efae5f229..acbb880e72 100644 --- a/macros/latex-dev/base/ltcmdhooks-doc.tex +++ b/macros/latex-dev/base/ltcmdhooks-doc.tex @@ -2,5 +2,6 @@ \AtBeginDocument{\OnlyDescription \let\tableofcontents\relax + \RenewCommandCopy\MaybeStop\StopEventually } \input{ltcmdhooks.dtx} diff --git a/macros/latex-dev/base/ltcmdhooks.dtx b/macros/latex-dev/base/ltcmdhooks.dtx index 208f7c3d22..ccb5a35a71 100644 --- a/macros/latex-dev/base/ltcmdhooks.dtx +++ b/macros/latex-dev/base/ltcmdhooks.dtx @@ -270,7 +270,7 @@ % If you do that then both hooks automatically work and are patched % into the right places. % -% \StopEventually{\setlength\IndexMin{200pt} \PrintIndex } +% \MaybeStop{\setlength\IndexMin{200pt} \PrintIndex } % % % @@ -1394,3 +1394,12 @@ % % \Finale % +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\endinput + +^^A Needed for emacs +^^A +^^A Local Variables: +^^A mode: latex +^^A coding: utf-8-unix +^^A End: diff --git a/macros/latex-dev/base/ltcntrl.dtx b/macros/latex-dev/base/ltcntrl.dtx index d65b3aee94..5ebe256c75 100644 --- a/macros/latex-dev/base/ltcntrl.dtx +++ b/macros/latex-dev/base/ltcntrl.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -66,7 +66,7 @@ % This section defines a number of control structure macros, such as % while-loops and for-loops. % -% \StopEventually{} +% \MaybeStop{} % % \begin{oldcomments} % \begin{macrocode} diff --git a/macros/latex-dev/base/ltcounts.dtx b/macros/latex-dev/base/ltcounts.dtx index 39fb47728d..ffe2265ac3 100644 --- a/macros/latex-dev/base/ltcounts.dtx +++ b/macros/latex-dev/base/ltcounts.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -124,7 +124,7 @@ % the default for \meta{format}. % Star form omits redefining the print representation. % -% \StopEventually{} +% \MaybeStop{} % % \begin{macrocode} %<*2ekernel> diff --git a/macros/latex-dev/base/ltdefns.dtx b/macros/latex-dev/base/ltdefns.dtx index 6c85ca915d..3a92e827fe 100644 --- a/macros/latex-dev/base/ltdefns.dtx +++ b/macros/latex-dev/base/ltdefns.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -96,7 +96,7 @@ % % This section contains commands used in defining other macros. % -% \StopEventually{} +% \MaybeStop{} % % \begin{macrocode} %<*2ekernel> diff --git a/macros/latex-dev/base/ltdirchk.dtx b/macros/latex-dev/base/ltdirchk.dtx index 36a1ca616c..16a2ed9e68 100644 --- a/macros/latex-dev/base/ltdirchk.dtx +++ b/macros/latex-dev/base/ltdirchk.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -37,7 +37,7 @@ %<*driver> % \fi \ProvidesFile{ltdirchk.dtx} - [2021/01/15 v1.3a LaTeX Kernel (System Dependent Parts)] + [2021/12/11 v1.3a LaTeX Kernel (System Dependent Parts)] % \iffalse \documentclass{ltxdoc} \GetFileInfo{ltdirchk.dtx} @@ -206,12 +206,26 @@ % error messages that use the default settings with a current version of % \TeX, but this should not cause any confusion we hope. % -% \StopEventually{} +% \MaybeStop{} % % \section{Initialization} % As this file is read at a very early stage, some definitions that % are normally considered to be part of the format must be made here. % +% Most such definitions are repeated later in the ``right'' place, +% usually (but not always) with different implementations. To be able +% to spot this more easily if you look into the file +% \texttt{latex.ltx} (which is stripped of comments) we add some +% comment lines to that effect that survive the stripping process by +% \texttt{docstrip}. +% \changes{v1.3a}{2021/12/11}{Add comment lines into latex.ltx to +% indicate temp definitions that are later overwritten (gh/725)} +% \begin{macrocode} +%<*dircheck> +%% ---- START temporary definitions for bootstrapping; later overwritten ---- +%</dircheck> +% \end{macrocode} +% % \subsection{INITEX} % \changes{v0.2i}{1994/01/25} % {Protect against looping on \cs{@@input} and \cs{@@end}.} @@ -1007,6 +1021,7 @@ % \end{macro} % % \begin{macrocode} +%% ---- END temporary definitions for bootstrapping ---- %</dircheck> % \end{macrocode} % diff --git a/macros/latex-dev/base/lterror.dtx b/macros/latex-dev/base/lterror.dtx index 10d93a1dbd..b302a9a74c 100644 --- a/macros/latex-dev/base/lterror.dtx +++ b/macros/latex-dev/base/lterror.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -91,7 +91,7 @@ % % This section defines \LaTeX's error commands. % -% \StopEventually{} +% \MaybeStop{} % % % \begin{macrocode} diff --git a/macros/latex-dev/base/ltexpl.dtx b/macros/latex-dev/base/ltexpl.dtx index 021edc644c..e6a83d5725 100644 --- a/macros/latex-dev/base/ltexpl.dtx +++ b/macros/latex-dev/base/ltexpl.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2019-2021 +% Copyright (C) 2019-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -33,7 +33,7 @@ %<*driver> % \fi \ProvidesFile{ltexpl.dtx} - [2021/04/20 v1.3c LaTeX Kernel (expl3-dependent code)] + [2022/01/06 v1.3e LaTeX Kernel (expl3-dependent code)] % \iffalse \documentclass{ltxdoc} \GetFileInfo{ltexpl.dtx} @@ -57,7 +57,7 @@ % % \section{\pkg{expl3}-dependent code} % -% \StopEventually{} +% \MaybeStop{} % % \changes{v0.0}{2019-10-02}{Initial version} % @@ -387,4 +387,127 @@ % \end{macrocode} % % +% +% +% +% +% \section{Document-level command names for \pkg{expl3} functions} +% +% Current home for L3 programing layer functions that we make +% directly available at the document level. This section may need +% to be moved later (after \cs{NewDocumentCommand} is defined in +% case we want to use that in the setup). +% +% +% \DescribeMacro\fpeval +% The expandable command \cs{fpeval} takes as its argument a +% floating point expression and produces a result using the normal +% rules of mathematics. As this command is expandable it can be +% used where \TeX{} requires a number and for example within a +% low-level \cs{edef} operation to give a purely numerical +% result. See \texttt{usrguide3} for further explanation. +% +% \DescribeMacro\inteval +% \DescribeMacro\dimeval +% \DescribeMacro\skipeval +% The expandable command \cs{inteval} takes as its argument an +% integer expression and produces a result using the normal rules +% of mathematics. The operations recognised are |+|, |-|, |*| and +% |/| plus parentheses. Division occurs with \emph{rounding}, and +% ties are rounded away from zero. As this command is expandable it +% can be used where \TeX{} requires a number and for example within +% a low-level \cs{edef} operation to give a purely numerical +% result. See \texttt{usrguide3} for further explanation. +% \cs{dimeval} and \cs{skipeval} are similar, but generate fixed and +% rubber length values, respectively. +% +% +% +% \begin{macro}{\fpeval,\inteval,\dimeval,\skipeval} +% A document level wrapper around the code level function for +% floating point calculations. +% \changes{v1.3d}{2021/11/30}{Moved over from \texttt{xfp} package (gh/711)} +% \begin{macrocode} +%<*2ekernel|latexrelease> +%<latexrelease>\IncludeInRelease{2022/06/01}% +%<latexrelease> {\fpeval}{fp and int calculations}% +\ExplSyntaxOn +\cs_new_eq:NN \fpeval \fp_eval:n +% \end{macrocode} +% And a few more, this time wrappers around the e\TeX{} primitives. +% \begin{macrocode} +\cs_new_eq:NN \inteval \int_eval:n +% \end{macrocode} +% +% \changes{v1.3d}{2021/12/07}{Added \cs{dimeval} and \cs{skipeval} (gh/711)} +% \begin{macrocode} +\cs_new_eq:NN \dimeval \dim_eval:n +\cs_new_eq:NN \skipeval \skip_eval:n +\ExplSyntaxOff +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +%</2ekernel|latexrelease> +%<latexrelease>\EndIncludeInRelease +%<latexrelease>\IncludeInRelease{0000/00/00}% +%<latexrelease> {\fpeval}{fp and int calculations}% + +%<latexrelease> +%<latexrelease>\let\fpeval\@undefined +%<latexrelease>\let\inteval\@undefined +%<latexrelease>\let\dimeval\@undefined +%<latexrelease>\let\skipeval\@undefined +%<latexrelease>\EndIncludeInRelease +% \end{macrocode} +% +% +% \DescribeMacro\UseName +% \DescribeMacro\ExpandArgs +% When declaring new commands with \cs{NewDocumentCommand} or +% \cs{NewCommandCopy} or similar, it is sometimes necessary to +% ``construct'' the csname. As a general mechanism the L3 +% programming layer has \cs{exp\_args:N...} for this, but there is +% no mechanism for it if \cs{ExplSyntaxOn} is not active. We +% therefore offer a few of these commands also with CamelCase names. +% +% +% \begin{macro}{\UseName,\ExpandArgs} +% A document wrapper for changing arguments to cs names for use +% with \cs{NewDocumentCommand} and similar functions. +% +% \changes{v1.3d}{2021/12/28}{Added document level names for \cs{exp\_args:Nc} and the like (gh/735)} +% \changes{v1.3e}{2022/01/06}{Adjust document level names for \cs{exp\_args:Nc} and the like (gh/735)} +% \begin{macrocode} +%<*2ekernel|latexrelease> +%<latexrelease>\IncludeInRelease{2022/06/01}% +%<latexrelease> {\ExpandArgs}{Some pre-expansion commands}% +\ExplSyntaxOn +\cs_new_eq:NN \UseName \use:c +% \end{macrocode} +% +% \begin{macrocode} +\cs_new:Npn \ExpandArgs #1 + { + \cs_if_exist_use:cF { exp_args:N #1 } + { \msg_expandable_error:nnn { kernel } { unknown-arg-expansion } {#1} } + } +\msg_new:nnn { kernel } { unknown-arg-expansion } + { Unknown~arg~expansion~"#1" } +\ExplSyntaxOff +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +%</2ekernel|latexrelease> +%<latexrelease>\EndIncludeInRelease +%<latexrelease>\IncludeInRelease{0000/00/00}% +%<latexrelease> {\ExpandArgs}{Some pre-expansion commands}% + +%<latexrelease> +%<latexrelease>\let\UseName\@undefined +%<latexrelease>\let\ExpandArgs\@undefined +%<latexrelease>\EndIncludeInRelease +% \end{macrocode} +% % \Finale diff --git a/macros/latex-dev/base/ltfilehook-code.pdf b/macros/latex-dev/base/ltfilehook-code.pdf Binary files differindex b3dc125d4b..16144c7a73 100644 --- a/macros/latex-dev/base/ltfilehook-code.pdf +++ b/macros/latex-dev/base/ltfilehook-code.pdf diff --git a/macros/latex-dev/base/ltfilehook-doc.pdf b/macros/latex-dev/base/ltfilehook-doc.pdf Binary files differindex 751d35f5e2..3e3d0da175 100644 --- a/macros/latex-dev/base/ltfilehook-doc.pdf +++ b/macros/latex-dev/base/ltfilehook-doc.pdf diff --git a/macros/latex-dev/base/ltfilehook-doc.tex b/macros/latex-dev/base/ltfilehook-doc.tex index 220de94188..c9287dfb2f 100644 --- a/macros/latex-dev/base/ltfilehook-doc.tex +++ b/macros/latex-dev/base/ltfilehook-doc.tex @@ -3,5 +3,6 @@ \AtBeginDocument{\OnlyDescription % \let\tableofcontents\relax + \RenewCommandCopy\MaybeStop\StopEventually } \input{ltfilehook.dtx} diff --git a/macros/latex-dev/base/ltfilehook.dtx b/macros/latex-dev/base/ltfilehook.dtx index 000f4d8c2a..533aacbf2b 100644 --- a/macros/latex-dev/base/ltfilehook.dtx +++ b/macros/latex-dev/base/ltfilehook.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2020-2021 +% Copyright (C) 2020-2022 % Frank Mittelbach, Phelype Oleinik & LaTeX Team % % This file is part of the LaTeX base system. @@ -471,7 +471,7 @@ % the level value and search further for \texttt{LEVEL} with that value % which should then be the \texttt{START} level of the file you are in. % -% \StopEventually{\setlength\IndexMin{200pt} \PrintIndex } +% \MaybeStop{\setlength\IndexMin{200pt} \PrintIndex } % % % \section{The Implementation} diff --git a/macros/latex-dev/base/ltfiles.dtx b/macros/latex-dev/base/ltfiles.dtx index 4c24716df6..9b31b50197 100644 --- a/macros/latex-dev/base/ltfiles.dtx +++ b/macros/latex-dev/base/ltfiles.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -106,7 +106,7 @@ % If the file exists on the system, execute \emph{then} and input % \emph{NAME} otherwise execute \emph{else}. % -% \StopEventually{} +% \MaybeStop{} % % \changes{v1.0a}{1994/03/07}{Initial version, split from latex.dtx} % \changes{v1.0a}{1994/03/07}{Long lines wrapped to 72 columns} diff --git a/macros/latex-dev/base/ltfinal.dtx b/macros/latex-dev/base/ltfinal.dtx index 40017a205a..46c7ded4aa 100644 --- a/macros/latex-dev/base/ltfinal.dtx +++ b/macros/latex-dev/base/ltfinal.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -33,7 +33,7 @@ %<*driver> % \fi \ProvidesFile{ltfinal.dtx} - [2021/09/06 v2.2q LaTeX Kernel (Final Settings)] + [2021/12/07 v2.2q LaTeX Kernel (Final Settings)] % \iffalse \documentclass{ltxdoc} \GetFileInfo{ltfinal.dtx} @@ -57,11 +57,14 @@ % % % \section{Final settings} -% This section contains the final settings for \LaTeX. It initializes -% some debugging and typesetting parameters, sets the default -% |\catcode|s and uc/lc codes, and inputs the hyphenation file. % -% \StopEventually{} +% This section contains the final settings for \LaTeX. It initializes +% some debugging and typesetting parameters, sets the default +% |\catcode|s and uc/lc codes, and inputs the hyphenation file. +% +% +% +% \MaybeStop{} % % \changes{v0.1a}{1994/03/07}{Initial version, split from latex.dtx} % \changes{v0.1a}{1994/03/07}{Remove oldcomments environment} diff --git a/macros/latex-dev/base/ltfloat.dtx b/macros/latex-dev/base/ltfloat.dtx index ac3b641817..8b5b92759a 100644 --- a/macros/latex-dev/base/ltfloat.dtx +++ b/macros/latex-dev/base/ltfloat.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -83,7 +83,7 @@ % For example, `pht' specifies that the float can appear in any of % three locations: page, here or top. % -% \StopEventually{} +% \MaybeStop{} % % % \changes{v1.0a}{1994/03/04}{Initial version, split from latex.dtx} diff --git a/macros/latex-dev/base/ltfntcmd.dtx b/macros/latex-dev/base/ltfntcmd.dtx index 6c4ec4b3d1..64064abcb5 100644 --- a/macros/latex-dev/base/ltfntcmd.dtx +++ b/macros/latex-dev/base/ltfntcmd.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -271,7 +271,7 @@ % amstex.sty} is used as this version can cause space to be removed % immediately before the |\/|. % -% \StopEventually{} +% \MaybeStop{} % % % \section{The implementation} diff --git a/macros/latex-dev/base/ltfssaxes.dtx b/macros/latex-dev/base/ltfssaxes.dtx index 86c84b111f..843e8b544c 100644 --- a/macros/latex-dev/base/ltfssaxes.dtx +++ b/macros/latex-dev/base/ltfssaxes.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2019-2021 +% Copyright (C) 2019-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -66,7 +66,7 @@ % % % -% \StopEventually{} +% \MaybeStop{} % % \changes{v1.0h}{2020/12/04}{Reorganized the rollback data} % diff --git a/macros/latex-dev/base/ltfssbas.dtx b/macros/latex-dev/base/ltfssbas.dtx index 1f30372d06..d013ec0ecb 100644 --- a/macros/latex-dev/base/ltfssbas.dtx +++ b/macros/latex-dev/base/ltfssbas.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -76,7 +76,7 @@ % completely accurate. % \end{quote} % -% \StopEventually{} +% \MaybeStop{} % % \changes{v3.0v}{1998/08/17}{(RmS) Documentation fixes.} % \changes{v3.0j}{1995/10/22}{(RmS) New size function macro @@ -2257,3 +2257,13 @@ % % \Finale % +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\endinput + +^^A Needed for emacs +^^A +^^A Local Variables: +^^A mode: latex +^^A coding: utf-8-unix +^^A End: + diff --git a/macros/latex-dev/base/ltfsscmp.dtx b/macros/latex-dev/base/ltfsscmp.dtx index 03be855127..09f43a0d94 100644 --- a/macros/latex-dev/base/ltfsscmp.dtx +++ b/macros/latex-dev/base/ltfsscmp.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -82,7 +82,7 @@ % kernel and made available via \textsf{latexrelease} package so that % backward compatibility remains ensured for very old documents. % -% \StopEventually{} +% \MaybeStop{} % % % \changes{v3.0b}{1995/06/15} diff --git a/macros/latex-dev/base/ltfssdcl.dtx b/macros/latex-dev/base/ltfssdcl.dtx index 4f2cabd613..65bc40803e 100644 --- a/macros/latex-dev/base/ltfssdcl.dtx +++ b/macros/latex-dev/base/ltfssdcl.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -77,7 +77,7 @@ % completely accurate. % \end{quote} % -% \StopEventually{} +% \MaybeStop{} % % \section{Interface Commands} % diff --git a/macros/latex-dev/base/ltfssini.dtx b/macros/latex-dev/base/ltfssini.dtx index f817fdd847..12e3b6289b 100644 --- a/macros/latex-dev/base/ltfssini.dtx +++ b/macros/latex-dev/base/ltfssini.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -70,7 +70,7 @@ % distribution, or \emph{The \LaTeX\ Companion} for higher level % documentation of these commands. % -% \StopEventually{} +% \MaybeStop{} % % % \changes{v3.0i}{1998/08/17}{(RmS) Minor documentation fixes.} diff --git a/macros/latex-dev/base/ltfsstrc.dtx b/macros/latex-dev/base/ltfsstrc.dtx index f562a4fa90..699fd2c594 100644 --- a/macros/latex-dev/base/ltfsstrc.dtx +++ b/macros/latex-dev/base/ltfsstrc.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -138,7 +138,7 @@ % \end{description} % % -% \StopEventually{} +% \MaybeStop{} % % \section{A driver for this document} % diff --git a/macros/latex-dev/base/lthooks-code.pdf b/macros/latex-dev/base/lthooks-code.pdf Binary files differindex e6b9391438..12c7438683 100644 --- a/macros/latex-dev/base/lthooks-code.pdf +++ b/macros/latex-dev/base/lthooks-code.pdf diff --git a/macros/latex-dev/base/lthooks-doc.pdf b/macros/latex-dev/base/lthooks-doc.pdf Binary files differindex 4f1d9c820d..76321bbfe0 100644 --- a/macros/latex-dev/base/lthooks-doc.pdf +++ b/macros/latex-dev/base/lthooks-doc.pdf diff --git a/macros/latex-dev/base/lthooks-doc.tex b/macros/latex-dev/base/lthooks-doc.tex index a51e2cd6e0..b5f3622a17 100644 --- a/macros/latex-dev/base/lthooks-doc.tex +++ b/macros/latex-dev/base/lthooks-doc.tex @@ -3,5 +3,6 @@ \AtBeginDocument{\OnlyDescription % \let\tableofcontents\relax + \RenewCommandCopy\MaybeStop\StopEventually } \input{lthooks.dtx} diff --git a/macros/latex-dev/base/lthooks.dtx b/macros/latex-dev/base/lthooks.dtx index 5b3d80e984..e07658fa88 100644 --- a/macros/latex-dev/base/lthooks.dtx +++ b/macros/latex-dev/base/lthooks.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2020-2021 +% Copyright (C) 2020-2022 % Frank Mittelbach, Phelype Oleinik & LaTeX Team % % This file is part of the LaTeX base system. @@ -32,27 +32,12 @@ % % \begin{macrocode} \def\lthooksversion{v1.0s} -\def\lthooksdate{2021/09/28} +\def\lthooksdate{2022/01/06} % \end{macrocode} % %<*driver> \documentclass{l3doc} -% bug fix fo l3doc.cls -\ExplSyntaxOn -\cs_set_protected:Npn \__codedoc_macro_typeset_one:nN #1#2 - { - \vbox_set:Nn \l__codedoc_macro_box - { - \vbox_unpack_drop:N \l__codedoc_macro_box - \hbox { \llap { \__codedoc_print_macroname:nN {#1} #2 - \MacroFont % <----- without it the \ is in lmr10 if a link is made - \ - } } - } - \int_incr:N \l__codedoc_macro_int - } -\ExplSyntaxOff \providecommand\InternalDetectionOff{} \providecommand\InternalDetectionOn{} @@ -798,6 +783,7 @@ % \begin{function}{\ShowHook,\LogHook} % \begin{syntax} % \cs{ShowHook} \Arg{hook} +% \cs{LogHook} \Arg{hook} % \end{syntax} % Displays information about the \meta{hook} such as % \begin{itemize} @@ -1096,6 +1082,7 @@ % \begin{function}{\hook_show:n,\hook_log:n} % \begin{syntax} % \cs{hook_show:n} \Arg{hook} +% \cs{hook_log:n} \Arg{hook} % \end{syntax} % Displays information about the \meta{hook} such as % \begin{itemize} @@ -1502,9 +1489,6 @@ % Like \cs{AtBeginDocument} but for the \hook{enddocument} hook. % \end{function} % -% There is also \cs{AtBeginDvi} which is discussed in conjunction -% with the shipout hooks. -% % \bigskip % % The few hooks that existed previously in \LaTeXe{} used internally @@ -1962,7 +1946,7 @@ % \end{description} % % -% \StopEventually{\setlength\IndexMin{200pt} \PrintIndex } +% \MaybeStop{\setlength\IndexMin{200pt} \PrintIndex } % % % \section{The Implementation} @@ -2219,7 +2203,7 @@ % A token list holding the relation between \meta{label1} and % \meta{label2} in the \meta{hook}. The \meta{labels} are lexically % (reverse) sorted to ensure that two labels always point to the same -% token list. For global rules, the \meta{hook} name is |??|. +% token list. For global rules, the \meta{hook} name is \texttt{??}. % % \item[\cs{@@\textvisiblespace\meta{hook}}] The code that is actually executed % when the hook is called in the document is stored in this token @@ -3589,7 +3573,7 @@ % expansion in the code later on. % % \cs{@@\textvisiblespace??} isn't used, but it has to be defined to trick -% the code into thinking that \verb=??= is actually a hook. +% the code into thinking that \texttt{??} is actually a hook. % \begin{macrocode} \prop_new:c {g_@@_??_code_prop} \prop_new:c {@@~??} @@ -4169,7 +4153,7 @@ % \meta{hook-code-plist}. We are about to apply the next rule and % enter it into the data structure. \cs{@@_apply_label_pair:nnn} will % just call \cs{@@_label_if_exist_apply:nnnF} for the \meta{hook}, and -% if no rule is found, also try the \meta{hook} name \verb=??= +% if no rule is found, also try the \meta{hook} name \texttt{??} % denoting a default hook rule. % % \cs{@@_label_if_exist_apply:nnnF} will check if the rule exists for @@ -4286,7 +4270,7 @@ % out to be a real issue, we can improve the code. % % Here the code is removed from \cs{l_@@_cur_hook_tl} rather than -% \verb=#3= because the latter may be \verb=??=, and the default +% \verb=#3= because the latter may be \texttt{??}, and the default % hook doesn't store any code. Removing it instead from \cs{l_@@_cur_hook_tl} % makes the default rules \verb=->= and \verb=<-= work properly. % \begin{macrocode} @@ -4535,7 +4519,7 @@ % \meta{inline function} is executed with |#1|${}={}$\meta{relation}, % |#2|${}={}$\meta{label_1}\verb=|=\meta{label_2}, % and |#3|${}={}$\meta{hook} (the latter may be the argument |#1| to -% \cs{@@_list_rules:nn}, or |??| if it is a default rule). +% \cs{@@_list_rules:nn}, or \texttt{??} if it is a default rule). % \begin{macrocode} \cs_new_protected:Npn \@@_list_rules:nn #1 #2 { @@ -5596,4 +5580,10 @@ % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \endinput -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +^^A Needed for emacs +^^A +^^A Local Variables: +^^A mode: latex +^^A coding: utf-8-unix +^^A End: diff --git a/macros/latex-dev/base/lthyphen.dtx b/macros/latex-dev/base/lthyphen.dtx index 9244db0642..b7cede1175 100644 --- a/macros/latex-dev/base/lthyphen.dtx +++ b/macros/latex-dev/base/lthyphen.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -65,7 +65,7 @@ % of \texttt{hyphen.ltx}. See the comments below for additional % information. % -% \StopEventually{} +% \MaybeStop{} % % To produce the printed version of this file the following code % is used. It can be extracted with the \dst{} program, or one can run diff --git a/macros/latex-dev/base/ltidxglo.dtx b/macros/latex-dev/base/ltidxglo.dtx index 75a80cd439..395fe83975 100644 --- a/macros/latex-dev/base/ltidxglo.dtx +++ b/macros/latex-dev/base/ltidxglo.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -68,7 +68,7 @@ % % \DescribeMacro{\glossary} Make a glossary entry for |#1|. % -% \StopEventually{} +% \MaybeStop{} % % % \changes{v1.0a}{1994/03/31}{Initial version of ltidxbib.dtx, diff --git a/macros/latex-dev/base/ltkeys.dtx b/macros/latex-dev/base/ltkeys.dtx new file mode 100644 index 0000000000..3c58585de9 --- /dev/null +++ b/macros/latex-dev/base/ltkeys.dtx @@ -0,0 +1,454 @@ +% \iffalse meta-comment +% +% Copyright (C) 2021-2022 +% The LaTeX Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% It may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3c +% of this license or (at your option) any later version. +% The latest version of this license is in +% https://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2008 or later. +% +% This file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% +% \iffalse +%%% From File: ltkeys.dtx +% +%<*driver> +% \fi +\ProvidesFile{ltkeys.dtx} + [2021/11/30 v1.0a LaTeX Kernel (Kevyal options)] +% \iffalse +\documentclass{l3doc} +\GetFileInfo{ltkeys.dtx} +\title{\filename} +\date{\filedate} +\author{% + \LaTeX{} Team} + +\begin{document} + \maketitle + \DocInput{ltkeys.dtx} +\end{document} +%</driver> +% \fi +% +% \section{Creating and using keyval options} +% +% As with any key--value input, using key--value pairs as package or +% class options has two parts: creating the key options and setting (using) +% them. Options created in this way \emph{may} be used after package loading +% as general key--value settings: this will depend on the nature of the +% underlying code. +% +% \begin{function}{\DeclareKeys} +% \begin{syntax} +% \cs{DeclareKeys} \oarg{family} \marg{declarations} +% \end{syntax} +% Creates a series of options from a comma-separated \meta{declarations} list. +% Each entry in this list is a key--value pair, with the \meta{key} having one +% or more \meta{properties}. A small number of \enquote{basic} +% \meta{properties} are described below. The full range of properties, +% provided by \pkg{l3keys}, can also be used for more powerful processing. +% See \texttt{interface3} for the full details. +% +% The basic properties provided here are +% \begin{itemize} +% \item \texttt{.if} --- sets a \TeX{} \cs{if...} switch +% \item \texttt{.store} --- stores a value in a macro +% \item \texttt{.usage} -- defines whether the option can be given only +% when loading (\texttt{load}), in the preamble (\texttt{preamble}) or +% has no limitation on scope (\texttt{general}) +% \end{itemize} +% The part of the \meta{key} before the \meta{property} is the \meta{name}, +% with the \meta{value} working with the \meta{property} to define the +% behaviour of the option. +% +% For example, with +% \begin{verbatim} +% \DeclareKeys[mypkg] +% { +% draft.if = @mypkg@draft , +% draft.usage = preamble , +% name.store = \@mypkg@name , +% name.usage = load , +% second-name.store = \@mypkg@other@name +% } +% \end{verbatim} +% three options would be create. The option \texttt{draft} can be given +% anywhere in the preamble, and will set a switch called \cs{if@mypkg@draft}. +% The option \texttt{name} can only be given during package loading, and will +% save whatever value it is given in \cs{@mypkg@name}. Finally, the option +% \texttt{second-name} can be given anywhere, and will save its value in +% \cs{@mypkg@other@name}. +% +% Keys created \emph{before} the use of +% \cs{ProcessKeyOptions}/\cs{ProcessKeyPackageOptions} act as package options. +% \end{function} +% +% \begin{function}{\ProcessKeyOptions} +% \begin{syntax} +% \cs{ProcessKeyOptions} \oarg{family} +% \end{syntax} +% The \cs{ProcessKeyOptions} function is used to check the current +% option list against the keys defined for \meta{family}. Global (class) +% options and local (package) options are checked when this function +% is called in a package. +% \end{function} +% +% \begin{function}{\ProcessKeyPackageOptions} +% \begin{syntax} +% \cs{ProcessKeyPackageOptions} \oarg{family} +% \end{syntax} +% This function works in a similar manner to \cs{ProcessKeyOptions}. +% When used in a package, \cs{ProcessKeyPackageOptions} +% will not examine any global (class) class options available. In contrast, +% \cs{ProcessKeyOptions} does parse class options (in common with the +% classical \cs{ProcessOptions} command). +% \end{function} +% +% \begin{function}{\SetKeys} +% \begin{syntax} +% \cs{SetKeys} \oarg{family} \Arg{keyvals} +% \end{syntax} +% Sets (applies) the explicit list of \meta{keyvals} for the \meta{family}: +% it the latter is not given, the value of \cs{@currname} used. This command +% may be used within a package to set options before or after using +% \cs{ProcessKeyOptions}/\cs{ProcessKeyPackageOptions}. +% \end{function} +% +% \StopEventually{} +% +% \subsection{Implementation of \pkg{ltkeys}} +% +% \begin{macrocode} +%<@@=keys> +% \end{macrocode} +% +% \begin{macrocode} +%<*2ekernel> +% \end{macrocode} +% +% \begin{macrocode} +\ExplSyntaxOn +% \end{macrocode} +% +% \begin{macrocode} +\cs_generate_variant:Nn \clist_put_right:Nn { Nv } +% \end{macrocode} +% +% \begin{macro}{\l_@@_options_clist} +% A single list is used for all options, into which they are collected +% before processing. +% \begin{macrocode} +\clist_new:N \l_@@_options_clist +% \end{macrocode} +% \end{macro} +% +% \begin{variable}{\l_@@_options_loading_bool} +% Used to indicate we are in the loading phase: controls the outcome +% of warnings. +% \begin{macrocode} +\bool_new:N \l_@@_options_loading_bool +% \end{macrocode} +% \end{variable} +% +% \begin{macro}{\@@_options:Nn, \@@_options:NV} +% \begin{macro}{\@@_options_end:} +% The main function calls functions to collect up the global and local +% options into \cs{l_@@_options_clist} before calling the +% underlying functions to actually do the processing. So that a suitable +% message is produced if the option is unknown, the special +% \texttt{unknown} key is set if it does not already exist for the +% current family, and is cleaned up afterwards if required. To allow +% the \LaTeXe{} layer to know this mechanism is active, and to deal +% with the key family not matching the file name, we store the family +% in all cases. +% \begin{macrocode} +\cs_new_protected:Npn \@@_options:Nn #1#2 + { + \cs_gset_nopar:cpn { opt@fam@\@currname.\@currext } {#2} + \cs_set_protected:Npn \@@_option_end: { } + \clist_clear:N \l_@@_options_clist + \@@_options_global:Nn #1 {#2} + \@@_options_local: + \keys_if_exist:nnF {#2} { unknown } + { + \keys_define:nn {#2} + { + unknown .code:n = + { + \msg_error:nnxx { keys } { option-unknown } + { \l_keys_key_str } { \@currname } + } + } + \cs_set_protected:Npn \@@_option_end: + { \keys_define:nn {#2} { unknown .undefine: } } + } + \bool_set_true:N \l_@@_options_loading_bool + \keys_set:nV {#2} \l_@@_options_clist + \bool_set_false:N \l_@@_options_loading_bool + \cs_set_eq:NN \@unprocessedoptions \scan_stop: + \@@_option_end: + \@@_options_loaded:n {#2} + } +\cs_generate_variant:Nn \@@_options:Nn { NV } +\msg_new:nnnn { keys } { option-unknown } + { Unknown~option~'#1'~for~package~#2. } + { + LaTeX~has~been~asked~to~set~an~option~called~'#1'~ + but~the~#2~package~has~not~created~an~option~with~this~name. + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\@@_options_global:Nn} +% Global (class) options are handled differently for \LaTeXe{} packages +% and classes. Hence this function is essentially a check on the current +% file type. The initial test is needed as \LaTeXe{} allows variables to +% be equal to \cs{scan_stop:}, which is usually forbidden in \pkg{expl3} +% code. +% \begin{macrocode} +\cs_new_protected:Npn \@@_options_global:Nn #1#2 + { + \cs_if_eq:NNF \@classoptionslist \scan_stop: + { + \cs_if_eq:NNTF \@currext \@clsextension + { \@@_options_class:n {#2} } + { + \bool_if:NT #1 + { \@@_options_package:n {#2} } + } + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@@_options_class:n} +% For classes, each option (stripped of any content after |=|) +% is checked for existence as a key. If found, the option is added to +% the combined list for processing. On the other hand, unused options +% are stored up in \cs{@unusedoptionlist}. Before any of that, though, +% there is a simple check to see if there is an |unknown| key. If there +% is, then \emph{everything} will match and the mapping can be skipped. +% \begin{macrocode} +\cs_new_protected:Npn \@@_options_class:n #1 + { + \cs_if_free:cF { opt@ \@currname . \@currext } + { + \keys_if_exist:nnTF {#1} { unknown } + { + \clist_put_right:Nv \l_@@_options_clist + { opt@ \@currname . \@currext } + } + { + \clist_map_inline:cn { opt@ \@currname . \@currext } + { + \keys_if_exist:neTF + {#1} { \@@_remove_equals:n {##1} } + { \clist_put_right:Nn \l_@@_options_clist {##1} } + { \clist_put_right:Nn \@unusedoptionlist {##1} } + } + } + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@@_options_package:n} +% For global options when processing a package, the tasks are slightly +% different from those for a class. The check is the same, but here +% there is nothing to do if the option is not applicable. Each valid +% option also needs to be removed from \cs{@unusedoptionlist}. +% \begin{macrocode} +\cs_new_protected:Npn \@@_options_package:n #1 + { + \clist_map_inline:Nn \@classoptionslist + { + \keys_if_exist:neT {#1} { \@@_remove_equals:n {##1} } + { + \clist_put_right:Nn \l_@@_options_clist {##1} + \clist_remove_all:Nn \@unusedoptionlist {##1} + } + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@@_options_local:} +% If local options are found, the are added to the processing list. +% \LaTeXe{} stores options for each file in a macro which may or may not +% exist, hence the need to use \cs{cs_if_exist:c}. +% \begin{macrocode} +\cs_new_protected:Npn \@@_options_local: + { + \cs_if_eq:NNF \@currext \@clsextension + { + \cs_if_exist:cT { opt@ \@currname . \@currext } + { + \clist_put_right:Nv \l_@@_options_clist + { opt@ \@currname . \@currext } + } + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}[EXP]{\@@_remove_equals:n} +% \begin{macro}[EXP]{\@@_remove_equals:w} +% As the name suggests, this is a simple function to remove an equals +% sign from the input. This is all wrapped up in an \texttt{n} function +% so that there will always be a sign available. +% \begin{macrocode} +\cs_new:Npn \@@_remove_equals:n #1 + { \@@_remove_equals:w #1 = \s_@@_stop } +\cs_new:Npn \@@_remove_equals:w #1 = #2 \s_@@_stop { \exp_not:n {#1} } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \subsection{The document interfaces} +% +% \begin{macro}{\DeclareKeys} +% Defining key options is quite straight-forward: we have an intermediate +% function to allow for potential set-up steps. +% \begin{macrocode} +\NewDocumentCommand \DeclareKeys { o +m } + { + \IfNoValueTF {#1} + { \exp_args:NV \keys_define:nn \@currname } + { \keys_define:nn {#1} } + {#2} + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ProcessKeyOptions, \ProcessKeyPackageOptions} +% We need to deal with the older interface from \pkg{l3keys2e} here: it had +% a mandatory argument. We can mop that up using a look-ahead, and then +% exploit that information to determine whether the package option handling +% is set up for the new approach for clash handling. +% \begin{macrocode} +\NewDocumentCommand \ProcessKeyOptions { o } + { + \IfNoValueTF {#1} + { \@@_options:NV \c_true_bool \@currname } + { \@@_options:Nn \c_true_bool {#1} } + } +\NewDocumentCommand \ProcessKeyPackageOptions { o } + { + \IfNoValueTF {#1} + { \@@_options:NV \c_false_bool \@currname } + { \@@_options:Nn \c_false_bool {#1} } + } +\@onlypreamble \ProcessKeyOptions +\@onlypreamble \ProcessKeyPackageOptions +% \end{macrocode} +% \end{macro} +% +% \subsection{Option usage scope} +% +% \begin{macro}{\@@_options_loaded:n} +% \begin{macro}{\@@_options_loaded:nn} +% Indicates that the load-time options for a package have been processed: +% once this has happened, make them unavailable either with a warning or +% an error. +% \begin{macrocode} +\cs_new_protected:Npn \@@_options_loaded:n #1 + { + \prop_get:NnNT \l_keys_usage_load_prop {#1} \l_@@_tmpa_tl + { + \clist_map_inline:Nn \l_@@_tmpa_tl + { + \keys_define:nn {#1} + { + ##1 .code:n = + \@@_options_loaded:nn {#1} {##1} + } + } + } + } +\cs_new_protected:Npn \@@_options_loaded:nn #1#2 + { + \bool_if:NTF \l_@@_options_loading_bool + { + \msg_warning:nnxx { keys } { load-option-ignored } + { \use:c { opt@fam@\@currname.\@currext } } {#2} + } + { \msg_error:nnnn { keys } { load-only } {#1} {#2} } + } +\msg_new:nnn { keys } { load-option-ignored } + { Package~"#1"~has~already~been~loaded:~ignoring~load-time~option~"#2". } +\msg_new:nnnn { keys } { load-only } + { Key~"#2"~may~only~be~used~in~the~during~loading~of~package~"#1". } + { + LaTeX~was~asked~to~set~a~key~called~"#2",~but~this~is~only~allowed~ + in~the~optional~argument~when~loading~package~"#1". + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% Disable all preamble options in one shot. +% \begin{macrocode} +\tl_gput_left:Nn \@kernel@after@begindocument + { + \prop_map_inline:Nn \l_keys_usage_preamble_prop + { + \clist_map_inline:nn {#2} + { + \keys_define:nn {#1} + { + ##1 .code:n = + \msg_error:nnn { keys } { preamble-only } {##1} + } + } + } + } +\msg_new:nnnn { keys } { preamble-only } + { Key~"#1"~may~only~be~used~in~the~preamble. } + { + LaTeX~was~asked~to~set~a~key~called~"#1",~but~this~is~only~allowed~ + before~\begin{document}.~You~will~need~to~set~the~key~earlier. + } +% \end{macrocode} +% +% \subsection{General key setting} +% +% \begin{macro}{\SetKeys} +% A simple wrapper. +% \begin{macrocode} +\NewDocumentCommand \SetKeys { o +m } + { + \IfNoValueTF {#1} + { \keys_set:Vn \@currname } + { \keys_set:nn {#1} } + {#2} + } +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +\ExplSyntaxOff +% \end{macrocode} +% +% \begin{macrocode} +%</2ekernel> +% \end{macrocode} diff --git a/macros/latex-dev/base/ltlength.dtx b/macros/latex-dev/base/ltlength.dtx index 1be147547e..f979dd4e23 100644 --- a/macros/latex-dev/base/ltlength.dtx +++ b/macros/latex-dev/base/ltlength.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -83,7 +83,7 @@ % \DescribeMacro{\settodepth} % Set the length, |#1| to the depth of a box containing |#2|. % -% \StopEventually{} +% \MaybeStop{} % % \begin{macrocode} %<*2ekernel> diff --git a/macros/latex-dev/base/ltlists.dtx b/macros/latex-dev/base/ltlists.dtx index fecb312588..d0413dad08 100644 --- a/macros/latex-dev/base/ltlists.dtx +++ b/macros/latex-dev/base/ltlists.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -135,7 +135,7 @@ % when it occurs immediately after an |\item| command in an enclosing % list. % -% \StopEventually{} +% \MaybeStop{} % % % \changes{v1.0a}{1994/03/07}{Initial version, split from latex.dtx} diff --git a/macros/latex-dev/base/ltlogos.dtx b/macros/latex-dev/base/ltlogos.dtx index 132eaf636f..56453f73db 100644 --- a/macros/latex-dev/base/ltlogos.dtx +++ b/macros/latex-dev/base/ltlogos.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -65,7 +65,7 @@ % % Various logos are defined here. % -% \StopEventually{} +% \MaybeStop{} % % \begin{macro}{\TeX} % The \TeX{} logo, adjusted so that a full stop after the logo diff --git a/macros/latex-dev/base/ltluatex.dtx b/macros/latex-dev/base/ltluatex.dtx index 258ac48297..18623fd677 100644 --- a/macros/latex-dev/base/ltluatex.dtx +++ b/macros/latex-dev/base/ltluatex.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2015-2021 +% Copyright (C) 2015-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -28,7 +28,7 @@ \ProvidesFile{ltluatex.dtx} %</driver> %<*tex> -[2021/10/15 v1.1v +[2021/12/27 v1.1x %</tex> %<plain> LuaTeX support for plain TeX (core) %<*tex> @@ -120,6 +120,17 @@ % tables from $1$ so |\luafunction0| is not available). % % \noindent +% \DescribeMacro{\newluacmd} +% |\newluadef{|\meta{function}|}|\\ +% Like \cs{newluafunction}, but defines the command using \cs{luadef} +% instead of just assigning an integer. +% +% \noindent +% \DescribeMacro{\newprotectedluacmd} +% |\newluadef{|\meta{function}|}|\\ +% Like \cs{newluacmd}, but the defined command is not expandable. +% +% \noindent % \DescribeMacro{\newwhatsit} % |\newwhatsit{|\meta{whatsit}|}|\\ % Defines a custom \cs{whatsit}, indexed from~$1$. @@ -380,7 +391,7 @@ % % \endgroup % -% \StopEventually{} +% \MaybeStop{} % % \section{Implementation} % @@ -722,6 +733,22 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\newluacmd, \newprotectedluacmd} +% \changes{v1.1x}{2021/12/27}{Macros added} +% Additionally two variants are provided to make the passed control +% sequence call the function directly. +% \begin{macrocode} +\def\newluacmd{% + \e@alloc\luafunction\luadef + \e@alloc@luafunction@count\m@ne\e@alloc@top +} +\def\newprotectedluacmd{% + \e@alloc\luafunction{\protected\luadef} + \e@alloc@luafunction@count\m@ne\e@alloc@top +} +% \end{macrocode} +% \end{macro} +% % \subsection{Custom whatsits} % % \begin{macro}{\newwhatsit} @@ -1351,6 +1378,8 @@ local callbacktypes = callbacktypes or { % \changes{v1.1k}{2019/10/02}{mlist\_to\_hlist is \texttt{exclusive}} % \changes{v1.1l}{2020/02/02}{post\_linebreak\_filter is \texttt{reverselist}} % \changes{v1.1p}{2020/08/01}{new\_graf is \texttt{exclusive}} +% \changes{v1.1w}{2021/11/17}{hpack\_quality is \texttt{exclusive}} +% \changes{v1.1w}{2021/11/17}{vpack\_quality is \texttt{exclusive}} % \begin{macrocode} contribute_filter = simple, buildpage_filter = simple, @@ -1361,8 +1390,8 @@ local callbacktypes = callbacktypes or { post_linebreak_filter = reverselist, hpack_filter = list, vpack_filter = list, - hpack_quality = list, - vpack_quality = list, + hpack_quality = exclusive, + vpack_quality = exclusive, pre_output_filter = list, process_rule = exclusive, hyphenate = simple, @@ -1516,11 +1545,11 @@ end % Handler for |list| callbacks. % \changes{v1.0k}{2015/12/02}{resolve name and i.description (PHG)} % \changes{v1.1s}{2020/12/02}{Fix return value of list callbacks} +% \changes{v1.1w}{2021/11/17}{Never pass on \texttt{true} return values for list callbacks} % \begin{macrocode} local function list_handler(name) return function(head, ...) local ret - local alltrue = true for _,i in ipairs(callbacklist[name]) do ret = i.func(head, ...) if ret == false then @@ -1531,18 +1560,17 @@ local function list_handler(name) return false end if ret ~= true then - alltrue = false head = ret end end - return alltrue and true or head + return head end end % \end{macrocode} % Default for user-defined |list| and |reverselist| callbacks without explicit default. % \begin{macrocode} -local function list_handler_default() - return true +local function list_handler_default(head) +return head end % \end{macrocode} % Handler for |reverselist| callbacks. @@ -1551,7 +1579,6 @@ end local function reverselist_handler(name) return function(head, ...) local ret - local alltrue = true local callbacks = callbacklist[name] for i = #callbacks, 1, -1 do local cb = callbacks[i] @@ -1564,11 +1591,10 @@ local function reverselist_handler(name) return false end if ret ~= true then - alltrue = false head = ret end end - return alltrue and true or head + return head end end % \end{macrocode} @@ -1899,14 +1925,10 @@ callback_register("mlist_to_hlist", function(head, display_type, need_penalties) if current == false then flush_list(head) return nil - elseif current == true then - current = head end current = call_callback("mlist_to_hlist", current, display_type, need_penalties) local post = call_callback("post_mlist_to_hlist_filter", current, display_type, need_penalties) - if post == true then - return current - elseif post == false then + if post == false then flush_list(current) return nil end diff --git a/macros/latex-dev/base/ltluatex.pdf b/macros/latex-dev/base/ltluatex.pdf Binary files differindex 88335534b9..6d45e9e955 100644 --- a/macros/latex-dev/base/ltluatex.pdf +++ b/macros/latex-dev/base/ltluatex.pdf diff --git a/macros/latex-dev/base/ltmath.dtx b/macros/latex-dev/base/ltmath.dtx index 59e0d89a10..9f000a41b4 100644 --- a/macros/latex-dev/base/ltmath.dtx +++ b/macros/latex-dev/base/ltmath.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -74,7 +74,7 @@ % This file contains a lot of the original plain \TeX{} code, as well % as the \LaTeX{} environments for math. It still needs sorting out. % -% \StopEventually{} +% \MaybeStop{} % % \begin{macrocode} %<*2ekernel> diff --git a/macros/latex-dev/base/ltmeta.dtx b/macros/latex-dev/base/ltmeta.dtx new file mode 100644 index 0000000000..e1c296ae1d --- /dev/null +++ b/macros/latex-dev/base/ltmeta.dtx @@ -0,0 +1,189 @@ +% \iffalse meta-comment +% +%% File: ltmeta.dtx (C) Copyright 2021 +% Frank Mittelbach, LaTeX Team +% +% It may be distributed and/or modified under the conditions of the +% LaTeX Project Public License (LPPL), either version 1.3c of this +% license or (at your option) any later version. The latest version +% of this license is in the file +% +% https://www.latex-project.org/lppl.txt +% +% +%%% From File: ltmeta.dtx +% +% \begin{macrocode} +\def\ltmetaversion{v1.0a} +\def\ltmetadate{2021/12/07} +% \end{macrocode} +%<*driver> +\documentclass{l3doc} + +%\usepackage{ltmeta} + +% Fixing footnotes in functions and variables: this should be in l3doc! + +\newcommand\fixfootnote[2]{\footnotemark + \AddToHookNext{env/#1/after}{\footnotetext{#2}}} +\AddToHook{env/function/begin}{\def\footnote{\fixfootnote{function}}} +\AddToHook{env/variable/begin}{\def\footnote{\fixfootnote{variable}}} + +\EnableCrossrefs +\CodelineIndex +\begin{document} + \DocInput{ltmeta.dtx} +\end{document} +%</driver> +% +% \fi +% +% \providecommand\hook[1]{\texttt{#1}} +% \providecommand\env[1]{\texttt{#1}} +% +% +% +% \title{The \texttt{ltmeta.dtx} code\thanks{This file has version +% \ltmetaversion\ dated \ltmetadate, \copyright\ \LaTeX\ +% Project.}} +% \author{Frank Mittelbach} +% +% \maketitle +% +% +% \begin{abstract} +% This code defines the \cs{DocumentMetadata} interface. +% \end{abstract} +% +% \tableofcontents +% +% +% \section{Introduction} +% +% +% In the past there was no dedicated location to declare settings +% concerning a document as a whole. Settings are placed somewhere +% in the preamble or with the class options or even with some +% package options. For some settings this can be too late, for +% example the pdf version can no longer be changed if a package has +% used code which already opened the PDF. +% +% \cs{DocumentMetadata} as a new command unifies such settings in +% one place. It must be used before \cs{documentclass} but can be +% issued more than once there. +% +% At the moment most of the code run by \cs{DocumentMetadata} is +% external to the format and subject to change. This includes the +% supported key/values. +% +% For that reason all that happens right now in the format is to +% look for suitable support files and if found, to redirect the +% processing to them. +% +% \subsection{\cs{DocumentMetadata}} +% +% \begin{function}{\DocumentMetadata} +% \begin{syntax} +% \cs{DocumentMetadata}\Arg{key-value list} +% \end{syntax} +% \end{function} +% +% +% +% The keys defined for \cs{DocumentMetadata} +% currently allow to set the PDF version, to set the PDF \texttt{/Lang}, +% to uncompress a PDF, to set the language and to declare a few PDF standards +% and some color profiles. +% +% \cs{DocumentMetadata} is also used to +% activate the new PDF management code and it loads +% a number of required files for the PDF management code. +% As this forces the loading of the backend files, a backend +% which can't be detected automatically like |dvipdfmx|, +% must be set in the first \cs{DocumentMetadata} call (if there is more than one). +% +% The full set of keys currently supported is documented in \texttt{documentmetadata-support.pdf} +% for now. +% +% +% \StopEventually{\setlength\IndexMin{200pt} \PrintIndex } +% +% +% \section{The Implementation} +% +% +% +% \begin{macrocode} +%<*2ekernel|latexrelease> +% \end{macrocode} +% Not needed yet but \ldots +% \begin{macrocode} +%\ExplSyntaxOn +% \end{macrocode} +% +% \begin{macrocode} +%<latexrelease>\NewModuleRelease{2021/06/01}{ltmeta} +%<latexrelease> {Document Metadata handling} +% \end{macrocode} +% +% \begin{macrocode} +\protected\def\DocumentMetadata{% + \InputIfFileExists{documentmetadata-support.ltx}% + {}% +% \end{macrocode} +% The above file is changing \cs{DocumentMetadata} to a suitable +% definition (or so we hope), so that we can try again --- if not +% tough. +% +% If the file can't be found we say so and carry on without it. +% \begin{macrocode} + {% + \@latex@error{No support files for + \noexpand\DocumentMetadata found} + {Is the 'LaTeX-lab' bundle installed?% + \MessageBreak + Without it, the declaration is ignored.}% +% \end{macrocode} +% No point in trying this more than once if there are several calls +% in the document. +% \begin{macrocode} + \let\DocumentMetadata\@gobble + }% + \DocumentMetadata +} +% \end{macrocode} +% +% +% +% +% +% \begin{macrocode} +% +%<latexrelease>\IncludeInRelease{0000/00/00}{ltmeta}% +%<latexrelease> {Undo Document Metadata handling} +%<latexrelease> +%<latexrelease>\let\DocumentMetadata\@undefined +%<latexrelease> +%<latexrelease>\EndModuleRelease +% \end{macrocode} +% Again for the future \ldots +% \begin{macrocode} +%\ExplSyntaxOff +% \end{macrocode} +% \begin{macrocode} +%</2ekernel|latexrelease> +% \end{macrocode} +% +% Restore module prefix (if any): +% \begin{macrocode} +%<@@=> +% \end{macrocode} +% +% +% +% +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\endinput +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% diff --git a/macros/latex-dev/base/ltmiscen.dtx b/macros/latex-dev/base/ltmiscen.dtx index 6cc58907a0..b7b2bf5e31 100644 --- a/macros/latex-dev/base/ltmiscen.dtx +++ b/macros/latex-dev/base/ltmiscen.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -81,7 +81,7 @@ % environments and related commands, the `flushing' environments, % (|center|, |flushleft|, |flushright|), and |verbatim|. % -% \StopEventually{} +% \MaybeStop{} % % \begin{macrocode} %<*2ekernel> diff --git a/macros/latex-dev/base/ltnews.pdf b/macros/latex-dev/base/ltnews.pdf Binary files differindex aaf1aedb2a..af545c21fe 100644 --- a/macros/latex-dev/base/ltnews.pdf +++ b/macros/latex-dev/base/ltnews.pdf diff --git a/macros/latex-dev/base/ltnews.tex b/macros/latex-dev/base/ltnews.tex index 406787c5f0..cba11c3ce3 100644 --- a/macros/latex-dev/base/ltnews.tex +++ b/macros/latex-dev/base/ltnews.tex @@ -38,9 +38,9 @@ \NeedsTeXFormat{LaTeX2e} \ProvidesFile{ltnews.tex}% - [2021/06/07 v1.4d Master file for ltnews*.tex (LaTeX Project)] + [2021/11/12 v1.4d Master file for ltnews*.tex (LaTeX Project)] -\providecommand*{\lastissue}{34} +\providecommand*{\lastissue}{35} \InputIfFileExists{ltnews-lastissue.cfg}{}{} @@ -222,7 +222,11 @@ \def\y{|multicol}% \ifx\x\y \else - \@latex@error{ltnews.tex: \string\usepackage[#1]{#2} found}\@ehc + \def\y{|color}% + \ifx\x\y + \else + \@latex@error{ltnews.tex: \string\usepackage[#1]{#2} found}\@ehc + \fi \fi \fi \fi diff --git a/macros/latex-dev/base/ltnews01.pdf b/macros/latex-dev/base/ltnews01.pdf Binary files differindex 4179783fd4..1ab890fe99 100644 --- a/macros/latex-dev/base/ltnews01.pdf +++ b/macros/latex-dev/base/ltnews01.pdf diff --git a/macros/latex-dev/base/ltnews01.tex b/macros/latex-dev/base/ltnews01.tex index 3703f23f61..08ac57d27d 100644 --- a/macros/latex-dev/base/ltnews01.tex +++ b/macros/latex-dev/base/ltnews01.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews02.pdf b/macros/latex-dev/base/ltnews02.pdf Binary files differindex 1d1284ca5d..39e5eb69ac 100644 --- a/macros/latex-dev/base/ltnews02.pdf +++ b/macros/latex-dev/base/ltnews02.pdf diff --git a/macros/latex-dev/base/ltnews02.tex b/macros/latex-dev/base/ltnews02.tex index dfc78e4843..1d875dcd03 100644 --- a/macros/latex-dev/base/ltnews02.tex +++ b/macros/latex-dev/base/ltnews02.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews03.pdf b/macros/latex-dev/base/ltnews03.pdf Binary files differindex 5644d1f86b..48f5b26526 100644 --- a/macros/latex-dev/base/ltnews03.pdf +++ b/macros/latex-dev/base/ltnews03.pdf diff --git a/macros/latex-dev/base/ltnews03.tex b/macros/latex-dev/base/ltnews03.tex index e555e12df4..93f0963426 100644 --- a/macros/latex-dev/base/ltnews03.tex +++ b/macros/latex-dev/base/ltnews03.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews04.pdf b/macros/latex-dev/base/ltnews04.pdf Binary files differindex a6408f8aca..f6d36a762e 100644 --- a/macros/latex-dev/base/ltnews04.pdf +++ b/macros/latex-dev/base/ltnews04.pdf diff --git a/macros/latex-dev/base/ltnews04.tex b/macros/latex-dev/base/ltnews04.tex index 0a313664ba..527024fa18 100644 --- a/macros/latex-dev/base/ltnews04.tex +++ b/macros/latex-dev/base/ltnews04.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews05.pdf b/macros/latex-dev/base/ltnews05.pdf Binary files differindex 3696f58f19..e8eb6f67a4 100644 --- a/macros/latex-dev/base/ltnews05.pdf +++ b/macros/latex-dev/base/ltnews05.pdf diff --git a/macros/latex-dev/base/ltnews05.tex b/macros/latex-dev/base/ltnews05.tex index 840f04fe72..d13f469dd6 100644 --- a/macros/latex-dev/base/ltnews05.tex +++ b/macros/latex-dev/base/ltnews05.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews06.pdf b/macros/latex-dev/base/ltnews06.pdf Binary files differindex 445505966f..b4a0f5dd17 100644 --- a/macros/latex-dev/base/ltnews06.pdf +++ b/macros/latex-dev/base/ltnews06.pdf diff --git a/macros/latex-dev/base/ltnews06.tex b/macros/latex-dev/base/ltnews06.tex index 52ecba9918..ac32eab8d1 100644 --- a/macros/latex-dev/base/ltnews06.tex +++ b/macros/latex-dev/base/ltnews06.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews07.pdf b/macros/latex-dev/base/ltnews07.pdf Binary files differindex ea6fbd6d5e..d411bef57a 100644 --- a/macros/latex-dev/base/ltnews07.pdf +++ b/macros/latex-dev/base/ltnews07.pdf diff --git a/macros/latex-dev/base/ltnews07.tex b/macros/latex-dev/base/ltnews07.tex index db3812e387..56cfd76661 100644 --- a/macros/latex-dev/base/ltnews07.tex +++ b/macros/latex-dev/base/ltnews07.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews08.pdf b/macros/latex-dev/base/ltnews08.pdf Binary files differindex b0205c8549..ba927184d0 100644 --- a/macros/latex-dev/base/ltnews08.pdf +++ b/macros/latex-dev/base/ltnews08.pdf diff --git a/macros/latex-dev/base/ltnews08.tex b/macros/latex-dev/base/ltnews08.tex index d79a1b1b74..68cd1247e6 100644 --- a/macros/latex-dev/base/ltnews08.tex +++ b/macros/latex-dev/base/ltnews08.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews09.pdf b/macros/latex-dev/base/ltnews09.pdf Binary files differindex eb5684db03..1385507355 100644 --- a/macros/latex-dev/base/ltnews09.pdf +++ b/macros/latex-dev/base/ltnews09.pdf diff --git a/macros/latex-dev/base/ltnews09.tex b/macros/latex-dev/base/ltnews09.tex index 2d56515ca0..af14a53e34 100644 --- a/macros/latex-dev/base/ltnews09.tex +++ b/macros/latex-dev/base/ltnews09.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews10.pdf b/macros/latex-dev/base/ltnews10.pdf Binary files differindex 08b736b4fe..ee0327a5c8 100644 --- a/macros/latex-dev/base/ltnews10.pdf +++ b/macros/latex-dev/base/ltnews10.pdf diff --git a/macros/latex-dev/base/ltnews10.tex b/macros/latex-dev/base/ltnews10.tex index 5ab159f0bb..c6a77e6e36 100644 --- a/macros/latex-dev/base/ltnews10.tex +++ b/macros/latex-dev/base/ltnews10.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews11.pdf b/macros/latex-dev/base/ltnews11.pdf Binary files differindex 16b61b603d..51e82c1f02 100644 --- a/macros/latex-dev/base/ltnews11.pdf +++ b/macros/latex-dev/base/ltnews11.pdf diff --git a/macros/latex-dev/base/ltnews11.tex b/macros/latex-dev/base/ltnews11.tex index 6d27fee067..b4f6d19910 100644 --- a/macros/latex-dev/base/ltnews11.tex +++ b/macros/latex-dev/base/ltnews11.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews12.pdf b/macros/latex-dev/base/ltnews12.pdf Binary files differindex eff43ee46c..0f02498fd4 100644 --- a/macros/latex-dev/base/ltnews12.pdf +++ b/macros/latex-dev/base/ltnews12.pdf diff --git a/macros/latex-dev/base/ltnews12.tex b/macros/latex-dev/base/ltnews12.tex index 62b08324b7..b7a01bc208 100644 --- a/macros/latex-dev/base/ltnews12.tex +++ b/macros/latex-dev/base/ltnews12.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews13.pdf b/macros/latex-dev/base/ltnews13.pdf Binary files differindex 8a902117fc..bc7e4244ba 100644 --- a/macros/latex-dev/base/ltnews13.pdf +++ b/macros/latex-dev/base/ltnews13.pdf diff --git a/macros/latex-dev/base/ltnews13.tex b/macros/latex-dev/base/ltnews13.tex index 08acf95df6..0cbbe49a5d 100644 --- a/macros/latex-dev/base/ltnews13.tex +++ b/macros/latex-dev/base/ltnews13.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews14.pdf b/macros/latex-dev/base/ltnews14.pdf Binary files differindex 3ebbf0704d..e00f82dd75 100644 --- a/macros/latex-dev/base/ltnews14.pdf +++ b/macros/latex-dev/base/ltnews14.pdf diff --git a/macros/latex-dev/base/ltnews14.tex b/macros/latex-dev/base/ltnews14.tex index 61c96c81ae..b5fa7cb019 100644 --- a/macros/latex-dev/base/ltnews14.tex +++ b/macros/latex-dev/base/ltnews14.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews15.pdf b/macros/latex-dev/base/ltnews15.pdf Binary files differindex fb8b6a1539..89f68f003c 100644 --- a/macros/latex-dev/base/ltnews15.pdf +++ b/macros/latex-dev/base/ltnews15.pdf diff --git a/macros/latex-dev/base/ltnews15.tex b/macros/latex-dev/base/ltnews15.tex index e143d5f4dd..3b1ea3f89c 100644 --- a/macros/latex-dev/base/ltnews15.tex +++ b/macros/latex-dev/base/ltnews15.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews16.pdf b/macros/latex-dev/base/ltnews16.pdf Binary files differindex 8334c9c0ac..d1f12d79a4 100644 --- a/macros/latex-dev/base/ltnews16.pdf +++ b/macros/latex-dev/base/ltnews16.pdf diff --git a/macros/latex-dev/base/ltnews16.tex b/macros/latex-dev/base/ltnews16.tex index 17f9cd094a..7f7183ac0e 100644 --- a/macros/latex-dev/base/ltnews16.tex +++ b/macros/latex-dev/base/ltnews16.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews17.pdf b/macros/latex-dev/base/ltnews17.pdf Binary files differindex 7a3603af62..2029148dc7 100644 --- a/macros/latex-dev/base/ltnews17.pdf +++ b/macros/latex-dev/base/ltnews17.pdf diff --git a/macros/latex-dev/base/ltnews17.tex b/macros/latex-dev/base/ltnews17.tex index 614c5c7d63..4dab20f53f 100644 --- a/macros/latex-dev/base/ltnews17.tex +++ b/macros/latex-dev/base/ltnews17.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews18.pdf b/macros/latex-dev/base/ltnews18.pdf Binary files differindex d2ecaf5b3b..ecdd021457 100644 --- a/macros/latex-dev/base/ltnews18.pdf +++ b/macros/latex-dev/base/ltnews18.pdf diff --git a/macros/latex-dev/base/ltnews18.tex b/macros/latex-dev/base/ltnews18.tex index 518aeda067..04491760b2 100644 --- a/macros/latex-dev/base/ltnews18.tex +++ b/macros/latex-dev/base/ltnews18.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews19.pdf b/macros/latex-dev/base/ltnews19.pdf Binary files differindex 1cb3bf11c4..c6cf9a5d4b 100644 --- a/macros/latex-dev/base/ltnews19.pdf +++ b/macros/latex-dev/base/ltnews19.pdf diff --git a/macros/latex-dev/base/ltnews19.tex b/macros/latex-dev/base/ltnews19.tex index f733c41dd4..43d388b29b 100644 --- a/macros/latex-dev/base/ltnews19.tex +++ b/macros/latex-dev/base/ltnews19.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews20.pdf b/macros/latex-dev/base/ltnews20.pdf Binary files differindex 7ec8810601..c9b1e7dc6c 100644 --- a/macros/latex-dev/base/ltnews20.pdf +++ b/macros/latex-dev/base/ltnews20.pdf diff --git a/macros/latex-dev/base/ltnews21.pdf b/macros/latex-dev/base/ltnews21.pdf Binary files differindex d0d620eded..67c8925470 100644 --- a/macros/latex-dev/base/ltnews21.pdf +++ b/macros/latex-dev/base/ltnews21.pdf diff --git a/macros/latex-dev/base/ltnews22.pdf b/macros/latex-dev/base/ltnews22.pdf Binary files differindex eea02d5344..f556f2a7b2 100644 --- a/macros/latex-dev/base/ltnews22.pdf +++ b/macros/latex-dev/base/ltnews22.pdf diff --git a/macros/latex-dev/base/ltnews22.tex b/macros/latex-dev/base/ltnews22.tex index 7551616154..8d1c91acfa 100644 --- a/macros/latex-dev/base/ltnews22.tex +++ b/macros/latex-dev/base/ltnews22.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2015-2021 +% Copyright (C) 2015-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews23.pdf b/macros/latex-dev/base/ltnews23.pdf Binary files differindex a8727c72ac..44e8064b3c 100644 --- a/macros/latex-dev/base/ltnews23.pdf +++ b/macros/latex-dev/base/ltnews23.pdf diff --git a/macros/latex-dev/base/ltnews23.tex b/macros/latex-dev/base/ltnews23.tex index 99e9615074..29241766ca 100644 --- a/macros/latex-dev/base/ltnews23.tex +++ b/macros/latex-dev/base/ltnews23.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2015-2021 +% Copyright (C) 2015-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews24.pdf b/macros/latex-dev/base/ltnews24.pdf Binary files differindex 0e5a969ed5..35b80e46c5 100644 --- a/macros/latex-dev/base/ltnews24.pdf +++ b/macros/latex-dev/base/ltnews24.pdf diff --git a/macros/latex-dev/base/ltnews24.tex b/macros/latex-dev/base/ltnews24.tex index 44cd76a060..13d2fc8519 100644 --- a/macros/latex-dev/base/ltnews24.tex +++ b/macros/latex-dev/base/ltnews24.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2015-2021 +% Copyright (C) 2015-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews25.pdf b/macros/latex-dev/base/ltnews25.pdf Binary files differindex 5857ae116c..1b096ddcbc 100644 --- a/macros/latex-dev/base/ltnews25.pdf +++ b/macros/latex-dev/base/ltnews25.pdf diff --git a/macros/latex-dev/base/ltnews25.tex b/macros/latex-dev/base/ltnews25.tex index 735fda356e..5a9f480718 100644 --- a/macros/latex-dev/base/ltnews25.tex +++ b/macros/latex-dev/base/ltnews25.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2016-2021 +% Copyright (C) 2016-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews26.pdf b/macros/latex-dev/base/ltnews26.pdf Binary files differindex fc3cc7060b..42a9e76e10 100644 --- a/macros/latex-dev/base/ltnews26.pdf +++ b/macros/latex-dev/base/ltnews26.pdf diff --git a/macros/latex-dev/base/ltnews26.tex b/macros/latex-dev/base/ltnews26.tex index f0e7578b70..94b4c4818b 100644 --- a/macros/latex-dev/base/ltnews26.tex +++ b/macros/latex-dev/base/ltnews26.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2017-2021 +% Copyright (C) 2017-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews27.pdf b/macros/latex-dev/base/ltnews27.pdf Binary files differindex 410338cc85..7c45486bb2 100644 --- a/macros/latex-dev/base/ltnews27.pdf +++ b/macros/latex-dev/base/ltnews27.pdf diff --git a/macros/latex-dev/base/ltnews27.tex b/macros/latex-dev/base/ltnews27.tex index ba17d26e5e..03c8c04205 100644 --- a/macros/latex-dev/base/ltnews27.tex +++ b/macros/latex-dev/base/ltnews27.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2017-2021 +% Copyright (C) 2017-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews28.pdf b/macros/latex-dev/base/ltnews28.pdf Binary files differindex e88bfdcdb4..c1f63b59de 100644 --- a/macros/latex-dev/base/ltnews28.pdf +++ b/macros/latex-dev/base/ltnews28.pdf diff --git a/macros/latex-dev/base/ltnews28.tex b/macros/latex-dev/base/ltnews28.tex index 03d4a04ae1..28bfe0577c 100644 --- a/macros/latex-dev/base/ltnews28.tex +++ b/macros/latex-dev/base/ltnews28.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2017-2021 +% Copyright (C) 2017-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews29.pdf b/macros/latex-dev/base/ltnews29.pdf Binary files differindex 1cd9485123..b1de2fc801 100644 --- a/macros/latex-dev/base/ltnews29.pdf +++ b/macros/latex-dev/base/ltnews29.pdf diff --git a/macros/latex-dev/base/ltnews29.tex b/macros/latex-dev/base/ltnews29.tex index 749b927218..c06d4de347 100644 --- a/macros/latex-dev/base/ltnews29.tex +++ b/macros/latex-dev/base/ltnews29.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2018-2021 +% Copyright (C) 2018-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltnews30.pdf b/macros/latex-dev/base/ltnews30.pdf Binary files differindex 7f4bf25930..8bb8e3e732 100644 --- a/macros/latex-dev/base/ltnews30.pdf +++ b/macros/latex-dev/base/ltnews30.pdf diff --git a/macros/latex-dev/base/ltnews31.pdf b/macros/latex-dev/base/ltnews31.pdf Binary files differindex 35218ae875..928a14e4be 100644 --- a/macros/latex-dev/base/ltnews31.pdf +++ b/macros/latex-dev/base/ltnews31.pdf diff --git a/macros/latex-dev/base/ltnews32.pdf b/macros/latex-dev/base/ltnews32.pdf Binary files differindex 5a1923988a..4ba4ff8185 100644 --- a/macros/latex-dev/base/ltnews32.pdf +++ b/macros/latex-dev/base/ltnews32.pdf diff --git a/macros/latex-dev/base/ltnews33.pdf b/macros/latex-dev/base/ltnews33.pdf Binary files differindex 29c95d920b..4c0e50b65f 100644 --- a/macros/latex-dev/base/ltnews33.pdf +++ b/macros/latex-dev/base/ltnews33.pdf diff --git a/macros/latex-dev/base/ltnews34.pdf b/macros/latex-dev/base/ltnews34.pdf Binary files differindex 8d4a258059..a6d8fbbd53 100644 --- a/macros/latex-dev/base/ltnews34.pdf +++ b/macros/latex-dev/base/ltnews34.pdf diff --git a/macros/latex-dev/base/ltnews34.tex b/macros/latex-dev/base/ltnews34.tex index badd25b97c..a6450b97c3 100644 --- a/macros/latex-dev/base/ltnews34.tex +++ b/macros/latex-dev/base/ltnews34.tex @@ -493,7 +493,8 @@ for which these are now the preferred replacements. This optional argument specifies the format of the counter, such as \cs{roman}; the default value is \cs{arabic}. - +Alternatively, you can use a starred form, in which case the format of the +counter is not altered at all. \subsection{Tests for package and class loading} @@ -738,7 +739,7 @@ setting the new defaults. \subsection{Use of \texttt{\textup{\#}} in \cs{textbf} and similar commands} Previously you could not use the macro parameter character \texttt{\#} in inline functions -within the argument of \cs{texbf} or similar text font commands. +within the argument of \cs{textbf} or similar text font commands. An internal definition is now guarded with \cs{unexpanded} so that the use of \texttt{\#} here no longer generates an error. % @@ -783,7 +784,7 @@ possibilities. A \env{tabular} environment is typeset (internally) as an \env{array} environment with special settings, and it therefore uses (hidden) math mode. Since it is not in fact a math formula, -no extra space from \cs{mathsuround} should be added +no extra space from \cs{mathsurround} should be added (the spacing around the \env{tabular} should not get changed). % Note that this bug has been present ``forever'', which shows that \cs{mathsurround} @@ -830,7 +831,7 @@ brace groups inside \cs{r@}\meta{label}) However, if \pkg{nameref} or arguments; this could cause low-level errors in some cases. The code has therefore now been changed to avoid these errors. % -\sxissue{603948} +\sxissue{q/603948} \medskip diff --git a/macros/latex-dev/base/ltnews35.pdf b/macros/latex-dev/base/ltnews35.pdf Binary files differnew file mode 100644 index 0000000000..44fea294e8 --- /dev/null +++ b/macros/latex-dev/base/ltnews35.pdf diff --git a/macros/latex-dev/base/ltnews35.tex b/macros/latex-dev/base/ltnews35.tex new file mode 100644 index 0000000000..31bce8a115 --- /dev/null +++ b/macros/latex-dev/base/ltnews35.tex @@ -0,0 +1,583 @@ +% \iffalse meta-comment +% +% Copyright 2019-2021 +% The LaTeX Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% -—————————————— +% +% It may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3c +% of this license or (at your option) any later version. +% The latest version of this license is in +% https://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2008 or later. +% +% This file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews35.tex +% +% This is issue 35 of LaTeX News. + +\NeedsTeXFormat{LaTeX2e}[2020-02-02] + +\documentclass{ltnews} + +%% Maybe needed only for Chris' inadequate system: +\providecommand\Dash {\unskip \textemdash} + +%% NOTE: Chris' preferred hyphens! +%%\showhyphens{parameters} +%% \hyphenation{because parameters parameter} + +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url,hologo} + +\usepackage{csquotes} +\usepackage{multicol} +\usepackage{color} + +\providecommand\hook[1]{\texttt{#1}} + +\providecommand\meta[1]{$\langle$\textrm{\itshape#1}$\rangle$} +\providecommand\option[1]{\texttt{#1}} +\providecommand\env[1]{\texttt{#1}} +\providecommand\Arg[1]{\texttt\{\meta{#1}\texttt\}} + + +\providecommand\eTeX{\hologo{eTeX}} +\providecommand\XeTeX{\hologo{XeTeX}} +\providecommand\LuaTeX{\hologo{LuaTeX}} +\providecommand\pdfTeX{\hologo{pdfTeX}} +\providecommand\MiKTeX{\hologo{MiKTeX}} +\providecommand\CTAN{\textsc{ctan}} +\providecommand\TL{\TeX\,Live} +\providecommand\githubissue[2][]{\ifhmode\unskip\fi + \quad\penalty500\strut\nobreak\hfill + \mbox{\small\slshape(% + \href{https://github.com/latex3/latex2e/issues/\getfirstgithubissue#2 \relax}% + {github issue#1 #2}% + )}% + \par\smallskip} +%% But Chris has to mostly disable \href for his TEXPAD app: +%% \def\href #1{} % Only For Chris' deficient TeX engine + +% simple solution right now (just link to the first issue if there are more) +\def\getfirstgithubissue#1 #2\relax{#1} + +\providecommand\sxissue[1]{\ifhmode\unskip\fi + \quad\penalty500\strut\nobreak\hfill + \mbox{\small\slshape(\url{https://tex.stackexchange.com/#1})}\par} + +\providecommand\gnatsissue[2]{\ifhmode\unskip\fi + \quad\penalty500\strut\nobreak\hfill + \mbox{\small\slshape(% + \href{https://www.latex-project.org/cgi-bin/ltxbugs2html?pr=#1\%2F\getfirstgithubissue#2 \relax}% + {gnats issue #1/#2}% + )}% + \par} + +\let\cls\pkg +\providecommand\env[1]{\texttt{#1}} +\providecommand\acro[1]{\textsc{#1}} + +\vbadness=1400 % accept slightly empty columns + + +\makeatletter +% maybe not the greatest design but normally we wouldn't have subsubsections +\renewcommand{\subsubsection}{% + \@startsection {subsubsection}{2}{0pt}{1.5ex \@plus 1ex \@minus .2ex}% + {-1em}{\@subheadingfont\colonize}% +} +\providecommand\colonize[1]{#1:} +\makeatother + +\let\finalvspace\vspace % for document layout fixes + +% Undo ltnews's \verbatim@font with active < and > +\makeatletter +\def\verbatim@font{% + \normalsize\ttfamily} +\makeatletter + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\providecommand\tubcommand[1]{} +\tubcommand{\input{tubltmac}} + +\publicationmonth{June} +\publicationyear{2022 --- DRAFT version for upcoming release} + +\publicationissue{35} + +\begin{document} + +\tubcommand{\addtolength\textheight{4.2pc}} % only for TUB + +\maketitle +{\hyphenpenalty=10000 \spaceskip=3.33pt \hbadness=10000 \tableofcontents} + +\setlength\rightskip{0pt plus 3em} + + +\medskip + + +\section{Introduction} + +\section{Document metadata interface} + +Until recently there was no dedicated location to declare +settings that affect a document as a whole. Settings had to be placed +somewhere in the preamble or as class options or sometimes even as +package options. For some such settings this may cause issues, e.g., +setting the PDF version is only possible as long as the PDF output +file has not yet been opened which can be caused by loading one or the +other package. + +For the \enquote{\LaTeX{} Tagged PDF project}~\cite{35:blueprint} +further metadata about the whole document (and its processing) need to +be specified and again this data should be all placed in a single +well-defined place. + +For this reason we introduce the new command \cs{DocumentMetadata} to +unify all such settings in one place. The command expects a key/value +list that describes all document metadata for the current document. It +is only allowed to be used at the very beginning of the document, +i.e., the declaration has to be placed \emph{before} +\cs{documentclass} and will issue an error if found later. + + +At this point in time we only provide the bare command in the format, +the actual processing of the key/value is defined externally and the +necessary code will be loaded if the command is used. This scheme is +chosen for two reasons: by adding the command in the kernel it is +available to everybody without the need to load a special package +using \cs{RequirePackage}. The actual processing, though, is external +so that we can easily extend the code (e.g., offering additional keys +or changing the internal processing) while the above mentioned project +is progressing. Both together allows users to immediately benefit from +intermediate results produced as part of the project, as well as +offering the \LaTeX{} Project Team the flexibility to enable such +intermediate results (for test purposes or even production use) +in-between and independently of regular \LaTeX{} releases. Over time, +tested and approved functionality can then seamlessly move into the +kernel at a later stage without any alterations to documents already +using it. At the same time, not using the new consolidated interface +means that existing documents are in no way affected by the work that +is carried out and is in a wider alpha or beta test phase. + +Documentation about the new command and +already existing keys are in \file{l3meta.pdf} and \file{documentmetadata-support.pdf} +and also in the documentation of the \pkg{pdfmanagement-testphase} package. + + +\section{The \pkg{latex-lab} bundle} + +\emph{write about it} + + + + +\section{New or improved commands} + +\subsection{A kevyal approach to option handling} + +The classical \LaTeXe{} method for handling options, using \cs{ProcessOptions}, +treats each entry in the list as a string. Many package authors have sought to +extend this handling by treating each entry as a key--value pair (keyval) +instead. To-date, this has required the use of additional packages, for example +\pkg{kvoptions}. + +The \LaTeX{} team have for some time offered the package \pkg{l3keys2e} to +allow keyvals defined using the L3 programming layer module \pkg{l3keys} to act +as package options. This ability has now been integrated directly into the +kernel. As part of this integration, the syntax for processing keyval options +has been refined, such that +\begin{verbatim} +\ProcessKeyOptions +\end{verbatim} +will now automatically pick up the package name as the key \emph{family}, +unless explicitly given as an optional argument. +\begin{verbatim} +\ProcessKeyOptions[family] +\end{verbatim} +A version which does not consider global options, +\cs{ProcessKeyPackageOptions}, is also available. + +To support creating key options in for this mechanism, the new command +\cs{DeclareKeys} has been added. This works using the same general +approach as \pkg{l3keys} or \pkg{pgfkeys}: each key has one or more +\emph{properties} which define its behavior. + +Options for packages which use this new approach will not be checked for +clashes by the kernel. Instead, each time a \cs{usepackage} or +\cs{RequirePackage} line is encountered, the list of options given will be +passed to \cs{ProcessKeyPackageOptions}. Options which can only be given +the first time a package is loaded can be marked using the property +\texttt{.usage = load}, and will result in a warning if used in a subsequent +package loading line. + +Package options defined in this way can also be set within a package using +the new command \cs{SetKeys}, which again takes an optional argument +to specify the \emph{family}, plus a mandatory one for the options themselves. + +\subsection{Floating point and integer calculations} + +The L3 programming layer offers expandable commands for calculating +floating point and integer values, but so far these functions have +only been available to programmers, because they require +\cs{ExplSyntaxOn} to be in force. To make them easily available at the +document-level, the small package \pkg{xfp} defined \cs{fpeval} and +\cs{inteval}. + + +An example of use could be the following: +\begin{verbatim} +\LaTeX{} can now compute: +\[ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3} + = \fpeval{sin(3.5)/2 + 2e-3} \] +\end{verbatim} +which produces the following output: +\begin{quote} +\LaTeX{} can now compute: +\[ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3} + = \fpeval{sin(3.5)/2 + 2e-3} \] +\end{quote} +These two commands have now been moved into the kernel and in addition +we also provide \cs{dimeval} and \cs{skipeval}. The details of their +syntax are described in \file{usrguide3.pdf}. The command \cs{fpeval} +offers a rich syntax allows for extensive calculations whereas the +other three commands are essentially thin wrappers for \cs{numexpr}, +\cs{dimexpr}, and \cs{glueexpr} \Dash therefore inheriting some syntax +peculiars and limitations in expressiveness. +\begin{verbatim} +\newcommand\calulateheight[1]{% + \setlength\textheight{\dimeval{\topskip + + \baselineskip * \inteval{#1-1}}}} +\end{verbatim} +The above, for example, calculates the appropriate \cs{textheight} for +a given number of text lines. +% +\githubissue{711} + + +\subsection{CamelCase commands for changing arguments to csnames} + +It is sometimes helpful to \enquote{construct} a command name on the +fly rather than providing it as a single \cs{...} token. For these +kind of tasks the \LaTeX3 programming layer offers a general mechanism +(in form of \cs{exp\_args:N...} and +\cs{cs\_generate\_variant:Nn}). However, when declaring new +document-level commands with \cs{NewDocumentCommand} or +\cs{NewCommandCopy}, etc.\ the L3 programming layer may not be active, +and even if it is, mixing CamelCase syntax with L3 programming syntax +is not really a good approach. We have therefore added the commands +\cs{UseName} and \cs{ExpandArgs} to assist in such +situations, e.g., +\begin{verbatim} +\NewDocumentCommand\newcopyedit{mO{red}} + {\newcounter{todo#1}% + \ExpandArgs{c}\NewDocumentCommand{#1}{s m}% + {\stepcounter{todo#1}% + \IfBooleanTF {##1}% + {\todo[color=#2!10]% + {\UseName{thetodo#1}: ##2}}% + {\todo[inline,color=#2!10]% + {\UseName{thetodo#1}: ##2}}% + }% + } +\end{verbatim} +which provides a declaration mechanism for copyedit commands, so that +\verb=\newcopyedit{FMi}[blue]= then defines \cs{FMi} (and the +necessary counter). + +The command \cs{ExpandArgs} can be useful with the argument \texttt{cc} or +\texttt{Nc} in +combination with \cs{NewCommandCopy} if the old or new command name +or both need constructing. Finally, there is \cs{UseName} which +takes its argument and turns it into a command (i.e., a CamelCase +version of \cs{@nameuse} (\LaTeXe) or \cs{use:c} (L3 programming +layer)) which was also used in the example above. +% +\githubissue{735} + + + +\subsection{???} +% +\githubissue{???} + + +\section{Code improvements} + +\subsection{\class{ltxdoc} gets a \option{nocfg} option} + +The \LaTeX{} sources are formatted with the \class{ltxdoc} class, +which supports loading a local config file \file{ltxdoc.cfg}. In the +past the \LaTeX{} sources used such a file but it was not distributed. +As a result reprocessing the \LaTeX{} sources elsewhere showed +formatting changes. We now distribute this file which means that it +is loaded by default. With the option \option{nocfg} this can be +prevented. + + +\subsection{\pkg{doc} upgraded to version~3} + +After roughly three decades the \pkg{doc} package gets a cautious +uplift, as already announced at the TUG conference 2019\Dash changes +to \pkg{doc} are obviously always done in a leisurely manner. + +Given that most documentation is nowadays viewed on screen, +\pkg{hyperref} support is added and by default enabled (suppress it +with option \option{nohyperref} or alternatively with +\option{hyperref}\texttt{=false}) so the internal cross-reference are +properly resolved including those from the index back into the +document. + +Furthermore, \pkg{doc} has now a general mechanism to define +additional \enquote{doc} elements besides the two \texttt{Macro} and +\texttt{Env} it did know in the past. This enables better +documentation because you can now clearly mark different types of +objects instead of simply calling them all \enquote{macros}. +If desired, they can be collected together under a heading +in the index so that you have a section just with your document +interface commands, or with all parameters, or \ldots + +The code borrows ideas from Didier Verna's \pkg{dox} package (although +the document level interface is different) and it makes use of Heiko +Oberdiek's \pkg{hypdoc} package, which at some point in the future +will be completely integrated, given that its whole purpose it to +patch \pkg{doc}'s internal commands to make them \pkg{hyperref}-aware. + +All changes are expected to be upward compatible, but if you run into +issues with older documentation using \pkg{doc} a simple and quick +solution is to load the package as follows: +\verb/\usepackage{doc}[=v2]/ + +\subsection{\pkg{doc} can now show dates in change log} + +Up to now the change log was always sorted by version numbers +(ignoring the date that was given in the \cs{changes} command). It +can now be sorted by both version and date if you specify the option +\option{reportchangedates} on package level and in that case the +changes are displayed with +\begin{quote} + \meta{version} -- \meta{date} +\end{quote} +as the heading (instead of just \meta{version}), when using +\cs{PrintChanges}. +% +\githubissue{gh/531} + + + +\subsection{Lua\TeX\ callback improvements} + +The Lua\TeX\ callbacks \texttt{hpack\_quality} and \texttt{vpack\_quality} are +now \texttt{exclusive} and therefore only allow a single handler. +The previous type \texttt{list} resulted in incorrect parameters when multiple +handlers were set, therefore this only makes an existing restriction more +explicit. + +Additionally the return value \texttt{true} for \texttt{list} +callbacks is now handled internally and no longer passed on to the +engine. This simplifies the handling of these callbacks and makes it +easier to provide consistent interfaces for user defined \texttt{list} +callbacks. + + +\subsection{Class \class{proc} supports \option{twoside}} + +The document class \class{proc}, which is a small variation on the +\class{article} class, now supports the \option{twoside} option +displaying different data in the footer line on recto and verso pages. +% +\githubissue{gh/704} + + +\subsection{Croatian character support} + +The default \pkg{inputenc} support has been extended to support the 9 characters +D\v Z, D\v z, d\v z, LJ, Lj, lj, NJ, Nj, nj, input as single UTF-8 codepoints +in the range U+01C4 to U+01CC. +% +\githubissue{gh/723} + + +\subsection{Cleanup of the Unicode declaration interface} + +When declaring encoding specific commands for the Unicode (TU) +encoding some declarations (e.g., \cs{DeclareUnicodeComposite}) do not +have an explicit argument for the the encoding name, but instead use +the command \cs{UnicodeEncodingName} internally. There was one +exception though: \cs{DeclareUnicodeAccent} required an explicit +encoding argument. This inconsistency has now been removed and the +encoding name is always implicit. To avoid a breaking change for a few +packages on CTAN \cs{DeclareUnicodeAccent} still accepts three +arguments if the second argument is \texttt{TU} or +\cs{UnicodeEncodingName}. Once all packages have been updated this +code branch will get removed. + +At the same time we added \cs{DeclareUnicodeCommand} and +\cs{DeclareUnicodeSymbol} for consistency. They also use +\cs{UnincodeEncodingName} internally, instead of requiring an encoding +argument as their general purpose counterparts do. +% +\githubissue{253} + + + +\subsection{???} +% +\githubissue{???} + + +\section{Bug fixes} + +\subsection{Using \cs{DeclareUnicodeCharacter} with C1 control points} +An error in the UTF-8 handling for non-Unicode \TeX, has prevented +\cs{DeclareUnicodeCharacter} being used with characters in the range +hex 80 to 9F, this has been corrected in this release. +% +\githubissue{730} + + + +\subsection{Fix \cs{ShowCommand} when used with \pkg{ltcmd}} + +When \cs{ShowCommand} support was added for \pkg{ltcmd} in the previous +release~\cite{35:ltnews34}, a blunder in the code made it so that +when \cs{ShowCommand} was used on a command defined with \pkg{ltcmd}, it +only printed the meaning of the command in the terminal, but didn't stop +for interaction as it does elsewhere (mimicking \cs{show}). The issue +is now fixed. +% +\githubissue{739} + + + + +\section{Changes to packages in the \pkg{amsmath} category} + +\subsection{???} +% +\githubissue{???} + + +\section{Changes to packages in the \pkg{graphics} category} + +\subsection{Color in formulas} + +While it is possible to color parts of a formula using \cs{color} +commands the approach is fairly cumbersome. For example, to color an +summation sign, but not its limits, you need four \cs{color} commands and +some seemingly unnecessary set of braces to get coloring and spacing +right: +\begin{verbatim} +\[ X = \color{red} \sum +% without {{ the superscript below is misplaced + _{{\color{black} i=1}} +% without {{ the \sum is black + ^{{\color{black} n}} + \color{black} % without it the x_i is red + x_i \] +\end{verbatim} +Leave out any of the \cs{color} commands or any of the \verb={{...}}= +will give you a wrong result instead of the desired +\[ X = \color{red} \sum + _{{\color{black} i=1}} % without {{ the superscript is misplaced + ^{{\color{black} n}} % without {{ the \sum is black + \color{black} % without it the x_i is red + x_i +\] +So even if this is possible, it is not a very practical solution and +furthermore there are a number of cases where it is impossible to +color a certain part of a formula, for example, an opening symbol such +as \verb=\left(= but not the corresponding \verb=\right)=. + +We have therefore added the command \cs{mathcolor} to the \pkg{color} +and \pkg{xcolor} package, which has the same syntax as \cs{textcolor}, +but is specially designed for use in math and handles sub and +superscripts and other aspects correctly and preserves correct +spacing. Thus, the above example can now be written as +\begin{verbatim} +\[ X = \mathcolor{red}{\sum}_{i=1}^n x_i \] +\end{verbatim} +For details and further examples, see \file{mathcolor.pdf}. + + +\subsection{???} +% +\githubissue{???} + + + +\section{Changes to packages in the \pkg{tools} category} + +\subsection{\pkg{multicol}: Fix \cs{newcolumn}} + +The recently added \cs{newcolumn} didn't work properly if used in +vertical mode, where it behaved like \cs{columnbreak}, i.e., spreading +the column material out instead running the column short. +% +\sxissue{q/624940} + + +\subsection{\pkg{bm}: Fix for \pkg{amsmath} operators} + +An internal command used in the definition of operator commands such +as \cs{sin} in \pkg{amsmath} has been guarded in \cs{bm} to prevent +internal syntax errors due to premature expansion. +% +\githubissue{744} + + + +\medskip + +\begin{thebibliography}{9} + +\fontsize{9.3}{11.3}\selectfont + +\bibitem{35:blueprint} Frank Mittelbach and Chris Rowley: + \emph{\LaTeX{} Tagged PDF \Dash A blueprint for a large project}.\\ + \url{https://latex-project.org/publications/indexbyyear/2020/} + +\bibitem{35:source2e} + \emph{\LaTeX{} documentation on the \LaTeX{} Project Website}.\\ + \url{https://latex-project.org/help/documentation/} + +\bibitem{35:ltnews31} \LaTeX{} Project Team: + \emph{\LaTeXe{} news 31}.\\ + \url{https://latex-project.org/news/latex2e-news/ltnews31.pdf} + +\bibitem{35:ltnews32} \LaTeX{} Project Team: + \emph{\LaTeXe{} news 32}.\\ + \url{https://latex-project.org/news/latex2e-news/ltnews32.pdf} + +\bibitem{35:ltnews33} \LaTeX{} Project Team: + \emph{\LaTeXe{} news 33}.\\ + \url{https://latex-project.org/news/latex2e-news/ltnews33.pdf} + +\bibitem{35:ltnews34} \LaTeX{} Project Team: + \emph{\LaTeXe{} news 34}.\\ + \url{https://latex-project.org/news/latex2e-news/ltnews34.pdf} + +\end{thebibliography} + + + +\end{document} diff --git a/macros/latex-dev/base/ltoutenc.dtx b/macros/latex-dev/base/ltoutenc.dtx index 61ea381823..8e4867417b 100644 --- a/macros/latex-dev/base/ltoutenc.dtx +++ b/macros/latex-dev/base/ltoutenc.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -44,7 +44,7 @@ %<*driver> % \fi \ProvidesFile{ltoutenc.dtx} - [2021/10/16 v2.0x LaTeX Kernel (font encodings)] + [2021/12/12 v2.0y LaTeX Kernel (font encodings)] % \iffalse \documentclass{ltxdoc} \GetFileInfo{ltoutenc.dtx} @@ -477,7 +477,7 @@ % \texttt{TS1} encoding. % % -% \StopEventually{} +% \MaybeStop{} % % \subsection{Docstrip modules} % @@ -2949,14 +2949,14 @@ \endgroup } \else - \newluafunction\@remove@tlig@@@@ + \newprotectedluacmd\@remove@tlig@@@ % \end{macrocode} % Now we can define the function. Mostly we just have to insert a protected glyph % node, which is a glyph node with subtype 256. But we have to keep track of the % current mode to avoid inserting the glyph into a vlist. % \begin{macrocode} \now@and@everyjob{\directlua{ - local rawchar_func = token.create'@remove@tlig@@@@'.index + local rawchar_func = token.create'@remove@tlig@@@'.index local forcehmode = tex.forcehmode local put_next = token.put_next local glyph_id = node.id'glyph' @@ -2972,7 +2972,6 @@ n.char = token.scan_int() return node.write(n) end - token.set_lua('@remove@tlig@@@', rawchar_func, 'global', 'protected') }} % \end{macrocode} % Now \verb+\remove@tlig+ can be implemented almost as in XeTeX. @@ -3017,8 +3016,33 @@ \char#1\relax} % \end{macrocode} % -% \begin{macrocode} -\def\DeclareUnicodeAccent#1#2#3{% +% In its original implementation \cs{DeclareUnicodeAccent} was +% given 3 arguments (with second the ``Unicode encoding'' a.k.a., +% \cs{UnicodeEncodingName}) while in other places, e.g., +% \cs{DeclareUnicodeComposite}, we always made encoding implicit. So +% we now change it here to implicit too so that the interfaces +% become a bit more consistent. To avoid making that a +% breaking change (even though it only affects two packages on +% CTAN) we test for \verb=#2= being \cs{UnicodeEncodingName}. This +% would not catch if somebody used +% \verb|\DeclareUnicodeAccent{\=}{TU-sub}{"0304}| +% but that fortunately hasn't happened. With the implicit argument +% you would need to change \cs{UnicodeEncodingName} instead, as you +% have to do anyway for the other interface commands. +% \changes{v2.0y}{2021/12/12}{\cs{DeclareUnicodeAccent} now makes the +% encoding argument implicit (gh/253)} +% \begin{macrocode} +\def\DeclareUnicodeAccent#1#2{% + \edef\reserved@a{#2}% + \edef\reserved@b{\UnicodeEncodingName}% + \ifx\reserved@a\reserved@b + \def\reserved@a{\DeclareUnicodeAccent@{#1}}% + \else + \def\reserved@a{\DeclareUnicodeAccent@{#1}\UnicodeEncodingName}% + \fi + \reserved@a{#2}% +} +\def\DeclareUnicodeAccent@#1#2#3{% \DeclareTextCommand{#1}{#2}{\add@unicode@accent{#3}}% } % \end{macrocode} @@ -3059,113 +3083,119 @@ \def\reserved@b{#1#2}} % \end{macrocode} % +% Next two commands are simply syntactic sugar to go with the other +% \cs{DeclareUnicode...} declarations. +% \changes{v2.0y}{2021/12/12}{Added \cs{DeclareUnicodeCommand} and +% \cs{DeclareUnicodeSymbol} (gh/253)} +% \begin{macrocode} +\def\DeclareUnicodeSymbol#1{\DeclareTextSymbol{#1}{\UnicodeEncodingName}} +\def\DeclareUnicodeCommand#1{\DeclareTextCommand{#1}{\UnicodeEncodingName}} +% \end{macrocode} +% % \begin{macrocode} -\DeclareTextCommand\textquotesingle \UnicodeEncodingName{% - \remove@tlig{"0027}} -\DeclareTextCommand\textasciigrave \UnicodeEncodingName{% - \remove@tlig{"0060}} -\DeclareTextCommand\textquotedbl \UnicodeEncodingName{% - \remove@tlig{"0022}} -% \end{macrocode} -% -% \begin{macrocode} -\DeclareTextSymbol{\textdollar} \UnicodeEncodingName{"0024} -\DeclareTextSymbol{\textless} \UnicodeEncodingName{"003C} -\DeclareTextSymbol{\textgreater} \UnicodeEncodingName{"003E} -\DeclareTextSymbol{\textbackslash} \UnicodeEncodingName{"005C} -\DeclareTextSymbol{\textasciicircum} \UnicodeEncodingName{"005E} -\DeclareTextSymbol{\textunderscore} \UnicodeEncodingName{"005F} -\DeclareTextSymbol{\textbraceleft} \UnicodeEncodingName{"007B} -\DeclareTextSymbol{\textbar} \UnicodeEncodingName{"007C} -\DeclareTextSymbol{\textbraceright} \UnicodeEncodingName{"007D} -\DeclareTextSymbol{\textasciitilde} \UnicodeEncodingName{"007E} -\DeclareTextSymbol{\textexclamdown} \UnicodeEncodingName{"00A1} -\DeclareTextSymbol{\textcent} \UnicodeEncodingName{"00A2} -\DeclareTextSymbol{\textsterling} \UnicodeEncodingName{"00A3} -\DeclareTextSymbol{\textcurrency} \UnicodeEncodingName{"00A4} -\DeclareTextSymbol{\textyen} \UnicodeEncodingName{"00A5} -\DeclareTextSymbol{\textbrokenbar} \UnicodeEncodingName{"00A6} -\DeclareTextSymbol{\textsection} \UnicodeEncodingName{"00A7} -\DeclareTextSymbol{\textasciidieresis} \UnicodeEncodingName{"00A8} -\DeclareTextSymbol{\textcopyright} \UnicodeEncodingName{"00A9} -\DeclareTextSymbol{\textordfeminine} \UnicodeEncodingName{"00AA} +\DeclareUnicodeCommand\textquotesingle {\remove@tlig{"0027}} +\DeclareUnicodeCommand\textasciigrave {\remove@tlig{"0060}} +\DeclareUnicodeCommand\textquotedbl {\remove@tlig{"0022}} +% \end{macrocode} +% +% \begin{macrocode} +\DeclareUnicodeSymbol{\textdollar} {"0024} +\DeclareUnicodeSymbol{\textless} {"003C} +\DeclareUnicodeSymbol{\textgreater} {"003E} +\DeclareUnicodeSymbol{\textbackslash} {"005C} +\DeclareUnicodeSymbol{\textasciicircum} {"005E} +\DeclareUnicodeSymbol{\textunderscore} {"005F} +\DeclareUnicodeSymbol{\textbraceleft} {"007B} +\DeclareUnicodeSymbol{\textbar} {"007C} +\DeclareUnicodeSymbol{\textbraceright} {"007D} +\DeclareUnicodeSymbol{\textasciitilde} {"007E} +\DeclareUnicodeSymbol{\textexclamdown} {"00A1} +\DeclareUnicodeSymbol{\textcent} {"00A2} +\DeclareUnicodeSymbol{\textsterling} {"00A3} +\DeclareUnicodeSymbol{\textcurrency} {"00A4} +\DeclareUnicodeSymbol{\textyen} {"00A5} +\DeclareUnicodeSymbol{\textbrokenbar} {"00A6} +\DeclareUnicodeSymbol{\textsection} {"00A7} +\DeclareUnicodeSymbol{\textasciidieresis} {"00A8} +\DeclareUnicodeSymbol{\textcopyright} {"00A9} +\DeclareUnicodeSymbol{\textordfeminine} {"00AA} % \end{macrocode} % \changes{v2.0j}{2018/08/11}{Provide \cs{guillemetleft} and \cs{guillemetright}} % \begin{macrocode} -\DeclareTextSymbol{\guillemetleft} \UnicodeEncodingName{"00AB} +\DeclareUnicodeSymbol{\guillemetleft} {"00AB} % old Adobe name -\DeclareTextSymbol{\guillemotleft} \UnicodeEncodingName{"00AB} +\DeclareUnicodeSymbol{\guillemotleft} {"00AB} % \end{macrocode} % % \begin{macrocode} -\DeclareTextSymbol{\textlnot} \UnicodeEncodingName{"00AC} -\DeclareTextSymbol{\textregistered} \UnicodeEncodingName{"00AE} -\DeclareTextSymbol{\textasciimacron} \UnicodeEncodingName{"00AF} -\DeclareTextSymbol{\textdegree} \UnicodeEncodingName{"00B0} -\DeclareTextSymbol{\textpm} \UnicodeEncodingName{"00B1} -\DeclareTextSymbol{\texttwosuperior} \UnicodeEncodingName{"00B2} -\DeclareTextSymbol{\textthreesuperior} \UnicodeEncodingName{"00B3} -\DeclareTextSymbol{\textasciiacute} \UnicodeEncodingName{"00B4} -\DeclareTextSymbol{\textmu} \UnicodeEncodingName{"00B5} -\DeclareTextSymbol{\textparagraph} \UnicodeEncodingName{"00B6} -\DeclareTextSymbol{\textperiodcentered} \UnicodeEncodingName{"00B7} -\DeclareTextSymbol{\textonesuperior} \UnicodeEncodingName{"00B9} -\DeclareTextSymbol{\textordmasculine} \UnicodeEncodingName{"00BA} +\DeclareUnicodeSymbol{\textlnot} {"00AC} +\DeclareUnicodeSymbol{\textregistered} {"00AE} +\DeclareUnicodeSymbol{\textasciimacron} {"00AF} +\DeclareUnicodeSymbol{\textdegree} {"00B0} +\DeclareUnicodeSymbol{\textpm} {"00B1} +\DeclareUnicodeSymbol{\texttwosuperior} {"00B2} +\DeclareUnicodeSymbol{\textthreesuperior} {"00B3} +\DeclareUnicodeSymbol{\textasciiacute} {"00B4} +\DeclareUnicodeSymbol{\textmu} {"00B5} +\DeclareUnicodeSymbol{\textparagraph} {"00B6} +\DeclareUnicodeSymbol{\textperiodcentered} {"00B7} +\DeclareUnicodeSymbol{\textonesuperior} {"00B9} +\DeclareUnicodeSymbol{\textordmasculine} {"00BA} % \end{macrocode} % \changes{v2.0j}{2018/08/11}{Provide \cs{guillemetleft} and \cs{guillemetright}} % \begin{macrocode} -\DeclareTextSymbol{\guillemetright} \UnicodeEncodingName{"00BB} +\DeclareUnicodeSymbol{\guillemetright} {"00BB} % old Adobe name -\DeclareTextSymbol{\guillemotright} \UnicodeEncodingName{"00BB} -% \end{macrocode} -% -% \begin{macrocode} -\DeclareTextSymbol{\textonequarter} \UnicodeEncodingName{"00BC} -\DeclareTextSymbol{\textonehalf} \UnicodeEncodingName{"00BD} -\DeclareTextSymbol{\textthreequarters} \UnicodeEncodingName{"00BE} -\DeclareTextSymbol{\textquestiondown} \UnicodeEncodingName{"00BF} -\DeclareTextSymbol{\AE} \UnicodeEncodingName{"00C6} -\DeclareTextSymbol{\DH} \UnicodeEncodingName{"00D0} -\DeclareTextSymbol{\texttimes} \UnicodeEncodingName{"00D7} -\DeclareTextSymbol{\O} \UnicodeEncodingName{"00D8} -\DeclareTextSymbol{\TH} \UnicodeEncodingName{"00DE} -\DeclareTextSymbol{\ss} \UnicodeEncodingName{"00DF} -\DeclareTextSymbol{\ae} \UnicodeEncodingName{"00E6} -\DeclareTextSymbol{\dh} \UnicodeEncodingName{"00F0} -\DeclareTextSymbol{\textdiv} \UnicodeEncodingName{"00F7} -\DeclareTextSymbol{\o} \UnicodeEncodingName{"00F8} -\DeclareTextSymbol{\th} \UnicodeEncodingName{"00FE} -\DeclareTextSymbol{\DJ} \UnicodeEncodingName{"0110} -\DeclareTextSymbol{\dj} \UnicodeEncodingName{"0111} -\DeclareTextSymbol{\i} \UnicodeEncodingName{"0131} -\DeclareTextSymbol{\IJ} \UnicodeEncodingName{"0132} -\DeclareTextSymbol{\ij} \UnicodeEncodingName{"0133} -\DeclareTextSymbol{\L} \UnicodeEncodingName{"0141} -\DeclareTextSymbol{\l} \UnicodeEncodingName{"0142} -\DeclareTextSymbol{\NG} \UnicodeEncodingName{"014A} -\DeclareTextSymbol{\ng} \UnicodeEncodingName{"014B} -\DeclareTextSymbol{\OE} \UnicodeEncodingName{"0152} -\DeclareTextSymbol{\oe} \UnicodeEncodingName{"0153} -\DeclareTextSymbol{\textflorin} \UnicodeEncodingName{"0192} -\DeclareTextSymbol{\j} \UnicodeEncodingName{"0237} -\DeclareTextSymbol{\textasciicaron} \UnicodeEncodingName{"02C7} -\DeclareTextSymbol{\textasciibreve} \UnicodeEncodingName{"02D8} -\DeclareTextSymbol{\textacutedbl} \UnicodeEncodingName{"02DD} -\DeclareTextSymbol{\textgravedbl} \UnicodeEncodingName{"02F5} -\DeclareTextSymbol{\texttildelow} \UnicodeEncodingName{"02F7} -\DeclareTextSymbol{\textbaht} \UnicodeEncodingName{"0E3F} -\DeclareTextSymbol{\SS} \UnicodeEncodingName{"1E9E} -\DeclareTextSymbol{\textcompwordmark} \UnicodeEncodingName{"200C} +\DeclareUnicodeSymbol{\guillemotright} {"00BB} +% \end{macrocode} +% +% \begin{macrocode} +\DeclareUnicodeSymbol{\textonequarter} {"00BC} +\DeclareUnicodeSymbol{\textonehalf} {"00BD} +\DeclareUnicodeSymbol{\textthreequarters} {"00BE} +\DeclareUnicodeSymbol{\textquestiondown} {"00BF} +\DeclareUnicodeSymbol{\AE} {"00C6} +\DeclareUnicodeSymbol{\DH} {"00D0} +\DeclareUnicodeSymbol{\texttimes} {"00D7} +\DeclareUnicodeSymbol{\O} {"00D8} +\DeclareUnicodeSymbol{\TH} {"00DE} +\DeclareUnicodeSymbol{\ss} {"00DF} +\DeclareUnicodeSymbol{\ae} {"00E6} +\DeclareUnicodeSymbol{\dh} {"00F0} +\DeclareUnicodeSymbol{\textdiv} {"00F7} +\DeclareUnicodeSymbol{\o} {"00F8} +\DeclareUnicodeSymbol{\th} {"00FE} +\DeclareUnicodeSymbol{\DJ} {"0110} +\DeclareUnicodeSymbol{\dj} {"0111} +\DeclareUnicodeSymbol{\i} {"0131} +\DeclareUnicodeSymbol{\IJ} {"0132} +\DeclareUnicodeSymbol{\ij} {"0133} +\DeclareUnicodeSymbol{\L} {"0141} +\DeclareUnicodeSymbol{\l} {"0142} +\DeclareUnicodeSymbol{\NG} {"014A} +\DeclareUnicodeSymbol{\ng} {"014B} +\DeclareUnicodeSymbol{\OE} {"0152} +\DeclareUnicodeSymbol{\oe} {"0153} +\DeclareUnicodeSymbol{\textflorin} {"0192} +\DeclareUnicodeSymbol{\j} {"0237} +\DeclareUnicodeSymbol{\textasciicaron} {"02C7} +\DeclareUnicodeSymbol{\textasciibreve} {"02D8} +\DeclareUnicodeSymbol{\textacutedbl} {"02DD} +\DeclareUnicodeSymbol{\textgravedbl} {"02F5} +\DeclareUnicodeSymbol{\texttildelow} {"02F7} +\DeclareUnicodeSymbol{\textbaht} {"0E3F} +\DeclareUnicodeSymbol{\SS} {"1E9E} +\DeclareUnicodeSymbol{\textcompwordmark} {"200C} % \end{macrocode} % % \changes{v2.0u}{2021/02/19}{Add \cs{textnonbreakinghyphen}, \cs{textfiguredash} % and \cs{texthorizontalbar} (gh/404)} % \begin{macrocode} -%\DeclareTextSymbol{\textnonbreakinghyphen} \UnicodeEncodingName{"2011} -%\DeclareTextSymbol{\textfiguredash} \UnicodeEncodingName{"2012} -\DeclareTextSymbol{\textendash} \UnicodeEncodingName{"2013} -\DeclareTextSymbol{\textemdash} \UnicodeEncodingName{"2014} -%\DeclareTextSymbol{\texthorizontalbar} \UnicodeEncodingName{"2015} +%\DeclareUnicodeSymbol{\textnonbreakinghyphen} {"2011} +%\DeclareUnicodeSymbol{\textfiguredash} {"2012} +\DeclareUnicodeSymbol{\textendash} {"2013} +\DeclareUnicodeSymbol{\textemdash} {"2014} +%\DeclareUnicodeSymbol{\texthorizontalbar} {"2015} % \end{macrocode} % Unfortunately some fonts do not implement \texttt{"2011}, \texttt{"2012} and/or % \texttt{"2015} (including the \LaTeX{} default fonts for Unicode @@ -3175,70 +3205,70 @@ % The \verb=\nobreak\hskip\z@= is there to prevent a break after % the hyphen but allow later breaks in the remainder of the word. % \begin{macrocode} -\DeclareTextCommand{\textnonbreakinghyphen} \UnicodeEncodingName +\DeclareUnicodeCommand{\textnonbreakinghyphen} {\iffontchar\font "2011 \char "2011 \else \mbox{-}\nobreak\hskip\z@ \fi} -\DeclareTextCommand{\textfiguredash} \UnicodeEncodingName +\DeclareUnicodeCommand{\textfiguredash} {\iffontchar\font "2012 \char "2012 \else \char "2013 \fi} -\DeclareTextCommand{\texthorizontalbar} \UnicodeEncodingName +\DeclareUnicodeCommand{\texthorizontalbar} {\iffontchar\font "2015 \char "2015 \else \char "2014 \fi} % \end{macrocode} % % \begin{macrocode} -\DeclareTextSymbol{\textbardbl} \UnicodeEncodingName{"2016} -\DeclareTextSymbol{\textquoteleft} \UnicodeEncodingName{"2018} -\DeclareTextSymbol{\textquoteright} \UnicodeEncodingName{"2019} -\DeclareTextSymbol{\quotesinglbase} \UnicodeEncodingName{"201A} -\DeclareTextSymbol{\textquotedblleft} \UnicodeEncodingName{"201C} -\DeclareTextSymbol{\textquotedblright} \UnicodeEncodingName{"201D} -\DeclareTextSymbol{\quotedblbase} \UnicodeEncodingName{"201E} -\DeclareTextSymbol{\textdagger} \UnicodeEncodingName{"2020} -\DeclareTextSymbol{\textdaggerdbl} \UnicodeEncodingName{"2021} -\DeclareTextSymbol{\textbullet} \UnicodeEncodingName{"2022} -\DeclareTextSymbol{\textellipsis} \UnicodeEncodingName{"2026} -\DeclareTextSymbol{\textperthousand} \UnicodeEncodingName{"2030} -\DeclareTextSymbol{\textpertenthousand} \UnicodeEncodingName{"2031} -\DeclareTextSymbol{\guilsinglleft} \UnicodeEncodingName{"2039} -\DeclareTextSymbol{\guilsinglright} \UnicodeEncodingName{"203A} -\DeclareTextSymbol{\textreferencemark} \UnicodeEncodingName{"203B} -\DeclareTextSymbol{\textinterrobang} \UnicodeEncodingName{"203D} -\DeclareTextSymbol{\textfractionsolidus} \UnicodeEncodingName{"2044} -\DeclareTextSymbol{\textlquill} \UnicodeEncodingName{"2045} -\DeclareTextSymbol{\textrquill} \UnicodeEncodingName{"2046} -\DeclareTextSymbol{\textdiscount} \UnicodeEncodingName{"2052} -\DeclareTextSymbol{\textcolonmonetary} \UnicodeEncodingName{"20A1} -\DeclareTextSymbol{\textlira} \UnicodeEncodingName{"20A4} -\DeclareTextSymbol{\textnaira} \UnicodeEncodingName{"20A6} -\DeclareTextSymbol{\textwon} \UnicodeEncodingName{"20A9} -\DeclareTextSymbol{\textdong} \UnicodeEncodingName{"20AB} -\DeclareTextSymbol{\texteuro} \UnicodeEncodingName{"20AC} -\DeclareTextSymbol{\textpeso} \UnicodeEncodingName{"20B1} -\DeclareTextSymbol{\textcelsius} \UnicodeEncodingName{"2103} -\DeclareTextSymbol{\textnumero} \UnicodeEncodingName{"2116} -\DeclareTextSymbol{\textcircledP} \UnicodeEncodingName{"2117} -\DeclareTextSymbol{\textrecipe} \UnicodeEncodingName{"211E} -\DeclareTextSymbol{\textservicemark} \UnicodeEncodingName{"2120} -\DeclareTextSymbol{\texttrademark} \UnicodeEncodingName{"2122} -\DeclareTextSymbol{\textohm} \UnicodeEncodingName{"2126} -\DeclareTextSymbol{\textmho} \UnicodeEncodingName{"2127} -\DeclareTextSymbol{\textestimated} \UnicodeEncodingName{"212E} -\DeclareTextSymbol{\textleftarrow} \UnicodeEncodingName{"2190} -\DeclareTextSymbol{\textuparrow} \UnicodeEncodingName{"2191} -\DeclareTextSymbol{\textrightarrow} \UnicodeEncodingName{"2192} -\DeclareTextSymbol{\textdownarrow} \UnicodeEncodingName{"2193} -\DeclareTextSymbol{\textminus} \UnicodeEncodingName{"2212} +\DeclareUnicodeSymbol{\textbardbl} {"2016} +\DeclareUnicodeSymbol{\textquoteleft} {"2018} +\DeclareUnicodeSymbol{\textquoteright} {"2019} +\DeclareUnicodeSymbol{\quotesinglbase} {"201A} +\DeclareUnicodeSymbol{\textquotedblleft} {"201C} +\DeclareUnicodeSymbol{\textquotedblright} {"201D} +\DeclareUnicodeSymbol{\quotedblbase} {"201E} +\DeclareUnicodeSymbol{\textdagger} {"2020} +\DeclareUnicodeSymbol{\textdaggerdbl} {"2021} +\DeclareUnicodeSymbol{\textbullet} {"2022} +\DeclareUnicodeSymbol{\textellipsis} {"2026} +\DeclareUnicodeSymbol{\textperthousand} {"2030} +\DeclareUnicodeSymbol{\textpertenthousand} {"2031} +\DeclareUnicodeSymbol{\guilsinglleft} {"2039} +\DeclareUnicodeSymbol{\guilsinglright} {"203A} +\DeclareUnicodeSymbol{\textreferencemark} {"203B} +\DeclareUnicodeSymbol{\textinterrobang} {"203D} +\DeclareUnicodeSymbol{\textfractionsolidus} {"2044} +\DeclareUnicodeSymbol{\textlquill} {"2045} +\DeclareUnicodeSymbol{\textrquill} {"2046} +\DeclareUnicodeSymbol{\textdiscount} {"2052} +\DeclareUnicodeSymbol{\textcolonmonetary} {"20A1} +\DeclareUnicodeSymbol{\textlira} {"20A4} +\DeclareUnicodeSymbol{\textnaira} {"20A6} +\DeclareUnicodeSymbol{\textwon} {"20A9} +\DeclareUnicodeSymbol{\textdong} {"20AB} +\DeclareUnicodeSymbol{\texteuro} {"20AC} +\DeclareUnicodeSymbol{\textpeso} {"20B1} +\DeclareUnicodeSymbol{\textcelsius} {"2103} +\DeclareUnicodeSymbol{\textnumero} {"2116} +\DeclareUnicodeSymbol{\textcircledP} {"2117} +\DeclareUnicodeSymbol{\textrecipe} {"211E} +\DeclareUnicodeSymbol{\textservicemark} {"2120} +\DeclareUnicodeSymbol{\texttrademark} {"2122} +\DeclareUnicodeSymbol{\textohm} {"2126} +\DeclareUnicodeSymbol{\textmho} {"2127} +\DeclareUnicodeSymbol{\textestimated} {"212E} +\DeclareUnicodeSymbol{\textleftarrow} {"2190} +\DeclareUnicodeSymbol{\textuparrow} {"2191} +\DeclareUnicodeSymbol{\textrightarrow} {"2192} +\DeclareUnicodeSymbol{\textdownarrow} {"2193} +\DeclareUnicodeSymbol{\textminus} {"2212} % \end{macrocode} % \changes{v2.0k}{2018/11/18}{Provide \cs{Hwithstroke} and \cs{hwithstroke}} % \begin{macrocode} -\DeclareTextSymbol{\Hwithstroke} \UnicodeEncodingName{"0126} -\DeclareTextSymbol{\hwithstroke} \UnicodeEncodingName{"0127} +\DeclareUnicodeSymbol{\Hwithstroke} {"0126} +\DeclareUnicodeSymbol{\hwithstroke} {"0127} % \end{macrocode} % % Not all fonts have U+2217 but using U+002A requires some adjustment. % \changes{v2.0t}{2021/02/17}{Adjust values for % \cs{textasteriskcentered} To match TS1 definition (gh/502)} % \begin{macrocode} -\DeclareTextCommand{\textasteriskcentered}\UnicodeEncodingName{% +\DeclareUnicodeCommand{\textasteriskcentered}{% \iffontchar\font"2217 \char"2217 \else \begingroup \fontsize @@ -3251,36 +3281,39 @@ } % \end{macrocode} % \begin{macrocode} -\DeclareTextSymbol{\textsurd} \UnicodeEncodingName{"221A} -\DeclareTextSymbol{\textlangle} \UnicodeEncodingName{"2329} -\DeclareTextSymbol{\textrangle} \UnicodeEncodingName{"232A} -\DeclareTextSymbol{\textblank} \UnicodeEncodingName{"2422} -\DeclareTextSymbol{\textvisiblespace} \UnicodeEncodingName{"2423} -\DeclareTextSymbol{\textopenbullet} \UnicodeEncodingName{"25E6} -\DeclareTextSymbol{\textbigcircle} \UnicodeEncodingName{"25EF} -\DeclareTextSymbol{\textmusicalnote} \UnicodeEncodingName{"266A} -\DeclareTextSymbol{\textmarried} \UnicodeEncodingName{"26AD} -\DeclareTextSymbol{\textdivorced} \UnicodeEncodingName{"26AE} -\DeclareTextSymbol{\textinterrobangdown} \UnicodeEncodingName{"2E18} +\DeclareUnicodeSymbol{\textsurd} {"221A} +\DeclareUnicodeSymbol{\textlangle} {"2329} +\DeclareUnicodeSymbol{\textrangle} {"232A} +\DeclareUnicodeSymbol{\textblank} {"2422} +\DeclareUnicodeSymbol{\textvisiblespace} {"2423} +\DeclareUnicodeSymbol{\textopenbullet} {"25E6} +\DeclareUnicodeSymbol{\textbigcircle} {"25EF} +\DeclareUnicodeSymbol{\textmusicalnote} {"266A} +\DeclareUnicodeSymbol{\textmarried} {"26AD} +\DeclareUnicodeSymbol{\textdivorced} {"26AE} +\DeclareUnicodeSymbol{\textinterrobangdown} {"2E18} % \end{macrocode} % Accents must be declared before the composites that use them. % \begin{macrocode} -\DeclareUnicodeAccent{\`} \UnicodeEncodingName{"0300} -\DeclareUnicodeAccent{\'} \UnicodeEncodingName{"0301} -\DeclareUnicodeAccent{\^} \UnicodeEncodingName{"0302} -\DeclareUnicodeAccent{\~} \UnicodeEncodingName{"0303} -\DeclareUnicodeAccent{\=} \UnicodeEncodingName{"0304} -\DeclareUnicodeAccent{\u} \UnicodeEncodingName{"0306} -\DeclareUnicodeAccent{\.} \UnicodeEncodingName{"0307} -\DeclareUnicodeAccent{\"} \UnicodeEncodingName{"0308} -\DeclareUnicodeAccent{\r} \UnicodeEncodingName{"030A} -\DeclareUnicodeAccent{\H} \UnicodeEncodingName{"030B} -\DeclareUnicodeAccent{\v} \UnicodeEncodingName{"030C} -\DeclareUnicodeAccent{\b} \UnicodeEncodingName{"0332} -\DeclareUnicodeAccent{\d} \UnicodeEncodingName{"0323} -\DeclareUnicodeAccent{\c} \UnicodeEncodingName{"0327} -\DeclareUnicodeAccent{\k} \UnicodeEncodingName{"0328} -\DeclareTextCommand\textcommabelow \UnicodeEncodingName[1] +\DeclareUnicodeAccent{\`}{"0300} +\DeclareUnicodeAccent{\'}{"0301} +\DeclareUnicodeAccent{\^}{"0302} +\DeclareUnicodeAccent{\~}{"0303} +\DeclareUnicodeAccent{\=}{"0304} +\DeclareUnicodeAccent{\u}{"0306} +\DeclareUnicodeAccent{\.}{"0307} +\DeclareUnicodeAccent{\"}{"0308} +\DeclareUnicodeAccent{\r}{"030A} +\DeclareUnicodeAccent{\H}{"030B} +\DeclareUnicodeAccent{\v}{"030C} +\DeclareUnicodeAccent{\b}{"0332} +\DeclareUnicodeAccent{\d}{"0323} +\DeclareUnicodeAccent{\c}{"0327} +\DeclareUnicodeAccent{\k}{"0328} +% \end{macrocode} +% The odd one out: +% \begin{macrocode} +\DeclareUnicodeCommand\textcommabelow[1] {\hmode@bgroup\ooalign{\null#1\crcr\hidewidth\raise-.31ex \hbox{\check@mathfonts\fontsize\ssf@size\z@ \math@fontsfalse\selectfont,}\hidewidth}\egroup} @@ -3743,4 +3776,12 @@ % % \Finale % +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \endinput + +^^A Needed for emacs +^^A +^^A Local Variables: +^^A mode: latex +^^A coding: utf-8-unix +^^A End: diff --git a/macros/latex-dev/base/ltoutenc.ins b/macros/latex-dev/base/ltoutenc.ins index 1330b5c44e..8ff0f02608 100644 --- a/macros/latex-dev/base/ltoutenc.ins +++ b/macros/latex-dev/base/ltoutenc.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/ltoutput.dtx b/macros/latex-dev/base/ltoutput.dtx index 78b0f2335f..2d9f857173 100644 --- a/macros/latex-dev/base/ltoutput.dtx +++ b/macros/latex-dev/base/ltoutput.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -120,7 +120,7 @@ % \changes{v1.2n}{2015/02/21} % {Removed autoload code} % -% \StopEventually{} +% \MaybeStop{} % % \def \ie {i.e.~} % \def \eg {e.g.~} diff --git a/macros/latex-dev/base/ltpage.dtx b/macros/latex-dev/base/ltpage.dtx index 4504033f54..9c0ed1fee6 100644 --- a/macros/latex-dev/base/ltpage.dtx +++ b/macros/latex-dev/base/ltpage.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -112,7 +112,7 @@ % command (|\ps@...|) to |\markboth| for setting the heading or to % |\@gobbletwo| to do nothing. % -% \StopEventually{} +% \MaybeStop{} % % \begin{macrocode} %<*2ekernel> diff --git a/macros/latex-dev/base/ltpageno.dtx b/macros/latex-dev/base/ltpageno.dtx index 03d36a53d9..8142639633 100644 --- a/macros/latex-dev/base/ltpageno.dtx +++ b/macros/latex-dev/base/ltpageno.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -77,7 +77,7 @@ % numbered i, ii, etc. % % -% \StopEventually{} +% \MaybeStop{} % % \begin{macrocode} %<*2ekernel> diff --git a/macros/latex-dev/base/ltpar.dtx b/macros/latex-dev/base/ltpar.dtx index 969954be0a..50ff57183c 100644 --- a/macros/latex-dev/base/ltpar.dtx +++ b/macros/latex-dev/base/ltpar.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -96,7 +96,7 @@ % \end{itemize} % % -% \StopEventually{} +% \MaybeStop{} % % \subsection{Implementation} % diff --git a/macros/latex-dev/base/ltpara-code.pdf b/macros/latex-dev/base/ltpara-code.pdf Binary files differindex 3bf225ee5c..594234c308 100644 --- a/macros/latex-dev/base/ltpara-code.pdf +++ b/macros/latex-dev/base/ltpara-code.pdf diff --git a/macros/latex-dev/base/ltpara-doc.pdf b/macros/latex-dev/base/ltpara-doc.pdf Binary files differindex aae32c908a..a13c61f0e6 100644 --- a/macros/latex-dev/base/ltpara-doc.pdf +++ b/macros/latex-dev/base/ltpara-doc.pdf diff --git a/macros/latex-dev/base/ltpara-doc.tex b/macros/latex-dev/base/ltpara-doc.tex index c3892b8180..f3a51bbd2e 100644 --- a/macros/latex-dev/base/ltpara-doc.tex +++ b/macros/latex-dev/base/ltpara-doc.tex @@ -2,5 +2,6 @@ \AtBeginDocument{\OnlyDescription \let\tableofcontents\relax + \RenewCommandCopy\MaybeStop\StopEventually } \input{ltpara.dtx} diff --git a/macros/latex-dev/base/ltpara.dtx b/macros/latex-dev/base/ltpara.dtx index a2da67198a..36d07337bd 100644 --- a/macros/latex-dev/base/ltpara.dtx +++ b/macros/latex-dev/base/ltpara.dtx @@ -123,7 +123,7 @@ % \verb=\hbox{a\par b}= is ignored, but \verb=$a\par b$= would complain. % % If this primitive ends the paragraph it does some special -% \enquote{end of horizontal list} processing, then calls \TeX{}’s paragraph +% \enquote{end of horizontal list} processing, then calls \TeX{}'s paragraph % builder; this breaks the horizontal list into lines and then these % lines are added as boxes to the enclosing vertical list and % \TeX{} returns to vertical mode. @@ -665,7 +665,7 @@ % % % -% \StopEventually{\setlength\IndexMin{200pt} \PrintIndex } +% \MaybeStop{\setlength\IndexMin{200pt} \PrintIndex } % % % \section{The Implementation} diff --git a/macros/latex-dev/base/ltpictur.dtx b/macros/latex-dev/base/ltpictur.dtx index ae8b58995d..453ec6149e 100644 --- a/macros/latex-dev/base/ltpictur.dtx +++ b/macros/latex-dev/base/ltpictur.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -83,7 +83,7 @@ % variant of this command, |\bezier|, is defined, in which the first % argument is not optional. % -% \StopEventually{} +% \MaybeStop{} % % % \changes{v0.1a}{1994/03/07}{Initial version, split from latex.dtx} diff --git a/macros/latex-dev/base/ltplain.dtx b/macros/latex-dev/base/ltplain.dtx index 5fa7039679..c6f295ef6b 100644 --- a/macros/latex-dev/base/ltplain.dtx +++ b/macros/latex-dev/base/ltplain.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -102,7 +102,7 @@ % \LaTeX{} uses its own output routine, so most of the plain one was % removed. % -% \StopEventually{} +% \MaybeStop{} % % % \begin{macrocode} diff --git a/macros/latex-dev/base/ltsect.dtx b/macros/latex-dev/base/ltsect.dtx index 67974c7387..71ab1ee89d 100644 --- a/macros/latex-dev/base/ltsect.dtx +++ b/macros/latex-dev/base/ltsect.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -73,7 +73,7 @@ % document level commands are defined in the class files, in terms of % these commands. % -% \StopEventually{} +% \MaybeStop{} % % % \changes{v1.0a}{1994/03/04}{Initial version, split from latex.dtx} diff --git a/macros/latex-dev/base/ltshipout-code.pdf b/macros/latex-dev/base/ltshipout-code.pdf Binary files differindex 0d2c86e03f..5c37e40e02 100644 --- a/macros/latex-dev/base/ltshipout-code.pdf +++ b/macros/latex-dev/base/ltshipout-code.pdf diff --git a/macros/latex-dev/base/ltshipout-doc.pdf b/macros/latex-dev/base/ltshipout-doc.pdf Binary files differindex fc51162b24..c5df9ae53c 100644 --- a/macros/latex-dev/base/ltshipout-doc.pdf +++ b/macros/latex-dev/base/ltshipout-doc.pdf diff --git a/macros/latex-dev/base/ltshipout-doc.tex b/macros/latex-dev/base/ltshipout-doc.tex index 33f87d8862..4cca5e9cbe 100644 --- a/macros/latex-dev/base/ltshipout-doc.tex +++ b/macros/latex-dev/base/ltshipout-doc.tex @@ -3,5 +3,6 @@ \AtBeginDocument{\OnlyDescription % \let\tableofcontents\relax + \RenewCommandCopy\MaybeStop\StopEventually } \input{ltshipout.dtx} diff --git a/macros/latex-dev/base/ltshipout.dtx b/macros/latex-dev/base/ltshipout.dtx index 7f6555d18c..09495dde9a 100644 --- a/macros/latex-dev/base/ltshipout.dtx +++ b/macros/latex-dev/base/ltshipout.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment %% -%% Copyright (C) 2020-2021 +%% Copyright (C) 2020-2022 %% Frank Mittelbach, LaTeX Team %% % @@ -32,8 +32,8 @@ %%% From File: ltshipout.dtx % % \begin{macrocode} -\providecommand\ltshipoutversion{v1.0j} -\providecommand\ltshipoutdate{2021/06/09} +\providecommand\ltshipoutversion{v1.0l} +\providecommand\ltshipoutdate{2022/01/06} % \end{macrocode} % %<*driver> @@ -327,7 +327,10 @@ % \subsection{Legacy \LaTeX{} commands} % % \begin{function}{\AtBeginDvi,\AtEndDvi} -% \cs{AtBeginDvi} is the existing \LaTeXe{} interface to fill the +% \begin{syntax} +% \cs{AtBeginDvi} \Arg{code} +% \end{syntax} + % \cs{AtBeginDvi} is the existing \LaTeXe{} interface to fill the % \hook{shipout/firstpage} hook. This is not really a good name % as it is not just supporting \texttt{.dvi} but also \texttt{.pdf} % output or \texttt{.xdv}. @@ -335,15 +338,24 @@ % \cs{AtEndDvi} is the counterpart that was not available in the % kernel but only through the package \pkg{atenddvi}. It fills the % \hook{shipout/lastpage} hook. +% +% Neither interface can set a code label but uses the current default label. +% % \end{function} % % As these two wrappers have been available for a long time we -% continue offering them. However, for new code we suggest using -% the high-level hook management commands directly instead of -% ``randomly-named'' wrappers. This will lead to code that is -% easier to understand and to maintain. For this reason we do not -% provide any other wrapper commands for the above hooks in the -% kernel. +% continue offering them (but not enhancing them, e.g., by providing +% support for code labels). +% +% For new code we strongly suggest using the high-level hook +% management commands directly instead of ``randomly-named'' +% wrappers. This will lead to code that is easier to understand +% and to maintain and it also allows you to set code labels if +% needed. +% +% For this reason we do not provide any other ``new'' wrapper +% commands for the above hooks in the kernel, but only keep +% the existing ones for backward compatibility. % % % \subsection{Special commands for use inside the hooks} @@ -644,7 +656,7 @@ % \end{function} % % -% \StopEventually{\setlength\IndexMin{200pt} \PrintIndex } +% \MaybeStop{\setlength\IndexMin{200pt} \PrintIndex } % % % \section{The Implementation} @@ -734,21 +746,21 @@ % \begin{macrocode} \sys_if_engine_luatex:TF { - \newluafunction \@@_finalize_box: + \newprotectedluacmd \@@_finalize_box: \exp_args:Nx \everyjob { \exp_not:V \everyjob \exp_not:N \lua_now:n { luatexbase.create_callback('pre_shipout_filter', 'list') local~call, getbox, setbox = luatexbase.call_callback, tex.getbox, tex.setbox~ - lua.get_functions_table()[\the \@@_finalize_box:] = function() - local~result = call('pre_shipout_filter', getbox(\the \l_shipout_box)) - if~not (result == true) then~ + lua.get_functions_table()[\the \allocationnumber] = function() + local~head = getbox(\the \l_shipout_box) + local~result = call('pre_shipout_filter', head) + if~not (result == head) then~ setbox(\the \l_shipout_box, result~or~nil) end~ end } } - \protected \luadef \@@_finalize_box: \the \@@_finalize_box: } { \cs_set_eq:NN \@@_finalize_box: \scan_stop: } @@ -1966,15 +1978,17 @@ % % % \begin{macro}{\AtEndDvi} -% This package has only one public command to simulating it is easy +% This package has only one public command, so simulating it is easy % and actually sensible to provide as part of the kernel. +% \changes{v1.0l}{2022/01/06}{Correctly simulate \cs{AtEndDvi} without +% extending the syntax} % \begin{macrocode} %</2ekernel> %<*2ekernel|latexrelease> %<latexrelease>\IncludeInRelease{2020/10/01}% %<latexrelease> {\AtEndDvi}{atenddvi emulation}% \ExplSyntaxOn -\cs_new_protected:Npn \AtEndDvi {\AddToHook{shipout/lastpage}} +\cs_new_protected:Npn \AtEndDvi #1 {\AddToHook{shipout/lastpage}{#1}} \ExplSyntaxOff % \end{macrocode} % As the package is integrate we prevent loading (no need to roll that back): @@ -2041,9 +2055,11 @@ % % \begin{macro}{\AtBeginShipout,\AtBeginShipoutNext} % Filling hooks +% \changes{v1.0l}{2022/01/06}{Correctly simulate \cs{AtBeginShipout} +% and \cs{AtBeginShipoutNext} without extending the syntax} % \begin{macrocode} -\protected \def \AtBeginShipout {\AddToHook{shipout/before}} -\protected \def \AtBeginShipoutNext {\AddToHookNext{shipout/before}} +\protected\long\def\AtBeginShipout #1{\AddToHook{shipout/before}{#1}} +\protected\long\def\AtBeginShipoutNext #1{\AddToHookNext{shipout/before}{#1}} % \end{macrocode} % \end{macro} % diff --git a/macros/latex-dev/base/ltspace.dtx b/macros/latex-dev/base/ltspace.dtx index 17fb0d6518..feb82730ec 100644 --- a/macros/latex-dev/base/ltspace.dtx +++ b/macros/latex-dev/base/ltspace.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -114,7 +114,7 @@ % |\restorecr| : restores <CR> to its usual meaning. % % -% \StopEventually{} +% \MaybeStop{} % % \subsection{Chris' comments} % diff --git a/macros/latex-dev/base/lttab.dtx b/macros/latex-dev/base/lttab.dtx index 48627f40a3..e32153f31c 100644 --- a/macros/latex-dev/base/lttab.dtx +++ b/macros/latex-dev/base/lttab.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -74,7 +74,7 @@ % \LaTeX\ Companion}. Use the |array| package to obtain the extended % version. % -% \StopEventually{} +% \MaybeStop{} % % % \changes{v1.0a}{1994/03/04}{Initial version, split from latex.dtx} diff --git a/macros/latex-dev/base/lttextcomp.dtx b/macros/latex-dev/base/lttextcomp.dtx index 1efc36d563..de6b221b6c 100644 --- a/macros/latex-dev/base/lttextcomp.dtx +++ b/macros/latex-dev/base/lttextcomp.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2019-2021 +% Copyright (C) 2019-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -25,9 +25,10 @@ % and covered by LPPL is defined by the unpacking scripts (with % extension .ins) which are part of the distribution. % +%%% From File: lttextcomp.dtx +% % \fi % -%%% From File: lttextcomp.dtx % % \iffalse % @@ -36,7 +37,7 @@ % % \ProvidesFile{lttextcomp.dtx} - [2021/04/16 v1.0f LaTeX Kernel (text companion symbols)] + [2021/12/09 v1.0f LaTeX Kernel (text companion symbols)] % \iffalse \documentclass{ltxdoc} \begin{document} @@ -68,7 +69,7 @@ % % % -% \StopEventually{} +% \MaybeStop{} % % \changes{v1.0e}{2021/03/19} % {Use \cs{NewModuleRelease}} @@ -470,16 +471,17 @@ % \end{macrocode} % % -% In the following sections the remaining default definitions are ordered by -% sub-encoding in which they are become unavailable (i.e., they are -% not provided in the sub-encoding with that number and all -% sub-encodings with higher numbers. +% In the following sections the remaining default definitions are +% ordered by sub-encoding in which they are become +% \textbf{unavailable}, i.e., they are not provided in the +% sub-encoding with that number and all sub-encodings with higher +% numbers. % % Thus the symbols that are available in sub-encoding $x$ are the -% symbols above (always available) and the symbols list in the -% sections for sub-encodings $x+1$ and higher. +% symbols above (always available) and the symbols listed as becoming +% unavailable in sub-encodings $x+1$ and higher. % -% \subsection{Sub-encoding \texttt{1} (drop symbols not working in +% \subsection{Unavailable in sub-encoding \texttt{1} and higher (drop symbols not working in % Latin Modern)} % % The \cs{textcircled} is available but the glyph is simply too @@ -493,7 +495,7 @@ % % % -% \subsection{Sub-encoding \texttt{2} (majority of new OTF fonts via autoinst)} +% \subsection{Unavailable in sub-encoding \texttt{2} (majority of new OTF fonts via autoinst) and higher} % % \begin{macrocode} \DeclareTextCommandDefault{\t} @@ -722,7 +724,7 @@ % % % -% \subsection{Sub-encoding \texttt{3}} +% \subsection{Unavailable in sub-encoding \texttt{3} and higher} % % Sub-encoding \texttt{2} is the one where we loose many % symbols. In the higher-numbered sub-encodings we see only a few @@ -738,7 +740,7 @@ % % % -% \subsection{Sub-encoding \texttt{4}} +% \subsection{Unavailable in sub-encoding \texttt{4} and higher} % % \begin{macrocode} \DeclareTextCommandDefault{\textcolonmonetary} @@ -763,7 +765,7 @@ % % % -% \subsection{Sub-encoding \texttt{5} (most older PS fonts)} +% \subsection{Unavailable in sub-encoding \texttt{5} (most older PS fonts) and higher} % % Most older PS fonts (supported in \TeX{} since the early nineties % when virtual fonts became available) are sorted under this @@ -790,7 +792,7 @@ % % % -% \subsection{Sub-encoding \texttt{6}} +% \subsection{Unavailable in sub-encoding \texttt{6} and higher} % % \begin{macrocode} \DeclareTextCommandDefault{\textflorin} @@ -801,7 +803,7 @@ % % % -% \subsection{Sub-encoding \texttt{7}} +% \subsection{Unavailable in sub-encoding \texttt{7} and higher} % % \begin{macrocode} \DeclareTextCommandDefault{\textfractionsolidus} @@ -816,7 +818,7 @@ % % % -% \subsection{Sub-encoding \texttt{8}} +% \subsection{Unavailable in sub-encoding \texttt{8} and higher} % % \begin{macrocode} \DeclareTextCommandDefault{\textblank} @@ -837,7 +839,7 @@ % % % -% \subsection{Sub-encoding \texttt{9} (most missing)} +% \subsection{Unavailable in Sub-encoding \texttt{9} (most missing)} % % \begin{macrocode} \DeclareTextCommandDefault{\textcelsius} diff --git a/macros/latex-dev/base/ltthm.dtx b/macros/latex-dev/base/ltthm.dtx index 00fe97c77a..d0d04d9669 100644 --- a/macros/latex-dev/base/ltthm.dtx +++ b/macros/latex-dev/base/ltthm.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -80,7 +80,7 @@ % The way \meta{name} environments are numbered can be changed by % redefining |\the|\meta{name}. % -% \StopEventually{} +% \MaybeStop{} % % % \changes{v1.0a}{1994/03/28}{Initial version, split from latex.dtx} diff --git a/macros/latex-dev/base/ltvers.dtx b/macros/latex-dev/base/ltvers.dtx index c1024b938c..451b9f51a1 100644 --- a/macros/latex-dev/base/ltvers.dtx +++ b/macros/latex-dev/base/ltvers.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -61,7 +61,7 @@ % \LaTeX, and set |\everyjob| so that it is printed at the start of % every \LaTeX\ run. % -% \StopEventually{} +% \MaybeStop{} % % \changes{v1.0g}{1996/11/28} % {Check for old format modified /2319} @@ -115,7 +115,7 @@ {2022-06-01} %</2ekernel|latexrelease> %<*2ekernel> -\def\patch@level{0} +\def\patch@level{-1} % \end{macrocode} % % \begin{macro}{\development@branch@name} diff --git a/macros/latex-dev/base/ltx3info.pdf b/macros/latex-dev/base/ltx3info.pdf Binary files differindex 345556db0e..4f23908f57 100644 --- a/macros/latex-dev/base/ltx3info.pdf +++ b/macros/latex-dev/base/ltx3info.pdf diff --git a/macros/latex-dev/base/ltx3info.tex b/macros/latex-dev/base/ltx3info.tex index 2a376f6431..13231da818 100644 --- a/macros/latex-dev/base/ltx3info.tex +++ b/macros/latex-dev/base/ltx3info.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltxcheck.tex b/macros/latex-dev/base/ltxcheck.tex index 9e013bc2af..7f4b925b79 100644 --- a/macros/latex-dev/base/ltxcheck.tex +++ b/macros/latex-dev/base/ltxcheck.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/ltxdoc.dtx b/macros/latex-dev/base/ltxdoc.dtx index 7a21f7d871..10ddd44828 100644 --- a/macros/latex-dev/base/ltxdoc.dtx +++ b/macros/latex-dev/base/ltxdoc.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -30,7 +30,7 @@ % %<class>\NeedsTeXFormat{LaTeX2e} %<class>\ProvidesClass{ltxdoc} -%<class> [2020/12/05 v2.1b Standard LaTeX documentation class] +%<class> [2021/12/07 v2.1d Standard LaTeX documentation class] % %<*driver> \documentclass{ltxdoc} @@ -102,7 +102,7 @@ % \PassOptionsToClass{a4paper}{article} %\end{verbatim} % -% All the source files are in two parts, separated by |\StopEventually|. +% All the source files are in two parts, separated by |\MaybeStop|. % The first part (should) contain `user' documentation. The second part % is a full documented listing of the source code. The |doc| package % provides the command |\OnlyDescription| which suppresses the code @@ -156,39 +156,53 @@ % \includeonly{ltvers,ltboxes} %\end{verbatim} % -% \StopEventually{} +% \MaybeStop{} % % % \section{Options} % % \begin{macrocode} %<*class> +% \end{macrocode} +% +% \begin{macrocode} \DeclareOption{a5paper}{\@latexerr{Option not supported}% {}} % \end{macrocode} +% Prevent loading of a config file. +% \begin{macrocode} +\newif\ifltxdoc@load@cfg@ \ltxdoc@load@cfg@true +\DeclareOption{nocfg}{\ltxdoc@load@cfg@false} +% \end{macrocode} % % \begin{macrocode} \DeclareOption*{% \PassOptionsToClass {\CurrentOption}{article}} % \end{macrocode} % -% \section{Configuration} +% \section{Option Processing} +% +% \begin{macrocode} +\ProcessOptions +% \end{macrocode} +% +% \section{Local configuration} % Input a local configuration file, if it exists. % \begin{macrocode} +\ifltxdoc@load@cfg@ \InputIfFileExists{ltxdoc.cfg} {\typeout{*************************************^^J% * Local config file ltxdoc.cfg used^^J% *************************************}} {} +\else + \typeout{*************************************^^J% + * Local config file ignored^^J% + *************************************} +\fi % \end{macrocode} % % -% \section{Option Processing} -% -% \begin{macrocode} -\ProcessOptions -% \end{macrocode} -% % \section{Loading article and doc} % % \begin{macrocode} @@ -256,7 +270,7 @@ % arguments. It can \emph{not} be use to record commands that are defined as % ``|\outer|'' nor is it possible to use it on conditionals such as % |\iftrue| or defined by |\newif|. -% |\cs{foo}| also prints |\foo|, for those who prefer that +% |\cs{foo}| already available with the \texttt{doc} package also prints |\foo|, for those who prefer that % syntax. (This second form can be used to record all types of command so the % above restrictions do not apply. % \begin{macro}{\cmd} @@ -266,7 +280,7 @@ % \begin{macrocode} \def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}} \def\cmd@to@cs#1#2{\char\number`#2\relax} -\DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}} +%\DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}} % already part of doc.sty % \end{macrocode} % \end{macro} % \end{macro} @@ -602,5 +616,58 @@ Bug reports can be opened (category \texttt{#1}) at\\% \def\task#1#2{} %</class> % \end{macrocode} +% +% +% +% \section{Configuration file} +% +% +% \begin{macrocode} +%<*cfg> +% +% This is the ltxdoc configuration file we use to format the LaTeX +% kernel sources. +% +% +% Copyright 2006, 2007, 2011 Heiko Oberdiek +% Copyright 2014-2021 The LaTeX Project +% + +\ProvidesFile{ltxdoc.cfg}% + [2021/12/07 v2.0c ltxdoc.cls configuration (LaTeX Project)] +\PassOptionsToClass{a4paper}{article} + +% hyperref and hypdoc are now loaded late (or by the user) so we have to wait +% with any adjustments until that has happened + +\AddToHook{package/hyperref/after}{% +%% \RequirePackage{hypdoc}% % this is now triggered by doc + \RequirePackage{pdftexcmds}\relax + \ifnum\pdf@strcmp{\jobname}{inputenc}=0 % + \hypersetup{pdfencoding=auto}% + \pdfstringdefDisableCommands{% + \def\meta#1{% inputenc.dtx + \9060\010#1\9060\011% + }% + }% + \else + \fi + \pdfstringdefDisableCommands{% + \let\env\relax % longtable.dtx + \let\mytt\relax % tabularx.dtx + }% +} + +% This should work well for documentation of packages outside the +% LaTeX kernel, but if not, you can prevent the loading with the +% option "nocfg", i.e., +% +% \documentclass[nocfg]{ltxdoc] +% +% or by providing your own config file + +\endinput +%</cfg> +% \end{macrocode} % \Finale % diff --git a/macros/latex-dev/base/ltxdoc.pdf b/macros/latex-dev/base/ltxdoc.pdf Binary files differindex 0ab58522f8..65cae4bc53 100644 --- a/macros/latex-dev/base/ltxdoc.pdf +++ b/macros/latex-dev/base/ltxdoc.pdf diff --git a/macros/latex-dev/base/ltxref.dtx b/macros/latex-dev/base/ltxref.dtx index dd482299b2..53224103d9 100644 --- a/macros/latex-dev/base/ltxref.dtx +++ b/macros/latex-dev/base/ltxref.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -88,7 +88,7 @@ % a space on either side. % % -% \StopEventually{} +% \MaybeStop{} % % \subsection{Cross Referencing} % diff --git a/macros/latex-dev/base/makeindx.dtx b/macros/latex-dev/base/makeindx.dtx index 9dc03a8431..fb6c474659 100644 --- a/macros/latex-dev/base/makeindx.dtx +++ b/macros/latex-dev/base/makeindx.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -83,7 +83,7 @@ % \texttt{book} document classes, but works with other classes as % well. It makes |\flushbottom| the default. % -% \StopEventually{} +% \MaybeStop{} % % \section{The {\sc docstrip} modules} % diff --git a/macros/latex-dev/base/makeindx.ins b/macros/latex-dev/base/makeindx.ins index 427d4c7967..0fe55ed039 100644 --- a/macros/latex-dev/base/makeindx.ins +++ b/macros/latex-dev/base/makeindx.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/makeindx.pdf b/macros/latex-dev/base/makeindx.pdf Binary files differindex 22f2af62c6..a35431c671 100644 --- a/macros/latex-dev/base/makeindx.pdf +++ b/macros/latex-dev/base/makeindx.pdf diff --git a/macros/latex-dev/base/manifest.txt b/macros/latex-dev/base/manifest.txt index f6afcccce7..b671200a3a 100644 --- a/macros/latex-dev/base/manifest.txt +++ b/macros/latex-dev/base/manifest.txt @@ -1,5 +1,5 @@ % -% The following files form the LaTeX2e distribution of 2020-10-01 +% The following files form the LaTeX2e distribution % % % CONTENTS OF THE LaTeX DISTRIBUTION @@ -11,10 +11,6 @@ % README.md -- The distribution guide. START BY READING THIS FILE % manifest.txt -- This file. % -% tex2.txt -- Extras for installing LaTeX on TeX2. -% -% texpert.txt -- Documentation for TeX experts. -% % legal.txt -- Copyright notice; warranty; copying conditions. % lppl.txt -- The LaTeX Project Public License (current version). % lppl-1-0.txt -- The LaTeX Project Public License (version 1.0). @@ -72,6 +68,9 @@ % ltnews30.tex -- What was new in the release dated 2019/10. % ltnews31.tex -- What was new in the release dated 2020/02. % ltnews32.tex -- What was new in the release dated 2020/10. +% ltnews33.tex -- What was new in the release dated 2021/06. +% ltnews34.tex -- What was new in the release dated 2021/11. +% ltnews35.tex -- What was new in the release dated 2022/06. % % ltx3info.tex -- Information about the LaTeX3 project. @@ -139,6 +138,8 @@ % lthooks.dtx -- Hook management % ltfilehook.dtx -- Hook management for file loading % ltshipout.dtx -- Hook management for \shipout +% ltcmdhooks.dtx -- Hook management (generic) for commands +% ltpara.dtx -- Hook management for paragraphs % % Standard Classes: % ----------------- @@ -186,7 +187,7 @@ % doc.dtx -- Package for self documenting code. % docstrip.dtx -- Module for removing comments. % ltxdoc.dtx -- Class file for printing documentation. -% doc-v3beta.sty -- New version of doc, current for internal use only. +% ltxdoc.cfg -- config file to format the LaTeX sources. % % % Installation scripts for the various parts: diff --git a/macros/latex-dev/base/modguide.pdf b/macros/latex-dev/base/modguide.pdf Binary files differindex e425b8a075..4dab73b2ab 100644 --- a/macros/latex-dev/base/modguide.pdf +++ b/macros/latex-dev/base/modguide.pdf diff --git a/macros/latex-dev/base/modguide.tex b/macros/latex-dev/base/modguide.tex index 15aad3358f..b0651da0a5 100644 --- a/macros/latex-dev/base/modguide.tex +++ b/macros/latex-dev/base/modguide.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/newdc.ins b/macros/latex-dev/base/newdc.ins index e2ce183f05..eeec6479eb 100644 --- a/macros/latex-dev/base/newdc.ins +++ b/macros/latex-dev/base/newdc.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/newlfont.dtx b/macros/latex-dev/base/newlfont.dtx index 3b6e001075..86c0d47ab6 100644 --- a/macros/latex-dev/base/newlfont.dtx +++ b/macros/latex-dev/base/newlfont.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -84,7 +84,7 @@ % NFSS1, i.e., to change one font attribute without resetting the % other attributes. % -% \StopEventually{} +% \MaybeStop{} % % % \section{The Code} diff --git a/macros/latex-dev/base/nfssfont.dtx b/macros/latex-dev/base/nfssfont.dtx index 554c7ae8f0..51d7834aa3 100644 --- a/macros/latex-dev/base/nfssfont.dtx +++ b/macros/latex-dev/base/nfssfont.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -82,7 +82,7 @@ % the moment only a crude adaption of the test program for the % Computer Modern fonts by Donald Knuth. % -% \StopEventually{} +% \MaybeStop{} % % \section{A driver for this document} % diff --git a/macros/latex-dev/base/nfssfont.ins b/macros/latex-dev/base/nfssfont.ins index 7d1b9cc41a..a181c61972 100644 --- a/macros/latex-dev/base/nfssfont.ins +++ b/macros/latex-dev/base/nfssfont.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/nfssfont.pdf b/macros/latex-dev/base/nfssfont.pdf Binary files differindex 8737c708f2..1148a19767 100644 --- a/macros/latex-dev/base/nfssfont.pdf +++ b/macros/latex-dev/base/nfssfont.pdf diff --git a/macros/latex-dev/base/olddc.ins b/macros/latex-dev/base/olddc.ins index d878507d8e..707fb207e6 100644 --- a/macros/latex-dev/base/olddc.ins +++ b/macros/latex-dev/base/olddc.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/oldlfont.dtx b/macros/latex-dev/base/oldlfont.dtx index d04ddb6323..b7c9abc3eb 100644 --- a/macros/latex-dev/base/oldlfont.dtx +++ b/macros/latex-dev/base/oldlfont.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -95,7 +95,7 @@ % \end{tabular} % \end{center} % -% \StopEventually{} +% \MaybeStop{} % % \changes{v2.2k}{1995/11/29}{Remove duplicate driver code.} % diff --git a/macros/latex-dev/base/preload.dtx b/macros/latex-dev/base/preload.dtx index bf2bfebbfa..3b75df38fd 100644 --- a/macros/latex-dev/base/preload.dtx +++ b/macros/latex-dev/base/preload.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -131,7 +131,7 @@ % \end{quote} % % -% \StopEventually{} +% \MaybeStop{} % % \section{Module switches for the \dst{} program} % diff --git a/macros/latex-dev/base/proc.dtx b/macros/latex-dev/base/proc.dtx index 7a1329fb82..135c67bc0b 100644 --- a/macros/latex-dev/base/proc.dtx +++ b/macros/latex-dev/base/proc.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -73,7 +73,7 @@ %</driver> %<+class>\ProvidesClass{proc} %<+style>\ProvidesFile{proc.sty} - [2020/11/23 v1.3l + [2021/12/09 v1.3m %<+class> Standard LaTeX document class] %<+style> LaTeX 2.09 compatibility style option `proc'] % \end{macrocode} @@ -131,7 +131,7 @@ % should appear after any |\footnote| commands that produce % footnotes for the first column. % -% \StopEventually{} +% \MaybeStop{} % % \section{The {\sc docstrip} modules} % @@ -338,9 +338,17 @@ % \begin{macrocode} \let\@oddhead\@empty \let\@evenhead\@empty -\def\@oddfoot{\normalfont\rightmark \hfil - \pagename{} \thepage} -\def\@evenfoot{\@oddfoot} +\def\@oddfoot{\rightmark \hfil \pagename{} \thepage} +% \end{macrocode} +% If the \texttt{twoside} option is passed to the class we provide +% a different footer that shows the \cs{leftmark} if that is set. +% \changes{v1.3m}{2021/12/09}{Support twoside (gh/704)} +% \begin{macrocode} +\if@twoside + \def\@evenfoot{\pagename{} \thepage \hfil \leftmark} +\else + \def\@evenfoot{\@oddfoot} +\fi % \end{macrocode} % % diff --git a/macros/latex-dev/base/proc.ins b/macros/latex-dev/base/proc.ins index cfed5bd6a3..16f60195e5 100644 --- a/macros/latex-dev/base/proc.ins +++ b/macros/latex-dev/base/proc.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/proc.pdf b/macros/latex-dev/base/proc.pdf Binary files differindex 4dfc3ba645..0e238c067b 100644 --- a/macros/latex-dev/base/proc.pdf +++ b/macros/latex-dev/base/proc.pdf diff --git a/macros/latex-dev/base/slides.dtx b/macros/latex-dev/base/slides.dtx index e63c1901d6..06a4326277 100644 --- a/macros/latex-dev/base/slides.dtx +++ b/macros/latex-dev/base/slides.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -205,7 +205,7 @@ % features without adding additional |\DeclareFontShape| commands to % your |.fd| files or the preamble of your document. % -% \StopEventually{} +% \MaybeStop{} % % % \section{The Implementation} diff --git a/macros/latex-dev/base/slides.ins b/macros/latex-dev/base/slides.ins index 43ec2bebdf..8c9862c2d5 100644 --- a/macros/latex-dev/base/slides.ins +++ b/macros/latex-dev/base/slides.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. @@ -96,7 +96,7 @@ extension .ins) which are part of the distribution. This is a generated file. -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. @@ -138,7 +138,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/slides.pdf b/macros/latex-dev/base/slides.pdf Binary files differindex 328a87af8a..add1f4592e 100644 --- a/macros/latex-dev/base/slides.pdf +++ b/macros/latex-dev/base/slides.pdf diff --git a/macros/latex-dev/base/slifonts.pdf b/macros/latex-dev/base/slifonts.pdf Binary files differindex 21c53533be..894aead8ff 100644 --- a/macros/latex-dev/base/slifonts.pdf +++ b/macros/latex-dev/base/slifonts.pdf diff --git a/macros/latex-dev/base/source2e.pdf b/macros/latex-dev/base/source2e.pdf Binary files differindex f1dd97c296..bd750e892f 100644 --- a/macros/latex-dev/base/source2e.pdf +++ b/macros/latex-dev/base/source2e.pdf diff --git a/macros/latex-dev/base/source2e.tex b/macros/latex-dev/base/source2e.tex index abe8c1aac2..9eea9ddd0f 100644 --- a/macros/latex-dev/base/source2e.tex +++ b/macros/latex-dev/base/source2e.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -264,6 +264,8 @@ page_precedence "rnaA" \DocInclude{ltpara} % Paragraph hooks (L3 module) + \DocInclude{ltmeta} % Document Metadara interface (L3 module) + \DocInclude{ltspace} % Spacing, line and page breaking. \DocInclude{ltlogos} % Logos. @@ -326,6 +328,8 @@ page_precedence "rnaA" \DocInclude{ltclass} % Package & Class interface + \DocInclude{ltkeys} % Key-based option management (L3 module) + \DocInclude{ltfilehook} % Hook management for files (L3 module) \DocInclude{ltshipout}% \shipout redefinition (L3 module) diff --git a/macros/latex-dev/base/source2edoc.cls b/macros/latex-dev/base/source2edoc.cls index bef81d995d..b17c4c52b1 100644 --- a/macros/latex-dev/base/source2edoc.cls +++ b/macros/latex-dev/base/source2edoc.cls @@ -5,6 +5,8 @@ [2021/01/14 v0.2b Quick hack to typeset source2.tex (not usable for anything else and buggy -- will vanish again)!] + + \LoadClass{l3doc} \RemoveFromHook{begindocument}[l3doc] % drop the standard setting making " a shortverb @@ -18,7 +20,7 @@ \ExplSyntaxOn % in 2e we have a lot of functions that have no ``user-level'' documentation so we disable -% a bogus backref in that case. Over time the sources should be clean up to have such documentation. +% a bogus backref in that case. Over time the sources should be cleaned up to have such documentation. \cs_set_protected:Npn \__codedoc_print_documented: { diff --git a/macros/latex-dev/base/syntonly.dtx b/macros/latex-dev/base/syntonly.dtx index b214c49ae4..ae4d4cd1f8 100644 --- a/macros/latex-dev/base/syntonly.dtx +++ b/macros/latex-dev/base/syntonly.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -55,7 +55,7 @@ % This command can be used in the preamble for running a document % through \LaTeX{} without actually getting any output. % -% \StopEventually{} +% \MaybeStop{} % % % \section{Identification} diff --git a/macros/latex-dev/base/syntonly.ins b/macros/latex-dev/base/syntonly.ins index 6b4113ed11..5812ef2fd6 100644 --- a/macros/latex-dev/base/syntonly.ins +++ b/macros/latex-dev/base/syntonly.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 1993-2021 +Copyright (C) 1993-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/syntonly.pdf b/macros/latex-dev/base/syntonly.pdf Binary files differindex 8d67df1a00..47b7e2517b 100644 --- a/macros/latex-dev/base/syntonly.pdf +++ b/macros/latex-dev/base/syntonly.pdf diff --git a/macros/latex-dev/base/testpage.tex b/macros/latex-dev/base/testpage.tex index ff17984ee1..e199a2bb71 100644 --- a/macros/latex-dev/base/testpage.tex +++ b/macros/latex-dev/base/testpage.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/tex2.txt b/macros/latex-dev/base/tex2.txt deleted file mode 100644 index 09cd388cde..0000000000 --- a/macros/latex-dev/base/tex2.txt +++ /dev/null @@ -1,83 +0,0 @@ - LaTeX installation TeX2 information - - 16 September 1995 - - -In order to make a LaTeX format and use it you need, in addition to -the LaTeX source files, a TeX implementation. - -If your TeX is very old, prior to version TeX3, then certain features -will be missing from your system. In particular, you will probably -have no support for `8-bit' input and hyphenation of words with -accented characters. - -Most (perhaps all) TeX implementations are available in versions that -are at least as recent as TeX3 (released in 1989) so the best course -of action is to update your TeX installation before building LaTeX. - -However, if you must for some reason make the LaTeX format by running -the old TeX2 then it is necessary to have a `configuration file' named -fonttext.cfg. The existence of this file will prevent LaTeX trying to -access 8-bit characters, which is not allowed in the old TeX2 version -of TeX. - -If you fail to use such a configuration file, LaTeX will detect that it -is running under TeX2 and stop with the following message (without -making a format file): - -************************************* -* -* You MUST use a fonttext.cfg file! -* As you are still using TeX2!!!!!! -* -* See the documentation file tex2.txt -* -************************************* - - -There is more information about the file fonttext.cfg in the file -cfgguide.tex; but for a minimal configuration that allows LaTeX to -be built on TeX2, just do the following: - - * Copy the standard fonttext.ltx file to fonttext.cfg - * Then edit the file fonttext.cfg as follows: - -- Change the \ProvidesFile call (see below). - -- Comment out all the lines referring to the `T1' encoding (but not - those referring to the `OT1' encoding). - -Thus the resulting file will look something like the following. - -%%% File: fonttext.cfg -\ProvidesFile{fonttext.cfg} - [1995/06/05 v1.0 TeX2 text font setup] - -\input {OMLenc.def} -%%%%% NOT FOR TeX2 \input {T1enc.def} -\input {OT1enc.def} % <- should come after T1 for speed -\input {OMSenc.def} -\fontencoding{OT1} -\DeclareFontEncodingDefaults{}{} -%%%%% NOT FOR TeX2 \DeclareFontSubstitution{T1}{cmr}{m}{n} -\DeclareFontSubstitution{OT1}{cmr}{m}{n} -%%%%% NOT FOR TeX2 \input {T1cmr.fd} -\input {OT1cmr.fd} -\input {OT1cmss.fd} -\input {OT1cmtt.fd} -\DeclareErrorFont{OT1}{cmr}{m}{n}{10} -\newcommand\rmdefault{cmr} -\newcommand\sfdefault{cmss} -\newcommand\ttdefault{cmtt} - -\newcommand\bfdefault{bx} -\newcommand\mddefault{m} - -\newcommand\itdefault{it} -\newcommand\sldefault{sl} -\newcommand\scdefault{sc} -\newcommand\updefault{n} - -\newcommand\encodingdefault{OT1} -\newcommand\familydefault{\rmdefault} -\newcommand\seriesdefault{\mddefault} -\newcommand\shapedefault{\updefault} -\endinput diff --git a/macros/latex-dev/base/texpert.txt b/macros/latex-dev/base/texpert.txt deleted file mode 100644 index 0eb1dd7784..0000000000 --- a/macros/latex-dev/base/texpert.txt +++ /dev/null @@ -1,210 +0,0 @@ - LaTeX installation TeX expert information - - 1 June 1997 - - -SUMMARY -======= - -This document contains information about the LaTeX installation for -TeX experts. In particular it describes: - - * The checks performed by ltxcheck.tex - - * How to print the LaTeX source. - -For more general information, see install.txt. - -For information on configuring LaTeX see cfgguide.tex. - - -THE LTXCHECK.TEX CHECKS -======================= - -Here is a description of the checks run by ltxcheck. - -1) The \@currdir check. - - It is useful for LaTeX to know the syntax for the `current directory - (or folder)', or `default directory', if the operating system has - such a concept. - - For example, file abc.tex in this directory, or folder, is specified - by: - ./abc.tex on Unix and most DOS/OS2 TeX's, - []abc.tex on VMS - :abc.tex on a Macintosh. - The above possibilities will be found automatically during the - installation. However, if none of these syntaxes works on your - system then the internal macro \@currdir will be set to be empty - and ltxcheck will report this. - - If your system does have a notion of a current directory, you can - define \@currdir in the file texsys.cfg. - - You could also report this to the latex-bug address, so that - later releases can automatically cope with your system. - -2) The file name parser check. - \filename@parse may be defined in texsys.cfg if the default - installation does not define a suitable parser. (In fact no widely - used TeX system should need such a re-definition as the standard - installation should correctly define this command for unix, dos, - atari, VMS, and Macintosh, at least.) - Because of differences in directory syntax, most features of this - command can not be checked in a portable way, however ltxcheck does - check that at least {article.cls} is correctly parsed as base name - article and extension cls. - -3) The \input@path check. - - On some systems TeX cannot check whether a file exists before - trying to input it, unless the filename is expressed as a full path - name, including the directory. On these systems LaTeX needs to be - given a list of directories in which to look for files; the - internal macro \input@path holds this information. - - When run, ltxcheck will try to locate the file article.cls. - If it fails to find this file (and you have placed it in the - `standard input directory') then you must define \input@path in - the file texsys.cfg. - - The files texsys.cfg and ltdirchk.dtx contain examples of how to do - this but only you know the directories and syntax that should be used - for your installation. - - We hope to build up a better collection of examples in future - releases of LaTeX, as it is tested on more TeX systems. - -4) TeX version check. - - The next check tests that you are running a recent version of TeX. - If ltxcheck reports that you have TeX2, then you should try to - upgrade TeX (and rebuild LaTeX) as soon as possible. LaTeX may be - used with TeX2, but certain features will be missing and you will - not be able to use the new (8-bit) font families that are now - available. If you must stick with TeX2, please read the extra - information in the file tex2.txt. - - If ltxcheck reports that your TeX version is older than 3.141, you - will see some strange messages during the installation. This is - because earlier versions of TeX printed certain line-breaks in - messages on the terminal as `^^J' rather than starting a new line. - - LaTeX will work round this bug and thus avoid `^^J' appearing in - error messages, but you should upgrade your TeX as soon as - possible, as other bugs have been fixed, not just line breaks in - messages. - - At the present time (2005) the current TeX version is 3.141592. - -5) Fonts check. - - Finally ltxcheck.tex tests to see if it can find a `representative - sample' of the fonts used by LaTeX. - - Fonts that may cause problems are: - a) The circle fonts. These were renamed some years ago from circle* - to lcircle*, although some sites still have them under the old - name. Also the names are longer than 8 letters which may cause - some problems. - b) The `extra Computer Modern' fonts. The American Mathematical - Society has extended the range of sizes available in the - Computer Modern fonts. LaTeX now assumes that these extra cm - fonts are available. - The fonts are available from a CTAN archive, in the directory - ctan:macros/latex/fonts or alternatively as part of the - AMS fonts collection, which also includes many useful - mathematical fonts. - c) The `T1 encoded Computer Modern' fonts. This is the ec or dc font - collection. The new (1995) release 1.2 of the dc fonts changed - most of the file names. For this reason the fd files such as - t1cmr.fd cannot be written to work with the dc fonts of different - releases. LaTeX by default unpacks the fd files for the ec - dc fonts. - If you have an older release of the dc fonts and do not wish to - upgrade then you should unpack the necessary fd files by running - LaTeX on the file olddc.ins (dc older than version 1.2) or - newdc.ins (version 1.2 and 1.3). - As the T1 fd files will have been used when making the format, - you must re-run initex latex.ltx to remake the format if you - update the fd files in this way. - Running ltxcheck will produce a ! BAD LaTeX2e system!! error - message if it detects that the `new' fd files are loaded into - the format, but only the old dc fonts are available, and vice - versa. - If the old fonts are detected, and the `old' fd files are loaded - then no error is generated, but a message suggesting that you - upgrade is produced. - The ec fonts are available from a CTAN archive, in the directory - ctan:fonts/ec . - - -6) Files check. - - Finally ltxcheck checks that the main TeX input files that LaTeX - will use when running documents (such as the article class file, - fd files, and main packages such as fontenc) are all available. - - -DOCUMENTATION OF THE CODE -========================= - -Most of the documentation is nowadays available as precomplied PDF -files. This section describes how to produce typeset code -documentation yourself from the source. - -To typeset a documented code file (a .dtx file) you simply run LaTeX -on it. The file source2e.tex is a master file which produces the -documented code for the whole LaTeX kernel (but not the standard -packages, classes, or compatibility mode). You need to have LaTeX2e -installed before doing this. - -To configure the appearance of this documentation, you can use a -ltxdoc.cfg file. For example, putting the following line into this -file will format the documentation for A4 paper: - - \PassOptionsToClass{a4paper}{article} - -The doc package, which is used by the documentation files, writes -index files and change-history files that can be processed by the -program MakeIndex. If this program is part of your TeX installation, -you can get an index and history listing for a documentation file -by running the .idx and .glo files through this program. - -For example, in Unix MakeIndex, you should say: - - makeindex -s gind.ist FILENAME - makeindex -s gglo.ist -o FILENAME.gls FILENAME.glo - -source2e.tex needs a special source2e.ist file (in place of gind.ist). -Running makeindex will produce some warning messages about ignored -style specifiers; these can be safely ignored. - -See the comments at the end of source2e.tex for more information. - - -CONFIGURING LaTeX -================= - -In addition to the system-dependent customisation in texsys.cfg, -various other parts of LaTeX can be configured to suit local needs. -Further details can be found in the document cfgguide.tex. We -recommend that you install the standard system before attempting any -further customisation. - -If you are thinking of making other changes to LaTeX, please read the -document modguide.tex as it describes the precautions you need to take -when making modifications in order to ensure that standard LaTeX -remains a stable, maintainable system. - - -FURTHER INFORMATION -=================== - -You will find further information about various aspects of LaTeX in -the distributed files with names <*>guide.tex. You will need -to install the new version before you can typeset these files. - - ---- Copyright (C) 1995-2019 the LaTeX Project. All rights reserved --- diff --git a/macros/latex-dev/base/tlc2.err b/macros/latex-dev/base/tlc2.err index 46ba9ed845..8925a8bee1 100644 --- a/macros/latex-dev/base/tlc2.err +++ b/macros/latex-dev/base/tlc2.err @@ -1,4 +1,4 @@ -\newcommand\erratafiledate{2014-09-30} +\newcommand\erratafiledate{2022-01-03} \def\comando#1{\texttt{\string#1}} @@ -852,6 +852,9 @@ highlighting color\u{ as demonstrated below}: \erroronpage{116}{Footnote 1, line 1}{CBC}{2004/05/18}{2} Replace: ``I managed to confuse'' with ``we managed to confuse''. +\erroronpage{117}{para 1, l.1}{EOl}{2022/01/02}{} + Missing letter: ``to cho\u{o}se'' + \erroronpage{117}{para 2, l.2}{HjG}{2004/05/25}{2} Missing letter: ``It take\u{s} two \ldots'' @@ -2233,6 +2236,10 @@ Change: ``The unaccented ASCII Latin letters and Arabic Various deviations from alphabetical sort order of the table entries. +\erroronpage{553}{para 3, l.1}{EOl}{2022/01/02}{} + Missing letter: ``sup\u{p}ressing'' + + \iffalse % more blue align stuff \erroronpage{534}{page}{FMi}{2004/04/23}{} Printing problem: blue color not properly aligned (horizontally). @@ -2313,7 +2320,7 @@ Plural: ``Clearly, 8 bits \u{are} not sufficient\ldots'' \erroronpage{551}{tab 9.3}{CBe}{2004/07/27}{} I am surprised that in Russian there is no word for ``Glossary''. - Frank: It most certainly exits :-), but right now Babel doesn't + Frank: It most certainly exists :-), but right now Babel doesn't know about it---so there is nothing we can do about it at the moment. Actually the same problem exists with Polish, although here I got a translation ``s\l{}ownik termin\'ow'' which will eventually @@ -2715,6 +2722,9 @@ some of the listed drivers are only of historical interest. \erroronpage{616}{boxed texts}{FMi}{2004/05/26}{2} Corrections as outlined in summary entry above. +\erroronpage{617}{Fig. 10-2-2}{EOl}{2021/11/17}{} + A ``|%|'' should follow the ending ``|}|'' of the two |\bluefbox|es. + \erroronpage{618}{boxed text}{CAR}{2004/05/26}{2} Replace: ``\textit{key val list}'' \> ``\textit{key/val-list}'' (also in following text). @@ -2740,6 +2750,9 @@ some of the listed drivers are only of historical interest. %\erroronpage{621}{page}{FMi}{2004/04/23}{} % Printing problem: blue color not properly aligned. +\erroronpage{621}{Fig. 10-2-8}{EOl}{2021/11/17}{} + A ``|%|'' should follow the ending ``|}|'' of the first |\bluefbox|. + \erroronpage{623}{para 1, l.7}{HjG}{2004/06/07}{2} Delete word: ``some \u{of} key combinations'' @@ -2752,7 +2765,7 @@ some of the listed drivers are only of historical interest. \u{\texttt{tabular}} examples'' \erroronpage{631}{para.2, l.6}{FMi/HjG}{2006/10/22}{s} - Ersetze: "`\u{This point} is shown \ldots"' \> + Replace: "`\u{This point} is shown \ldots"' \> "`\u{This} is shown \ldots"' \erroronpage{631}{para -1, l.-1}{JBr}{2004/08/02}{2} @@ -4547,6 +4560,7 @@ and \contributor{DHL}{Dan Luecking} \contributor{DIs}{Daniel Isaacson} \contributor{DSch}{Dirk Schlimm} +\contributor{EOl}{Edgar Olthof} \contributor{ERy}{Elizabeth Ryan} \contributor{FHa}{Ferdy Hanssen} \contributor{FMi}{Frank Mittelbach} @@ -4621,7 +4635,7 @@ preferably in a form usable directly in this file, i.e., \begin{flushleft} |\erroronpage{|\textit{page-number}|}{|\textit{line-identification}|}{|% \textit{your-initials}|}{|\textit{date}|}{}| \\ - \hspace*{2em}\textit{description of the the erratum} + \hspace*{2em}\textit{description of the erratum} \end{flushleft} Here is an example: \begin{verbatim} diff --git a/macros/latex-dev/base/tlc2.pdf b/macros/latex-dev/base/tlc2.pdf Binary files differindex 58ae5264ac..06731d0a9d 100644 --- a/macros/latex-dev/base/tlc2.pdf +++ b/macros/latex-dev/base/tlc2.pdf diff --git a/macros/latex-dev/base/tulm.ins b/macros/latex-dev/base/tulm.ins index 98962f2b20..a50060b201 100644 --- a/macros/latex-dev/base/tulm.ins +++ b/macros/latex-dev/base/tulm.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 2016-2021 +%% Copyright (C) 2016-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% @@ -48,7 +48,7 @@ reports for it can be opened at https://latex-project.org/bugs.html (but please observe conditions on bug reports sent to that address!) -Copyright (C) 2016-2021 +Copyright (C) 2016-2022 The LaTeX Project and any individual authors listed elsewhere in this file. diff --git a/macros/latex-dev/base/tulm.pdf b/macros/latex-dev/base/tulm.pdf Binary files differindex 023c70c0b0..4d5c375eb9 100644 --- a/macros/latex-dev/base/tulm.pdf +++ b/macros/latex-dev/base/tulm.pdf diff --git a/macros/latex-dev/base/unpack.ins b/macros/latex-dev/base/unpack.ins index 6332fcb5c0..21ba62a33a 100644 --- a/macros/latex-dev/base/unpack.ins +++ b/macros/latex-dev/base/unpack.ins @@ -3,7 +3,7 @@ %% driver files from the doc files in this package when run through %% LaTeX or TeX. %% -%% Copyright (C) 1993-2021 +%% Copyright (C) 1993-2022 %% The LaTeX Project and any individual authors listed elsewhere %% in this file. %% diff --git a/macros/latex-dev/base/usrguide.pdf b/macros/latex-dev/base/usrguide.pdf Binary files differindex 6dc20a37df..59e7711019 100644 --- a/macros/latex-dev/base/usrguide.pdf +++ b/macros/latex-dev/base/usrguide.pdf diff --git a/macros/latex-dev/base/usrguide.tex b/macros/latex-dev/base/usrguide.tex index a94d8a6a70..dfdf9443e6 100644 --- a/macros/latex-dev/base/usrguide.tex +++ b/macros/latex-dev/base/usrguide.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % diff --git a/macros/latex-dev/base/usrguide3.pdf b/macros/latex-dev/base/usrguide3.pdf Binary files differindex a051df898c..11da2b74b8 100644 --- a/macros/latex-dev/base/usrguide3.pdf +++ b/macros/latex-dev/base/usrguide3.pdf diff --git a/macros/latex-dev/base/usrguide3.tex b/macros/latex-dev/base/usrguide3.tex index 82c1c06863..249b708943 100644 --- a/macros/latex-dev/base/usrguide3.tex +++ b/macros/latex-dev/base/usrguide3.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2020-2021 +% Copyright (C) 2020-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -31,12 +31,13 @@ \documentclass{ltxguide} \usepackage[T1]{fontenc} % needed for \textbackslash in tt +\usepackage{csquotes} \title{New \LaTeX\ methods for authors (starting 2020)} -\author{\copyright~Copyright 2020-2021, \LaTeX\ Project Team.\\ +\author{\copyright~Copyright 2020-2022, \LaTeX\ Project Team.\\ All rights reserved.} -\date{2021-06-11} +\date{2022-01-03} \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}} \NewDocumentCommand\marg{m}{\arg{#1}} @@ -48,6 +49,18 @@ \renewcommand \verbatim@font {\normalfont \ttfamily} \makeatother + +% for fpeval documentation + +\providecommand\fpop[1]{\mathop{\texttt{#1}}} +\providecommand\fpbin[1]{\mathbin{\texttt{#1}}} +\providecommand\fprel[1]{\mathrel{\texttt{#1}}} +\providecommand\nan{\texttt{NaN}} + +\ExplSyntaxOn +\ProvideExpandableDocumentCommand \fpeval { m } { \fp_eval:n {#1} } +\ExplSyntaxOff + \begin{document} \maketitle @@ -227,6 +240,11 @@ defined. same name. This should be used sparingly. \end{itemize} +If the \meta{cmd} can't be provided as a single token but needs +\enquote{constructing}, you can use \cs{ExpandArgs} as explained in +Section~\ref{sec:preconstructing-csnames} which also gives an example +in which this is needed. + \begin{decl} |\NewDocumentEnvironment| \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\ |\RenewDocumentEnvironment| \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\ @@ -288,7 +306,7 @@ must exist). So after \end{verbatim} the user input |\foo{arg1}[arg2]{arg3}| and \verb*|\foo{arg1} [arg2] {arg3}| will both be parsed in the same way. - + The behavior of optional arguments \emph{after} any mandatory arguments is selectable. The standard settings will allow spaces here, and thus with \begin{verbatim} @@ -554,10 +572,12 @@ spaces are trimmed at both ends of the body: in the example there would otherwise be spaces coming from the ends the lines after |[\itshape]| and |world!|. Putting the prefix |!| before \texttt{b} suppresses space-trimming. -When \texttt{b} is used in the argument specification, the last argument of the environment declaration (e.g., \cs{NewDocumentEnvironment}), which consists of an \meta{end code} to insert at -|\end|\marg{environment}, is redundant since one can simply put that code at -the end of the \meta{start code}. Nevertheless this (empty) \meta{end code} -must be provided. +When \texttt{b} is used in the argument specification, the last +argument of the environment declaration (e.g., +\cs{NewDocumentEnvironment}), which consists of an \meta{end code} to +insert at |\end|\marg{environment}, is redundant since one can simply +put that code at the end of the \meta{start code}. Nevertheless this +(empty) \meta{end code} must be provided. Environments that use this feature can be nested. @@ -665,7 +685,7 @@ with both calls to the command seeing the delimiter |\x|. \subsection{Creating new argument processors} \begin{decl} - |\ProcessedArgument| + |\ProcessedArgument| \end{decl} Argument processors allow manipulation of a grabbed argument before it is passed to the underlying code. New processor implementations may be created @@ -710,4 +730,280 @@ requested \meta{function} or \meta{environment} at the terminal. If the \meta{function} or \meta{environment} has no known argument specification then an error is issued. + + +\section{Copying and showing (robust) commands} + +If you want to (slightly) alter an existing command you may want to +save the current definition under a new name and then use that in a +new definition. If the existing command is robust, then the old trick of +using the low-level \cs{let} for this doesn't work, because it only +copies the top-level definition, but not the part that actually does +the work. As most \LaTeX{} commands are nowadays robust, \LaTeX{} +now offers some high-level declarations for this instead. + +However, please note that it is usually better to make use of +available hooks (e.g., the generic command or environment hooks), +instead of copying the current definition and thereby freezing it; see +the hook management documentation \texttt{lthooks-doc.pdf} for +details. + +\begin{decl} + |\NewCommandCopy| \arg{cmd} \arg{existing-cmd} \\ + |\RenewCommandCopy| \arg{cmd} \arg{existing-cmd} \\ + |\DeclareCommandCopy| \arg{cmd} \arg{existing-cmd} +\end{decl} + +This copies the definition of \meta{existing-cmd} to \meta{cmd}. After +this \meta{existing-cmd} can be redefined and \meta{cmd} +still works! This allows you to then provide a new definition for +\meta{existing-cmd} that makes use of \meta{cmd} (i.e., of its old +definition). For example, after +\begin{verbatim} + \NewCommandCopy\LaTeXorig\LaTeX + \RenewDocumentCommand\LaTeX{}{\textcolor{blue}{\LaTeXorig}} +\end{verbatim} +all \LaTeX{} logos generated with \cs{LaTeX} will come out in blue +(assuming you have a color package loaded). + +The differences between \cs{New...} and \cs{Renew...} are as +elsewhere: i.e., you get an error depending on whether or not +\meta{cmd} already exists, or in case of \cs{Declare...} it is copied +regardless. Note that there is no \cs{Provide...} declaration, because +that would be of limited value. + + +If the \meta{cmd} or \meta{existing-cmd} can't be provided as a single +token but need \enquote{constructing}, you can use \cs{ExpandArgs} +as explained in +Section~\ref{sec:preconstructing-csnames}. + + + + +\begin{decl} + |\ShowCommand| \arg{cmd} +\end{decl} + +This displays the meaning of the \meta{cmd} on the terminal and then +stops (just like the primitive \cs{show}). The difference is that it +correctly shows the meaning of more complex commands, e.g., in case of +robust commands it displays not only the top-level definition but +also the actual payload code and in case of commands declared with +\cs{NewDocumentCommand}, etc.\ it also gives you detailed information +about the argument signature. + + +\section[Preconstructing command names \\ (or otherwise expanding arguments)] + {Preconstructing command names (or otherwise expanding arguments)} +\label{sec:preconstructing-csnames} + +When declaring new commands with \cs{NewDocumentCommand} or +\cs{NewCommandCopy} or similar, it is sometimes necessary to +``construct'' the csname. As a general mechanism the L3 programming +layer has \cs{exp_args:N...} for this, but there is no mechanism for +it if \cs{ExplSyntaxOn} is not active (and mixing programming and user +interface level commands is not a good approach anyhow). We therefore +offer a mechanism to access this ability using CamelCase naming. + +\begin{decl} + |\UseName| \arg{string} \\ + |\ExpandArgs| \arg{spec} \arg{cmd} \arg{arg1} \dots +\end{decl} + +\cs{UseName} turns the \meta{string} directly into a csname and +then executes it: this is equivalent to the long-standing +\LaTeXe{} internal command \cs{@nameuse}, or the L3 programming +equivalent \cs{use:c}. \cs{ExpandArgs} takes a \meta{spec} which +describes how to expand the \meta{arguments}, carries out these +operations then executes the \meta{cmd}. The \meta{spec} uses +the descriptions offered by the L3 programming layer, and the +relevant \cs{exp_args:N...} function must exist. Common cases will +have a \meta{spec} of \texttt{c}, \texttt{cc} or \texttt{Nc}: see below. + +As an example, the following declaration provides a method to generate +copyedit commands: +\begin{verbatim} +\NewDocumentCommand\newcopyedit{mO{red}} + {\newcounter{todo#1}% + \ExpandArgs{c}\NewDocumentCommand{#1}{s m}% + {\stepcounter{todo#1}% + \IfBooleanTF {##1}% + {\todo[color=#2!10]{\UseName{thetodo#1}: ##2}}% + {\todo[inline,color=#2!10]{\UseName{thetodo#1}: ##2}}% + }% + } +\end{verbatim} +Given that declaration you can then write +\verb/\newcopyedit{note}[blue]/ which defines the command \cs{note} +and the corresponding counter for you. + +A second example is to copy a command by string name using +\cs{NewCommandCopy}: here we might need to construct both command +names. +\begin{verbatim} +\NewDocumentCommand\savebyname{m} + {\ExpandArgs{cc}\NewCommandCopy{saved#1}{#1}} +\end{verbatim} + +In the \meta{spec} each \texttt{c} stands for one argument that is +turned into a `\texttt{c}'ommand. An \texttt{n} represents a +`\texttt{n}'ormal argument that is not altered and \texttt{N} stands for +a `\texttt{N}'ormal argument which is also left unchanged, but one +consisting only of a single token (and usually unbraced). Thus, to +construct a command from a string only for the second argument of +\cs{NewCommandCopy} you would write +\begin{verbatim} +\ExpandArgs{Nc}\NewCommandCopy\mysectionctr{c@section} +\end{verbatim} +There are several other single letters supported in the L3 programming +layer that \emph{could} be used in the \meta{spec} to manipulate +arguments in other ways. If you are interested, take a look at the +\enquote{Argument expansion} section in the L3 programming layer +documentation in \texttt{interface3.pdf}. + + + +\section{Expandable floating point (and other) calculations} + +The \LaTeX3 programming layer which is part of the format offers a +rich interface to manipulate floating point variables and values. To +allow for (simpler) applications to use this on document-level or in +packages otherwise not making use of the L3 programming layer a few +interface commands are made available. + + +\begin{decl} + |\fpeval| \arg{floating point expression} +\end{decl} + +The expandable command \cs{fpeval} takes as its argument a floating +point expression and produces a result using the normal rules of +mathematics. As this command is expandable it can be used where \TeX{} +requires a number and for example within a low-level \cs{edef} operation +to give a purely numerical result. + + + +Briefly, the floating point expressions may comprise: +\begin{itemize} + \item Basic arithmetic: addition $x\fpbin{+}y$, subtraction $x\fpbin{-}y$, + multiplication $x\fpbin{*}y$, division $x\fpbin{/}y$, square root~$\sqrt{x}$, + and parentheses. + \item Comparison operators: $x\fprel{<}y$, + $x\fprel{<=}y$, $x\fprel{>?}y$, + $x\fprel{!=}y$ \emph{etc.} + \item Boolean logic: sign $\fpop{sign} x$, + negation $\fpop{!}x$, conjunction + $x\fprel{\&\&}y$, disjunction $x\fprel{\string|\string|}y$, ternary + operator $x\fprel{?}y\fprel{:}z$. + \item Exponentials: $\fpop{exp} x$, $\fpop{ln} x$, $x\mathord{\texttt{\^{}}}y$. + \item Integer factorial: $\fpop{fact} x$. + \item Trigonometry: $\fpop{sin} x$, $\fpop{cos} x$, $\fpop{tan} x$, $\fpop{cot} x$, $\fpop{sec} + x$, $\fpop{csc} x$ expecting their arguments in radians, and + $\fpop{sind} x$, $\fpop{cosd} x$, + $\fpop{tand} x$, $\fpop{cotd} x$, + $\fpop{secd} x$, $\fpop{cscd} x$ expecting their + arguments in degrees. + \item Inverse trigonometric functions: $\fpop{asin} x$, + $\fpop{acos} x$, $\fpop{atan} x$, + $\fpop{acot} x$, $\fpop{asec} x$, + $\fpop{acsc} x$ giving a result in radians, and + $\fpop{asind} x$, $\fpop{acosd} x$, + $\fpop{atand} x$, $\fpop{acotd} x$, + $\fpop{asecd} x$, $\fpop{acscd} x$ giving a result + in degrees. + \item Extrema: $\fpop{max}(x_{1},x_{2},\ldots)$, $\fpop{min}(x_{1},x_{2},\ldots)$, + $\fpop{abs}(x)$. + \item Rounding functions, controlled by two optional + values, $n$ (number of places, $0$ by default) and + $t$ (behavior on a tie, $\nan$ by default): + \begin{itemize} + \item $\fpop{trunc}(x,n)$ rounds towards zero, + \item $\fpop{floor}(x,n)$ rounds towards~$-\infty$, + \item $\fpop{ceil}(x,n)$ rounds towards~$+\infty$, + \item $\fpop{round}(x,n,t)$ rounds to the closest value, with + ties rounded to an even value by default, towards zero if $t=0$, + towards $+\infty$ if $t>0$ and towards $-\infty$ if $t<0$. + \end{itemize} + \item Random numbers: $\fpop{rand}()$, $\fpop{randint}(m,n)$. + \item Constants: \texttt{pi}, \texttt{deg} (one degree in radians). + \item Dimensions, automatically expressed in points, \emph{e.g.}, + \texttt{pc} is~$12$. + \item Automatic conversion (no need for \cs{number}) of + integer, dimension, and skip variables to floating points numbers, + expressing dimensions in points and ignoring the stretch and + shrink components of skips. + \item Tuples: $(x_1,\ldots{},x_n)$ that can be added together, + multiplied or divided by a floating point number, and nested. +\end{itemize} + +An example of use could be the following: +\begin{verbatim} + \LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3} + = \fpeval{sin(3.5)/2 + 2e-3} $. +\end{verbatim} +which produces the following output: +\begin{quote} + \LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3} + = \fpeval{sin(3.5)/2 + 2e-3} $. +\end{quote} + +\begin{decl} + |\inteval| \arg{integer expression} +\end{decl} + + The expandable command \cs{inteval} takes as its argument an integer + expression and produces a result using the normal rules of + mathematics with some restrictions, see below. The operations + recognized are |+|, |-|, |*| and |/| plus parentheses. As this + command is expandable it can be used where \TeX{} requires a number + and for example within a low-level \cs{edef} operation to give a + purely numerical result. + + This is basically a thin wrapper for the primitive \cs{numexpr} + command and therefore has some syntax restrictions. These are: + \begin{itemize} + \item \texttt{/} denotes division rounded to the closest integer with + ties rounded away from zero; + \item there is an error and the overall expression evaluates to zero + whenever the absolute value of any intermediate result exceeds + $2^{31}-1$, except in the case of scaling operations + $a$\texttt{*}$b$\texttt{/}$c$, for which $a$\texttt{*}$b$ may be + arbitrarily large; + \item parentheses may not appear after unary \texttt{+} or + \texttt{-}, namely placing \texttt{+(} or \texttt{-(} at the start + of an expression or after \texttt{+}, \texttt{-}, \texttt{*}, + \texttt{/} or~\texttt{(} leads to an error. + \end{itemize} + +An example of use could be the following. +\begin{verbatim} +\LaTeX{} can now compute: The sum of the numbers is $\inteval{1 + 2 + 3}$. +\end{verbatim} +which results in +\enquote{\LaTeX{} can now compute: The sum of the numbers is $\inteval{1 + 2 + 3}$.} + + +\begin{decl} + |\dimeval| \arg{dimen expression} \qquad + |\skipeval| \arg{skip expression} +\end{decl} + +Similar to \cs{inteval} but computing a length (\texttt{dimen}) or a +rubber length (\texttt{skip}) value. Both are thin wrappers around +the corresponding engine primitives, which makes them fast, but +therefore shows the same syntax peculiars as discussed +above. Nevertheless, in practice they are usually sufficient. For +example +\begin{verbatim} +\newcommand\calulateheight[1]{% + \setlength\textheight{\dimeval{\topskip+\baselineskip*\inteval{#1-1}}}} +\end{verbatim} +sets the \cs{textheight} to the appropriate value if a page should +hold a specific number of text lines. Thus after |\calulateheight{40}| +it is set to \dimeval{\topskip+\baselineskip*\inteval{40-1}}, given +the values \cs{topskip} (\dimeval{\topskip}) and \cs{baselineskip} +(\dimeval{\baselineskip}) in the current document. + \end{document} diff --git a/macros/latex-dev/base/utf8ienc.dtx b/macros/latex-dev/base/utf8ienc.dtx index 75990d1b03..a0c96357a0 100644 --- a/macros/latex-dev/base/utf8ienc.dtx +++ b/macros/latex-dev/base/utf8ienc.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2021 +% Copyright (C) 1993-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -190,7 +190,7 @@ % information. % % -% \StopEventually{} +% \MaybeStop{} % % % @@ -216,7 +216,7 @@ %<+ts1> \ProvidesFile{ts1enc.dfu} %<+x2> \ProvidesFile{x2enc.dfu} %<+all> \ProvidesFile{utf8enc.dfu} -%<-utf8-2018> [2021/06/21 v1.2n UTF-8 support] +%<-utf8-2018> [2021/12/13 v1.2o UTF-8 support] % \end{macrocode} % % \begin{macrocode} @@ -773,12 +773,13 @@ % looks slightly strange but is designed for the sequence of |\expandafter| % in |\DeclareUnicodeCharacter|. % +% \changes{v1.2o}{2021/12/13}{Use 80 not A0 to test for single byte UTF-8} % \begin{macrocode} - \ifnum\count@<"A0\relax + \ifnum\count@<"80\relax \ifnum\catcode\count@=13 \uccode`\~=\count@\uppercase{\def\UTFviii@tmp{\@empty\@empty~}}% \else - \@latex@error{Cannot define non-active Unicode char value < 00A0}% + \@latex@error{Cannot define non-active Unicode char value < 0080}% \@eha \def\UTFviii@tmp{\UTFviii@tmp}% \fi @@ -1368,6 +1369,18 @@ %<all,t1,ly1>\DeclareUnicodeCharacter{017E}{\v z} %<all,ts1,ly1>\DeclareUnicodeCharacter{0192}{\textflorin} % \end{macrocode} +% \changes{v1.2n}{2021/12/10}{add 01C4-01CC} +% \begin{macrocode} +%<all,t1>\DeclareUnicodeCharacter{01C4}{D\v Z} +%<all,t1>\DeclareUnicodeCharacter{01C5}{D\v z} +%<all,t1>\DeclareUnicodeCharacter{01C6}{d\v z} +%<all,t1>\DeclareUnicodeCharacter{01C7}{LJ} +%<all,t1>\DeclareUnicodeCharacter{01C8}{Lj} +%<all,t1>\DeclareUnicodeCharacter{01C9}{lj} +%<all,t1>\DeclareUnicodeCharacter{01CA}{NJ} +%<all,t1>\DeclareUnicodeCharacter{01CB}{Nj} +%<all,t1>\DeclareUnicodeCharacter{01CC}{nj} +% \end{macrocode} % \changes{v1.1s}{2016/01/11}{add 01CD-01F4} % \begin{macrocode} %<all,t1>\DeclareUnicodeCharacter{01CD}{\v A} diff --git a/macros/latex-dev/base/utf8ienc.pdf b/macros/latex-dev/base/utf8ienc.pdf Binary files differindex 55e0342500..def7db995c 100644 --- a/macros/latex-dev/base/utf8ienc.pdf +++ b/macros/latex-dev/base/utf8ienc.pdf diff --git a/macros/latex-dev/base/webcomp.pdf b/macros/latex-dev/base/webcomp.pdf Binary files differindex 0eedccd171..0addcf94c0 100644 --- a/macros/latex-dev/base/webcomp.pdf +++ b/macros/latex-dev/base/webcomp.pdf |