summaryrefslogtreecommitdiff
path: root/macros
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-05-26 03:02:08 +0000
committerNorbert Preining <norbert@preining.info>2023-05-26 03:02:08 +0000
commit8057c647880f05a2624b3d04ab0eb38d5cbf8c18 (patch)
tree2df10dbc859977e89de9b6797303c039106aca37 /macros
parented4c98e3a1f3e2160094ac1b05cfc304832cce4d (diff)
CTAN sync 202305260302
Diffstat (limited to 'macros')
-rw-r--r--macros/latex-dev/base/README.md2
-rw-r--r--macros/latex-dev/base/alltt.pdfbin223829 -> 223829 bytes
-rw-r--r--macros/latex-dev/base/cfgguide.pdfbin264161 -> 264161 bytes
-rw-r--r--macros/latex-dev/base/changes.txt139
-rw-r--r--macros/latex-dev/base/classes.dtx9
-rw-r--r--macros/latex-dev/base/classes.pdfbin560248 -> 560972 bytes
-rw-r--r--macros/latex-dev/base/clsguide-historic.pdfbin0 -> 415568 bytes
-rw-r--r--macros/latex-dev/base/clsguide-historic.tex1881
-rw-r--r--macros/latex-dev/base/clsguide.pdfbin414447 -> 451991 bytes
-rw-r--r--macros/latex-dev/base/clsguide.tex1903
-rw-r--r--macros/latex-dev/base/cmfonts.fdd6
-rw-r--r--macros/latex-dev/base/cmfonts.pdfbin292136 -> 292590 bytes
-rw-r--r--macros/latex-dev/base/cyrguide.pdfbin257355 -> 257355 bytes
-rw-r--r--macros/latex-dev/base/doc-code.pdfbin1074767 -> 1075457 bytes
-rw-r--r--macros/latex-dev/base/doc.dtx4
-rw-r--r--macros/latex-dev/base/doc.pdfbin755242 -> 755883 bytes
-rw-r--r--macros/latex-dev/base/docstrip.pdfbin504361 -> 504397 bytes
-rw-r--r--macros/latex-dev/base/encguide.pdfbin1318139 -> 1318562 bytes
-rw-r--r--macros/latex-dev/base/exscale.pdfbin204709 -> 204709 bytes
-rw-r--r--macros/latex-dev/base/fix-cm.pdfbin287724 -> 287724 bytes
-rw-r--r--macros/latex-dev/base/fntguide.pdfbin517890 -> 517677 bytes
-rw-r--r--macros/latex-dev/base/fntguide.tex21
-rw-r--r--macros/latex-dev/base/graphpap.pdfbin161725 -> 161725 bytes
-rw-r--r--macros/latex-dev/base/ifthen.pdfbin221226 -> 221226 bytes
-rw-r--r--macros/latex-dev/base/inputenc.pdfbin318166 -> 318166 bytes
-rw-r--r--macros/latex-dev/base/lamport-manual.pdfbin170874 -> 170874 bytes
-rw-r--r--macros/latex-dev/base/latexrelease.pdfbin282105 -> 282105 bytes
-rw-r--r--macros/latex-dev/base/latexsym.pdfbin200762 -> 200762 bytes
-rw-r--r--macros/latex-dev/base/lb2.pdfbin252313 -> 252510 bytes
-rw-r--r--macros/latex-dev/base/letter.pdfbin337493 -> 337766 bytes
-rw-r--r--macros/latex-dev/base/lgc2.pdfbin217560 -> 217757 bytes
-rw-r--r--macros/latex-dev/base/lppl.pdfbin132384 -> 132384 bytes
-rw-r--r--macros/latex-dev/base/ltclass.dtx23
-rw-r--r--macros/latex-dev/base/ltcmd.dtx110
-rw-r--r--macros/latex-dev/base/ltcmdhooks-code.pdfbin719205 -> 755337 bytes
-rw-r--r--macros/latex-dev/base/ltcmdhooks-doc.pdfbin478517 -> 498869 bytes
-rw-r--r--macros/latex-dev/base/ltcmdhooks.dtx424
-rw-r--r--macros/latex-dev/base/ltfilehook-code.pdfbin803151 -> 803843 bytes
-rw-r--r--macros/latex-dev/base/ltfilehook-doc.pdfbin547988 -> 548468 bytes
-rw-r--r--macros/latex-dev/base/ltfilehook.dtx10
-rw-r--r--macros/latex-dev/base/ltfiles.dtx66
-rw-r--r--macros/latex-dev/base/ltfinal.dtx94
-rw-r--r--macros/latex-dev/base/ltfssbas.dtx13
-rw-r--r--macros/latex-dev/base/lthooks-code.pdfbin1091279 -> 1242206 bytes
-rw-r--r--macros/latex-dev/base/lthooks-doc.pdfbin701283 -> 739995 bytes
-rw-r--r--macros/latex-dev/base/lthooks.dtx2769
-rw-r--r--macros/latex-dev/base/ltlists.dtx7
-rw-r--r--macros/latex-dev/base/ltluatex.pdfbin325056 -> 325056 bytes
-rw-r--r--macros/latex-dev/base/ltmarks-code.pdfbin715474 -> 716217 bytes
-rw-r--r--macros/latex-dev/base/ltmarks-doc.pdfbin585862 -> 586545 bytes
-rw-r--r--macros/latex-dev/base/ltmarks.dtx5
-rw-r--r--macros/latex-dev/base/ltmath.dtx23
-rw-r--r--macros/latex-dev/base/ltmeta.dtx5
-rw-r--r--macros/latex-dev/base/ltnews.cls2
-rw-r--r--macros/latex-dev/base/ltnews.pdfbin1265382 -> 1285592 bytes
-rw-r--r--macros/latex-dev/base/ltnews01.pdfbin161534 -> 161534 bytes
-rw-r--r--macros/latex-dev/base/ltnews02.pdfbin159811 -> 159811 bytes
-rw-r--r--macros/latex-dev/base/ltnews03.pdfbin159349 -> 159349 bytes
-rw-r--r--macros/latex-dev/base/ltnews04.pdfbin152545 -> 152545 bytes
-rw-r--r--macros/latex-dev/base/ltnews05.pdfbin174686 -> 174686 bytes
-rw-r--r--macros/latex-dev/base/ltnews06.pdfbin142870 -> 142870 bytes
-rw-r--r--macros/latex-dev/base/ltnews07.pdfbin138211 -> 138211 bytes
-rw-r--r--macros/latex-dev/base/ltnews08.pdfbin155426 -> 155426 bytes
-rw-r--r--macros/latex-dev/base/ltnews09.pdfbin129989 -> 129989 bytes
-rw-r--r--macros/latex-dev/base/ltnews10.pdfbin169414 -> 169414 bytes
-rw-r--r--macros/latex-dev/base/ltnews11.pdfbin112191 -> 112191 bytes
-rw-r--r--macros/latex-dev/base/ltnews12.pdfbin156746 -> 156746 bytes
-rw-r--r--macros/latex-dev/base/ltnews13.pdfbin182464 -> 182464 bytes
-rw-r--r--macros/latex-dev/base/ltnews14.pdfbin170716 -> 170716 bytes
-rw-r--r--macros/latex-dev/base/ltnews15.pdfbin130323 -> 130323 bytes
-rw-r--r--macros/latex-dev/base/ltnews16.pdfbin138090 -> 138090 bytes
-rw-r--r--macros/latex-dev/base/ltnews17.pdfbin166247 -> 166247 bytes
-rw-r--r--macros/latex-dev/base/ltnews18.pdfbin38320 -> 38424 bytes
-rw-r--r--macros/latex-dev/base/ltnews19.pdfbin230181 -> 230331 bytes
-rw-r--r--macros/latex-dev/base/ltnews20.pdfbin318566 -> 318787 bytes
-rw-r--r--macros/latex-dev/base/ltnews20.tex2
-rw-r--r--macros/latex-dev/base/ltnews21.pdfbin244870 -> 245007 bytes
-rw-r--r--macros/latex-dev/base/ltnews21.tex2
-rw-r--r--macros/latex-dev/base/ltnews22.pdfbin317779 -> 318003 bytes
-rw-r--r--macros/latex-dev/base/ltnews23.pdfbin286600 -> 286796 bytes
-rw-r--r--macros/latex-dev/base/ltnews24.pdfbin265292 -> 265470 bytes
-rw-r--r--macros/latex-dev/base/ltnews25.pdfbin204948 -> 205087 bytes
-rw-r--r--macros/latex-dev/base/ltnews26.pdfbin379472 -> 379718 bytes
-rw-r--r--macros/latex-dev/base/ltnews27.pdfbin251083 -> 251260 bytes
-rw-r--r--macros/latex-dev/base/ltnews28.pdfbin376652 -> 376892 bytes
-rw-r--r--macros/latex-dev/base/ltnews29.pdfbin455116 -> 455423 bytes
-rw-r--r--macros/latex-dev/base/ltnews30.pdfbin511895 -> 512207 bytes
-rw-r--r--macros/latex-dev/base/ltnews30.tex2
-rw-r--r--macros/latex-dev/base/ltnews31.pdfbin526332 -> 526646 bytes
-rw-r--r--macros/latex-dev/base/ltnews31.tex2
-rw-r--r--macros/latex-dev/base/ltnews32.pdfbin546186 -> 546525 bytes
-rw-r--r--macros/latex-dev/base/ltnews32.tex2
-rw-r--r--macros/latex-dev/base/ltnews33.pdfbin522416 -> 522729 bytes
-rw-r--r--macros/latex-dev/base/ltnews33.tex2
-rw-r--r--macros/latex-dev/base/ltnews34.pdfbin508052 -> 508339 bytes
-rw-r--r--macros/latex-dev/base/ltnews34.tex2
-rw-r--r--macros/latex-dev/base/ltnews35.pdfbin563098 -> 563295 bytes
-rw-r--r--macros/latex-dev/base/ltnews35.tex20
-rw-r--r--macros/latex-dev/base/ltnews36.pdfbin517571 -> 517917 bytes
-rw-r--r--macros/latex-dev/base/ltnews36.tex2
-rw-r--r--macros/latex-dev/base/ltnews37.pdfbin456714 -> 500493 bytes
-rw-r--r--macros/latex-dev/base/ltnews37.tex472
-rw-r--r--macros/latex-dev/base/ltpara-code.pdfbin671573 -> 672305 bytes
-rw-r--r--macros/latex-dev/base/ltpara-doc.pdfbin559554 -> 560232 bytes
-rw-r--r--macros/latex-dev/base/ltpara.dtx5
-rw-r--r--macros/latex-dev/base/ltplain.dtx54
-rw-r--r--macros/latex-dev/base/ltshipout-code.pdfbin821006 -> 821768 bytes
-rw-r--r--macros/latex-dev/base/ltshipout-doc.pdfbin566006 -> 566650 bytes
-rw-r--r--macros/latex-dev/base/ltshipout.dtx2
-rw-r--r--macros/latex-dev/base/ltspace.dtx4
-rw-r--r--macros/latex-dev/base/ltvers.dtx2
-rw-r--r--macros/latex-dev/base/ltx3info.pdfbin219354 -> 219354 bytes
-rw-r--r--macros/latex-dev/base/ltxdoc.dtx14
-rw-r--r--macros/latex-dev/base/ltxdoc.pdfbin243283 -> 244221 bytes
-rw-r--r--macros/latex-dev/base/ltxguide.cls2
-rw-r--r--macros/latex-dev/base/ltxref.dtx93
-rw-r--r--macros/latex-dev/base/makeindx.pdfbin165817 -> 165817 bytes
-rw-r--r--macros/latex-dev/base/manifest.txt6
-rw-r--r--macros/latex-dev/base/minimal.cls2
-rw-r--r--macros/latex-dev/base/modguide.pdfbin257827 -> 257827 bytes
-rw-r--r--macros/latex-dev/base/nfssfont.pdfbin211180 -> 211180 bytes
-rw-r--r--macros/latex-dev/base/proc.pdfbin227056 -> 227056 bytes
-rw-r--r--macros/latex-dev/base/slides.pdfbin375514 -> 375514 bytes
-rw-r--r--macros/latex-dev/base/slifonts.fdd2
-rw-r--r--macros/latex-dev/base/slifonts.pdfbin234188 -> 234188 bytes
-rw-r--r--macros/latex-dev/base/source2e.pdfbin5797424 -> 6002270 bytes
-rw-r--r--macros/latex-dev/base/syntonly.pdfbin189552 -> 189847 bytes
-rw-r--r--macros/latex-dev/base/tlc2.pdfbin291015 -> 291239 bytes
-rw-r--r--macros/latex-dev/base/tlc3.err829
-rw-r--r--macros/latex-dev/base/tlc3.pdfbin0 -> 249698 bytes
-rw-r--r--macros/latex-dev/base/tulm.fdd2
-rw-r--r--macros/latex-dev/base/tulm.pdfbin162766 -> 162766 bytes
-rw-r--r--macros/latex-dev/base/usrguide-historic.pdfbin438570 -> 438586 bytes
-rw-r--r--macros/latex-dev/base/usrguide.pdfbin474841 -> 479591 bytes
-rw-r--r--macros/latex-dev/base/usrguide.tex93
-rw-r--r--macros/latex-dev/base/utf8ienc.pdfbin353281 -> 353320 bytes
-rw-r--r--macros/latex-dev/base/webcomp.pdfbin146195 -> 146195 bytes
-rw-r--r--macros/latex-dev/required/amsmath/README.md4
-rw-r--r--macros/latex-dev/required/amsmath/amsbsy.ins2
-rw-r--r--macros/latex-dev/required/amsmath/amsbsy.pdfbin174944 -> 174946 bytes
-rw-r--r--macros/latex-dev/required/amsmath/amscd.dtx2
-rw-r--r--macros/latex-dev/required/amsmath/amscd.ins4
-rw-r--r--macros/latex-dev/required/amsmath/amscd.pdfbin179945 -> 179953 bytes
-rw-r--r--macros/latex-dev/required/amsmath/amsgen.dtx2
-rw-r--r--macros/latex-dev/required/amsmath/amsgen.ins2
-rw-r--r--macros/latex-dev/required/amsmath/amsgen.pdfbin178187 -> 178185 bytes
-rw-r--r--macros/latex-dev/required/amsmath/amsldoc.pdfbin508210 -> 508225 bytes
-rw-r--r--macros/latex-dev/required/amsmath/amsldoc.tex2
-rw-r--r--macros/latex-dev/required/amsmath/amsmath.dtx9
-rw-r--r--macros/latex-dev/required/amsmath/amsmath.ins4
-rw-r--r--macros/latex-dev/required/amsmath/amsmath.pdfbin419913 -> 419994 bytes
-rw-r--r--macros/latex-dev/required/amsmath/amsopn.dtx2
-rw-r--r--macros/latex-dev/required/amsmath/amsopn.ins4
-rw-r--r--macros/latex-dev/required/amsmath/amsopn.pdfbin140095 -> 140093 bytes
-rw-r--r--macros/latex-dev/required/amsmath/amstext.dtx2
-rw-r--r--macros/latex-dev/required/amsmath/amstext.ins4
-rw-r--r--macros/latex-dev/required/amsmath/amstext.pdfbin217498 -> 217497 bytes
-rw-r--r--macros/latex-dev/required/amsmath/amsxtra.dtx2
-rw-r--r--macros/latex-dev/required/amsmath/amsxtra.ins4
-rw-r--r--macros/latex-dev/required/amsmath/amsxtra.pdfbin113561 -> 113557 bytes
-rw-r--r--macros/latex-dev/required/amsmath/changes.txt5
-rw-r--r--macros/latex-dev/required/amsmath/subeqn.pdfbin109731 -> 109734 bytes
-rw-r--r--macros/latex-dev/required/amsmath/technote.pdfbin147462 -> 147458 bytes
-rw-r--r--macros/latex-dev/required/amsmath/testmath.pdfbin454511 -> 454535 bytes
-rw-r--r--macros/latex-dev/required/firstaid/changes.txt11
-rw-r--r--macros/latex-dev/required/firstaid/latex2e-first-aid-for-external-files.dtx102
-rw-r--r--macros/latex-dev/required/firstaid/latex2e-first-aid-for-external-files.pdfbin271476 -> 269095 bytes
-rw-r--r--macros/latex-dev/required/tools/README.md2
-rw-r--r--macros/latex-dev/required/tools/afterpage.dtx2
-rw-r--r--macros/latex-dev/required/tools/afterpage.ins4
-rw-r--r--macros/latex-dev/required/tools/afterpage.pdfbin197738 -> 197733 bytes
-rw-r--r--macros/latex-dev/required/tools/array.dtx2
-rw-r--r--macros/latex-dev/required/tools/array.pdfbin516836 -> 517094 bytes
-rw-r--r--macros/latex-dev/required/tools/bm.dtx2
-rw-r--r--macros/latex-dev/required/tools/bm.ins4
-rw-r--r--macros/latex-dev/required/tools/bm.pdfbin323432 -> 323437 bytes
-rw-r--r--macros/latex-dev/required/tools/calc.dtx2
-rw-r--r--macros/latex-dev/required/tools/calc.pdfbin370657 -> 370647 bytes
-rw-r--r--macros/latex-dev/required/tools/changes.txt19
-rw-r--r--macros/latex-dev/required/tools/dcolumn.dtx2
-rw-r--r--macros/latex-dev/required/tools/dcolumn.pdfbin220834 -> 220839 bytes
-rw-r--r--macros/latex-dev/required/tools/delarray.dtx2
-rw-r--r--macros/latex-dev/required/tools/delarray.pdfbin191064 -> 191066 bytes
-rw-r--r--macros/latex-dev/required/tools/enumerate.dtx2
-rw-r--r--macros/latex-dev/required/tools/enumerate.pdfbin215498 -> 215500 bytes
-rw-r--r--macros/latex-dev/required/tools/fileerr.dtx2
-rw-r--r--macros/latex-dev/required/tools/fileerr.pdfbin187725 -> 187723 bytes
-rw-r--r--macros/latex-dev/required/tools/fontsmpl.dtx2
-rw-r--r--macros/latex-dev/required/tools/fontsmpl.pdfbin146446 -> 146446 bytes
-rw-r--r--macros/latex-dev/required/tools/ftnright.dtx2
-rw-r--r--macros/latex-dev/required/tools/ftnright.pdfbin387231 -> 387234 bytes
-rw-r--r--macros/latex-dev/required/tools/hhline.dtx2
-rw-r--r--macros/latex-dev/required/tools/hhline.pdfbin189679 -> 189674 bytes
-rw-r--r--macros/latex-dev/required/tools/indentfirst.dtx2
-rw-r--r--macros/latex-dev/required/tools/indentfirst.pdfbin157954 -> 157956 bytes
-rw-r--r--macros/latex-dev/required/tools/layout.dtx2
-rw-r--r--macros/latex-dev/required/tools/layout.pdfbin259969 -> 259966 bytes
-rw-r--r--macros/latex-dev/required/tools/longtable.dtx2
-rw-r--r--macros/latex-dev/required/tools/longtable.ins4
-rw-r--r--macros/latex-dev/required/tools/longtable.pdfbin391313 -> 391316 bytes
-rw-r--r--macros/latex-dev/required/tools/multicol.dtx60
-rw-r--r--macros/latex-dev/required/tools/multicol.ins4
-rw-r--r--macros/latex-dev/required/tools/multicol.pdfbin521367 -> 523525 bytes
-rw-r--r--macros/latex-dev/required/tools/rawfonts.dtx2
-rw-r--r--macros/latex-dev/required/tools/rawfonts.pdfbin138963 -> 138962 bytes
-rw-r--r--macros/latex-dev/required/tools/shellesc.dtx11
-rw-r--r--macros/latex-dev/required/tools/shellesc.pdfbin175929 -> 176209 bytes
-rw-r--r--macros/latex-dev/required/tools/showkeys.dtx12
-rw-r--r--macros/latex-dev/required/tools/showkeys.pdfbin251782 -> 252911 bytes
-rw-r--r--macros/latex-dev/required/tools/somedefs.dtx2
-rw-r--r--macros/latex-dev/required/tools/somedefs.pdfbin167572 -> 167585 bytes
-rw-r--r--macros/latex-dev/required/tools/tabularx.dtx2
-rw-r--r--macros/latex-dev/required/tools/tabularx.ins4
-rw-r--r--macros/latex-dev/required/tools/tabularx.pdfbin287073 -> 287073 bytes
-rw-r--r--macros/latex-dev/required/tools/theorem.dtx2
-rw-r--r--macros/latex-dev/required/tools/theorem.pdfbin351702 -> 351675 bytes
-rw-r--r--macros/latex-dev/required/tools/tools-overview.pdfbin73672 -> 73672 bytes
-rw-r--r--macros/latex-dev/required/tools/tools-overview.tex2
-rw-r--r--macros/latex-dev/required/tools/tools.ins4
-rw-r--r--macros/latex-dev/required/tools/trace.dtx2
-rw-r--r--macros/latex-dev/required/tools/trace.pdfbin222076 -> 222080 bytes
-rw-r--r--macros/latex-dev/required/tools/varioref.dtx2
-rw-r--r--macros/latex-dev/required/tools/varioref.ins4
-rw-r--r--macros/latex-dev/required/tools/varioref.pdfbin398798 -> 393151 bytes
-rw-r--r--macros/latex-dev/required/tools/verbatim.dtx2
-rw-r--r--macros/latex-dev/required/tools/verbatim.pdfbin330746 -> 330773 bytes
-rw-r--r--macros/latex-dev/required/tools/xr.dtx2
-rw-r--r--macros/latex-dev/required/tools/xr.pdfbin169986 -> 169986 bytes
-rw-r--r--macros/latex-dev/required/tools/xspace.dtx2
-rw-r--r--macros/latex-dev/required/tools/xspace.pdfbin257018 -> 257019 bytes
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/README.md4
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015-preamble.tex10
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015.pdfbin1711489 -> 1722838 bytes
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015.tex403
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/chinese-jmw.bbx81
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/chinese-jmw.cbx7
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015.bbx33
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015.cbx64
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ay.bbx33
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ay.cbx119
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ms.bbx1
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015mx.bbx1
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/makeall.py4
-rw-r--r--macros/latex/contrib/listlbls/Makefile44
-rw-r--r--macros/latex/contrib/listlbls/listlbls.dtx86
-rw-r--r--macros/latex/contrib/listlbls/listlbls.pdfbin74422 -> 102919 bytes
-rw-r--r--macros/latex/contrib/nicematrix/nicematrix-code.dtx48
-rw-r--r--macros/latex/contrib/nicematrix/nicematrix-code.pdfbin909639 -> 909512 bytes
-rw-r--r--macros/latex/contrib/nicematrix/nicematrix-french.pdfbin577804 -> 575208 bytes
-rw-r--r--macros/latex/contrib/nicematrix/nicematrix-french.tex5
-rw-r--r--macros/latex/contrib/nicematrix/nicematrix.pdfbin571224 -> 592717 bytes
-rw-r--r--macros/latex/contrib/nicematrix/nicematrix.tex4
-rw-r--r--macros/latex/contrib/oststud/hsrstud-classes.pdfbin127717 -> 127670 bytes
-rw-r--r--macros/latex/contrib/oststud/hsrstud.pdfbin143177 -> 143159 bytes
-rw-r--r--macros/latex/contrib/oststud/oststud.dtx119
-rw-r--r--macros/latex/contrib/oststud/oststud.pdfbin145415 -> 159801 bytes
256 files changed, 8302 insertions, 2245 deletions
diff --git a/macros/latex-dev/base/README.md b/macros/latex-dev/base/README.md
index 49f51d34a3..494705bbab 100644
--- a/macros/latex-dev/base/README.md
+++ b/macros/latex-dev/base/README.md
@@ -1,7 +1,7 @@
The LaTeX kernel
================
-Release 2023-06-01 pre-release 2
+Release 2023-06-01 pre-release 3
Overview
--------
diff --git a/macros/latex-dev/base/alltt.pdf b/macros/latex-dev/base/alltt.pdf
index b5a773fce8..c03d479351 100644
--- a/macros/latex-dev/base/alltt.pdf
+++ b/macros/latex-dev/base/alltt.pdf
Binary files differ
diff --git a/macros/latex-dev/base/cfgguide.pdf b/macros/latex-dev/base/cfgguide.pdf
index 9199195161..8e27a300f1 100644
--- a/macros/latex-dev/base/cfgguide.pdf
+++ b/macros/latex-dev/base/cfgguide.pdf
Binary files differ
diff --git a/macros/latex-dev/base/changes.txt b/macros/latex-dev/base/changes.txt
index 218b2b9db7..790f9a5ad1 100644
--- a/macros/latex-dev/base/changes.txt
+++ b/macros/latex-dev/base/changes.txt
@@ -6,19 +6,156 @@ completeness or accuracy and it contains some references to files that
are not part of the distribution.
================================================================================
+2023-05-22 Joseph Wright <Joseph.Wright@latex-project.org>
+
+ * usrguide.tex
+ Ensure url package is always loaded
+
+2023-05-21 Phelype Oleinik <phelype.oleinik@latex-project.org>
+
+ * lthooks.dtx, ltcmdhooks.dtx:
+ Add support for accessing arguments in 'cmd' hooks.
+
+2023-05-19 Joseph Wright <Joseph.Wright@latex-project.org>
+
+ * usrguide.tex (section Creating document commands and environments)
+ Add details of result of trailing optional arguments on
+ \inputlineno
+
+2023-05-12 Ulrike Fischer <Ulrike.Fischer@latex-project.org>
+
+ * ltxref.dtx
+ extend \label to store five values and add a hook with argument
+
+2023-05-17 Joseph Wright <Joseph.Wright@latex-project.org>
+
+ * usrguide.tex (section Creating document commands and environments)
+ Add details of brace stripping by \SplitList
+ Add guidance on creating commands to use at start of
+ tabular cells
+
+2023-05-15 Joseph Wright <Joseph.Wright@latex-project.org>
+
+ * ltfiles.dtx:
+ Use expl3-based file-existence test
+
+2023-05-13 David Carlisle <David.Carlisle@latex-project.org>
+
+ * ltmath.dtx: Add \ignorespaces to \eqno (gh/1059)
+
+2023-04-19 Joseph Wright <joseph.wright@latex-project.org>
+
+ * ltfinal.dtx (subsection{Lccodes and uccodes}):
+ Add \DeclareLowercaseMapping, \DeclareTitlecaseMapping and
+ \DeclareUppercaseMapping (gh/1033)
+
+2023-04-19 Phelype Oleinik <phelype.oleinik@latex-project.org>
+
+ * lthooks.dtx (subsection{Specifying code for next invocation}):
+ Initialise hook structure when adding 'next' code (gh/1052)
+
+2023-04-17 Joseph Wright <Joseph.Wright@latex-project.org>
+
+ * ltfinal.dtx (subsubsection{Lccodes and uccodes}):
+ Add \BCPdata (gh/1035)
+ Adapt \MakeLowercase, \MakeTitlecase and \MakeLowercase
+ to use \BCPdata for locale info
+
+2023-04-16 Phelype Oleinik <phelype.oleinik@latex-project.org>
+
+ * lthooks.dtx (subsubsection{Setting hooks up}):
+ Use \@@_replacing_args_false: in \@@_include_legacy_code_chunk:n.
+
+2023-04-15 David Carlisle <David.Carlisle@latex-project.org>
+
+ * ltplain.dtx: adjust \extrafloats so it does not error if thousands
+ of float boxes are allocated. github/1041
+
+2023-04-14 Phelype Oleinik <phelype.oleinik@latex-project.org>
+
+ * ltclass.dtx (\@onefilewithoptions):
+ When in latexrelease.sty, define \load@onefilewithoptions (gh/992).
+
+2023-04-13 David Carlisle <David.Carlisle@latex-project.org>
+
+ * cmfonts.fdd: add missing substitution for U/cmtt/bx/sl gh/1037
+
+2023-04-12 Phelype Oleinik <phelype.oleinik@latex-project.org>
+
+ * ltcmd.dtx (subsection{Grabbing arguments}):
+ Set \tex_endlinechar:D earlier to correct parsing of newlines in
+ special catcode settings (e.g., \ExplSyntaxOn) (gh/876).
+
+2023-04-02 David Carlisle <David.Carlisle@latex-project.org>
+
+ * ltfilehook.dtx: allow par as a filename. (gh/942)
+
+2023-04-06 Phelype Oleinik <phelype.oleinik@latex-project.org>
+
+ * lthooks.dtx, ltcmdhooks.dtx:
+ Add support for providing and using arguments in hooks:
+ - Modify hook data structures to allow access to arguments;
+ - Add commands to declare hooks with arguments;
+ - Add commands to add code that references hook arguments;
+ - Add commands to use hooks with arguments.
+
+2023-04-01 David Carlisle <David.Carlisle@latex-project.org>
+
+ * ltfssbas.dtx: locally reset frozen mathversions when the math
+ version changes. (gh/1028)
+
+2023-03-28 Joseph Wright <Joseph.Wright@latex-project.org>
+
+ * ltclass.dtx:
+ Add \IfFileAtLeastTF (gh/1015)
+
+2023-03-28 Frank Mittelbach <Frank.Mittelbach@latex-project.org>
+
+ * ltxdoc.dtx (section{Options}):
+ Define \cs if doc is rolled back to v2 (gh/981)
+
+2023-03-28 David Carlisle <David.Carlisle@latex-project.org>
+
+ * ltfinal.dtx: Restore groups to \MakeUppercase and
+ \MakeLowercase, and add a group to \MakeTitlecase. (gh/1021)
+
+2023-03-22 Frank Mittelbach <Frank.Mittelbach@latex-project.org>
+
+ * ltspace.dtx:
+ Add \predisplaypenalty setting of 10000 to \samepage in case
+ that was changed (gh/1022)
+
+2023-03-11 Yukai Chou <muzimuzhi@gmail.com>
+
+ * ltcmd.dtx (subsubsection{Showing the definition of a command}),
+ (subsubsection{Copying a command and its internal structure}):
+ Correctly recognize (non-expandable) document commands with empty or only
+ m-type arguments (gh/1009)
+
2023-01-30 Frank Mittelbach <Frank.Mittelbach@latex-project.org>
* ltpara.dtx (subsection{Providing hooks for paragraphs}):
Backout \parskip at top of minipage if it shouldn't be there
but is due to whatsits (gh/989)
+2023-02-05 Yukai Chou <muzimuzhi@gmail.com>
+
+ * fntguide.tex:
+ Adjusted pagination due to recently added doc paragraphs (gh/994)
+
2023-01-16 Yukai Chou <muzimuzhi@gmail.com>
* ltnews.cls:
- Added full release date yyyy-mm-dd to _all_ ltnews issues.
+ Added full release date yyyy-mm-dd to _all_ ltnews issues (gh/982)
Added \publicationday{<day>} to specify day in a month in ltnews<n>.tex.
<day> defaults to 01.
+2023-01-12 Joseph Joseph <Joseph.Joseph@latex-project.org>
+
+ * clsguide.tex, clsguide-historic,tex
+ Pre-2023 source moved to new name, re-worked material which remains
+ relevant in updated file
+
================================================================================
All changes above are only part of the development branch for the next release.
================================================================================
diff --git a/macros/latex-dev/base/classes.dtx b/macros/latex-dev/base/classes.dtx
index e16dc657a1..58690e8375 100644
--- a/macros/latex-dev/base/classes.dtx
+++ b/macros/latex-dev/base/classes.dtx
@@ -53,7 +53,7 @@
%<*driver>
\ProvidesFile{classes.drv}
%</driver>
- [2022/07/02 v1.4n
+ [2023/05/17 v1.4n
%<article|report|book> Standard LaTeX document class]
%<10pt|11pt|12pt> Standard LaTeX file (size option)]
% \end{macrocode}
@@ -3688,9 +3688,8 @@
%
% A |\caption| command in a `figure' environment writes
%
-% |\contentsline{figure}{\numberline{|\meta{num}|}{|%
+% |\contentsline{figure}{\numberline{|\meta{num}|}{|^^A
% \meta{caption}|}}{|\meta{page}|}|
-%
% on the .\file{lof} file, where \meta{num} is the number produced
% by |\thefigure| and \meta{caption} is the figure caption. It
% works similarly for a `table' environment.
@@ -3707,8 +3706,8 @@
% \meta{title}|}{|\meta{page}|}|
%
% \begin{description}
-% \item[\meta{level}] An entry is produced only if\meta{ level}
-% $<=$ value of the \Lcount{tocdepth} counter. Note,
+% \item[\meta{level}] An entry is produced only if \meta{level}
+% $\leq$ value of the \Lcount{tocdepth} counter. Note,
% |\chapter| is level 0, |\section| is level 1, etc.
% \item[\meta{indent}] The indentation from the outer left margin
% of the start of the contents line.
diff --git a/macros/latex-dev/base/classes.pdf b/macros/latex-dev/base/classes.pdf
index 39f29d0e8b..ef4ed23c75 100644
--- a/macros/latex-dev/base/classes.pdf
+++ b/macros/latex-dev/base/classes.pdf
Binary files differ
diff --git a/macros/latex-dev/base/clsguide-historic.pdf b/macros/latex-dev/base/clsguide-historic.pdf
new file mode 100644
index 0000000000..196a93f86e
--- /dev/null
+++ b/macros/latex-dev/base/clsguide-historic.pdf
Binary files differ
diff --git a/macros/latex-dev/base/clsguide-historic.tex b/macros/latex-dev/base/clsguide-historic.tex
new file mode 100644
index 0000000000..d7a27e3c40
--- /dev/null
+++ b/macros/latex-dev/base/clsguide-historic.tex
@@ -0,0 +1,1881 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 1993-2023
+% The LaTeX Project and any individual authors listed elsewhere
+% in this file.
+%
+% This file is part of the LaTeX base system.
+% -------------------------------------------
+%
+% 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: clsguide-historic.tex
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+
+\documentclass{ltxguide}[1995/11/28]
+
+\title{\LaTeXe~for class and package writers --- historic version}
+
+\author{Copyright \copyright~1995--2006 The \LaTeX\ Project\\
+ All rights reserved.%
+ \footnote{This file 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. See the source
+ \texttt{clsguide.tex} for full details.}%
+}
+
+\date{11 January 2023}
+
+\begin{document}
+
+\maketitle
+
+\tableofcontents
+
+\section{Introduction}
+
+This document is an introduction to writing classes and packages for
+\LaTeX{}, with special attention given to upgrading existing
+\LaTeX~2.09 packages to \LaTeXe{}. The latter subject is also
+covered in an article by Johannes Braams published in TUGboat~15.3.
+
+It is somewhat of an historical document now, since \LaTeXe{} came into
+existence in 1994.
+
+\subsection{Writing classes and packages for \LaTeXe}
+
+\LaTeX{} is a document preparation system that enables the document
+writer to concentrate on the contents of their text, without bothering
+too much about the formatting of it. For example, chapters are
+indicated by |\chapter{<title>}| rather than by selecting 18pt bold.
+
+The file that contains the information about how to turn logical
+structure (like `|\chapter|') into formatting (like `18pt bold ragged
+right') is a \emph{document class}. In addition, some features (such
+as colour or included graphics) are independent of the document class
+and these are contained in \emph{packages}.
+
+One of the largest differences between \LaTeX~2.09 and \LaTeXe{} is in
+the commands used to write packages and classes. In \LaTeX~2.09,
+there was very little support for writing |.sty| files, and so writers
+had to resort to using low-level commands.
+
+\LaTeXe{} provides high-level commands for structuring packages.
+It is also much easier to build classes and packages on top of each
+other, for example writing a local technical report class |cetechr|
+(for the Chemical Engineering department) based on |article|.
+
+\subsection{Overview}
+
+This document contains an overview of how to write classes and
+packages for \LaTeX{}. It does \emph{not} introduce all of the
+commands necessary to write packages: these can be found in either
+\emph{\LaTeXbook} or \emph{\LaTeXcomp}. But it does describe the new
+commands for structuring classes and packages.
+
+\begin{description}
+
+\item[Section~\ref{Sec:general}] contains some general advice about
+ writing classes and packages. It describes the difference between
+ classes and packages, the command naming conventions, the use of
+ |doc| and |docstrip|, how \TeX's primitive file and box commands
+ interact with \LaTeX{}. It also contains some hints about general
+ \LaTeX{} style.
+
+\item[Section~\ref{Sec:structure}] describes the structure of classes
+ and packages. This includes building classes and packages on top of
+ other classes and packages, declaring options and declaring
+ commands. It also contains example classes.
+
+\item[Section~\ref{Sec:commands}] lists the new class and package
+ commands.
+
+ \item[Section~\ref{Sec:upgrade}] gives detailed advice on how to
+ upgrade existing \LaTeX~2.09 classes and packages to \LaTeXe{}.
+
+\end{description}
+
+\subsection{Further information}
+
+For a general introduction to \LaTeX{}, including the new features of
+\LaTeXe{}, you should read \emph{\LaTeXbook}
+by Leslie Lamport~\cite{A-W:LLa94}.
+
+A more detailed description of the new features of \LaTeX, including an
+overview of more than 200 packages and nearly 1000 ready to run examples, is
+to be found in \emph{\LaTeXcomp\ second edition} by Frank Mittelbach and
+Michel Goossens~\cite{A-W:MG2004}.
+
+The \LaTeX{} system is based on \TeX{}, which is
+described in \emph{The \TeX book} by Donald E.~Knuth~\cite{A-W:DEK91}.
+
+There are a number of documentation files which accompany every copy
+of \LaTeX{}. A copy of \emph{\LaTeX{} News} will come out with each
+six-monthly release of \LaTeX{}, and is found in the files
+|ltnews*.tex|. The author's guide \emph{\usrguide} describes the new
+\LaTeX{} document features; it is in |usrguide.tex|. The guide
+\emph{\fntguide} describes the \LaTeX{} font selection scheme for
+class- and package-writers; it is in |fntguide.tex|. Configuring
+\LaTeX{} is covered by the guide \emph{\cfgguide} in
+\texttt{cfgguide.tex} whilst the philosophy behind our policy on
+modifying \LaTeX{} is described in \emph{\modguide} in
+\texttt{modguide.tex}.
+
+The documented source code (from the files used to produce the kernel
+format via |latex.ltx|) is now available as
+\emph{The \LaTeXe\ Sources}.
+This very large document also includes an index of
+\LaTeX{} commands. It can be typeset from the \LaTeX{} file
+|source2e.tex| in the |base| directory, using the source files and
+the class file |ltxdoc.cls| from this directory.
+
+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}
+\end{quote}
+
+
+\subsection{Policy on standard classes}
+
+Many of the problem reports we receive concerning the standard classes
+are not concerned with bugs but are suggesting, more or less politely,
+that the design decisions embodied in them are `not optimal' and
+asking us to modify them.
+
+There are several reasons why we should not make such changes to these
+files.
+\begin{itemize}
+\item
+ However misguided, the current behaviour is clearly what was
+ intended when these classes were designed.
+\item
+ It is not good practice to change such aspects of `standard classes'
+ because many people will be relying on them.
+\end{itemize}
+
+We have therefore decided not to even consider making such
+modifications, nor to spend time justifying that decision. This does
+not mean that we do not agree that there are many deficiencies in the
+design of these classes, but we have many tasks with higher priority
+than continually explaining why the standard classes for \LaTeX{}
+cannot be changed.
+
+We would, of course, welcome the production of better classes, or of
+packages that can be used to enhance these classes. So your first
+thought when you consider such a deficiency will, we hope, be ``what
+can I do to improve this?''
+
+Similar considerations apply to those parts of the kernel that are
+implementing design decisions, many of which should be left to the
+class file but are not in the current system. We realise that in such
+cases it is much more difficult for you to rectify the problem
+yourself but it is also the case that making such changes in the
+kernel would probably be a major project for us; therefore such
+enhancements will have to wait for \LaTeX3.
+
+\section{Writing classes and packages}
+\label{Sec:writing}
+
+This section covers some general points concerned with writing
+\LaTeX{} classes and packages.
+
+
+\subsection{Old versions}
+
+If you are upgrading an existing \LaTeX~2.09 style file then we
+recommend freezing the 2.09 version and no longer maintaining it.
+Experience with the various dialects of \LaTeX{} which existed in the
+early 1990's suggests that maintaining packages for different versions
+of \LaTeX{} is almost impossible. It will, of course, be necessary
+for some organisations to maintain both versions in parallel for some
+time but this is not essential for those packages and classes
+supported by individuals: they should support only the new standard
+\LaTeXe{}, not obsolete versions of \LaTeX{}.
+
+
+\subsection{Using `docstrip' and `doc'}
+
+If you are going to write a large class or package for \LaTeX{} then
+you should consider using the |doc| software which comes with
+\LaTeX{}.
+\LaTeX{} classes and packages written using this can be
+processed in two ways: they can be run through \LaTeX{}, to produce
+documentation; and they can be processed with |docstrip|, to produce
+the |.cls| or |.sty| file.
+
+The |doc| software can automatically generate indexes of definitions,
+indexes of command use, and change-log lists. It is very useful for
+maintaining and documenting large \TeX{} sources.
+
+The documented sources of the \LaTeX{} kernel itself, and of the
+standard classes, etc, are |doc| documents; they are in the |.dtx|
+files in the distribution. You can, in fact, typeset the source code
+of the kernel as one long document, complete with index, by running
+\LaTeX{} on |source2e.tex|. Typesetting these documents uses the
+class file |ltxdoc.cls|.
+
+For more information on |doc| and |docstrip|, consult the files
+|docstrip.dtx|, |doc.dtx|, and \emph{\LaTeXcomp}. For examples of its
+use, look at the |.dtx| files.
+
+\subsection{Is it a class or a package?}
+\label{Sec:classorpkg}
+
+The first thing to do when you want to put some new \LaTeX{} commands
+in a file is to decide whether it should be a \emph{document class} or a
+\emph{package}. The rule of thumb is:
+\begin{quote}
+ If the commands could be used with any document class, then make
+ them a package; and if not, then make them a class.
+\end{quote}
+
+There are two major types of class: those like |article|, |report| or
+|letter|, which are free-standing; and those which are extensions or
+variations of other classes---for example, the |proc| document class,
+which is built on the |article| document class.
+
+Thus, a company might have a local |ownlet| class for printing letters
+with their own headed note-paper. Such a class would build on top of
+the existing |letter| class but it cannot be used with any other
+document class, so we have |ownlet.cls| rather than |ownlet.sty|.
+
+The |graphics| package, in contrast, provides commands for including
+images into a \LaTeX{} document. Since these commands can be used
+with any document class, we have |graphics.sty| rather than
+|graphics.cls|.
+
+
+\subsection{Command names}
+
+\LaTeX{} has three types of command.
+
+There are the author commands, such as |\section|, |\emph| and
+|\times|: most of these have short names, all in lower case.
+
+There are also the class and package writer commands:
+most of these have long mixed-case names such as the following.
+\begin{verbatim}
+ \InputIfFileExists \RequirePackage \PassOptionsToClass
+\end{verbatim}
+
+Finally, there are the internal commands used in the \LaTeX{}
+implementation, such as |\@tempcnta|, |\@ifnextchar| and |\@eha|:
+most of these commands contain |@| in their name, which means they
+cannot be used in documents, only in class and package files.
+
+Unfortunately, for historical reasons the distinction between these
+commands is often blurred. For example, |\hbox| is an internal
+command which should only be used in the \LaTeX{} kernel, whereas
+|\m@ne| is the constant $-1$ and could have been |\MinusOne|.
+
+However, this rule of thumb is still useful: if a command has |@| in
+its name then it is not part of the supported \LaTeX{} language---and
+its behaviour may change in future releases! If a command is
+mixed-case, or is described in \emph{\LaTeXbook}, then you can rely on
+future releases of \LaTeXe{} supporting the command.
+
+\subsection{Box commands and colour}
+\label{Sec:colour}
+
+Even if you do not intend to use colour in your own documents, by
+taking note of the points in this section you can ensure that your
+class or package is compatible with the |color| package. This may
+benefit people using your class or package who have access to colour
+printers.
+
+The simplest way to ensure `colour safety' is to always use \LaTeX{}
+box commands rather than \TeX{} primitives, that is use |\sbox| rather
+than |\setbox|, |\mbox| rather than |\hbox| and |\parbox| or
+the |minipage| environment rather than |\vbox|.
+The \LaTeX{} box commands have new options which mean that they are now
+as powerful as the \TeX{} primitives.
+
+As an example of what can go wrong, consider that in
+|{\ttfamily <text>}|
+the font is restored just \emph{before} the |}|, whereas in the
+similar looking construction
+|{\color{green} <text>}|
+the colour is restored just \emph{after} the final |}|. Normally this
+distinction does not matter at all; but consider a primitive \TeX{}
+box assignment such as:
+\begin{verbatim}
+ \setbox0=\hbox{\color{green} <text>}
+\end{verbatim}
+Now the colour-restore occurs after the |}| and so is \emph{not}
+stored in the box. Exactly what bad effects this can have depends on
+how colour is implemented: it can range from getting the wrong
+colours in the rest of the document, to causing errors in the
+dvi-driver used to print the document.
+
+Also of interest is the command |\normalcolor|. This is
+normally just |\relax| (i.e., does nothing)
+but you can use it rather like |\normalfont| to
+set regions of the page such as captions or section headings to the
+`main document colour'.
+
+
+\subsection{Defining text and math characters}
+\label{Sec:chars}
+
+Because \LaTeXe{} supports different encodings, definitions of commands
+for producing symbols, accents, composite glyphs, etc.\ must be
+defined using the commands provided for this purpose and described in
+\emph{\fntguide}. This part of the system is still under development
+so such tasks should be undertaken with great caution.
+
+Also, |\DeclareRobustCommand| should be used for encoding-independent
+commands of this type.
+
+Note that it is no longer possible to refer to the math font set-up
+outside math mode: for example, neither |\textfont 1| nor
+|\scriptfont 2| are guaranteed to be defined in other modes.
+
+
+\subsection{General style}
+\label{Sec:general}
+
+The new system provides many commands designed to help you produce
+well-structured class and package files that are both robust and
+portable. This section outlines some ways to make intelligent use of
+these.
+
+\subsubsection{Loading other files}
+\label{Sec:loading}
+
+\NEWdescription{1995/12/01}
+\LaTeX{} provides these commands:
+\begin{verbatim}
+ \LoadClass \LoadClassWithOptions
+ \RequirePackage \RequirePackageWithOptions
+\end{verbatim}
+for using classes or packages inside other classes or packages. We
+recommend strongly that you use them, rather than the primitive
+|\input| command, for a number of reasons.
+
+Files loaded with |\input <filename>| will not be listed in the
+|\listfiles| list.
+
+If a package is always loaded with |\RequirePackage...| or |\usepackage|
+then, even if its loading is requested several times, it will be
+loaded only once. By contrast, if it is loaded with |\input| then it
+can be loaded more than once; such an extra loading may waste time and
+memory and it may produce strange results.
+
+If a package provides option-processing then, again, strange results
+are possible if the package is |\input| rather than loaded by means of
+|\usepackage| or |\RequirePackage...|.
+
+If the package |foo.sty| loads the package |baz.sty| by use of
+|\input baz.sty| then the user will get a warning:
+\begin{verbatim}
+ LaTeX Warning: You have requested package `foo',
+ but the package provides `baz'.
+\end{verbatim}
+Thus, for several reasons, using |\input| to load packages is not a
+good idea.
+
+Unfortunately, if you are upgrading the file |myclass.sty| to a class
+file then you have to make sure that any old files which contain
+|\input myclass.sty| still work.
+
+This was also true for the standard classes (|article|, |book| and
+|report|), since a lot of existing \LaTeX~2.09 document styles contain
+|\input article.sty|. The approach which we use to solve this is
+to provide minimal files |article.sty|, |book.sty| and |report.sty|,
+which simply load the appropriate class files.
+
+For example, |article.sty| contains just the following lines:
+\begin{verbatim}
+ \NeedsTeXFormat{LaTeX2e}
+ \@obsoletefile{article.cls}{article.sty}
+ \LoadClass{article}
+\end{verbatim}
+You may wish to do the same or, if you think that it is safe to do so,
+you may decide to just remove |myclass.sty|.
+
+\subsubsection{Make it robust}
+
+We consider it good practice, when writing packages and classes, to use
+\LaTeX{} commands as much as possible.
+
+Thus, instead of using |\def...| we recommend using one of
+|\newcommand|, |\renewcommand| or |\providecommand|; |\CheckCommand| is
+also useful. Doing this makes
+it less likely that you will inadvertently redefine a command, giving
+unexpected results.
+
+When you define an environment, use |\newenvironment| or
+|\renewenvironment| instead |\def\foo{...}| and |\def\endfoo{...}|.
+
+If you need to set or change the value of a \m{dimen} or \m{skip}
+register, use |\setlength|.
+
+To manipulate boxes, use \LaTeX{} commands such as |\sbox|,
+|\mbox| and |\parbox| rather than |\setbox|, |\hbox| and |\vbox|.
+
+Use |\PackageError|, |\PackageWarning| or |\PackageInfo| (or the
+equivalent class commands) rather than |\@latexerr|, |\@warning| or
+|\wlog|.
+
+It is still possible to declare options by defining |\ds@<option>| and
+calling |\@options|; but we recommend the |\DeclareOption| and
+|\ProcessOptions| commands instead. These are more powerful and use
+less memory. So rather than using:
+\begin{verbatim}
+ \def\ds@draft{\overfullrule 5pt}
+ \@options
+\end{verbatim}
+you should use:
+\begin{verbatim}
+ \DeclareOption{draft}{\setlength{\overfullrule}{5pt}}
+ \ProcessOptions\relax
+\end{verbatim}
+
+The advantage of this kind of practice is that your code is more
+readable and, more important, that it is less likely to break when
+used with future versions of \LaTeX{}.
+
+\subsubsection{Make it portable}
+
+It is also sensible to make your files are as portable as possible. To
+ensure this; they should contain only visible 7-bit text; and the
+filenames should contain at most eight characters (plus the three
+letter extension). Also, of course, it \textbf{must not} have the
+same name as a file in the standard \LaTeX{} distribution, however
+similar its contents may be to one of these files.
+
+It is also useful if local classes or packages have a common prefix,
+for example the University of Nowhere classes might begin with |unw|.
+This helps to avoid every University having its own thesis class, all
+called |thesis.cls|.
+
+If you rely on some features of the \LaTeX{} kernel, or on a package,
+please specify the release-date you need. For example, the package
+error commands were introduced in the June 1994 release so, if you use
+them then you should put:
+\begin{verbatim}
+ \NeedsTeXFormat{LaTeX2e}[1994/06/01]
+\end{verbatim}
+
+\subsubsection{Useful hooks}
+
+Some packages and document styles had to redefine the command
+|\document| or |\enddocument| to achieve their goal. This is no
+longer necessary. You can now use the `hooks' |\AtBeginDocument| and
+|\AtEndDocument| (see Section~\ref{Sec:delays}). Again, using these
+hooks makes it less likely that your code breaks with future versions
+of \LaTeX{}. It also makes it more likely that your package can work
+together with someone else's.
+
+\NEWdescription{1996/12/01}
+However, note that code in the |\AtBeginDocument| hook is part of the
+preamble. Thus there are restrictions on what can be put there; in
+particular, no typesetting can be done.
+
+\section{The structure of a class or package}
+\label{Sec:structure}
+
+\LaTeXe{} classes and packages have more structure than \LaTeX~2.09
+style files did. The outline of a class or package file is:
+\begin{description}
+\item[Identification] The file says that it is a \LaTeXe{} package or
+ class, and gives a short description of itself.
+\item[Preliminary declarations]
+ Here the file declares some commands and can also load
+ other files. Usually these commands will be just those needed for
+ the code used in the declared options.
+\item[Options] The file declares and processes its options.
+\item[More declarations] This is where the file does most of its work:
+ declaring new variables, commands and fonts; and loading other files.
+\end{description}
+
+\subsection{Identification}
+
+The first thing a class or package file does is identify itself.
+Package files do this as follows:
+\begin{verbatim}
+ \NeedsTeXFormat{LaTeX2e}
+ \ProvidesPackage{<package>}[<date> <other information>]
+\end{verbatim}
+For example:
+\begin{verbatim}
+ \NeedsTeXFormat{LaTeX2e}
+ \ProvidesPackage{latexsym}[1994/06/01 Standard LaTeX package]
+\end{verbatim}
+Class files do this as follows:
+\begin{verbatim}
+ \NeedsTeXFormat{LaTeX2e}
+ \ProvidesClass{<class-name>}[<date> <other information>]
+\end{verbatim}
+For example:
+\begin{verbatim}
+ \NeedsTeXFormat{LaTeX2e}
+ \ProvidesClass{article}[1994/06/01 Standard LaTeX class]
+\end{verbatim}
+\NEWdescription{1998/06/19}
+The \m{date} should be given in the form `\textsc{yyyy/mm/dd}' and
+must be present if the optional argument is used (this is also true
+for the |\NeedsTeXFormat| command).
+Any derivation from this syntax will result in low-level \TeX{}
+errors---the commands expect a valid syntax to speed up the daily
+usage of the package or class and make no provision for the case that
+the developer made a mistake!
+
+This date is checked whenever a user specifies a date in their
+|\documentclass| or |\usepackage| command. For example, if you wrote:
+\begin{verbatim}
+ \documentclass{article}[1995/12/23]
+\end{verbatim}
+then users at a different location
+would get a warning that their copy of |article| was out of
+date.
+
+The description of a class is displayed when the class is used. The
+description of a package is put into the log file. These descriptions
+are also displayed by the |\listfiles| command. The phrase
+\texttt{Standard LaTeX} \textbf{must not} be used in the identification
+banner of any file other than those in the standard \LaTeX{}
+distribution.
+
+
+\subsection{Using classes and packages}
+
+The first major difference between \LaTeX~2.09 style files and
+\LaTeXe{} packages and classes is that \LaTeXe{} supports
+\emph{modularity}, in the sense of building files from small
+building-blocks rather than using large single files.
+
+A \LaTeX{} package or class can load a package as follows:
+\begin{verbatim}
+ \RequirePackage[<options>]{<package>}[<date>]
+\end{verbatim}
+For example:
+\begin{verbatim}
+ \RequirePackage{ifthen}[1994/06/01]
+\end{verbatim}
+This command has the same syntax as the author command |\usepackage|.
+It allows packages or classes to use features provided by other
+packages. For example, by loading the |ifthen| package, a package
+writer can use the `if\dots then\dots else\dots' commands provided
+by that package.
+
+A \LaTeX{} class can load one other class as follows:
+\begin{verbatim}
+ \LoadClass[<options>]{<class-name>}[<date>]
+\end{verbatim}
+For example:
+\begin{verbatim}
+ \LoadClass[twocolumn]{article}
+\end{verbatim}
+This command has the same syntax as the author command |\documentclass|.
+It allows classes to be based on the syntax and appearance of another
+class. For example, by loading the |article| class, a class writer
+only has to change the bits of |article| they don't like, rather than
+writing a new class from scratch.
+
+\NEWfeature{1995/12/01}
+The following commands can be used in the common case that you want to
+simply load a class or package file with exactly those options that
+are being used by the current class.
+\begin{verbatim}
+ \LoadClassWithOptions{<class-name>}[<date>]
+ \RequirePackageWithOptions{<package>}[<date>]
+\end{verbatim}
+For example:
+\begin{verbatim}
+ \LoadClassWithOptions{article}
+ \RequirePackageWithOptions{graphics}[1995/12/01]
+\end{verbatim}
+
+\subsection{Declaring options}
+
+\NEWdescription{1998/12/01}
+The other major difference between \LaTeX~2.09 styles and \LaTeXe{}
+packages and classes is in option handling. Packages and classes can
+now declare options and these can be specified by authors; for
+example, the |twocolumn| option is declared by the |article| class.
+Note that the name of an option should contain only those characters
+allowed in a `\LaTeX{} name'; in particular it must not contain any
+control sequences.
+
+An option is declared as follows:
+\begin{verbatim}
+ \DeclareOption{<option>}{<code>}
+\end{verbatim}
+For example, the |dvips| option (slightly simplified)
+to the |graphics| package is implemented as:
+\begin{verbatim}
+ \DeclareOption{dvips}{\input{dvips.def}}
+\end{verbatim}
+This means that when an author writes |\usepackage[dvips]{graphics}|,
+the file |dvips.def| is loaded. As another example, the |a4paper|
+option is declared in the |article| class to set the |\paperheight|
+and |\paperwidth| lengths:
+\begin{verbatim}
+ \DeclareOption{a4paper}{%
+ \setlength{\paperheight}{297mm}%
+ \setlength{\paperwidth}{210mm}%
+ }
+\end{verbatim}
+Sometimes a user will request an option which the class
+or package has not explicitly declared. By default this will produce
+a warning (for classes) or error (for packages); this behaviour
+can be altered as follows:
+\begin{verbatim}
+ \DeclareOption*{<code>}
+\end{verbatim}
+For example, to make the package |fred| produce a warning rather than
+an error for unknown options, you could specify:
+\begin{verbatim}
+ \DeclareOption*{%
+ \PackageWarning{fred}{Unknown option `\CurrentOption'}%
+ }
+\end{verbatim}
+Then, if an author writes |\usepackage[foo]{fred}|, they will get a
+warning \texttt{Package fred Warning: Unknown option `foo'.} As
+another example, the |fontenc| package tries to load a file
+|<ENC>enc.def| whenever the \m{ENC} option is used. This
+can be done by writing:
+\begin{verbatim}
+ \DeclareOption*{%
+ \input{\CurrentOption enc.def}%
+ }
+\end{verbatim}
+\NEWdescription{1998/12/01}
+It is possible to pass options on to another package or class, using
+the command |\PassOptionsToPackage| or |\PassOptionsToClass| (note
+that this is a specialised operation that works only for option
+names). For example, to pass every unknown option on to the |article|
+class, you can use:
+\begin{verbatim}
+ \DeclareOption*{%
+ \PassOptionsToClass{\CurrentOption}{article}%
+ }
+\end{verbatim}
+If you do this then you should make sure you load the class at some
+later point, otherwise the options will never be processed!
+
+So far, we have explained only how to declare options, not how to
+execute them. To process the options with which the file was called,
+you should use:
+\begin{verbatim}
+ \ProcessOptions\relax
+\end{verbatim}
+This executes the \m{code} for each option that was both specified and
+declared (see Section~\ref{Sec:commands.options} for details of how
+this is done).
+
+For example, if the |jane| package file contains:
+\begin{verbatim}
+ \DeclareOption{foo}{\typeout{Saw foo.}}
+ \DeclareOption{baz}{\typeout{Saw baz.}}
+ \DeclareOption*{\typeout{What's \CurrentOption?}}
+ \ProcessOptions\relax
+\end{verbatim}
+and an author writes |\usepackage[foo,bar]{jane}|, then they will see
+the messages \texttt{Saw foo.} and \texttt{What's bar?}
+
+\subsection{A minimal class file}
+
+Most of the work of a class or package is in defining new commands, or
+changing the appearance of documents. This is done in the body of the
+package, using commands such as |\newcommand| or |\setlength|.
+
+\LaTeXe{} provides several new commands to help class and package
+writers; these are described in detail in Section~\ref{Sec:commands}.
+
+There are four things that every class file \emph{must} contain: these
+are a definition of |\normalsize|, values for |\textwidth| and
+|\textheight| and a specification for page-numbering. So a minimal
+document class file\footnote {This class is now in the standard
+distribution, as \texttt{minimal.cls}.} looks like this:
+\begin{verbatim}
+ \NeedsTeXFormat{LaTeX2e}
+ \ProvidesClass{minimal}[1995/10/30 Standard LaTeX minimal class]
+ \renewcommand{\normalsize}{\fontsize{10pt}{12pt}\selectfont}
+ \setlength{\textwidth}{6.5in}
+ \setlength{\textheight}{8in}
+ \pagenumbering{arabic} % needed even though this class will
+ % not show page numbers
+\end{verbatim}
+However, this class file will not support footnotes, marginals,
+floats, etc., nor will it provide any of the 2-letter font commands
+such as |\rm|; thus most classes will contain more than this minimum!
+
+\subsection{Example: a local letter class}
+
+A company may have its own letter class, for setting letters in the
+company style. This section shows a simple implementation of such a
+class, although a real class would need more structure.
+
+The class begins by announcing itself as |neplet.cls|.
+\begin{verbatim}
+ \NeedsTeXFormat{LaTeX2e}
+ \ProvidesClass{neplet}[1995/04/01 NonExistent Press letter class]
+\end{verbatim}
+Then this next bit passes any options on to the |letter| class, which
+is loaded with the |a4paper| option.
+\begin{verbatim}
+ \DeclareOption*{\PassOptionsToClass{\CurrentOption}{letter}}
+ \ProcessOptions\relax
+ \LoadClass[a4paper]{letter}
+\end{verbatim}
+In order to use the company letter head, it redefines the
+|firstpage| page style: this is the page style that is used on
+the first page of letters.
+\begin{verbatim}
+ \renewcommand{\ps@firstpage}{%
+ \renewcommand{\@oddhead}{<letterhead goes here>}%
+ \renewcommand{\@oddfoot}{<letterfoot goes here>}%
+ }
+\end{verbatim}
+And that's it!
+
+\subsection{Example: a newsletter class}
+
+A simple newsletter can be typeset with \LaTeX{}, using a variant of the
+|article| class.
+The class begins by announcing itself as |smplnews.cls|.
+\begin{verbatim}
+ \NeedsTeXFormat{LaTeX2e}
+ \ProvidesClass{smplnews}[1995/04/01 The Simple News newsletter class]
+
+ \newcommand{\headlinecolor}{\normalcolor}
+\end{verbatim}
+It passes most specified options on to the |article| class: apart from
+the |onecolumn| option, which is switched off, and the |green| option,
+which sets the headline in green.
+\begin{verbatim}
+ \DeclareOption{onecolumn}{\OptionNotUsed}
+ \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}}
+
+ \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
+
+ \ProcessOptions\relax
+\end{verbatim}
+It then loads the class |article| with the option |twocolumn|.
+\begin{verbatim}
+ \LoadClass[twocolumn]{article}
+\end{verbatim}
+Since the newsletter is to be printed in colour, it now loads the
+|color| package. The class does not specify a device driver option
+since this should be specified by the user of the |smplnews| class.
+\begin{verbatim}
+ \RequirePackage{color}
+\end{verbatim}
+The class then redefines |\maketitle| to produce the title in 72pt
+Helvetica bold oblique, in the appropriate colour.
+\begin{verbatim}
+ \renewcommand{\maketitle}{%
+ \twocolumn[%
+ \fontsize{72}{80}\fontfamily{phv}\fontseries{b}%
+ \fontshape{sl}\selectfont\headlinecolor
+ \@title
+ ]%
+ }
+\end{verbatim}
+It redefines |\section| and switches off section numbering.
+\begin{verbatim}
+ \renewcommand{\section}{%
+ \@startsection
+ {section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}%
+ {1ex plus .2ex}{\large\sffamily\slshape\headlinecolor}%
+ }
+
+ \setcounter{secnumdepth}{0}
+\end{verbatim}
+It also sets the three essential things.
+\begin{verbatim}
+ \renewcommand{\normalsize}{\fontsize{9}{10}\selectfont}
+ \setlength{\textwidth}{17.5cm}
+ \setlength{\textheight}{25cm}
+\end{verbatim}
+In practice, a class would need more than this: it would provide
+commands for issue numbers, authors of articles, page styles and so
+on; but this skeleton gives a start. The |ltnews| class file is not
+much more complex than this one.
+
+\section{Commands for class and package writers}
+\label{Sec:commands}
+
+This section describes briefly each of the new commands for class and
+package writers. To find out about other aspects of the new system,
+you should also read \emph{\LaTeXbook}, \emph{\LaTeXcomp} and
+\emph{\usrguide}.
+
+\subsection{Identification}
+
+The first group of commands discussed here are those used
+to identify your class or package file.
+
+\begin{decl}
+|\NeedsTeXFormat| \arg{format-name} \oarg{release-date}
+\end{decl}
+This command tells \TeX{} that this file should be processed using a
+format with name \m{format-name}. You can use the optional argument
+\m{release-date} to further specify the earliest release date of the
+format that is needed. When the release date of the format is older
+than the one specified a warning will be generated. The standard
+\m{format-name} is \texttt{LaTeX2e}. The date, if present, must be in
+the form \textsc{yyyy/mm/dd}.
+
+Example:
+\begin{verbatim}
+ \NeedsTeXFormat{LaTeX2e}[1994/06/01]
+\end{verbatim}
+
+\begin{decl}
+|\ProvidesClass| \arg{class-name} \oarg{release-info} \\
+|\ProvidesPackage| \arg{package-name} \oarg{release-info}
+\end{decl}
+This declares that the current file contains the definitions for the
+document class \m{class-name} or package \m{package-name}.
+
+The optional \m{release-info}, if used, must contain:
+\begin{itemize}
+ \item the release date of
+ this version of the file, in the form \textsc{yyyy/mm/dd};
+\item optionally followed by a space and a short description, possibly
+ including a version number.
+\end{itemize}
+The above syntax must be followed exactly so that this information
+can be used by |\LoadClass| or |\documentclass| (for classes) or
+|\RequirePackage| or |\usepackage| (for packages) to test that the
+release is not too old.
+
+The whole of this \m{release-info} information is displayed by
+|\listfiles| and should therefore not be too long.
+
+Example:
+\begin{verbatim}
+ \ProvidesClass{article}[1994/06/01 v1.0 Standard LaTeX class]
+ \ProvidesPackage{ifthen}[1994/06/01 v1.0 Standard LaTeX package]
+\end{verbatim}
+
+\begin{decl}
+ |\ProvidesFile| \arg{file-name} \oarg{release-info}
+\end{decl}
+This is similar to the two previous commands except that here the full
+filename, including the extension, must be given. It is used for
+declaring any files other than main class and package files.
+
+Example:
+\begin{verbatim}
+ \ProvidesFile{T1enc.def}[1994/06/01 v1.0 Standard LaTeX file]
+\end{verbatim}
+
+Note that the phrase \texttt{Standard LaTeX} \textbf{must not} be used
+in the identification banner of any file other than those in the
+standard \LaTeX{} distribution.
+
+\subsection{Loading files}
+\label{Sec:loadf}
+
+\NEWfeature{1995/12/01}
+This group of commands can be used to create your own document class or
+package by building on existing classes or packages.
+\begin{decl}
+ |\RequirePackage| \oarg{options-list} \arg{package-name}
+ \oarg{release-info}\\
+ |\RequirePackageWithOptions| \arg{package-name}
+ \oarg{release-info}
+\end{decl}
+Packages and classes should use these commands to load other packages.
+
+The use of |\RequirePackage| is the same as the author command
+|\usepackage|.
+
+Examples:
+\begin{verbatim}
+ \RequirePackage{ifthen}[1994/06/01]
+ \RequirePackageWithOptions{graphics}[1995/12/01]
+\end{verbatim}
+
+\begin{decl}
+ |\LoadClass| \oarg{options-list} \arg{class-name}
+ \oarg{release-info}\\
+ |\LoadClassWithOptions| \arg{class-name}
+ \oarg{release-info}
+\end{decl}
+\NEWfeature{1995/12/01}
+These commands are for use \emph{only} in class files, they cannot be
+used in packages files;
+they can be used at most once within a class file.
+
+The use of |\LoadClass| is the same as
+the use of |\documentclass| to load a class file.
+
+Examples:
+\begin{verbatim}
+ \LoadClass{article}[1994/06/01]
+ \LoadClassWithOptions{article}[1995/12/01]
+\end{verbatim}
+
+\NEWfeature{1995/12/01}
+The two |WithOptions| versions simply load the class (or package) file
+with exactly those options that are being used by the current file
+(class or package). See below, in \ref{Sec:opmove}, for further
+discussion of their use.
+
+
+\subsection{Option declaration}
+\label{Sec:commands.options.dec}
+
+\NEWdescription{1998/12/01}
+The following commands deal with the declaration and handling of
+options to document classes and packages. Every option name must be a
+`\LaTeX{} name'.
+
+There are some commands designed especially for use within the
+\m{code} argument of these commands (see below).
+
+\begin{decl}
+ |\DeclareOption| \arg{option-name} \arg{code}
+\end{decl}
+This makes \m{option-name} a `declared option' of the class or package
+in which it is put.
+
+The \m{code} argument contains the code to be executed if that option
+is specified for the class or package; it can contain any valid
+\LaTeXe{} construct.
+
+Example:
+\begin{verbatim}
+ \DeclareOption{twoside}{\@twosidetrue}
+\end{verbatim}
+
+\begin{decl}
+ |\DeclareOption*| \arg{code}
+\end{decl}
+This declares the \m{code} to be executed for every option which is
+specified for, but otherwise not explicitly declared by, the class or
+package; this code is called the `default option code' and it can
+contain any valid \LaTeXe{} construct.
+
+If a class file contains no |\DeclareOption*| then, by default, all
+specified but undeclared options for that class will be silently
+passed to all packages (as will the specified and declared options for
+that class).
+
+If a package file contains no |\DeclareOption*| then, by default, each
+specified but undeclared option for that package will produce an error.
+
+
+\subsection{Commands within option code}
+\label{Sec:within.code}
+
+These two commands can be used only within the \m{code} argument of
+either |\DeclareOption| or |\DeclareOption*|. Other commands commonly
+used within these arguments can be found in the next few subsections.
+
+\begin{decl}
+ |\CurrentOption|
+\end{decl}
+This expands to the name of the current option.
+
+\begin{decl}
+ |\OptionNotUsed|
+\end{decl}
+This causes the current option to
+be added to the list of `unused options'.
+
+\NEWfeature{1995/06/01}
+ You can now include hash marks (\texttt{\#}) within these \m{code}
+ arguments without special treatment (formerly, it had been
+ necessary to double them).
+
+\subsection{Moving options around}
+\label{Sec:opmove}
+
+These two commands are also very useful within the \m{code} argument
+of |\DeclareOption| or |\DeclareOption*|:
+\begin{decl}
+ |\PassOptionsToPackage| \arg{options-list} \arg{package-name}\\
+ |\PassOptionsToClass| \arg{options-list} \arg{class-name}
+\end{decl}
+The command |\PassOptionsToPackage| passes the option names in
+\m{options-list} to package \m{package-name}.
+This means that it adds the \m{option-list} to the
+list of options used by any future |\RequirePackage| or |\usepackage|
+command for package \m{package-name}.
+
+Example:
+\begin{verbatim}
+ \PassOptionsToPackage{foo,bar}{fred}
+ \RequirePackage[baz]{fred}
+\end{verbatim}
+is the same as:
+\begin{verbatim}
+ \RequirePackage[foo,bar,baz]{fred}
+\end{verbatim}
+
+Similarly, |\PassOptionsToClass| may be used in a class file to pass
+options to another class to be loaded with |\LoadClass|.
+
+\NEWdescription{1995/12/01}
+The effects and use of these two commands should be contrasted with
+those of the following two (documented above, in \ref{Sec:loadf}):
+\begin{verbatim}
+ \LoadClassWithOptions
+ \RequirePackageWithOptions
+\end{verbatim}
+The command |\RequirePackageWithOptions| is similar to
+|\RequirePackage|, but it always loads the required package with
+exactly the same option list as that being used by the current class
+or package, rather than with any option explicitly supplied or passed
+on by |\PassOptionsToPackage|.
+
+The main purpose of |\LoadClassWithOptions| is to allow one class to
+simply build on another, for example:
+\begin{verbatim}
+ \LoadClassWithOptions{article}
+\end{verbatim}
+This should be compared with the slightly different construction
+\begin{verbatim}
+ \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
+ \ProcessOptions\relax
+ \LoadClass{article}
+\end{verbatim}
+As used above, the effects are more or less the same, but the first is
+a lot less to type; also the |\LoadClassWithOptions| method runs
+slightly quicker.
+
+If, however, the class declares options of its own then
+the two constructions are different. Compare, for example:
+\begin{verbatim}
+ \DeclareOption{landscape}{\@landscapetrue}
+ \ProcessOptions\relax
+ \LoadClassWithOptions{article}
+\end{verbatim}
+with:
+\begin{verbatim}
+ \DeclareOption{landscape}{\@landscapetrue}
+ \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
+ \ProcessOptions\relax
+ \LoadClass{article}
+\end{verbatim}
+In the first example, the \textsf{article} class will be loaded with
+option |landscape| precisely when the current class is called with
+this option. By contrast, in the second example it will never be
+called with option \texttt{landscape} as in that case \textsf{article}
+is passed options only by the default option handler, but this handler
+is not used for |landscape| because that option is explicitly
+declared.
+
+\subsection{Delaying code}
+\label{Sec:delays}
+
+These first two commands are also intended primarily for use within
+the \m{code} argument of |\DeclareOption| or |\DeclareOption*|.
+
+\begin{decl}
+ |\AtEndOfClass| \arg{code}\\
+ |\AtEndOfPackage| \arg{code}
+\end{decl}
+These commands declare \m{code} that is saved away internally and then
+executed after processing the whole of the current class or package
+file.
+
+Repeated use of these commands is permitted: the code in the
+arguments is stored (and later executed) in the order of their
+declarations.
+
+\begin{decl}
+ |\AtBeginDocument| \arg{code}\\
+ |\AtEndDocument| \arg{code}
+\end{decl}
+These commands declare \m{code} to be saved internally and executed
+while \LaTeX{} is executing |\begin{document}| or |\end{document}|.
+
+The \m{code} specified in the argument to |\AtBeginDocument| is
+executed near the end of the |\begin{document}| code, \emph{after} the
+font selection tables have been set up. It is therefore a useful
+place to put code which needs to be executed after everything has been
+prepared for typesetting and when the normal font for the document is
+the current font.
+
+\NEWdescription{1995/12/01}
+The |\AtBeginDocument| hook should not be used for code that does any
+typesetting since the typeset result would be unpredictable.
+
+The \m{code} specified in the argument to |\AtEndDocument| is
+executed at the beginning of the |\end{document}| code,
+\emph{before} the final page is finished and before any leftover
+floating environments are processed. If some of the \m{code} is to be
+executed after these two processes, you should include a |\clearpage|
+at the appropriate point in \m{code}.
+
+Repeated use of these commands is permitted: the code in the
+arguments is stored (and later executed) in the order of their
+declarations.
+
+\begin{decl}[1994/12/01]
+ |\AtBeginDvi| \arg{specials}
+\end{decl}
+These commands save in a box register things which are written to the
+|.dvi| file at the beginning of the `shipout' of the first page of the
+document.
+
+This should not be used for anything that will add any typeset
+material to the |.dvi| file.
+
+Repeated use of this command is permitted.
+
+
+\subsection{Option processing}
+\label{Sec:commands.options}
+
+\begin{decl}
+ |\ProcessOptions|
+\end{decl}
+This command executes the \m{code} for each selected option.
+
+We shall first describe how |\ProcessOptions| works in a package file,
+and then how this differs in a class file.
+
+To understand in detail what |\ProcessOptions| does in a package file,
+you have to know the difference between \emph{local} and \emph{global}
+options.
+\begin{itemize}
+\item \textbf{Local options} are those which have been explicitly
+ specified for this particular package in the \m{options} argument of
+ any of these:
+\begin{quote}
+ |\PassOptionsToPackage{<options>}| \ |\usepackage[<options>]|\\
+ |\RequirePackage[<options>]|
+\end{quote}
+\item \textbf{Global options} are any other options that are specified
+ by the author in the \m{options} argument of
+ |\documentclass[<options>]|.
+\end{itemize}
+For example, suppose that a document begins:
+\begin{verbatim}
+ \documentclass[german,twocolumn]{article}
+ \usepackage{gerhardt}
+\end{verbatim}
+whilst package |gerhardt| calls package |fred| with:
+\begin{verbatim}
+ \PassOptionsToPackage{german,dvips,a4paper}{fred}
+ \RequirePackage[errorshow]{fred}
+\end{verbatim}
+then:
+\begin{itemize}
+\item |fred|'s local options are |german|, |dvips|, |a4paper|
+ and |errorshow|;
+\item |fred|'s only global option is |twocolumn|.
+\end{itemize}
+
+When |\ProcessOptions| is called, the following happen.
+\begin{itemize}
+\item \emph{First}, for each option so far declared in |fred.sty|
+ by |\DeclareOption|, it looks to see if that option is either a
+ global or a local option for |fred|: if it is then the corresponding
+ code is executed.
+
+ This is done in the order in which these options
+ were declared in |fred.sty|.
+\item \emph{Then}, for each remaining \emph{local} option, the command
+ |\ds@<option>| is executed if it has been defined somewhere (other
+ than by a |\DeclareOption|); otherwise, the `default option code' is
+ executed. If no default option code has been declared then an error
+ message is produced.
+
+ This is done in the order in which these
+ options were specified.
+\end{itemize}
+Throughout this process, the system ensures that the code declared for
+an option is executed at most once.
+
+Returning to the example, if |fred.sty| contains:
+\begin{verbatim}
+ \DeclareOption{dvips}{\typeout{DVIPS}}
+ \DeclareOption{german}{\typeout{GERMAN}}
+ \DeclareOption{french}{\typeout{FRENCH}}
+ \DeclareOption*{\PackageWarning{fred}{Unknown `\CurrentOption'}}
+ \ProcessOptions\relax
+\end{verbatim}
+then the result of processing this document will be:
+\begin{verbatim}
+ DVIPS
+ GERMAN
+ Package fred Warning: Unknown `a4paper'.
+ Package fred Warning: Unknown `errorshow'.
+\end{verbatim}
+Note the following:
+
+\begin{itemize}
+\item the code for the |dvips| option is executed before that for the
+ |german| option, because that is the order in which they are declared
+ in |fred.sty|;
+\item the code for the |german| option is executed only once, when the
+ declared options are being processed;
+\item the |a4paper| and |errorshow| options produce the warning from
+ the code declared by |\DeclareOption*| (in the order in which they
+ were specified), whilst the |twocolumn| option does not: this is
+ because |twocolumn| is a global option.
+\end{itemize}
+
+In a class file, |\ProcessOptions| works in the same way, except
+that: \emph{all} options are local; and the default value for
+|\DeclareOption*| is |\OptionNotUsed| rather than an error.
+
+\NEWdescription{1995/12/01}
+Note that, because |\ProcessOptions| has a |*|-form, it is wise to
+follow the non-star form with |\relax|, as in the previous examples,
+since this prevents unnecessary look ahead and possibly misleading
+error messages being issued.
+
+\begin{decl}
+ |\ProcessOptions*| \\
+ |\@options|
+\end{decl}
+This is like |\ProcessOptions| but it executes the options in the
+order specified in the calling commands, rather than in the order of
+declaration in the class or package. For a package this means that the
+global options are processed first.
+
+The |\@options| command from \LaTeX~2.09 has been made equivalent to
+this in order to ease the task of updating old document styles to
+\LaTeXe{} class files.
+
+\begin{decl}
+ |\ExecuteOptions| \arg{options-list}
+\end{decl}
+
+For each option in the \m{options-list}, in order,
+this command simply executes the command
+|\ds@<option>| (if this command is not defined, then that option is
+silently ignored).
+
+It can be used to provide a `default option list' just before
+|\ProcessOptions|. For example, suppose that in a class file you want
+to set up the default design to be: two-sided printing; 11pt fonts;
+in two columns. Then it could specify:
+\begin{verbatim}
+ \ExecuteOptions{11pt,twoside,twocolumn}
+\end{verbatim}
+
+
+\subsection{Safe file commands}
+
+These commands deal with file input; they ensure that the non-existence
+of a requested file can be handled in a user-friendly way.
+
+\begin{decl}
+|\IfFileExists| \arg{file-name} \arg{true} \arg{false}
+\end{decl}
+If the file exists then the code specified in \m{true} is
+executed.
+
+If the file does not exist then the code specified in \m{false} is
+executed.
+
+This command does \emph{not} input the file.
+
+\begin{decl}
+ |\InputIfFileExists| \arg{file-name} \arg{true} \arg{false}
+\end{decl}
+This inputs the file \m{file-name} if it exists and, immediately
+before the input, the code specified in \m{true} is executed.
+
+If the file does not exist then the code specified in \m{false} is
+executed.
+
+It is implemented using |\IfFileExists|.
+
+
+\subsection{Reporting errors, etc}
+
+These commands should be used by third party classes and packages to
+report errors, or to provide information to authors.
+
+\begin{decl}
+ |\ClassError| \arg{class-name} \arg{error-text} \arg{help-text}\\
+ |\PackageError| \arg{package-name} \arg{error-text} \arg{help-text}
+\end{decl}
+These produce an error message. The \m{error-text} is displayed and the
+|?| error prompt is shown. If the user types |h|, they will be shown
+the \m{help-text}.
+
+Within the \m{error-text} and \m{help-text}: |\protect| can be used to
+stop a command from expanding; |\MessageBreak| causes a line-break;
+and |\space| prints a space.
+
+Note that the \m{error-text} will have a full stop added to it, so do
+not put one into the argument.
+
+For example:
+\begin{verbatim}
+ \newcommand{\foo}{FOO}
+ \PackageError{ethel}{%
+ Your hovercraft is full of eels,\MessageBreak
+ and \protect\foo\space is \foo
+ }{%
+ Oh dear! Something's gone wrong.\MessageBreak
+ \space \space Try typing \space <<return>>
+ \space to proceed, ignoring \protect\foo.
+ }
+\end{verbatim}
+produces this display:
+\begin{verbatim}
+ ! Package ethel Error: Your hovercraft is full of eels,
+ (ethel) and \foo is FOO.
+
+ See the ethel package documentation for explanation.
+\end{verbatim}
+If the user types |h|, this will be shown:
+\begin{verbatim}
+ Oh dear! Something's gone wrong.
+ Try typing <<return>> to proceed, ignoring \foo.
+\end{verbatim}
+
+\begin{decl}
+ |\ClassWarning| \arg{class-name} \arg{warning-text}\\
+ |\PackageWarning| \arg{package-name} \arg{warning-text}\\
+ |\ClassWarningNoLine| \arg{class-name} \arg{warning-text}\\
+ |\PackageWarningNoLine| \arg{package-name} \arg{warning-text}\\
+ |\ClassInfo| \arg{class-name} \arg{info-text}\\
+ |\PackageInfo| \arg{package-name} \arg{info-text}
+\end{decl}
+The four |Warning| commands are similar to the error commands, except
+that they produce only a warning on the screen, with no error prompt.
+
+The first two, |Warning| versions, also show the line number where the
+warning occurred, whilst the second two, |WarningNoLine| versions, do
+not.
+
+The two |Info| commands are similar except that they log the
+information only in the transcript file, including the line number.
+There are no |NoLine| versions of these two.
+
+Within the \m{warning-text} and \m{info-text}: |\protect| can be used to
+stop a command from expanding; |\MessageBreak| causes a line-break;
+and |\space| prints a space.
+Also, these should not end with a full stop as one is
+automatically added.
+
+
+\subsection{Defining commands}
+\label{Sec:commands.define}
+
+\LaTeXe{} provides some extra methods of (re)defining commands that are
+intended for use in class and package files.
+
+\NEWfeature{1994/12/01}
+The \texttt{*}-forms of these commands should be used to define
+commands that are not, in \TeX{} terms, long. This can be useful for
+error-trapping with commands whose arguments are not intended to
+contain whole paragraphs of text.
+
+\begin{decl}
+ |\DeclareRobustCommand| \arg{cmd} \oarg{num} \oarg{default}
+ \arg{definition}\\
+ |\DeclareRobustCommand*| \arg{cmd} \oarg{num} \oarg{default}
+ \arg{definition}
+\end{decl}
+This command takes the same arguments as |\newcommand| but it declares
+a robust command, even if some code within the \m{definition} is
+fragile. You can use this command to define new robust commands, or
+to redefine existing commands and make them robust. A log is put into
+the transcript file if a command is redefined.
+
+For example, if |\seq| is defined as follows:
+\begin{verbatim}
+ \DeclareRobustCommand{\seq}[2][n]{%
+ \ifmmode
+ #1_{1}\ldots#1_{#2}%
+ \else
+ \PackageWarning{fred}{You can't use \protect\seq\space in text}%
+ \fi
+ }
+\end{verbatim}
+Then the command |\seq| can be used in moving arguments, even though
+|\ifmmode| cannot, for example:
+\begin{verbatim}
+ \section{Stuff about sequences $\seq{x}$}
+\end{verbatim}
+
+Note also that there is no need to put a |\relax| before the
+|\ifmmode| at the beginning of the definition; this is because the
+protection given by this |\relax| against expansion at the wrong time
+will be provided internally.
+
+\begin{decl}
+ |\CheckCommand| \arg{cmd} \oarg{num} \oarg{default}
+ \arg{definition}\\
+ |\CheckCommand*| \arg{cmd} \oarg{num} \oarg{default}
+ \arg{definition}
+\end{decl}
+This takes the same arguments as |\newcommand| but, rather than define
+\m{cmd}, it just checks that the current definition of \m{cmd} is
+exactly as given by \m{definition}. An error is raised if these
+definitions differ.
+
+This command is useful for checking the state of the system before
+your package starts altering the definitions of commands. It allows
+you to check, in particular, that no other package has redefined the
+same command.
+
+\subsection{Moving arguments}
+
+\NEWdescription{1994/12/01}
+The setting of protect whilst processing (i.e.~moving) moving arguments
+has been reimplemented, as has the method of writing information from
+the |.aux| file to other files such as the |.toc| file. Details can
+be found in the file |ltdefns.dtx|.
+
+We hope that these changes will not affect many packages.
+
+\section{Miscellaneous commands, etc}
+\label{Sec:commands.misc}
+
+\subsection{Layout parameters}
+
+\begin{decl}
+|\paperheight|\\
+|\paperwidth|
+\end{decl}
+These two parameters are usually set by the class to be the size of
+the paper being used. This should be actual paper size, unlike
+|\textwidth| and |\textheight| which are the size of the main text
+body within the margins.
+
+
+\subsection{Case changing}
+\label{sec:case}
+
+\begin{decl}
+ |\MakeUppercase| \arg{text} \\
+ |\MakeLowercase| \arg{text}
+\end{decl}
+
+\NEWfeature{1995/06/01}
+\TeX{} provides two primitives |\uppercase| and |\lowercase| for
+changing the case of text. These are sometimes used in document
+classes, for example to set information in running heads in all
+capitals.
+
+Unfortunately, these \TeX{} primitives do not change the case of
+characters accessed by commands like |\ae| or |\aa|. To overcome this
+problem, \LaTeX{} provides two new commands |\MakeUppercase| and
+|\MakeLowercase| to do this.
+
+For example:
+\begin{quotation}
+\begin{tabular}{rl}
+ |\uppercase{aBcD\ae\AA\ss\OE}| & \uppercase{aBcD\ae\AA\ss\OE}\\
+ |\lowercase{aBcD\ae\AA\ss\OE}| & \lowercase{aBcD\ae\AA\ss\OE}\\
+ |\MakeUppercase{aBcD\ae\AA\ss\OE}| &
+ \MakeUppercase{aBcD\ae\AA\ss\OE}\\
+ |\MakeLowercase{aBcD\ae\AA\ss\OE}| & \MakeLowercase{aBcD\ae\AA\ss\OE}
+\end{tabular}
+\end{quotation}
+
+The commands |\MakeUppercase| and |\MakeLowercase| themselves are
+robust, but they have moving arguments.
+
+The commands use the \TeX{} primitives |\uppercase| and |\lowercase|,
+and so have a number of unexpected `features'. In particular, they
+change the case of everything (except characters in the names of
+control-sequences) in their text argument: this includes mathematics,
+environment names, and label names.
+
+For example:
+\begin{verbatim}
+ \MakeUppercase{$x+y$ in \ref{foo}}
+\end{verbatim}
+produces $X+Y$ and the warning:
+\begin{verbatim}
+ LaTeX Warning: Reference `FOO' on page ... undefined on ...
+\end{verbatim}
+In the long run, we would like to use all-caps fonts rather than any
+command like |\MakeUppercase| but this is not possible at the moment
+because such fonts do not exist.
+
+\NEWdescription{1995/12/01}
+In order that upper/lower-casing will work reasonably well, and in
+order to provide any correct hyphenation, \LaTeXe{} \emph{must} use,
+throughout a document, the same fixed table for changing case.
+The table used is designed for the font encoding |T1|; this works well
+with the standard \TeX{} fonts for all Latin alphabets but will cause
+problems when using other alphabets.
+
+\subsection{The `openany' option in the `book' class}
+
+\NEWdescription{1996/06/01}
+The |openany| option allows chapter and similar openings to
+occur on left hand pages. Previously this option affected only
+|\chapter| and |\backmatter|. It now also affects
+|\part|, |\frontmatter| and |\mainmatter|.
+
+\subsection{Better user-defined math display environments}
+
+\begin{decl}
+ |\ignorespacesafterend|
+\end{decl}
+
+\NEWfeature{1996/12/01}
+\NEWdescription{2003/12/01}
+Suppose that you want to define an environment for displaying text
+that is numbered as an equation. A straightforward way to do this is
+as follows:
+\begin{verbatim}
+ \newenvironment{texteqn}
+ {\begin{equation}
+ \begin{minipage}{0.9\linewidth}}
+ {\end{minipage}
+ \end{equation}}
+\end{verbatim}
+However, if you have tried this then you will probably have noticed
+that it does not work perfectly when used in the middle of a paragraph
+because an inter-word space appears at the beginning of the first
+line after the environment.
+
+There is now an extra command (with a very long name) available that
+you can use to avoid this problem; it should be inserted as shown here:
+\begin{verbatim}
+ \newenvironment{texteqn}
+ {\begin{equation}
+ \begin{minipage}{0.9\linewidth}}
+ {\end{minipage}
+ \end{equation}
+ \ignorespacesafterend}
+\end{verbatim}
+
+This command may also have other uses.
+
+\subsection{Normalising spacing}
+
+\begin{decl}
+ |\normalsfcodes|
+\end{decl}
+
+\NEWfeature{1997/06/01}
+This command should be used to restore the normal settings of the
+parameters that affect spacing between words, sentences, etc.
+
+An important use of this feature is to correct a problem, reported by
+Donald Arseneau, that punctuation in page headers has always (in all
+known \TeX{} formats) been potentially wrong whenever a page break
+happens while a local setting of the space codes is in effect. These
+space codes are changed by, for example, the command
+\verb|\frenchspacing|) and the \textsf{verbatim} environment.
+
+It is normally given the correct definition automatically in
+|\begin{document}| and so need not be explicitly set; however, if it
+is explicitly made nonempty in a class file then automatic
+default setting will be over-ridden.
+
+
+\section{Upgrading \LaTeX~2.09 classes and packages}
+\label{Sec:upgrade}
+
+This section describes the changes you may need to make when you
+upgrade an existing \LaTeX{} style to a package or class but we shall
+start in optimistic mode.
+
+Many existing style files will run with \LaTeXe{} without any
+modification to the file itself. When everything is running OK,
+please put a note in the newly created package or class file to record
+that it runs with the new standard \LaTeX{}; then distribute it to
+your users.
+
+\subsection{Try it first!}
+\label{Sec:try-it}
+
+The first thing you should do is to test your style in `compatibility
+mode'. The only change you need to make in order to do this is,
+possibly, to change the extension of the file to |.cls|: you should
+make this change only if your file was used as a main document style.
+Now, without any other modifications, run \LaTeXe{} on a document that
+uses your file. This assumes that you have a suitable collection of
+files that tests all the functionality provided by your style file.
+(If you haven't, now is the time to make one!)
+
+You now need to change the test document files so that they are
+\LaTeXe{} documents: see \emph{\usrguide} for details of how to do
+this and then try them again. You have now tried the test documents
+in both \LaTeXe{} native mode and \LaTeX~2.09 compatibility mode.
+
+\subsection{Troubleshooting}
+\label{Sec:trouble}
+
+If your file does not work with \LaTeXe{}, there are two likely
+reasons.
+\begin{itemize}
+\item \LaTeX{} now has a robust, well-defined designer's interface for
+ selecting fonts, which is very different from the \LaTeX~2.09
+ internals.
+\item Your style file may have used some \LaTeX~2.09 internal commands
+ which have changed, or which have been removed.
+\end{itemize}
+
+When you are debugging your file, you will probably need more
+information than is normally displayed by \LaTeXe. This is achieved
+by resetting the counter |errorcontextlines| from its default value of
+$-1$ to a much higher value, e.g.~999.
+
+\subsection{Accommodating compatibility mode}
+
+Sometimes an existing collection of \LaTeX~2.09 documents makes it
+inconvenient or impossible to abandon the old commands entirely.
+If this is the case, then it is possible to accommodate both conventions
+by making special provision for documents processed in compatibility
+mode.
+
+\begin{decl}
+|\if@compatibility|
+\end{decl}
+This switch is set when a document begins with |\documentstyle| rather
+than |\documentclass|. Appropriate code can be supplied for either
+condition, as follows:
+\begin{verbatim}
+ \if@compatibility
+ <code emulating LaTeX 2.09 behavior>
+ \else
+ <code suitable for LaTeX2e>
+ \fi
+\end{verbatim}
+
+
+\subsection{Font commands}
+
+Some font and size commands are now defined by the document class
+rather than by the \LaTeX{} kernel. If you are upgrading a
+\LaTeX~2.09 document style to a class that does not load one of the
+standard classes, then you will probably need to add definitions for
+these commands.
+
+\begin{decl}
+ |\rm| |\sf| |\tt| |\bf| |\it| |\sl| |\sc|
+\end{decl}
+None of these short-form font selection commands are defined in the
+\LaTeXe{} kernel. They are defined by all the standard class files.
+
+If you want to define them in your class file, there are several
+reasonable ways to do this.
+
+One possible definition is:
+\begin{verbatim}
+ \newcommand{\rm}{\rmfamily}
+ ...
+ \newcommand{\sc}{\scshape}
+\end{verbatim}
+This would make the font commands orthogonal; for example
+|{\bf\it text}| would produce bold italic, thus: \textbf{\textit{text}}.
+It will also make them produce an error if used in math mode.
+
+Another possible definition is:
+\begin{verbatim}
+ \DeclareOldFontCommand{\rm}{\rmfamily}{\mathrm}
+ ...
+ \DeclareOldFontCommand{\sc}{\scshape}{\mathsc}
+\end{verbatim}
+This will make |\rm| act like |\rmfamily| in text mode (see above) and
+it will make |\rm| select the |\mathrm| math alphabet in math mode.
+
+Thus |${\rm math} = X + 1$| will produce `${\rm math} = X + 1$'.
+
+If you do not want font selection to be orthogonal then you can
+follow the standard classes and define:
+\begin{verbatim}
+ \DeclareOldFontCommand{\rm}{\normalfont\rmfamily}{\mathrm}
+ ...
+ \DeclareOldFontCommand{\sc}{\normalfont\scshape}{\mathsc}
+\end{verbatim}
+This means, for example, that |{\bf\it text}| will produce medium
+weight (rather than bold) italic, thus: \textit{text}.
+
+\begin{decl}
+ |\normalsize| \\
+ |\@normalsize|
+\end{decl}
+The command |\@normalsize| is retained for compatibility with
+\LaTeX~2.09 packages which may have used its value; but redefining it
+in a class file will have no effect since it is always reset to have
+the same meaning as |\normalsize|.
+
+This means that classes \emph{must} now redefine |\normalsize| rather
+than redefining |\@normalsize|; for example (a rather incomplete one):
+\begin{verbatim}
+ \renewcommand{\normalsize}{\fontsize{10}{12}\selectfont}
+\end{verbatim}
+Note that |\normalsize| is defined by the \LaTeX{} kernel to be an
+error message.
+
+\begin{decl}
+ |\tiny| |\footnotesize| |\small| |\large|\\
+ |\Large| |\LARGE| |\huge| |\Huge|
+\end{decl}
+None of these other `standard' size-changing commands are defined in
+the kernel: each needs to be defined in a class file if you need it.
+They are all defined by the standard classes.
+
+This means you should use |\renewcommand| for |\normalsize| and
+|\newcommand| for the other size-changing commands.
+
+
+\subsection{Obsolete commands}
+
+Some packages will not work with \LaTeXe{}, normally because they relied
+on an internal \LaTeX{} command which was never supported and has now
+changed, or been removed.
+
+In many cases there will now be a robust, high-level means of
+achieving what previously required low-level commands. Please consult
+Section~\ref{Sec:commands} to see if you can now use the \LaTeXe{}
+class and package writers commands.
+
+Also, of course, if your package or class redefined any of the kernel
+commands (i.e.~those defined in the files |latex.tex|, |slitex.tex|,
+|lfonts.tex|, |sfonts.tex|) then you will need to check it very
+carefully against the new kernel in case the implementation has
+changed or the command no longer exists in the \LaTeX2e{} kernel.
+
+Too many of the internal commands of \LaTeX~2.09 have been
+re-implemented or removed to be able to list them all here. You must
+check any that you have used or changed.
+
+We shall, however, list some of the more important commands which are
+no longer supported.
+
+\begin{decl}
+ |\tenrm| |\elvrm| |\twlrm| \dots\\
+ |\tenbf| |\elvbf| |\twlbf| \dots\\
+ |\tensf| |\elvsf| |\twlsf| \dots\\
+ \qquad$\vdots$
+\end{decl}
+The (approximately) seventy internal commands of this form are no longer
+defined. If your class or package uses them then \emph{please}
+replace them with new font commands described in \emph{\fntguide}.
+
+For example, the command |\twlsf| should be replaced by:
+\begin{verbatim}
+ \fontsize{12}{14}\normalfont\sffamily\selectfont
+\end{verbatim}
+
+Another possibility is to use the |rawfonts| package, described in
+\emph{\usrguide}.
+
+Also, remember that many of the fonts preloaded by \LaTeX~2.09
+are no longer preloaded.
+
+\begin{decl}
+ |\vpt| |\vipt| |\viipt| \dots
+\end{decl}
+These were the internal size-selecting commands in \LaTeX~2.09.
+(They can still be used in \LaTeX~2.09 compatibility mode.)
+Please use the command |\fontsize| instead: see \emph{\fntguide} for
+details.
+
+For example, |\vpt| should be replaced by:
+\begin{verbatim}
+ \fontsize{5}{6}\normalfont\selectfont
+\end{verbatim}
+
+\begin{decl}
+ |\prm|, |\pbf|, |\ppounds|, |\pLaTeX| \dots
+\end{decl}
+\LaTeX~2.09 used several commands beginning with |\p| in order to
+provide `protected' commands. For example, |\LaTeX| was defined to be
+|\protect\pLaTeX|, and |\pLaTeX| was defined to produce the \LaTeX{}
+logo. This made |\LaTeX| robust, even though |\pLaTeX| was not.
+
+These commands have now been reimplemented using
+|\DeclareRobustCommand|
+(described in Section~\ref{Sec:commands.define}).
+If your package redefined one of the |\p|-commands then you must
+remove the redefinition and use |\DeclareRobustCommand| to redefine the
+non-|\p| command.
+
+\begin{decl}
+|\footheight|\\
+|\@maxsep|\\
+|\@dblmaxsep|
+\end{decl}
+These parameters are not used by \LaTeXe{} so they have been removed,
+except in \LaTeX~2.09 compatibility mode. Classes should no longer
+set them.
+
+\begin{thebibliography}{1}
+
+\bibitem{A-W:DEK91}
+Donald~E. Knuth.
+\newblock {\em The \TeX book}.
+\newblock Addison-Wesley, Reading, Massachusetts, 1986.
+\newblock Revised to cover \TeX3, 1991.
+
+\bibitem{A-W:LLa94}
+Leslie Lamport.
+\newblock {\em {\LaTeX:} A Document Preparation System}.
+\newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994.
+
+\bibitem{A-W:MG2004}
+Frank Mittelbach and Michel Goossens.
+\newblock {\em The {\LaTeX} Companion second edition}.
+\newblock With Johannes Braams, David Carlisle, and Chris Rowley.
+\newblock Addison-Wesley, Reading, Massachusetts, 2004.
+
+\end{thebibliography}
+
+\newpage
+\thispagestyle{empty}
+
+\section*{\LaTeXe{} Summary sheet: updating old styles}
+
+Section references below are to \emph{\clsguide}.
+
+\begin{enumerate}
+
+\item Should it become a class or a package?
+ See Section~\ref{Sec:classorpkg} for how to answer this question.
+
+\item If it uses another style file, then you will need to obtain an
+ updated version of this other file. Look at Section~\ref{Sec:loading}
+ for information on how to load other class and package files.
+
+\item Try it: see Section~\ref{Sec:try-it}.
+
+\item It worked? Excellent, but there are probably still some things
+ you should change in order to make your file into a well-structured
+ \LaTeXe{} file that is both robust and portable. So you should now
+ read Section~\ref{Sec:writing}, especially~\ref{Sec:general}. You
+ will also find some useful examples in Section~\ref{Sec:structure}.
+
+ If your file sets up new fonts, font-changing commands or symbols,
+ you should also read \emph{\fntguide}.
+
+\item It did not work? There are three possibilities here:
+ \begin{itemize}
+ \item error messages are produced whilst reading your file;
+ \item error messages are produced whilst processing test documents;
+ \item there are no errors but the output is not as it should be.
+ \end{itemize}
+ Don't forget to check carefully for this last possibility.
+
+ If you have got to this stage then you will need to read
+ Section~\ref{Sec:upgrade} to find the solutions that will make your
+ file work.
+\end{enumerate}
+
+\end{document}
diff --git a/macros/latex-dev/base/clsguide.pdf b/macros/latex-dev/base/clsguide.pdf
index ab8af60728..3d17c94cba 100644
--- a/macros/latex-dev/base/clsguide.pdf
+++ b/macros/latex-dev/base/clsguide.pdf
Binary files differ
diff --git a/macros/latex-dev/base/clsguide.tex b/macros/latex-dev/base/clsguide.tex
index ce2c1dcf81..7225425ec8 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-2023
+% Copyright (C) 2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
@@ -28,21 +28,32 @@
% \fi
% Filename: clsguide.tex
-\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\documentclass{ltxguide}
-\documentclass{ltxguide}[1995/11/28]
+\usepackage[T1]{fontenc} % needed for \textbackslash in tt
+\usepackage{csquotes}
-\title{\LaTeXe~for class and package writers}
-
-\author{Copyright \copyright~1995--2006 The \LaTeX\ Project\\
+\title{\LaTeX\ for package and class authors --- current version}
+\author{\copyright~Copyright 2023, \LaTeX\ Project Team.\\
All rights reserved.%
- \footnote{This file may be distributed and/or modified under the
+ \footnote{This file may 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. See the source
\texttt{clsguide.tex} for full details.}%
}
-\date{15 February 2006}
+\date{2023-01-12}
+
+\NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
+\NewDocumentCommand\marg{m}{\arg{#1}}
+\NewDocumentCommand\meta{m}{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle}}
+\NewDocumentCommand\pkg{m}{\textsf{#1}}
+\NewDocumentCommand\text{m}{\ifmmode\mbox{#1}\else#1\fi}
+% Fix a 'feature'
+\makeatletter
+\renewcommand \verbatim@font {\normalfont \ttfamily}
+\makeatother
+\providecommand\url[1]{\texttt{#1}}
\begin{document}
@@ -52,105 +63,74 @@
\section{Introduction}
-This document is an introduction to writing classes and packages for
-\LaTeX{}, with special attention given to upgrading existing
-\LaTeX~2.09 packages to \LaTeXe{}. The latter subject is also
-covered in an article by Johannes Braams published in TUGboat~15.3.
-
-\subsection{Writing classes and packages for \LaTeXe}
-
-\LaTeX{} is a document preparation system that enables the document
-writer to concentrate on the contents of their text, without bothering
-too much about the formatting of it. For example, chapters are
-indicated by |\chapter{<title>}| rather than by selecting 18pt bold.
-
-The file that contains the information about how to turn logical
-structure (like `|\chapter|') into formatting (like `18pt bold ragged
-right') is a \emph{document class}. In addition, some features (such
-as colour or included graphics) are independent of the document class
-and these are contained in \emph{packages}.
+\LaTeXe{} was released in 1994 and added a number of then-new concepts to
+\LaTeX{}. For package and class authors, these are described in
+\texttt{clsguide-historic}, which has largely remained unchanged. Since then,
+the \LaTeX{} team have worked on a number of ideas, firstly a programming
+language for \LaTeX{} (L3 programming layer) and then a range of tools for
+authors which build on that language. Here, we describe the current, stable set
+of tools provided by the \LaTeX{} kernel for package and class developers. We
+assume familiarity with general \LaTeX{} usage as a document author, and that
+the material here is read in conjunction with \texttt{usrguide}, which provides
+information for general \LaTeX{} users on up-to-date approaches to creating
+commands, etc.
-One of the largest differences between \LaTeX~2.09 and \LaTeXe{} is in
-the commands used to write packages and classes. In \LaTeX~2.09,
-there was very little support for writing |.sty| files, and so writers
-had to resort to using low-level commands.
+\section{Writing classes and packages}
+\label{Sec:writing}
-\LaTeXe{} provides high-level commands for structuring packages.
-It is also much easier to build classes and packages on top of each
-other, for example writing a local technical report class |cetechr|
-(for the Chemical Engineering department) based on |article|.
+This section covers some general points concerned with writing
+\LaTeX{} classes and packages.
-\subsection{Overview}
+\subsection{Is it a class or a package?}
+\label{Sec:classorpkg}
-This document contains an overview of how to write classes and
-packages for \LaTeX{}. It does \emph{not} introduce all of the
-commands necessary to write packages: these can be found in either
-\emph{\LaTeXbook} or \emph{\LaTeXcomp}. But it does describe the new
-commands for structuring classes and packages.
+The first thing to do when you want to put some new \LaTeX{} commands
+in a file is to decide whether it should be a \emph{document class} or a
+\emph{package}. The rule of thumb is:
+\begin{quote}
+ If the commands could be used with any document class, then make
+ them a package; and if not, then make them a class.
+\end{quote}
-\begin{description}
+There are two major types of class: those like |article|, |report| or
+|letter|, which are free-standing; and those which are extensions or
+variations of other classes---for example, the |proc| document class,
+which is built on the |article| document class.
-\item[Section~\ref{Sec:general}] contains some general advice about
- writing classes and packages. It describes the difference between
- classes and packages, the command naming conventions, the use of
- |doc| and |docstrip|, how \TeX's primitive file and box commands
- interact with \LaTeX{}. It also contains some hints about general
- \LaTeX{} style.
+Thus, a company might have a local |ownlet| class for printing letters
+with their own headed note-paper. Such a class would build on top of
+the existing |letter| class but it cannot be used with any other
+document class, so we have |ownlet.cls| rather than |ownlet.sty|.
-\item[Section~\ref{Sec:structure}] describes the structure of classes
- and packages. This includes building classes and packages on top of
- other classes and packages, declaring options and declaring
- commands. It also contains example classes.
+The |graphics| package, in contrast, provides commands for including
+images into a \LaTeX{} document. Since these commands can be used
+with any document class, we have |graphics.sty| rather than
+|graphics.cls|.
-\item[Section~\ref{Sec:commands}] lists the new class and package
- commands.
+\subsection{Using `docstrip' and `doc'}
- \item[Section~\ref{Sec:upgrade}] gives detailed advice on how to
- upgrade existing \LaTeX~2.09 classes and packages to \LaTeXe{}.
+If you are going to write a large class or package for \LaTeX{} then
+you should consider using the |doc| software which comes with
+\LaTeX{}.
+\LaTeX{} classes and packages written using this can be
+processed in two ways: they can be run through \LaTeX{}, to produce
+documentation; and they can be processed with |docstrip|, to produce
+the |.cls| or |.sty| file.
-\end{description}
+The |doc| software can automatically generate indexes of definitions,
+indexes of command use, and change-log lists. It is very useful for
+maintaining and documenting large \TeX{} sources.
-\subsection{Further information}
-
-For a general introduction to \LaTeX{}, including the new features of
-\LaTeXe{}, you should read \emph{\LaTeXbook}
-by Leslie Lamport~\cite{A-W:LLa94}.
-
-A more detailed description of the new features of \LaTeX, including an
-overview of more than 200 packages and nearly 1000 ready to run examples, is
-to be found in \emph{\LaTeXcomp\ second edition} by Frank Mittelbach and
-Michel Goossens~\cite{A-W:MG2004}.
-
-The \LaTeX{} system is based on \TeX{}, which is
-described in \emph{The \TeX book} by Donald E.~Knuth~\cite{A-W:DEK91}.
-
-There are a number of documentation files which accompany every copy
-of \LaTeX{}. A copy of \emph{\LaTeX{} News} will come out with each
-six-monthly release of \LaTeX{}, and is found in the files
-|ltnews*.tex|. The author's guide \emph{\usrguide} describes the new
-\LaTeX{} document features; it is in |usrguide.tex|. The guide
-\emph{\fntguide} describes the \LaTeX{} font selection scheme for
-class- and package-writers; it is in |fntguide.tex|. Configuring
-\LaTeX{} is covered by the guide \emph{\cfgguide} in
-\texttt{cfgguide.tex} whilst the philosophy behind our policy on
-modifying \LaTeX{} is described in \emph{\modguide} in
-\texttt{modguide.tex}.
-
-The documented source code (from the files used to produce the kernel
-format via |latex.ltx|) is now available as
-\emph{The \LaTeXe\ Sources}.
-This very large document also includes an index of
-\LaTeX{} commands. It can be typeset from the \LaTeX{} file
-|source2e.tex| in the |base| directory, using the source files and
-the class file |ltxdoc.cls| from this directory.
-
-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}
-\end{quote}
+The documented sources of the \LaTeX{} kernel itself, and of the
+standard classes, etc., are |doc| documents; they are in the |.dtx|
+files in the distribution. You can, in fact, typeset the source code
+of the kernel as one long document, complete with index, by running
+\LaTeX{} on |source2e.tex|. Typesetting these documents uses the
+class file |ltxdoc.cls|.
+For more information on |doc| and |docstrip|, consult the files
+|docstrip.dtx|, |doc.dtx|, and \emph{\LaTeXcomp}. For examples of its
+use, look at the |.dtx| files.
\subsection{Policy on standard classes}
@@ -182,89 +162,10 @@ packages that can be used to enhance these classes. So your first
thought when you consider such a deficiency will, we hope, be ``what
can I do to improve this?''
-Similar considerations apply to those parts of the kernel that are
-implementing design decisions, many of which should be left to the
-class file but are not in the current system. We realise that in such
-cases it is much more difficult for you to rectify the problem
-yourself but it is also the case that making such changes in the
-kernel would probably be a major project for us; therefore such
-enhancements will have to wait for \LaTeX3.
-
-\section{Writing classes and packages}
-\label{Sec:writing}
-
-This section covers some general points concerned with writing
-\LaTeX{} classes and packages.
-
-
-\subsection{Old versions}
-
-If you are upgrading an existing \LaTeX~2.09 style file then we
-recommend freezing the 2.09 version and no longer maintaining it.
-Experience with the various dialects of \LaTeX{} which existed in the
-early 1990's suggests that maintaining packages for different versions
-of \LaTeX{} is almost impossible. It will, of course, be necessary
-for some organisations to maintain both versions in parallel for some
-time but this is not essential for those packages and classes
-supported by individuals: they should support only the new standard
-\LaTeXe{}, not obsolete versions of \LaTeX{}.
-
-
-\subsection{Using `docstrip' and `doc'}
-
-If you are going to write a large class or package for \LaTeX{} then
-you should consider using the |doc| software which comes with
-\LaTeX{}.
-\LaTeX{} classes and packages written using this can be
-processed in two ways: they can be run through \LaTeX{}, to produce
-documentation; and they can be processed with |docstrip|, to produce
-the |.cls| or |.sty| file.
-
-The |doc| software can automatically generate indexes of definitions,
-indexes of command use, and change-log lists. It is very useful for
-maintaining and documenting large \TeX{} sources.
-
-The documented sources of the \LaTeX{} kernel itself, and of the
-standard classes, etc, are |doc| documents; they are in the |.dtx|
-files in the distribution. You can, in fact, typeset the source code
-of the kernel as one long document, complete with index, by running
-\LaTeX{} on |source2e.tex|. Typesetting these documents uses the
-class file |ltxdoc.cls|.
-
-For more information on |doc| and |docstrip|, consult the files
-|docstrip.dtx|, |doc.dtx|, and \emph{\LaTeXcomp}. For examples of its
-use, look at the |.dtx| files.
-
-\subsection{Is it a class or a package?}
-\label{Sec:classorpkg}
-
-The first thing to do when you want to put some new \LaTeX{} commands
-in a file is to decide whether it should be a \emph{document class} or a
-\emph{package}. The rule of thumb is:
-\begin{quote}
- If the commands could be used with any document class, then make
- them a package; and if not, then make them a class.
-\end{quote}
-
-There are two major types of class: those like |article|, |report| or
-|letter|, which are free-standing; and those which are extensions or
-variations of other classes---for example, the |proc| document class,
-which is built on the |article| document class.
-
-Thus, a company might have a local |ownlet| class for printing letters
-with their own headed note-paper. Such a class would build on top of
-the existing |letter| class but it cannot be used with any other
-document class, so we have |ownlet.cls| rather than |ownlet.sty|.
-
-The |graphics| package, in contrast, provides commands for including
-images into a \LaTeX{} document. Since these commands can be used
-with any document class, we have |graphics.sty| rather than
-|graphics.cls|.
-
-
\subsection{Command names}
-\LaTeX{} has three types of command.
+Prior to the introduction of the L3~programming layer described in the next
+section, \LaTeX{} had three types of command.
There are the author commands, such as |\section|, |\emph| and
|\times|: most of these have short names, all in lower case.
@@ -289,117 +190,97 @@ However, this rule of thumb is still useful: if a command has |@| in
its name then it is not part of the supported \LaTeX{} language---and
its behaviour may change in future releases! If a command is
mixed-case, or is described in \emph{\LaTeXbook}, then you can rely on
-future releases of \LaTeXe{} supporting the command.
-
-\subsection{Box commands and colour}
-\label{Sec:colour}
-
-Even if you do not intend to use colour in your own documents, by
-taking note of the points in this section you can ensure that your
-class or package is compatible with the |color| package. This may
-benefit people using your class or package who have access to colour
-printers.
-
-The simplest way to ensure `colour safety' is to always use \LaTeX{}
-box commands rather than \TeX{} primitives, that is use |\sbox| rather
-than |\setbox|, |\mbox| rather than |\hbox| and |\parbox| or
-the |minipage| environment rather than |\vbox|.
-The \LaTeX{} box commands have new options which mean that they are now
-as powerful as the \TeX{} primitives.
-
-As an example of what can go wrong, consider that in
-|{\ttfamily <text>}|
-the font is restored just \emph{before} the |}|, whereas in the
-similar looking construction
-|{\color{green} <text>}|
-the colour is restored just \emph{after} the final |}|. Normally this
-distinction does not matter at all; but consider a primitive \TeX{}
-box assignment such as:
+future releases of \LaTeX{} supporting the command.
+
+\subsection{Programming support}
+
+As noted in the introduction, the \LaTeX{} kernel today loads dedicated support
+from programming, here referred to as the L3 programming layer but also often
+called \pkg{expl3}. Details of the general approach taken by the L3
+programming layer are given in the document \texttt{expl3}, while a reference
+for all current code interfaces is available as \texttt{interface3}. This layer
+contains two types of command: a documented set of commands making up the API
+and a large number of private internal commands. The latter all start with two
+underscores and should not be used outside of the code module which defines
+them. This more structured approach means that using the L3 programming layer
+does not suffer from the somewhat fluid situation mentioned above with
+`\texttt{@} commands'.
+
+We do not cover the detail of using the L3 programming layer here. A good
+introduction to the approach is provided at
+\url{https://www.alanshawn.com/latex3-tutorial/}.
+
+\subsection{Box commands and color}
+\label{Sec:color}
+
+Even if you do not intend to use color in your own documents, by taking note of
+the points in this section you can ensure that your class or package is
+compatible with the |color| package. This may benefit people using your class
+or package and wish to use color.
+
+The simplest way to ensure `color safety' is to always use \LaTeX{} box
+commands rather than \TeX{} primitives, that is use |\sbox| rather than
+|\setbox|, |\mbox| rather than |\hbox| and |\parbox| or the |minipage|
+environment rather than |\vbox|. The \LaTeX{} box commands have new options
+which mean that they are now as powerful as the \TeX{} primitives.
+
+As an example of what can go wrong, consider that in |{\ttfamily <text>}| the
+font is restored just \emph{before} the |}|, whereas in the similar looking
+construction |{\color{green} <text>}| the color is restored just \emph{after}
+the final |}|. Normally this distinction does not matter at all; but consider a
+primitive \TeX{} box assignment such as:
\begin{verbatim}
\setbox0=\hbox{\color{green} <text>}
\end{verbatim}
-Now the colour-restore occurs after the |}| and so is \emph{not}
-stored in the box. Exactly what bad effects this can have depends on
-how colour is implemented: it can range from getting the wrong
-colours in the rest of the document, to causing errors in the
-dvi-driver used to print the document.
-
-Also of interest is the command |\normalcolor|. This is
-normally just |\relax| (i.e., does nothing)
-but you can use it rather like |\normalfont| to
-set regions of the page such as captions or section headings to the
-`main document colour'.
-
-
-\subsection{Defining text and math characters}
-\label{Sec:chars}
-
-Because \LaTeXe{} supports different encodings, definitions of commands
-for producing symbols, accents, composite glyphs, etc.\ must be
-defined using the commands provided for this purpose and described in
-\emph{\fntguide}. This part of the system is still under development
-so such tasks should be undertaken with great caution.
-
-Also, |\DeclareRobustCommand| should be used for encoding-independent
-commands of this type.
-
-Note that it is no longer possible to refer to the math font set-up
-outside math mode: for example, neither |\textfont 1| nor
-|\scriptfont 2| are guaranteed to be defined in other modes.
+Now the color-restore occurs after the |}| and so is \emph{not} stored in the
+box. Exactly what bad effects this can have depends on how color is
+implemented: it can range from getting the wrong colors in the rest of the
+document, to causing errors in the dvi-driver used to print the document.
+Also of interest is the command |\normalcolor|. This is normally just |\relax|
+(i.e., does nothing) but you can use it rather like |\normalfont| to set
+regions of the page such as captions or section headings to the `main document
+color'.
\subsection{General style}
\label{Sec:general}
-The new system provides many commands designed to help you produce
-well-structured class and package files that are both robust and
-portable. This section outlines some ways to make intelligent use of
-these.
+\LaTeX{} provides many commands designed to help you produce well-structured
+class and package files that are both robust and portable. This section
+outlines some ways to make intelligent use of these.
\subsubsection{Loading other files}
\label{Sec:loading}
-\NEWdescription{1995/12/01}
\LaTeX{} provides these commands:
\begin{verbatim}
\LoadClass \LoadClassWithOptions
\RequirePackage \RequirePackageWithOptions
\end{verbatim}
-for using classes or packages inside other classes or packages. We
-recommend strongly that you use them, rather than the primitive
-|\input| command, for a number of reasons.
+for using classes or packages inside other classes or packages. We recommend
+strongly that you use them, rather than the primitive |\input| command, for a
+number of reasons.
-Files loaded with |\input <filename>| will not be listed in the
-|\listfiles| list.
+Files loaded with |\input <filename>| will not be listed in the |\listfiles|
+list.
-If a package is always loaded with |\RequirePackage...| or |\usepackage|
-then, even if its loading is requested several times, it will be
-loaded only once. By contrast, if it is loaded with |\input| then it
-can be loaded more than once; such an extra loading may waste time and
-memory and it may produce strange results.
+If a package is always loaded with |\RequirePackage...| or |\usepackage| then,
+even if its loading is requested several times, it will be loaded only once. By
+contrast, if it is loaded with |\input| then it can be loaded more than once;
+such an extra loading may waste time and memory and it may produce strange
+results.
-If a package provides option-processing then, again, strange results
-are possible if the package is |\input| rather than loaded by means of
+If a package provides option-processing then, again, strange results are
+possible if the package is |\input| rather than loaded by means of
|\usepackage| or |\RequirePackage...|.
-If the package |foo.sty| loads the package |baz.sty| by use of
-|\input baz.sty| then the user will get a warning:
+If the package |foo.sty| loads the package |baz.sty| by use of |\input baz.sty|
+then the user will get a warning:
\begin{verbatim}
LaTeX Warning: You have requested package `foo',
but the package provides `baz'.
\end{verbatim}
-Thus, for several reasons, using |\input| to load packages is not a
-good idea.
-
-Unfortunately, if you are upgrading the file |myclass.sty| to a class
-file then you have to make sure that any old files which contain
-|\input myclass.sty| still work.
-
-This was also true for the standard classes (|article|, |book| and
-|report|), since a lot of existing \LaTeX~2.09 document styles contain
-|\input article.sty|. The approach which we use to solve this is
-to provide minimal files |article.sty|, |book.sty| and |report.sty|,
-which simply load the appropriate class files.
+Thus, for several reasons, using |\input| to load packages is not a good idea.
For example, |article.sty| contains just the following lines:
\begin{verbatim}
@@ -407,93 +288,72 @@ For example, |article.sty| contains just the following lines:
\@obsoletefile{article.cls}{article.sty}
\LoadClass{article}
\end{verbatim}
-You may wish to do the same or, if you think that it is safe to do so,
-you may decide to just remove |myclass.sty|.
+You may wish to do the same or, if you think that it is safe to do so, you may
+decide to just remove |myclass.sty|.
\subsubsection{Make it robust}
We consider it good practice, when writing packages and classes, to use
\LaTeX{} commands as much as possible.
-Thus, instead of using |\def...| we recommend using one of
-|\newcommand|, |\renewcommand| or |\providecommand|; |\CheckCommand| is
-also useful. Doing this makes
-it less likely that you will inadvertently redefine a command, giving
-unexpected results.
+Thus, instead of using |\def...| we recommend using one of |\newcommand|,
+|\renewcommand| or |\providecommand| for programming and for defining document
+interfaces |\NewDocumentCommand|, etc. (see \texttt{usrguide} for details of
+these commands).
-When you define an environment, use |\newenvironment| or
-|\renewenvironment| instead |\def\foo{...}| and |\def\endfoo{...}|.
+When you define an environment, use |\NewDocumentEnvironment|, etc., (or
+|\newenvironment|, etc., for simple cases) instead of using |\def\foo{...}| and
+|\def\endfoo{...}|.
-If you need to set or change the value of a \m{dimen} or \m{skip}
-register, use |\setlength|.
+If you need to set or change the value of a \m{dimen} or \m{skip} register, use
+|\setlength|.
-To manipulate boxes, use \LaTeX{} commands such as |\sbox|,
-|\mbox| and |\parbox| rather than |\setbox|, |\hbox| and |\vbox|.
+To manipulate boxes, use \LaTeX{} commands such as |\sbox|, |\mbox| and
+|\parbox| rather than |\setbox|, |\hbox| and |\vbox|.
-Use |\PackageError|, |\PackageWarning| or |\PackageInfo| (or the
-equivalent class commands) rather than |\@latexerr|, |\@warning| or
-|\wlog|.
-
-It is still possible to declare options by defining |\ds@<option>| and
-calling |\@options|; but we recommend the |\DeclareOption| and
-|\ProcessOptions| commands instead. These are more powerful and use
-less memory. So rather than using:
-\begin{verbatim}
- \def\ds@draft{\overfullrule 5pt}
- \@options
-\end{verbatim}
-you should use:
-\begin{verbatim}
- \DeclareOption{draft}{\setlength{\overfullrule}{5pt}}
- \ProcessOptions\relax
-\end{verbatim}
+Use |\PackageError|, |\PackageWarning| or |\PackageInfo| (or the equivalent
+class commands) rather than |\@latexerr|, |\@warning| or |\wlog|.
-The advantage of this kind of practice is that your code is more
-readable and, more important, that it is less likely to break when
-used with future versions of \LaTeX{}.
+The advantage of this kind of practice is that your code is more readable and
+accessible to other experienced \LaTeX{} programmers.
\subsubsection{Make it portable}
-It is also sensible to make your files are as portable as possible. To
-ensure this; they should contain only visible 7-bit text; and the
-filenames should contain at most eight characters (plus the three
-letter extension). Also, of course, it \textbf{must not} have the
-same name as a file in the standard \LaTeX{} distribution, however
-similar its contents may be to one of these files.
+It is also sensible to make your files are as portable as possible. To ensure
+this, files must not have the same name as a file in the standard \LaTeX{}
+distribution, however similar its contents may be to one of these files. It is
+also still lower risk to stick to file names which use only the ASCII range:
+whilst \LaTeX{} works natively with UTF-8, the same cannot be said with
+certainty for all tools. For the same reason, avoid spaces in file names.
-It is also useful if local classes or packages have a common prefix,
-for example the University of Nowhere classes might begin with |unw|.
-This helps to avoid every University having its own thesis class, all
-called |thesis.cls|.
+It is also useful if local classes or packages have a common prefix, for
+example the University of Nowhere classes might begin with |unw|. This helps to
+avoid every University having its own thesis class, all called |thesis.cls|.
If you rely on some features of the \LaTeX{} kernel, or on a package,
please specify the release-date you need. For example, the package
-error commands were introduced in the June 1994 release so, if you use
+error commands were introduced in the June 2022 release so, if you use
them then you should put:
\begin{verbatim}
- \NeedsTeXFormat{LaTeX2e}[1994/06/01]
+ \NeedsTeXFormat{LaTeX2e}[2022-06-01]
\end{verbatim}
\subsubsection{Useful hooks}
-Some packages and document styles had to redefine the command
-|\document| or |\enddocument| to achieve their goal. This is no
-longer necessary. You can now use the `hooks' |\AtBeginDocument| and
-|\AtEndDocument| (see Section~\ref{Sec:delays}). Again, using these
-hooks makes it less likely that your code breaks with future versions
-of \LaTeX{}. It also makes it more likely that your package can work
-together with someone else's.
-
-\NEWdescription{1996/12/01}
-However, note that code in the |\AtBeginDocument| hook is part of the
-preamble. Thus there are restrictions on what can be put there; in
-particular, no typesetting can be done.
+It is sometimes necessary for a package to arrange for code to be
+executed at the start or end of the preamble, at the end of the document
+or at the start of every use of an environment. This can be carried
+out by using hooks. As a document author, you will likely be familiar with
+|\AtBeginDocument|, a wrapper around the more powerful command |\AddToHook|.
+The \LaTeX{} kernel provides a large number of dedicated hooks (applying in
+a pre-defined location) and generic hooks (applying to arbitrary commands):
+the interface for using these is described in \texttt{lthooks} . There are
+also hooks to apply to files, described in \texttt{ltfilehooks}.
\section{The structure of a class or package}
\label{Sec:structure}
-\LaTeXe{} classes and packages have more structure than \LaTeX~2.09
-style files did. The outline of a class or package file is:
+The outline of a class or package file is:
\begin{description}
\item[Identification] The file says that it is a \LaTeXe{} package or
class, and gives a short description of itself.
@@ -517,7 +377,7 @@ Package files do this as follows:
For example:
\begin{verbatim}
\NeedsTeXFormat{LaTeX2e}
- \ProvidesPackage{latexsym}[1994/06/01 Standard LaTeX package]
+ \ProvidesPackage{latexsym}[1998-08-17 Standard LaTeX package]
\end{verbatim}
Class files do this as follows:
\begin{verbatim}
@@ -527,40 +387,30 @@ Class files do this as follows:
For example:
\begin{verbatim}
\NeedsTeXFormat{LaTeX2e}
- \ProvidesClass{article}[1994/06/01 Standard LaTeX class]
-\end{verbatim}
-\NEWdescription{1998/06/19}
-The \m{date} should be given in the form `\textsc{yyyy/mm/dd}' and
-must be present if the optional argument is used (this is also true
-for the |\NeedsTeXFormat| command).
-Any derivation from this syntax will result in low-level \TeX{}
-errors---the commands expect a valid syntax to speed up the daily
-usage of the package or class and make no provision for the case that
-the developer made a mistake!
-
-This date is checked whenever a user specifies a date in their
-|\documentclass| or |\usepackage| command. For example, if you wrote:
-\begin{verbatim}
- \documentclass{article}[1995/12/23]
-\end{verbatim}
-then users at a different location
-would get a warning that their copy of |article| was out of
-date.
-
-The description of a class is displayed when the class is used. The
-description of a package is put into the log file. These descriptions
-are also displayed by the |\listfiles| command. The phrase
-\texttt{Standard LaTeX} \textbf{must not} be used in the identification
-banner of any file other than those in the standard \LaTeX{}
-distribution.
+ \ProvidesClass{article}[2022-06-01 Standard LaTeX class]
+\end{verbatim}
+The \m{date} should be given in the form `\textsc{yyyy-mm-dd}' and must be
+present if the optional argument is used (this is also true for the
+|\NeedsTeXFormat| command). Any derivation from this syntax will result in
+low-level \TeX{} errors---the commands expect a valid syntax to speed up the
+daily usage of the package or class and make no provision for the case that the
+developer made a mistake!
+This date is checked whenever a user specifies a date in their |\documentclass|
+or |\usepackage| command. For example, if you wrote:
+\begin{verbatim}
+ \documentclass{article}[2022-06-01]
+\end{verbatim}
+then users at a different location would get a warning that their copy of
+|article| was out of date.
-\subsection{Using classes and packages}
+The description of a class is displayed when the class is used. The description
+of a package is put into the log file. These descriptions are also displayed by
+the |\listfiles| command. The phrase \texttt{Standard LaTeX} \textbf{must not}
+be used in the identification banner of any file other than those in the
+standard \LaTeX{} distribution.
-The first major difference between \LaTeX~2.09 style files and
-\LaTeXe{} packages and classes is that \LaTeXe{} supports
-\emph{modularity}, in the sense of building files from small
-building-blocks rather than using large single files.
+\subsection{Using classes and packages}
A \LaTeX{} package or class can load a package as follows:
\begin{verbatim}
@@ -568,13 +418,12 @@ A \LaTeX{} package or class can load a package as follows:
\end{verbatim}
For example:
\begin{verbatim}
- \RequirePackage{ifthen}[1994/06/01]
+ \RequirePackage{ifthen}[2022-06-01]
\end{verbatim}
-This command has the same syntax as the author command |\usepackage|.
-It allows packages or classes to use features provided by other
-packages. For example, by loading the |ifthen| package, a package
-writer can use the `if\dots then\dots else\dots' commands provided
-by that package.
+This command has the same syntax as the author command |\usepackage|. It allows
+packages or classes to use features provided by other packages. For example, by
+loading the |ifthen| package, a package writer can use the `if\dots then\dots
+else\dots' commands provided by that package.
A \LaTeX{} class can load one other class as follows:
\begin{verbatim}
@@ -584,13 +433,12 @@ For example:
\begin{verbatim}
\LoadClass[twocolumn]{article}
\end{verbatim}
-This command has the same syntax as the author command |\documentclass|.
-It allows classes to be based on the syntax and appearance of another
-class. For example, by loading the |article| class, a class writer
-only has to change the bits of |article| they don't like, rather than
-writing a new class from scratch.
+This command has the same syntax as the author command |\documentclass|. It
+allows classes to be based on the syntax and appearance of another class. For
+example, by loading the |article| class, a class writer only has to change the
+bits of |article| they don't like, rather than writing a new class from
+scratch.
-\NEWfeature{1995/12/01}
The following commands can be used in the common case that you want to
simply load a class or package file with exactly those options that
are being used by the current class.
@@ -606,14 +454,20 @@ For example:
\subsection{Declaring options}
-\NEWdescription{1998/12/01}
-The other major difference between \LaTeX~2.09 styles and \LaTeXe{}
-packages and classes is in option handling. Packages and classes can
-now declare options and these can be specified by authors; for
-example, the |twocolumn| option is declared by the |article| class.
-Note that the name of an option should contain only those characters
-allowed in a `\LaTeX{} name'; in particular it must not contain any
-control sequences.
+Packages and classes can declare options and these can be specified by authors;
+for example, the |twocolumn| option is declared by the |article| class. Note
+that the name of an option should contain only those characters allowed in a
+`\LaTeX{} name'; in particular it must not contain any control sequences.
+
+\LaTeX{} supports two methods for creating options: a key--value system and a
+`simple text' approach. The key--value system is recommended for new classes
+and packages, and is more flexible in handling of option classes than the
+simple text approach. Both option methods use the same basic structure within
+the \LaTeX{} source: declaration of options first then processing options in a
+second step. Both also allow options to be passed on to other packages or an
+underlying class. As the `classical' simple text approach is conceptually more
+straight-forward to illustrate, it is used here to show the general structure:
+see Section~\ref{Sec:opt:keyval} for full details of the key--value approach.
An option is declared as follows:
\begin{verbatim}
@@ -624,63 +478,58 @@ to the |graphics| package is implemented as:
\begin{verbatim}
\DeclareOption{dvips}{\input{dvips.def}}
\end{verbatim}
-This means that when an author writes |\usepackage[dvips]{graphics}|,
-the file |dvips.def| is loaded. As another example, the |a4paper|
-option is declared in the |article| class to set the |\paperheight|
-and |\paperwidth| lengths:
+This means that when an author writes |\usepackage[dvips]{graphics}|, the file
+|dvips.def| is loaded. As another example, the |a4paper| option is declared in
+the |article| class to set the |\paperheight| and |\paperwidth| lengths:
\begin{verbatim}
\DeclareOption{a4paper}{%
\setlength{\paperheight}{297mm}%
\setlength{\paperwidth}{210mm}%
}
\end{verbatim}
-Sometimes a user will request an option which the class
-or package has not explicitly declared. By default this will produce
-a warning (for classes) or error (for packages); this behaviour
-can be altered as follows:
+Sometimes a user will request an option which the class or package has not
+explicitly declared. By default this will produce a warning (for classes) or
+error (for packages); this behaviour can be altered as follows:
\begin{verbatim}
\DeclareOption*{<code>}
\end{verbatim}
-For example, to make the package |fred| produce a warning rather than
-an error for unknown options, you could specify:
+For example, to make the package |fred| produce a warning rather than an error
+for unknown options, you could specify:
\begin{verbatim}
\DeclareOption*{%
\PackageWarning{fred}{Unknown option `\CurrentOption'}%
}
\end{verbatim}
-Then, if an author writes |\usepackage[foo]{fred}|, they will get a
-warning \texttt{Package fred Warning: Unknown option `foo'.} As
-another example, the |fontenc| package tries to load a file
-|<ENC>enc.def| whenever the \m{ENC} option is used. This
-can be done by writing:
+Then, if an author writes |\usepackage[foo]{fred}|, they will get a warning
+\texttt{Package fred Warning: Unknown option `foo'.} As another example, the
+|fontenc| package tries to load a file |<ENC>enc.def| whenever the \m{ENC}
+option is used. This can be done by writing:
\begin{verbatim}
\DeclareOption*{%
\input{\CurrentOption enc.def}%
}
\end{verbatim}
-\NEWdescription{1998/12/01}
-It is possible to pass options on to another package or class, using
-the command |\PassOptionsToPackage| or |\PassOptionsToClass| (note
-that this is a specialised operation that works only for option
-names). For example, to pass every unknown option on to the |article|
-class, you can use:
+
+It is possible to pass options on to another package or class, using the
+command |\PassOptionsToPackage| or |\PassOptionsToClass| (note that this is a
+specialised operation that works only for option names): see
+Section~\ref{Sec:opmove}. For example, to pass every unknown option on to the
+|article| class, you can use:
\begin{verbatim}
\DeclareOption*{%
\PassOptionsToClass{\CurrentOption}{article}%
}
\end{verbatim}
-If you do this then you should make sure you load the class at some
-later point, otherwise the options will never be processed!
+If you do this then you should make sure you load the class at some later
+point, otherwise the options will never be processed!
-So far, we have explained only how to declare options, not how to
-execute them. To process the options with which the file was called,
-you should use:
+So far, we have explained only how to declare options, not how to execute them.
+To process the options with which the file was called, you should use:
\begin{verbatim}
\ProcessOptions\relax
\end{verbatim}
-This executes the \m{code} for each option that was both specified and
-declared (see Section~\ref{Sec:commands.options} for details of how
-this is done).
+This executes the \m{code} for each option that was both specified and declared
+(see Section~\ref{Sec:commands.options} for details of how this is done).
For example, if the |jane| package file contains:
\begin{verbatim}
@@ -689,8 +538,8 @@ For example, if the |jane| package file contains:
\DeclareOption*{\typeout{What's \CurrentOption?}}
\ProcessOptions\relax
\end{verbatim}
-and an author writes |\usepackage[foo,bar]{jane}|, then they will see
-the messages \texttt{Saw foo.} and \texttt{What's bar?}
+and an author writes |\usepackage[foo,bar]{jane}|, then they will see the
+messages \texttt{Saw foo.} and \texttt{What's bar?}
\subsection{A minimal class file}
@@ -698,9 +547,6 @@ Most of the work of a class or package is in defining new commands, or
changing the appearance of documents. This is done in the body of the
package, using commands such as |\newcommand| or |\setlength|.
-\LaTeXe{} provides several new commands to help class and package
-writers; these are described in detail in Section~\ref{Sec:commands}.
-
There are four things that every class file \emph{must} contain: these
are a definition of |\normalsize|, values for |\textwidth| and
|\textheight| and a specification for page-numbering. So a minimal
@@ -708,7 +554,7 @@ document class file\footnote {This class is now in the standard
distribution, as \texttt{minimal.cls}.} looks like this:
\begin{verbatim}
\NeedsTeXFormat{LaTeX2e}
- \ProvidesClass{minimal}[1995/10/30 Standard LaTeX minimal class]
+ \ProvidesClass{minimal}[2022-06-01 Standard LaTeX minimal class]
\renewcommand{\normalsize}{\fontsize{10pt}{12pt}\selectfont}
\setlength{\textwidth}{6.5in}
\setlength{\textheight}{8in}
@@ -728,18 +574,17 @@ class, although a real class would need more structure.
The class begins by announcing itself as |neplet.cls|.
\begin{verbatim}
\NeedsTeXFormat{LaTeX2e}
- \ProvidesClass{neplet}[1995/04/01 NonExistent Press letter class]
+ \ProvidesClass{neplet}[2022-06-01 NonExistent Press letter class]
\end{verbatim}
-Then this next bit passes any options on to the |letter| class, which
-is loaded with the |a4paper| option.
+Then this next bit passes any options on to the |letter| class, which is loaded
+with the |a4paper| option.
\begin{verbatim}
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{letter}}
\ProcessOptions\relax
\LoadClass[a4paper]{letter}
\end{verbatim}
-In order to use the company letter head, it redefines the
-|firstpage| page style: this is the page style that is used on
-the first page of letters.
+In order to use the company letter head, it redefines the |firstpage| page
+style: this is the page style that is used on the first page of letters.
\begin{verbatim}
\renewcommand{\ps@firstpage}{%
\renewcommand{\@oddhead}{<letterhead goes here>}%
@@ -751,17 +596,16 @@ And that's it!
\subsection{Example: a newsletter class}
A simple newsletter can be typeset with \LaTeX{}, using a variant of the
-|article| class.
-The class begins by announcing itself as |smplnews.cls|.
+|article| class. The class begins by announcing itself as |smplnews.cls|.
\begin{verbatim}
\NeedsTeXFormat{LaTeX2e}
- \ProvidesClass{smplnews}[1995/04/01 The Simple News newsletter class]
+ \ProvidesClass{smplnews}[2022-06-01 The Simple News newsletter class]
\newcommand{\headlinecolor}{\normalcolor}
\end{verbatim}
-It passes most specified options on to the |article| class: apart from
-the |onecolumn| option, which is switched off, and the |green| option,
-which sets the headline in green.
+It passes most specified options on to the |article| class: apart from the
+|onecolumn| option, which is switched off, and the |green| option, which sets
+the headline in green.
\begin{verbatim}
\DeclareOption{onecolumn}{\OptionNotUsed}
\DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}}
@@ -774,14 +618,14 @@ It then loads the class |article| with the option |twocolumn|.
\begin{verbatim}
\LoadClass[twocolumn]{article}
\end{verbatim}
-Since the newsletter is to be printed in colour, it now loads the
-|color| package. The class does not specify a device driver option
-since this should be specified by the user of the |smplnews| class.
+Since the newsletter is to be printed in colour, it now loads the |color|
+package. The class does not specify a device driver option since this should be
+specified by the user of the |smplnews| class.
\begin{verbatim}
\RequirePackage{color}
\end{verbatim}
-The class then redefines |\maketitle| to produce the title in 72pt
-Helvetica bold oblique, in the appropriate colour.
+The class then redefines |\maketitle| to produce the title in 72\,pt Helvetica
+bold oblique, in the appropriate colour.
\begin{verbatim}
\renewcommand{\maketitle}{%
\twocolumn[%
@@ -807,90 +651,91 @@ It also sets the three essential things.
\setlength{\textwidth}{17.5cm}
\setlength{\textheight}{25cm}
\end{verbatim}
-In practice, a class would need more than this: it would provide
-commands for issue numbers, authors of articles, page styles and so
-on; but this skeleton gives a start. The |ltnews| class file is not
-much more complex than this one.
+In practice, a class would need more than this: it would provide commands for
+issue numbers, authors of articles, page styles and so on; but this skeleton
+gives a start. The |ltnews| class file is not much more complex than this one.
\section{Commands for class and package writers}
\label{Sec:commands}
-This section describes briefly each of the new commands for class and
-package writers. To find out about other aspects of the new system,
+This section describes briefly each of the commands for class and package
+writers. To find out about other aspects of the system,
you should also read \emph{\LaTeXbook}, \emph{\LaTeXcomp} and
\emph{\usrguide}.
\subsection{Identification}
-The first group of commands discussed here are those used
-to identify your class or package file.
+The first group of commands discussed here are those used to identify your
+class or package file.
\begin{decl}
|\NeedsTeXFormat| \arg{format-name} \oarg{release-date}
\end{decl}
-This command tells \TeX{} that this file should be processed using a
-format with name \m{format-name}. You can use the optional argument
-\m{release-date} to further specify the earliest release date of the
-format that is needed. When the release date of the format is older
-than the one specified a warning will be generated. The standard
-\m{format-name} is \texttt{LaTeX2e}. The date, if present, must be in
-the form \textsc{yyyy/mm/dd}.
+This command tells \TeX{} that this file should be processed using a format
+with name \m{format-name}. You can use the optional argument \m{release-date}
+to further specify the earliest release date of the format that is needed. When
+the release date of the format is older than the one specified a warning will
+be generated. The standard \m{format-name} is \texttt{LaTeX2e}. The date, if
+present, must be in the form \textsc{yyyy-mm-dd}.
Example:
\begin{verbatim}
- \NeedsTeXFormat{LaTeX2e}[1994/06/01]
+ \NeedsTeXFormat{LaTeX2e}[2022-06-01]
\end{verbatim}
+People often don't know what date to put here. For the kernel, you can find out
+the right one by consulting |changes.txt| and select the release date of a new
+feature you are interested in. This is slightly different for packages as they
+are released throughout the year: you will need to consult their change
+history.
\begin{decl}
|\ProvidesClass| \arg{class-name} \oarg{release-info} \\
|\ProvidesPackage| \arg{package-name} \oarg{release-info}
\end{decl}
-This declares that the current file contains the definitions for the
-document class \m{class-name} or package \m{package-name}.
+This declares that the current file contains the definitions for the document
+class \m{class-name} or package \m{package-name}.
The optional \m{release-info}, if used, must contain:
\begin{itemize}
- \item the release date of
- this version of the file, in the form \textsc{yyyy/mm/dd};
+ \item the release date of this version of the file, in the form
+ \textsc{yyyy-mm-dd};
\item optionally followed by a space and a short description, possibly
including a version number.
\end{itemize}
-The above syntax must be followed exactly so that this information
-can be used by |\LoadClass| or |\documentclass| (for classes) or
-|\RequirePackage| or |\usepackage| (for packages) to test that the
-release is not too old.
+The above syntax must be followed exactly so that this information can be used
+by |\LoadClass| or |\documentclass| (for classes) or |\RequirePackage| or
+|\usepackage| (for packages) to test that the release is not too old.
-The whole of this \m{release-info} information is displayed by
-|\listfiles| and should therefore not be too long.
+The whole of this \m{release-info} information is displayed by |\listfiles| and
+should therefore not be too long.
Example:
\begin{verbatim}
- \ProvidesClass{article}[1994/06/01 v1.0 Standard LaTeX class]
- \ProvidesPackage{ifthen}[1994/06/01 v1.0 Standard LaTeX package]
+ \ProvidesClass{article}[2022-06-01 v1.0 Standard LaTeX class]
+ \ProvidesPackage{ifthen}[2022-06-01 v1.0 Standard LaTeX package]
\end{verbatim}
\begin{decl}
|\ProvidesFile| \arg{file-name} \oarg{release-info}
\end{decl}
This is similar to the two previous commands except that here the full
-filename, including the extension, must be given. It is used for
-declaring any files other than main class and package files.
+filename, including the extension, must be given. It is used for declaring any
+files other than main class and package files.
Example:
\begin{verbatim}
- \ProvidesFile{T1enc.def}[1994/06/01 v1.0 Standard LaTeX file]
+ \ProvidesFile{T1enc.def}[2022-06-01 v1.0 Standard LaTeX file]
\end{verbatim}
-Note that the phrase \texttt{Standard LaTeX} \textbf{must not} be used
-in the identification banner of any file other than those in the
-standard \LaTeX{} distribution.
+Note that the phrase \texttt{Standard LaTeX} \textbf{must not} be used in the
+identification banner of any file other than those in the standard \LaTeX{}
+distribution.
\subsection{Loading files}
\label{Sec:loadf}
-\NEWfeature{1995/12/01}
-This group of commands can be used to create your own document class or
-package by building on existing classes or packages.
+This group of commands can be used to create your own document class or package
+by building on existing classes or packages.
\begin{decl}
|\RequirePackage| \oarg{options-list} \arg{package-name}
\oarg{release-info}\\
@@ -899,13 +744,11 @@ package by building on existing classes or packages.
\end{decl}
Packages and classes should use these commands to load other packages.
-The use of |\RequirePackage| is the same as the author command
-|\usepackage|.
-
+The use of |\RequirePackage| is the same as the author command |\usepackage|.
Examples:
\begin{verbatim}
- \RequirePackage{ifthen}[1994/06/01]
- \RequirePackageWithOptions{graphics}[1995/12/01]
+ \RequirePackage{ifthen}[2022-06-01]
+ \RequirePackageWithOptions{graphics}[2022-06-01]
\end{verbatim}
\begin{decl}
@@ -914,107 +757,153 @@ Examples:
|\LoadClassWithOptions| \arg{class-name}
\oarg{release-info}
\end{decl}
-\NEWfeature{1995/12/01}
-These commands are for use \emph{only} in class files, they cannot be
-used in packages files;
-they can be used at most once within a class file.
+These commands are for use \emph{only} in class files, they cannot be used in
+packages files; they can be used at most once within a class file.
-The use of |\LoadClass| is the same as
-the use of |\documentclass| to load a class file.
+The use of |\LoadClass| is the same as the use of |\documentclass| to load a
+class file.
Examples:
\begin{verbatim}
- \LoadClass{article}[1994/06/01]
- \LoadClassWithOptions{article}[1995/12/01]
+ \LoadClass{article}[2022-06-01]
+ \LoadClassWithOptions{article}[2022-06-01]
\end{verbatim}
-\NEWfeature{1995/12/01}
-The two |WithOptions| versions simply load the class (or package) file
-with exactly those options that are being used by the current file
-(class or package). See below, in \ref{Sec:opmove}, for further
-discussion of their use.
-
+The two |WithOptions| versions simply load the class (or package) file with
+exactly those options that are being used by the current file (class or
+package). See below, in \ref{Sec:opmove}, for further discussion of their use.
-\subsection{Option declaration}
-\label{Sec:commands.options.dec}
+\subsection{Delaying code}
+\label{Sec:delays}
-\NEWdescription{1998/12/01}
-The following commands deal with the declaration and handling of
-options to document classes and packages. Every option name must be a
-`\LaTeX{} name'.
+As noted earlier, a sophisticated hook system is available and described in
+\texttt{lthooks}. Here, we document a small set of convenient short names for
+common hooks.
-There are some commands designed especially for use within the
-\m{code} argument of these commands (see below).
+These first two commands are also intended primarily for use within the
+\m{code} argument of |\DeclareOption| or |\DeclareOption*|.
\begin{decl}
- |\DeclareOption| \arg{option-name} \arg{code}
+ |\AtEndOfClass| \arg{code}\\
+ |\AtEndOfPackage| \arg{code}
\end{decl}
-This makes \m{option-name} a `declared option' of the class or package
-in which it is put.
-
-The \m{code} argument contains the code to be executed if that option
-is specified for the class or package; it can contain any valid
-\LaTeXe{} construct.
+These commands declare \m{code} that is saved away internally and then executed
+after processing the whole of the current class or package file.
-Example:
-\begin{verbatim}
- \DeclareOption{twoside}{\@twosidetrue}
-\end{verbatim}
+Repeated use of these commands is permitted: the code in the arguments is
+stored (and later executed) in the order of their declarations.
\begin{decl}
- |\DeclareOption*| \arg{code}
+ |\AtBeginDocument| \arg{code}\\
+ |\AtEndDocument| \arg{code}
\end{decl}
-This declares the \m{code} to be executed for every option which is
-specified for, but otherwise not explicitly declared by, the class or
-package; this code is called the `default option code' and it can
-contain any valid \LaTeXe{} construct.
+These commands declare \m{code} to be saved internally and executed while
+\LaTeX{} is executing |\begin{document}| or |\end{document}|.
-If a class file contains no |\DeclareOption*| then, by default, all
-specified but undeclared options for that class will be silently
-passed to all packages (as will the specified and declared options for
-that class).
+The \m{code} specified in the argument to |\AtBeginDocument| is executed near
+the end of the |\begin{document}| code, \emph{after} the font selection tables
+have been set up. It is therefore a useful place to put code which needs to be
+executed after everything has been prepared for typesetting and when the normal
+font for the document is the current font.
-If a package file contains no |\DeclareOption*| then, by default, each
-specified but undeclared option for that package will produce an error.
+The |\AtBeginDocument| hook should not be used for code that does any
+typesetting since the typeset result would be unpredictable.
+The \m{code} specified in the argument to |\AtEndDocument| is executed at the
+beginning of the |\end{document}| code, \emph{before} the final page is
+finished and before any leftover floating environments are processed. If some
+of the \m{code} is to be executed after these two processes, you should include
+a |\clearpage| at the appropriate point in \m{code}.
-\subsection{Commands within option code}
-\label{Sec:within.code}
+Repeated use of these commands is permitted: the code in the arguments is
+stored (and later executed) in the order of their declarations.
+
+\subsection{Creating and using keyval options}
+\label{Sec:opt:keyval}
-These two commands can be used only within the \m{code} argument of
-either |\DeclareOption| or |\DeclareOption*|. Other commands commonly
-used within these arguments can be found in the next few subsections.
+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{decl}
- |\CurrentOption|
+ |\DeclareKeys| \oarg{family} \arg{declarations}
\end{decl}
-This expands to the name of the current option.
+This command creates a series of options from a comma-separated
+\m{declarations} list. Each entry in this list is a key--value pair, with the
+\m{key} having one or more \m{properties}. A small number of `basic'
+\m{properties} are described below. The full range of properties, provided by
+\texttt{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{.code} --- execute arbitrary code
+ \item \texttt{.if} --- sets a \TeX{} |\if...| switch
+ \item \texttt{.ifnot} --- sets an inverted \TeX{} |\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 \m{property} is the \m{name}, with the
+\m{value} working with the \m{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 created. The option \texttt{draft} can be given anywhere
+in the preamble, and will set a switch called |\if@mypkg@draft|. The option
+\texttt{name} can only be given during package loading, and will save whatever
+value it is given in |\@mypkg@name|. Finally, the option \texttt{second-name}
+can be given anywhere, and will save its value in |\@mypkg@other@name|.
+
+Keys created \emph{before} the use of |\ProcessKeyOptions| act as package
+options.
\begin{decl}
- |\OptionNotUsed|
+ |\DeclareUnknownKeyHandler| \oarg{family} \arg{code}
\end{decl}
-This causes the current option to
-be added to the list of `unused options'.
+The command |\DeclareUnknownKeyHandler| may be used to define the behavior when
+an undefined key is encountered. The \m{code} will receive the unknown key name
+as |#1| and the value as |#2|. These can then be processed as appropriate,
+e.g.~by forwarding to another package.
-\NEWfeature{1995/06/01}
- You can now include hash marks (\texttt{\#}) within these \m{code}
- arguments without special treatment (formerly, it had been
- necessary to double them).
+\begin{decl}
+ |\ProcessKeyOptions| \oarg{family}
+\end{decl}
+The |\ProcessKeyOptions| function is used to check the current option list
+against the keys defined for \m{family}. Global (class) options and local
+(package) options are checked when this function is called in a package.
-\subsection{Moving options around}
+\begin{decl}
+ |\SetKeys| \oarg{family} \arg{keyvals}
+\end{decl}
+Sets (applies) the explicit list of \m{keyvals} for the \m{family}: if the
+latter is not given, the value of |\@currname| is used. This command may be used
+within a package to set options before or after using |\ProcessKeyOptions|.
+
+\subsection{Passing options around}
\label{Sec:opmove}
-These two commands are also very useful within the \m{code} argument
-of |\DeclareOption| or |\DeclareOption*|:
+These two commands are also very useful within the \m{code} argument of
+options.
\begin{decl}
|\PassOptionsToPackage| \arg{options-list} \arg{package-name}\\
|\PassOptionsToClass| \arg{options-list} \arg{class-name}
\end{decl}
-The command |\PassOptionsToPackage| passes the option names in
-\m{options-list} to package \m{package-name}.
-This means that it adds the \m{option-list} to the
-list of options used by any future |\RequirePackage| or |\usepackage|
-command for package \m{package-name}.
+The command |\PassOptionsToPackage| passes the option names in \m{options-list}
+to package \m{package-name}. This means that it adds the \m{option-list} to the
+list of options used by any future |\RequirePackage| or |\usepackage| command
+for package \m{package-name}.
Example:
\begin{verbatim}
@@ -1026,24 +915,22 @@ is the same as:
\RequirePackage[foo,bar,baz]{fred}
\end{verbatim}
-Similarly, |\PassOptionsToClass| may be used in a class file to pass
-options to another class to be loaded with |\LoadClass|.
+Similarly, |\PassOptionsToClass| may be used in a class file to pass options to
+another class to be loaded with |\LoadClass|.
-\NEWdescription{1995/12/01}
-The effects and use of these two commands should be contrasted with
-those of the following two (documented above, in \ref{Sec:loadf}):
+The effects and use of these two commands should be contrasted with those of
+the following two (documented above, in \ref{Sec:loadf}):
\begin{verbatim}
\LoadClassWithOptions
\RequirePackageWithOptions
\end{verbatim}
-The command |\RequirePackageWithOptions| is similar to
-|\RequirePackage|, but it always loads the required package with
-exactly the same option list as that being used by the current class
-or package, rather than with any option explicitly supplied or passed
-on by |\PassOptionsToPackage|.
+The command |\RequirePackageWithOptions| is similar to |\RequirePackage|, but
+it always loads the required package with exactly the same option list as that
+being used by the current class or package, rather than with any option
+explicitly supplied or passed on by |\PassOptionsToPackage|.
-The main purpose of |\LoadClassWithOptions| is to allow one class to
-simply build on another, for example:
+The main purpose of |\LoadClassWithOptions| is to allow one class to simply
+build on another, for example:
\begin{verbatim}
\LoadClassWithOptions{article}
\end{verbatim}
@@ -1053,12 +940,11 @@ This should be compared with the slightly different construction
\ProcessOptions\relax
\LoadClass{article}
\end{verbatim}
-As used above, the effects are more or less the same, but the first is
-a lot less to type; also the |\LoadClassWithOptions| method runs
-slightly quicker.
+As used above, the effects are more or less the same, but the first is a lot
+less to type; also the |\LoadClassWithOptions| method runs slightly quicker.
-If, however, the class declares options of its own then
-the two constructions are different. Compare, for example:
+If, however, the class declares options of its own then the two constructions
+are different. Compare, for example:
\begin{verbatim}
\DeclareOption{landscape}{\@landscapetrue}
\ProcessOptions\relax
@@ -1071,255 +957,56 @@ with:
\ProcessOptions\relax
\LoadClass{article}
\end{verbatim}
-In the first example, the \textsf{article} class will be loaded with
-option |landscape| precisely when the current class is called with
-this option. By contrast, in the second example it will never be
-called with option \texttt{landscape} as in that case \textsf{article}
-is passed options only by the default option handler, but this handler
-is not used for |landscape| because that option is explicitly
-declared.
-
-\subsection{Delaying code}
-\label{Sec:delays}
-
-These first two commands are also intended primarily for use within
-the \m{code} argument of |\DeclareOption| or |\DeclareOption*|.
-
-\begin{decl}
- |\AtEndOfClass| \arg{code}\\
- |\AtEndOfPackage| \arg{code}
-\end{decl}
-These commands declare \m{code} that is saved away internally and then
-executed after processing the whole of the current class or package
-file.
-
-Repeated use of these commands is permitted: the code in the
-arguments is stored (and later executed) in the order of their
-declarations.
-
-\begin{decl}
- |\AtBeginDocument| \arg{code}\\
- |\AtEndDocument| \arg{code}
-\end{decl}
-These commands declare \m{code} to be saved internally and executed
-while \LaTeX{} is executing |\begin{document}| or |\end{document}|.
-
-The \m{code} specified in the argument to |\AtBeginDocument| is
-executed near the end of the |\begin{document}| code, \emph{after} the
-font selection tables have been set up. It is therefore a useful
-place to put code which needs to be executed after everything has been
-prepared for typesetting and when the normal font for the document is
-the current font.
-
-\NEWdescription{1995/12/01}
-The |\AtBeginDocument| hook should not be used for code that does any
-typesetting since the typeset result would be unpredictable.
-
-The \m{code} specified in the argument to |\AtEndDocument| is
-executed at the beginning of the |\end{document}| code,
-\emph{before} the final page is finished and before any leftover
-floating environments are processed. If some of the \m{code} is to be
-executed after these two processes, you should include a |\clearpage|
-at the appropriate point in \m{code}.
-
-Repeated use of these commands is permitted: the code in the
-arguments is stored (and later executed) in the order of their
-declarations.
-
-\begin{decl}[1994/12/01]
- |\AtBeginDvi| \arg{specials}
-\end{decl}
-These commands save in a box register things which are written to the
-|.dvi| file at the beginning of the `shipout' of the first page of the
-document.
-
-This should not be used for anything that will add any typeset
-material to the |.dvi| file.
-
-Repeated use of this command is permitted.
-
-
-\subsection{Option processing}
-\label{Sec:commands.options}
-
-\begin{decl}
- |\ProcessOptions|
-\end{decl}
-This command executes the \m{code} for each selected option.
-
-We shall first describe how |\ProcessOptions| works in a package file,
-and then how this differs in a class file.
-
-To understand in detail what |\ProcessOptions| does in a package file,
-you have to know the difference between \emph{local} and \emph{global}
-options.
-\begin{itemize}
-\item \textbf{Local options} are those which have been explicitly
- specified for this particular package in the \m{options} argument of
- any of these:
-\begin{quote}
- |\PassOptionsToPackage{<options>}| \ |\usepackage[<options>]|\\
- |\RequirePackage[<options>]|
-\end{quote}
-\item \textbf{Global options} are any other options that are specified
- by the author in the \m{options} argument of
- |\documentclass[<options>]|.
-\end{itemize}
-For example, suppose that a document begins:
-\begin{verbatim}
- \documentclass[german,twocolumn]{article}
- \usepackage{gerhardt}
-\end{verbatim}
-whilst package |gerhardt| calls package |fred| with:
-\begin{verbatim}
- \PassOptionsToPackage{german,dvips,a4paper}{fred}
- \RequirePackage[errorshow]{fred}
-\end{verbatim}
-then:
-\begin{itemize}
-\item |fred|'s local options are |german|, |dvips|, |a4paper|
- and |errorshow|;
-\item |fred|'s only global option is |twocolumn|.
-\end{itemize}
-
-When |\ProcessOptions| is called, the following happen.
-\begin{itemize}
-\item \emph{First}, for each option so far declared in |fred.sty|
- by |\DeclareOption|, it looks to see if that option is either a
- global or a local option for |fred|: if it is then the corresponding
- code is executed.
-
- This is done in the order in which these options
- were declared in |fred.sty|.
-\item \emph{Then}, for each remaining \emph{local} option, the command
- |\ds@<option>| is executed if it has been defined somewhere (other
- than by a |\DeclareOption|); otherwise, the `default option code' is
- executed. If no default option code has been declared then an error
- message is produced.
-
- This is done in the order in which these
- options were specified.
-\end{itemize}
-Throughout this process, the system ensures that the code declared for
-an option is executed at most once.
-
-Returning to the example, if |fred.sty| contains:
-\begin{verbatim}
- \DeclareOption{dvips}{\typeout{DVIPS}}
- \DeclareOption{german}{\typeout{GERMAN}}
- \DeclareOption{french}{\typeout{FRENCH}}
- \DeclareOption*{\PackageWarning{fred}{Unknown `\CurrentOption'}}
- \ProcessOptions\relax
-\end{verbatim}
-then the result of processing this document will be:
-\begin{verbatim}
- DVIPS
- GERMAN
- Package fred Warning: Unknown `a4paper'.
- Package fred Warning: Unknown `errorshow'.
-\end{verbatim}
-Note the following:
-
-\begin{itemize}
-\item the code for the |dvips| option is executed before that for the
- |german| option, because that is the order in which they are declared
- in |fred.sty|;
-\item the code for the |german| option is executed only once, when the
- declared options are being processed;
-\item the |a4paper| and |errorshow| options produce the warning from
- the code declared by |\DeclareOption*| (in the order in which they
- were specified), whilst the |twocolumn| option does not: this is
- because |twocolumn| is a global option.
-\end{itemize}
-
-In a class file, |\ProcessOptions| works in the same way, except
-that: \emph{all} options are local; and the default value for
-|\DeclareOption*| is |\OptionNotUsed| rather than an error.
-
-\NEWdescription{1995/12/01}
-Note that, because |\ProcessOptions| has a |*|-form, it is wise to
-follow the non-star form with |\relax|, as in the previous examples,
-since this prevents unnecessary look ahead and possibly misleading
-error messages being issued.
-
-\begin{decl}
- |\ProcessOptions*| \\
- |\@options|
-\end{decl}
-This is like |\ProcessOptions| but it executes the options in the
-order specified in the calling commands, rather than in the order of
-declaration in the class or package. For a package this means that the
-global options are processed first.
-
-The |\@options| command from \LaTeX~2.09 has been made equivalent to
-this in order to ease the task of updating old document styles to
-\LaTeXe{} class files.
-
-\begin{decl}
- |\ExecuteOptions| \arg{options-list}
-\end{decl}
-
-For each option in the \m{options-list}, in order,
-this command simply executes the command
-|\ds@<option>| (if this command is not defined, then that option is
-silently ignored).
-
-It can be used to provide a `default option list' just before
-|\ProcessOptions|. For example, suppose that in a class file you want
-to set up the default design to be: two-sided printing; 11pt fonts;
-in two columns. Then it could specify:
-\begin{verbatim}
- \ExecuteOptions{11pt,twoside,twocolumn}
-\end{verbatim}
-
+In the first example, the \textsf{article} class will be loaded with option
+|landscape| precisely when the current class is called with this option. By
+contrast, in the second example it will never be called with option |landscape|
+as in that case \textsf{article} is passed options only by the default option
+handler, but this handler is not used for |landscape| because that option is
+explicitly declared.
\subsection{Safe file commands}
-These commands deal with file input; they ensure that the non-existence
-of a requested file can be handled in a user-friendly way.
+These commands deal with file input; they ensure that the non-existence of a
+requested file can be handled in a user-friendly way.
\begin{decl}
|\IfFileExists| \arg{file-name} \arg{true} \arg{false}
\end{decl}
-If the file exists then the code specified in \m{true} is
-executed.
+If the file exists then the code specified in \m{true} is executed.
-If the file does not exist then the code specified in \m{false} is
-executed.
+If the file does not exist then the code specified in \m{false} is executed.
This command does \emph{not} input the file.
\begin{decl}
|\InputIfFileExists| \arg{file-name} \arg{true} \arg{false}
\end{decl}
-This inputs the file \m{file-name} if it exists and, immediately
-before the input, the code specified in \m{true} is executed.
+This inputs the file \m{file-name} if it exists and, immediately before the
+input, the code specified in \m{true} is executed.
-If the file does not exist then the code specified in \m{false} is
-executed.
+If the file does not exist then the code specified in \m{false} is executed.
It is implemented using |\IfFileExists|.
-
\subsection{Reporting errors, etc}
-These commands should be used by third party classes and packages to
-report errors, or to provide information to authors.
+These commands should be used by third party classes and packages to report
+errors, or to provide information to authors.
\begin{decl}
|\ClassError| \arg{class-name} \arg{error-text} \arg{help-text}\\
|\PackageError| \arg{package-name} \arg{error-text} \arg{help-text}
\end{decl}
-These produce an error message. The \m{error-text} is displayed and the
-|?| error prompt is shown. If the user types |h|, they will be shown
-the \m{help-text}.
+These produce an error message. The \m{error-text} is displayed and the |?|
+error prompt is shown. If the user types |h|, they will be shown the
+\m{help-text}.
-Within the \m{error-text} and \m{help-text}: |\protect| can be used to
-stop a command from expanding; |\MessageBreak| causes a line-break;
-and |\space| prints a space.
+Within the \m{error-text} and \m{help-text}: |\protect| can be used to stop a
+command from expanding; |\MessageBreak| causes a line-break; and |\space|
+prints a space.
-Note that the \m{error-text} will have a full stop added to it, so do
-not put one into the argument.
+Note that the \m{error-text} will have a full stop added to it, so do not put
+one into the argument.
For example:
\begin{verbatim}
@@ -1354,96 +1041,22 @@ If the user types |h|, this will be shown:
|\ClassInfo| \arg{class-name} \arg{info-text}\\
|\PackageInfo| \arg{package-name} \arg{info-text}
\end{decl}
-The four |Warning| commands are similar to the error commands, except
-that they produce only a warning on the screen, with no error prompt.
+The four |Warning| commands are similar to the error commands, except that they
+produce only a warning on the screen, with no error prompt.
-The first two, |Warning| versions, also show the line number where the
-warning occurred, whilst the second two, |WarningNoLine| versions, do
-not.
+The first two, |Warning| versions, also show the line number where the warning
+occurred, whilst the second two, |WarningNoLine| versions, do not.
-The two |Info| commands are similar except that they log the
-information only in the transcript file, including the line number.
-There are no |NoLine| versions of these two.
+The two |Info| commands are similar except that they log the information only
+in the transcript file, including the line number. There are no |NoLine|
+versions of these two.
-Within the \m{warning-text} and \m{info-text}: |\protect| can be used to
-stop a command from expanding; |\MessageBreak| causes a line-break;
-and |\space| prints a space.
-Also, these should not end with a full stop as one is
+Within the \m{warning-text} and \m{info-text}: |\protect| can be used to stop a
+command from expanding; |\MessageBreak| causes a line-break; and |\space|
+prints a space. Also, these should not end with a full stop as one is
automatically added.
-
-\subsection{Defining commands}
-\label{Sec:commands.define}
-
-\LaTeXe{} provides some extra methods of (re)defining commands that are
-intended for use in class and package files.
-
-\NEWfeature{1994/12/01}
-The \texttt{*}-forms of these commands should be used to define
-commands that are not, in \TeX{} terms, long. This can be useful for
-error-trapping with commands whose arguments are not intended to
-contain whole paragraphs of text.
-
-\begin{decl}
- |\DeclareRobustCommand| \arg{cmd} \oarg{num} \oarg{default}
- \arg{definition}\\
- |\DeclareRobustCommand*| \arg{cmd} \oarg{num} \oarg{default}
- \arg{definition}
-\end{decl}
-This command takes the same arguments as |\newcommand| but it declares
-a robust command, even if some code within the \m{definition} is
-fragile. You can use this command to define new robust commands, or
-to redefine existing commands and make them robust. A log is put into
-the transcript file if a command is redefined.
-
-For example, if |\seq| is defined as follows:
-\begin{verbatim}
- \DeclareRobustCommand{\seq}[2][n]{%
- \ifmmode
- #1_{1}\ldots#1_{#2}%
- \else
- \PackageWarning{fred}{You can't use \protect\seq\space in text}%
- \fi
- }
-\end{verbatim}
-Then the command |\seq| can be used in moving arguments, even though
-|\ifmmode| cannot, for example:
-\begin{verbatim}
- \section{Stuff about sequences $\seq{x}$}
-\end{verbatim}
-
-Note also that there is no need to put a |\relax| before the
-|\ifmmode| at the beginning of the definition; this is because the
-protection given by this |\relax| against expansion at the wrong time
-will be provided internally.
-
-\begin{decl}
- |\CheckCommand| \arg{cmd} \oarg{num} \oarg{default}
- \arg{definition}\\
- |\CheckCommand*| \arg{cmd} \oarg{num} \oarg{default}
- \arg{definition}
-\end{decl}
-This takes the same arguments as |\newcommand| but, rather than define
-\m{cmd}, it just checks that the current definition of \m{cmd} is
-exactly as given by \m{definition}. An error is raised if these
-definitions differ.
-
-This command is useful for checking the state of the system before
-your package starts altering the definitions of commands. It allows
-you to check, in particular, that no other package has redefined the
-same command.
-
-\subsection{Moving arguments}
-
-\NEWdescription{1994/12/01}
-The setting of protect whilst processing (i.e.~moving) moving arguments
-has been reimplemented, as has the method of writing information from
-the |.aux| file to other files such as the |.toc| file. Details can
-be found in the file |ltdefns.dtx|.
-
-We hope that these changes will not affect many packages.
-
-\section{Miscellaneous commands, etc}
+\section{Miscellaneous commands, etc.}
\label{Sec:commands.misc}
\subsection{Layout parameters}
@@ -1452,78 +1065,25 @@ We hope that these changes will not affect many packages.
|\paperheight|\\
|\paperwidth|
\end{decl}
-These two parameters are usually set by the class to be the size of
-the paper being used. This should be actual paper size, unlike
-|\textwidth| and |\textheight| which are the size of the main text
-body within the margins.
-
+These two parameters are usually set by the class to be the size of the paper
+being used. This should be actual paper size, unlike |\textwidth| and
+|\textheight| which are the size of the main text body within the margins.
\subsection{Case changing}
\label{sec:case}
\begin{decl}
|\MakeUppercase| \arg{text} \\
- |\MakeLowercase| \arg{text}
+ |\MakeLowercase| \arg{text} \\
+ |\MakeTitlecase| \arg{text}
\end{decl}
-\NEWfeature{1995/06/01}
-\TeX{} provides two primitives |\uppercase| and |\lowercase| for
-changing the case of text. These are sometimes used in document
-classes, for example to set information in running heads in all
-capitals.
-
-Unfortunately, these \TeX{} primitives do not change the case of
-characters accessed by commands like |\ae| or |\aa|. To overcome this
-problem, \LaTeX{} provides two new commands |\MakeUppercase| and
-|\MakeLowercase| to do this.
-
-For example:
-\begin{quotation}
-\begin{tabular}{rl}
- |\uppercase{aBcD\ae\AA\ss\OE}| & \uppercase{aBcD\ae\AA\ss\OE}\\
- |\lowercase{aBcD\ae\AA\ss\OE}| & \lowercase{aBcD\ae\AA\ss\OE}\\
- |\MakeUppercase{aBcD\ae\AA\ss\OE}| &
- \MakeUppercase{aBcD\ae\AA\ss\OE}\\
- |\MakeLowercase{aBcD\ae\AA\ss\OE}| & \MakeLowercase{aBcD\ae\AA\ss\OE}
-\end{tabular}
-\end{quotation}
-
-The commands |\MakeUppercase| and |\MakeLowercase| themselves are
-robust, but they have moving arguments.
-
-The commands use the \TeX{} primitives |\uppercase| and |\lowercase|,
-and so have a number of unexpected `features'. In particular, they
-change the case of everything (except characters in the names of
-control-sequences) in their text argument: this includes mathematics,
-environment names, and label names.
-
-For example:
-\begin{verbatim}
- \MakeUppercase{$x+y$ in \ref{foo}}
-\end{verbatim}
-produces $X+Y$ and the warning:
-\begin{verbatim}
- LaTeX Warning: Reference `FOO' on page ... undefined on ...
-\end{verbatim}
-In the long run, we would like to use all-caps fonts rather than any
-command like |\MakeUppercase| but this is not possible at the moment
-because such fonts do not exist.
-
-\NEWdescription{1995/12/01}
-In order that upper/lower-casing will work reasonably well, and in
-order to provide any correct hyphenation, \LaTeXe{} \emph{must} use,
-throughout a document, the same fixed table for changing case.
-The table used is designed for the font encoding |T1|; this works well
-with the standard \TeX{} fonts for all Latin alphabets but will cause
-problems when using other alphabets.
-
-\subsection{The `openany' option in the `book' class}
-
-\NEWdescription{1996/06/01}
-The |openany| option allows chapter and similar openings to
-occur on left hand pages. Previously this option affected only
-|\chapter| and |\backmatter|. It now also affects
-|\part|, |\frontmatter| and |\mainmatter|.
+As described in \texttt{usrguide}, case changing for text should be carried out
+using the commands |\MakeUppercase|, |\MakeLowercase| and
+|\MakeTitlecase|. If you need to change the case of programmatic material, the
+team strongly suggest using the L3 programming layer commands in the
+\texttt{str} module. If you do not wish to do this, you should use the \TeX{}
+|\uppercase| and |\lowercase| primitives \emph{in this situation only}.
\subsection{Better user-defined math display environments}
@@ -1531,11 +1091,8 @@ occur on left hand pages. Previously this option affected only
|\ignorespacesafterend|
\end{decl}
-\NEWfeature{1996/12/01}
-\NEWdescription{2003/12/01}
-Suppose that you want to define an environment for displaying text
-that is numbered as an equation. A straightforward way to do this is
-as follows:
+Suppose that you want to define an environment for displaying text that is
+numbered as an equation. A straightforward way to do this is as follows:
\begin{verbatim}
\newenvironment{texteqn}
{\begin{equation}
@@ -1543,13 +1100,13 @@ as follows:
{\end{minipage}
\end{equation}}
\end{verbatim}
-However, if you have tried this then you will probably have noticed
-that it does not work perfectly when used in the middle of a paragraph
-because an inter-word space appears at the beginning of the first
-line after the environment.
+However, if you have tried this then you will probably have noticed that it
+does not work perfectly when used in the middle of a paragraph because an
+inter-word space appears at the beginning of the first line after the
+environment.
-There is now an extra command (with a very long name) available that
-you can use to avoid this problem; it should be inserted as shown here:
+You can avoid this problem using |\ignorespacesafterend|; it should be
+inserted as shown here:
\begin{verbatim}
\newenvironment{texteqn}
{\begin{equation}
@@ -1567,312 +1124,298 @@ This command may also have other uses.
|\normalsfcodes|
\end{decl}
-\NEWfeature{1997/06/01}
This command should be used to restore the normal settings of the
parameters that affect spacing between words, sentences, etc.
-An important use of this feature is to correct a problem, reported by
-Donald Arseneau, that punctuation in page headers has always (in all
-known \TeX{} formats) been potentially wrong whenever a page break
-happens while a local setting of the space codes is in effect. These
-space codes are changed by, for example, the command
-\verb|\frenchspacing|) and the \textsf{verbatim} environment.
-
-It is normally given the correct definition automatically in
-|\begin{document}| and so need not be explicitly set; however, if it
-is explicitly made nonempty in a class file then automatic
-default setting will be over-ridden.
-
-
-\section{Upgrading \LaTeX~2.09 classes and packages}
-\label{Sec:upgrade}
-
-This section describes the changes you may need to make when you
-upgrade an existing \LaTeX{} style to a package or class but we shall
-start in optimistic mode.
-
-Many existing style files will run with \LaTeXe{} without any
-modification to the file itself. When everything is running OK,
-please put a note in the newly created package or class file to record
-that it runs with the new standard \LaTeX{}; then distribute it to
-your users.
-
-\subsection{Try it first!}
-\label{Sec:try-it}
-
-The first thing you should do is to test your style in `compatibility
-mode'. The only change you need to make in order to do this is,
-possibly, to change the extension of the file to |.cls|: you should
-make this change only if your file was used as a main document style.
-Now, without any other modifications, run \LaTeXe{} on a document that
-uses your file. This assumes that you have a suitable collection of
-files that tests all the functionality provided by your style file.
-(If you haven't, now is the time to make one!)
-
-You now need to change the test document files so that they are
-\LaTeXe{} documents: see \emph{\usrguide} for details of how to do
-this and then try them again. You have now tried the test documents
-in both \LaTeXe{} native mode and \LaTeX~2.09 compatibility mode.
-
-\subsection{Troubleshooting}
-\label{Sec:trouble}
-
-If your file does not work with \LaTeXe{}, there are two likely
-reasons.
+An important use of this feature is to correct a problem, reported by Donald
+Arseneau, that punctuation in page headers has always (in all known \TeX{}
+formats) been potentially wrong whenever a page break happens while a local
+setting of the space codes is in effect. These space codes are changed by, for
+example, the command \verb|\frenchspacing|) and the \textsf{verbatim}
+environment.
+
+It is normally given the correct definition automatically in |\begin{document}|
+and so need not be explicitly set; however, if it is explicitly made non-empty
+in a class file then automatic default setting will be over-ridden.
+
+\subsection{Querying localisation}
+
+Localisation information is needed to customise a range of outputs. The
+\LaTeX{} kernel does not itself manage localisation, which is well-served by
+the bundles \pkg{babel} and \pkg{polyglossia}. To allow the kernel and other
+packages to access the current localisation information provided by \pkg{babel}
+or \pkg{polyglossia}, the command \cs{BCPdata} is defined by the kernel. The
+initial kernel definition expands to tag parts for \texttt{en-US}, as the
+kernel does not track localisation but does start out with a broadly US~English
+setup. However, if \pkg{babel} or \pkg{polyglossia} are loaded, it is redefined
+expand to the BCP-47 information from the appropriate package. The supported
+arguments are the BCP-47 tag breakdowns:
\begin{itemize}
-\item \LaTeX{} now has a robust, well-defined designer's interface for
- selecting fonts, which is very different from the \LaTeX~2.09
- internals.
-\item Your style file may have used some \LaTeX~2.09 internal commands
- which have changed, or which have been removed.
+ \item \texttt{tag} The full BCP-47 tag (e.g.~\texttt{en-US})
+ \item \texttt{language} (e.g.,~\texttt{de})
+ \item \texttt{region} (e.g.,~\texttt{AT})
+ \item \texttt{script} (e.g.,~\texttt{Latn})
+ \item \texttt{variant} (e.g.,~\texttt{1901})
+ \item \texttt{extension.t} (transformation, e.g.,~\texttt{en-t-ja})
+ \item \texttt{extension.u} (additional locale
+ information, e.g.,~\texttt{ar-u-nu-latn})
+ \item \texttt{extension.x} (private use area, e.g.,~\texttt{la-x-classic})
\end{itemize}
+The information for the \emph{main} language for a document is be provided
+if these are prefixed by \texttt{main.}, e.g.~\texttt{main.language} will
+expand to the main language even if another language is currently active.
-When you are debugging your file, you will probably need more
-information than is normally displayed by \LaTeXe. This is achieved
-by resetting the counter |errorcontextlines| from its default value of
-$-1$ to a much higher value, e.g.~999.
-
-\subsection{Accommodating compatibility mode}
-
-Sometimes an existing collection of \LaTeX~2.09 documents makes it
-inconvenient or impossible to abandon the old commands entirely.
-If this is the case, then it is possible to accommodate both conventions
-by making special provision for documents processed in compatibility
-mode.
+In addition to the tag breakdown, the following semantic arguments are
+supported
+\begin{itemize}
+ \item \texttt{casing} The tag for case changing, e.g.~\texttt{el-x-iota}
+ could be selected rather than \texttt{el} to select a capital adscript
+ iota on uppercasing an \emph{ypogegrammeni}
+\end{itemize}
-\begin{decl}
-|\if@compatibility|
-\end{decl}
-This switch is set when a document begins with |\documentstyle| rather
-than |\documentclass|. Appropriate code can be supplied for either
-condition, as follows:
+For example, the case changing command \cs{MakeUppercase} is (conceptually)
+defined as
\begin{verbatim}
- \if@compatibility
- <code emulating LaTeX 2.09 behavior>
- \else
- <code suitable for LaTeX2e>
- \fi
+\ExpandArgs{e}\MakeUppercaseAux{\BCPdata{casing}}{#1}
\end{verbatim}
+where |#1| is the user input and the first argument to
+\cs{MakeUppercaseAux} takes two arguments, the locale and input text.
+
+\section{Commands superseded for new material}
+A small number of commands were introduced as part of \LaTeXe{} in the
+mid-1990s, are widely used but have been superseded by more modern methods.
+These are covered here as they are likely to be encountered routinely in
+existing classes and packages.
-\subsection{Font commands}
+\subsection{Defining commands}
-Some font and size commands are now defined by the document class
-rather than by the \LaTeX{} kernel. If you are upgrading a
-\LaTeX~2.09 document style to a class that does not load one of the
-standard classes, then you will probably need to add definitions for
-these commands.
+The \texttt{*}-forms of these commands should be used to define
+commands that are not, in \TeX{} terms, long. This can be useful for
+error-trapping with commands whose arguments are not intended to
+contain whole paragraphs of text.
\begin{decl}
- |\rm| |\sf| |\tt| |\bf| |\it| |\sl| |\sc|
+ |\DeclareRobustCommand| \arg{cmd} \oarg{num} \oarg{default}
+ \arg{definition}\\
+ |\DeclareRobustCommand*| \arg{cmd} \oarg{num} \oarg{default}
+ \arg{definition}
\end{decl}
-None of these short-form font selection commands are defined in the
-\LaTeXe{} kernel. They are defined by all the standard class files.
-
-If you want to define them in your class file, there are several
-reasonable ways to do this.
-
-One possible definition is:
-\begin{verbatim}
- \newcommand{\rm}{\rmfamily}
- ...
- \newcommand{\sc}{\scshape}
-\end{verbatim}
-This would make the font commands orthogonal; for example
-|{\bf\it text}| would produce bold italic, thus: \textbf{\textit{text}}.
-It will also make them produce an error if used in math mode.
+This command takes the same arguments as |\newcommand| but it declares a robust
+command, even if some code within the \m{definition} is fragile. You can use
+this command to define new robust commands, or to redefine existing commands
+and make them robust. A log is put into the transcript file if a command is
+redefined.
-Another possible definition is:
+For example, if |\seq| is defined as follows:
\begin{verbatim}
- \DeclareOldFontCommand{\rm}{\rmfamily}{\mathrm}
- ...
- \DeclareOldFontCommand{\sc}{\scshape}{\mathsc}
+ \DeclareRobustCommand{\seq}[2][n]{%
+ \ifmmode
+ #1_{1}\ldots#1_{#2}%
+ \else
+ \PackageWarning{fred}{You can't use \protect\seq\space in text}%
+ \fi
+ }
\end{verbatim}
-This will make |\rm| act like |\rmfamily| in text mode (see above) and
-it will make |\rm| select the |\mathrm| math alphabet in math mode.
-
-Thus |${\rm math} = X + 1$| will produce `${\rm math} = X + 1$'.
-
-If you do not want font selection to be orthogonal then you can
-follow the standard classes and define:
+Then the command |\seq| can be used in moving arguments, even though
+|\ifmmode| cannot, for example:
\begin{verbatim}
- \DeclareOldFontCommand{\rm}{\normalfont\rmfamily}{\mathrm}
- ...
- \DeclareOldFontCommand{\sc}{\normalfont\scshape}{\mathsc}
+ \section{Stuff about sequences $\seq{x}$}
\end{verbatim}
-This means, for example, that |{\bf\it text}| will produce medium
-weight (rather than bold) italic, thus: \textit{text}.
-\begin{decl}
- |\normalsize| \\
- |\@normalsize|
-\end{decl}
-The command |\@normalsize| is retained for compatibility with
-\LaTeX~2.09 packages which may have used its value; but redefining it
-in a class file will have no effect since it is always reset to have
-the same meaning as |\normalsize|.
-
-This means that classes \emph{must} now redefine |\normalsize| rather
-than redefining |\@normalsize|; for example (a rather incomplete one):
-\begin{verbatim}
- \renewcommand{\normalsize}{\fontsize{10}{12}\selectfont}
-\end{verbatim}
-Note that |\normalsize| is defined by the \LaTeX{} kernel to be an
-error message.
+Note also that there is no need to put a |\relax| before the |\ifmmode| at the
+beginning of the definition; this is because the protection given by this
+|\relax| against expansion at the wrong time will be provided internally.
\begin{decl}
- |\tiny| |\footnotesize| |\small| |\large|\\
- |\Large| |\LARGE| |\huge| |\Huge|
+ |\CheckCommand| \arg{cmd} \oarg{num} \oarg{default}
+ \arg{definition}\\
+ |\CheckCommand*| \arg{cmd} \oarg{num} \oarg{default}
+ \arg{definition}
\end{decl}
-None of these other `standard' size-changing commands are defined in
-the kernel: each needs to be defined in a class file if you need it.
-They are all defined by the standard classes.
-
-This means you should use |\renewcommand| for |\normalsize| and
-|\newcommand| for the other size-changing commands.
-
+This takes the same arguments as |\newcommand| but, rather than define \m{cmd},
+it just checks that the current definition of \m{cmd} is exactly as given by
+\m{definition}. An error is raised if these definitions differ.
-\subsection{Obsolete commands}
+This command is useful for checking the state of the system before your package
+starts altering the definitions of commands. It allows you to check, in
+particular, that no other package has redefined the same command.
-Some packages will not work with \LaTeXe{}, normally because they relied
-on an internal \LaTeX{} command which was never supported and has now
-changed, or been removed.
-
-In many cases there will now be a robust, high-level means of
-achieving what previously required low-level commands. Please consult
-Section~\ref{Sec:commands} to see if you can now use the \LaTeXe{}
-class and package writers commands.
-
-Also, of course, if your package or class redefined any of the kernel
-commands (i.e.~those defined in the files |latex.tex|, |slitex.tex|,
-|lfonts.tex|, |sfonts.tex|) then you will need to check it very
-carefully against the new kernel in case the implementation has
-changed or the command no longer exists in the \LaTeX2e{} kernel.
+\subsection{Option declaration}
+\label{Sec:commands.options.dec}
-Too many of the internal commands of \LaTeX~2.09 have been
-re-implemented or removed to be able to list them all here. You must
-check any that you have used or changed.
+The following commands deal with the declaration and handling of options to
+document classes and packages using a classical `simple text' approach. Every
+option name must be a `\LaTeX{} name'.
-We shall, however, list some of the more important commands which are
-no longer supported.
+There are some commands designed especially for use within the \m{code}
+argument of these commands (see below).
\begin{decl}
- |\tenrm| |\elvrm| |\twlrm| \dots\\
- |\tenbf| |\elvbf| |\twlbf| \dots\\
- |\tensf| |\elvsf| |\twlsf| \dots\\
- \qquad$\vdots$
+ |\DeclareOption| \arg{option-name} \arg{code}
\end{decl}
-The (approximately) seventy internal commands of this form are no longer
-defined. If your class or package uses them then \emph{please}
-replace them with new font commands described in \emph{\fntguide}.
+This makes \m{option-name} a `declared option' of the class or package in which
+it is put.
+
+The \m{code} argument contains the code to be executed if that option is
+specified for the class or package; it can contain any valid \LaTeXe{}
+construct.
-For example, the command |\twlsf| should be replaced by:
+Example:
\begin{verbatim}
- \fontsize{12}{14}\normalfont\sffamily\selectfont
+ \DeclareOption{twoside}{\@twosidetrue}
\end{verbatim}
-Another possibility is to use the |rawfonts| package, described in
-\emph{\usrguide}.
-
-Also, remember that many of the fonts preloaded by \LaTeX~2.09
-are no longer preloaded.
-
\begin{decl}
- |\vpt| |\vipt| |\viipt| \dots
+ |\DeclareOption*| \arg{code}
\end{decl}
-These were the internal size-selecting commands in \LaTeX~2.09.
-(They can still be used in \LaTeX~2.09 compatibility mode.)
-Please use the command |\fontsize| instead: see \emph{\fntguide} for
-details.
+This declares the \m{code} to be executed for every option which is specified
+for, but otherwise not explicitly declared by, the class or package; this code
+is called the `default option code' and it can contain any valid \LaTeXe{}
+construct.
-For example, |\vpt| should be replaced by:
-\begin{verbatim}
- \fontsize{5}{6}\normalfont\selectfont
-\end{verbatim}
+If a class file contains no |\DeclareOption*| then, by default, all specified
+but undeclared options for that class will be silently passed to all packages
+(as will the specified and declared options for that class).
+
+If a package file contains no |\DeclareOption*| then, by default, each
+specified but undeclared option for that package will produce an error.
+
+\subsection{Commands within option code}
+\label{Sec:within.code}
+
+These two commands can be used only within the \m{code} argument of either
+|\DeclareOption| or |\DeclareOption*|. Other commands commonly used within
+these arguments can be found in the next few subsections.
\begin{decl}
- |\prm|, |\pbf|, |\ppounds|, |\pLaTeX| \dots
+ |\CurrentOption|
\end{decl}
-\LaTeX~2.09 used several commands beginning with |\p| in order to
-provide `protected' commands. For example, |\LaTeX| was defined to be
-|\protect\pLaTeX|, and |\pLaTeX| was defined to produce the \LaTeX{}
-logo. This made |\LaTeX| robust, even though |\pLaTeX| was not.
-
-These commands have now been reimplemented using
-|\DeclareRobustCommand|
-(described in Section~\ref{Sec:commands.define}).
-If your package redefined one of the |\p|-commands then you must
-remove the redefinition and use |\DeclareRobustCommand| to redefine the
-non-|\p| command.
+This expands to the name of the current option.
\begin{decl}
-|\footheight|\\
-|\@maxsep|\\
-|\@dblmaxsep|
+ |\OptionNotUsed|
\end{decl}
-These parameters are not used by \LaTeXe{} so they have been removed,
-except in \LaTeX~2.09 compatibility mode. Classes should no longer
-set them.
-
-\begin{thebibliography}{1}
+This causes the current option to be added to the list of `unused options'.
-\bibitem{A-W:DEK91}
-Donald~E. Knuth.
-\newblock {\em The \TeX book}.
-\newblock Addison-Wesley, Reading, Massachusetts, 1986.
-\newblock Revised to cover \TeX3, 1991.
-
-\bibitem{A-W:LLa94}
-Leslie Lamport.
-\newblock {\em {\LaTeX:} A Document Preparation System}.
-\newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994.
+\subsection{Option processing}
+\label{Sec:commands.options}
-\bibitem{A-W:MG2004}
-Frank Mittelbach and Michel Goossens.
-\newblock {\em The {\LaTeX} Companion second edition}.
-\newblock With Johannes Braams, David Carlisle, and Chris Rowley.
-\newblock Addison-Wesley, Reading, Massachusetts, 2004.
+\begin{decl}
+ |\ProcessOptions|
+\end{decl}
+This command executes the \m{code} for each selected option.
-\end{thebibliography}
+We shall first describe how |\ProcessOptions| works in a package file, and then
+how this differs in a class file.
-\newpage
-\thispagestyle{empty}
+To understand in detail what |\ProcessOptions| does in a package file, you have
+to know the difference between \emph{local} and \emph{global} options.
+\begin{itemize}
+\item \textbf{Local options} are those which have been explicitly
+ specified for this particular package in the \m{options} argument of
+ any of these:
+\begin{quote}
+ |\PassOptionsToPackage{<options>}| \ |\usepackage[<options>]|\\
+ |\RequirePackage[<options>]|
+\end{quote}
+\item \textbf{Global options} are any other options that are specified
+ by the author in the \m{options} argument of
+ |\documentclass[<options>]|.
+\end{itemize}
+For example, suppose that a document begins:
+\begin{verbatim}
+ \documentclass[german,twocolumn]{article}
+ \usepackage{gerhardt}
+\end{verbatim}
+whilst package |gerhardt| calls package |fred| with:
+\begin{verbatim}
+ \PassOptionsToPackage{german,dvips,a4paper}{fred}
+ \RequirePackage[errorshow]{fred}
+\end{verbatim}
+then:
+\begin{itemize}
+\item |fred|'s local options are |german|, |dvips|, |a4paper|
+ and |errorshow|;
+\item |fred|'s only global option is |twocolumn|.
+\end{itemize}
-\section*{\LaTeXe{} Summary sheet: updating old styles}
+When |\ProcessOptions| is called, the following happen.
+\begin{itemize}
+\item \emph{First}, for each option so far declared in |fred.sty|
+ by |\DeclareOption|, it looks to see if that option is either a
+ global or a local option for |fred|: if it is then the corresponding
+ code is executed.
-Section references below are to \emph{\clsguide}.
+ This is done in the order in which these options
+ were declared in |fred.sty|.
+\item \emph{Then}, for each remaining \emph{local} option, the command
+ |\ds@<option>| is executed if it has been defined somewhere (other
+ than by a |\DeclareOption|); otherwise, the `default option code' is
+ executed. If no default option code has been declared then an error
+ message is produced.
-\begin{enumerate}
+ This is done in the order in which these
+ options were specified.
+\end{itemize}
+Throughout this process, the system ensures that the code declared for
+an option is executed at most once.
-\item Should it become a class or a package?
- See Section~\ref{Sec:classorpkg} for how to answer this question.
+Returning to the example, if |fred.sty| contains:
+\begin{verbatim}
+ \DeclareOption{dvips}{\typeout{DVIPS}}
+ \DeclareOption{german}{\typeout{GERMAN}}
+ \DeclareOption{french}{\typeout{FRENCH}}
+ \DeclareOption*{\PackageWarning{fred}{Unknown `\CurrentOption'}}
+ \ProcessOptions\relax
+\end{verbatim}
+then the result of processing this document will be:
+\begin{verbatim}
+ DVIPS
+ GERMAN
+ Package fred Warning: Unknown `a4paper'.
+ Package fred Warning: Unknown `errorshow'.
+\end{verbatim}
+Note the following:
-\item If it uses another style file, then you will need to obtain an
- updated version of this other file. Look at Section~\ref{Sec:loading}
- for information on how to load other class and package files.
+\begin{itemize}
+\item the code for the |dvips| option is executed before that for the
+ |german| option, because that is the order in which they are declared
+ in |fred.sty|;
+\item the code for the |german| option is executed only once, when the
+ declared options are being processed;
+\item the |a4paper| and |errorshow| options produce the warning from
+ the code declared by |\DeclareOption*| (in the order in which they
+ were specified), whilst the |twocolumn| option does not: this is
+ because |twocolumn| is a global option.
+\end{itemize}
-\item Try it: see Section~\ref{Sec:try-it}.
+In a class file, |\ProcessOptions| works in the same way, except that:
+\emph{all} options are local; and the default value for |\DeclareOption*| is
+|\OptionNotUsed| rather than an error.
-\item It worked? Excellent, but there are probably still some things
- you should change in order to make your file into a well-structured
- \LaTeXe{} file that is both robust and portable. So you should now
- read Section~\ref{Sec:writing}, especially~\ref{Sec:general}. You
- will also find some useful examples in Section~\ref{Sec:structure}.
+Note that, because |\ProcessOptions| has a |*|-form, it is wise to follow the
+non-star form with |\relax|, as in the previous examples, since this prevents
+unnecessary look ahead and possibly misleading error messages being issued.
- If your file sets up new fonts, font-changing commands or symbols,
- you should also read \emph{\fntguide}.
+\begin{decl}
+ |\ProcessOptions*|
+\end{decl}
+This is like |\ProcessOptions| but it executes the options in the order
+specified in the calling commands, rather than in the order of declaration in
+the class or package. For a package this means that the global options are
+processed first.
-\item It did not work? There are three possibilities here:
- \begin{itemize}
- \item error messages are produced whilst reading your file;
- \item error messages are produced whilst processing test documents;
- \item there are no errors but the output is not as it should be.
- \end{itemize}
- Don't forget to check carefully for this last possibility.
+\begin{decl}
+ |\ExecuteOptions| \arg{options-list}
+\end{decl}
- If you have got to this stage then you will need to read
- Section~\ref{Sec:upgrade} to find the solutions that will make your
- file work.
-\end{enumerate}
+It can be used to provide a `default option list' just before
+|\ProcessOptions|. For example, suppose that in a class file you want to set up
+the default design to be: two-sided printing; 11pt fonts; in two columns. Then
+it could specify:
+\begin{verbatim}
+ \ExecuteOptions{11pt,twoside,twocolumn}
+\end{verbatim}
\end{document}
diff --git a/macros/latex-dev/base/cmfonts.fdd b/macros/latex-dev/base/cmfonts.fdd
index 477085eaef..af898e47b2 100644
--- a/macros/latex-dev/base/cmfonts.fdd
+++ b/macros/latex-dev/base/cmfonts.fdd
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 1993-2022
+% Copyright (C) 1993-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
@@ -67,7 +67,7 @@
%<*driver, >
\ProvidesFile{cmfonts.drv}
%</driver, >
- [2022/07/10 v2.5l Standard LaTeX font definitions]
+ [2023/04/13 v2.5m Standard LaTeX font definitions]
%
%<*driver>
\documentclass{ltxdoc}
@@ -1048,8 +1048,10 @@
% \end{macrocode}
%
% \changes{v2.5j}{2019/12/16}{Provide substitutions for cmtt/bx/sl}
+% \changes{v2.5m}{2023/04/13}{Add missing substitution for U/cmtt/bx/sl}
% \begin{macrocode}
%<+OT1cmtt>\DeclareFontShape{OT1}{cmtt}{bx}{sl}
+%<+Ucmtt>\DeclareFontShape{U}{cmtt}{bx}{sl}
%<-nowarn> {<->sub*cmtt/m/n}{}
%<+nowarn> {<->ssub*cmtt/m/n}{}
%<+OT1cmtt>\DeclareFontShape{OT1}{cmtt}{bx}{ui}
diff --git a/macros/latex-dev/base/cmfonts.pdf b/macros/latex-dev/base/cmfonts.pdf
index 6274984a6d..82de575e6d 100644
--- a/macros/latex-dev/base/cmfonts.pdf
+++ b/macros/latex-dev/base/cmfonts.pdf
Binary files differ
diff --git a/macros/latex-dev/base/cyrguide.pdf b/macros/latex-dev/base/cyrguide.pdf
index 1b614ae415..1aa77ffdf5 100644
--- a/macros/latex-dev/base/cyrguide.pdf
+++ b/macros/latex-dev/base/cyrguide.pdf
Binary files differ
diff --git a/macros/latex-dev/base/doc-code.pdf b/macros/latex-dev/base/doc-code.pdf
index 93037436a6..4181da4328 100644
--- a/macros/latex-dev/base/doc-code.pdf
+++ b/macros/latex-dev/base/doc-code.pdf
Binary files differ
diff --git a/macros/latex-dev/base/doc.dtx b/macros/latex-dev/base/doc.dtx
index a2c95694ae..75e04cc299 100644
--- a/macros/latex-dev/base/doc.dtx
+++ b/macros/latex-dev/base/doc.dtx
@@ -1,7 +1,7 @@
% \iffalse meta-comment
%
-% Copyright 1993-2022
-% The LaTeX3 Project and any individual authors listed elsewhere
+% Copyright (C) 1993-2023
+% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
% This file is part of the LaTeX base system.
diff --git a/macros/latex-dev/base/doc.pdf b/macros/latex-dev/base/doc.pdf
index 796e6319f2..c0a027ae5d 100644
--- a/macros/latex-dev/base/doc.pdf
+++ b/macros/latex-dev/base/doc.pdf
Binary files differ
diff --git a/macros/latex-dev/base/docstrip.pdf b/macros/latex-dev/base/docstrip.pdf
index a489d9b28a..88ef1e1370 100644
--- a/macros/latex-dev/base/docstrip.pdf
+++ b/macros/latex-dev/base/docstrip.pdf
Binary files differ
diff --git a/macros/latex-dev/base/encguide.pdf b/macros/latex-dev/base/encguide.pdf
index 0c2ed52b02..7f961d9148 100644
--- a/macros/latex-dev/base/encguide.pdf
+++ b/macros/latex-dev/base/encguide.pdf
Binary files differ
diff --git a/macros/latex-dev/base/exscale.pdf b/macros/latex-dev/base/exscale.pdf
index 8dd6ce4286..1182517613 100644
--- a/macros/latex-dev/base/exscale.pdf
+++ b/macros/latex-dev/base/exscale.pdf
Binary files differ
diff --git a/macros/latex-dev/base/fix-cm.pdf b/macros/latex-dev/base/fix-cm.pdf
index f3eb096139..762b79017f 100644
--- a/macros/latex-dev/base/fix-cm.pdf
+++ b/macros/latex-dev/base/fix-cm.pdf
Binary files differ
diff --git a/macros/latex-dev/base/fntguide.pdf b/macros/latex-dev/base/fntguide.pdf
index d92d3d71bb..034fe97db8 100644
--- a/macros/latex-dev/base/fntguide.pdf
+++ b/macros/latex-dev/base/fntguide.pdf
Binary files differ
diff --git a/macros/latex-dev/base/fntguide.tex b/macros/latex-dev/base/fntguide.tex
index 33bbed3ba3..619cc907b2 100644
--- a/macros/latex-dev/base/fntguide.tex
+++ b/macros/latex-dev/base/fntguide.tex
@@ -42,7 +42,7 @@
\title{\LaTeXe{} font selection}
-\author{\copyright~Copyright 1995--2022, \LaTeX\ Project
+\author{\copyright~Copyright 1995--2023, \LaTeX\ Project
Team.\thanks{Thanks to Arash Esbati for documenting the
newer NFSS features of 2020}\\
All rights reserved.%
@@ -52,7 +52,7 @@
\texttt{fntguide.tex} for full details.}%
}
-\date{August 2022}
+\date{May 2023}
\begin{document}
@@ -299,8 +299,6 @@ 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}
@@ -325,7 +323,7 @@ A less common value for font shape is:
\end{minipage}
\end{center}
and there is also |ui| for upright italic, i.e., an italic shape but
-artifically turned upright. This is sometimes useful and available in
+artificially turned upright. This is sometimes useful and available in
some fonts.
@@ -404,8 +402,6 @@ turned into \TeX{} font names. This is described in
Section~\ref{Sec:install}.
-\newpage
-
\subsection{Selection commands}
@@ -955,7 +951,6 @@ Example:
\DeclareMathSymbol{\alphld}{\mathalpha}{AMSb}{"0C}
\end{verbatim}
-\newpage
\begin{decl}
|\DeclareMathDelimiter| \arg{cmd} \arg{type}
@@ -1382,7 +1377,7 @@ the `cmr' family).
from this subsection.
\NEWdescription{2019/07/10}
-As an exception it may also contain a |\DeclareFontsubstitution|
+As an exception it may also contain a |\DeclareFontSubstitution|
declaration (described in \ref{sec:encoding-defaults}) to specify how
font substitution for this encoding should be handled. In that case it
is important that the values used point to a font that is guaranteed to
@@ -1431,6 +1426,8 @@ executed whenever a math alphabet with this encoding is called.
It also saves the value of \m{encoding} in the macro
|\LastDeclaredEncoding|.
+\newpage
+
Example:
\begin{verbatim}
\DeclareFontEncoding{OT1}{}{}
@@ -1496,6 +1493,8 @@ For example, the definition of |\ss| in the |OT1| encoding is:
It does not produce an error if the command has already
been defined but logs the redefinition in the transcript file.
+\newpage
+
\begin{decl}
|\DeclareTextAccent| \arg{cmd} \arg{encoding} \arg{slot}
\end{decl}
@@ -1611,6 +1610,8 @@ defined with |\DeclareTextSymbol|.
For more examples of these definitions, see |ltoutenc.dtx|.
+\newpage
+
\begin{decl}[1994/12/01]
|\ProvideTextCommandDefault| \arg{cmd} \arg{definition}
\end{decl}
@@ -2440,8 +2441,6 @@ 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]
diff --git a/macros/latex-dev/base/graphpap.pdf b/macros/latex-dev/base/graphpap.pdf
index c5d07452ce..734a7e60e7 100644
--- a/macros/latex-dev/base/graphpap.pdf
+++ b/macros/latex-dev/base/graphpap.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ifthen.pdf b/macros/latex-dev/base/ifthen.pdf
index d09c30cace..a5b90c8782 100644
--- a/macros/latex-dev/base/ifthen.pdf
+++ b/macros/latex-dev/base/ifthen.pdf
Binary files differ
diff --git a/macros/latex-dev/base/inputenc.pdf b/macros/latex-dev/base/inputenc.pdf
index 4c305b8bc1..ddd7928f37 100644
--- a/macros/latex-dev/base/inputenc.pdf
+++ b/macros/latex-dev/base/inputenc.pdf
Binary files differ
diff --git a/macros/latex-dev/base/lamport-manual.pdf b/macros/latex-dev/base/lamport-manual.pdf
index 14ffd31d47..fb9e0e0a25 100644
--- a/macros/latex-dev/base/lamport-manual.pdf
+++ b/macros/latex-dev/base/lamport-manual.pdf
Binary files differ
diff --git a/macros/latex-dev/base/latexrelease.pdf b/macros/latex-dev/base/latexrelease.pdf
index ce0a066012..3b4124e9d0 100644
--- a/macros/latex-dev/base/latexrelease.pdf
+++ b/macros/latex-dev/base/latexrelease.pdf
Binary files differ
diff --git a/macros/latex-dev/base/latexsym.pdf b/macros/latex-dev/base/latexsym.pdf
index 2b3650506a..dab8955e1c 100644
--- a/macros/latex-dev/base/latexsym.pdf
+++ b/macros/latex-dev/base/latexsym.pdf
Binary files differ
diff --git a/macros/latex-dev/base/lb2.pdf b/macros/latex-dev/base/lb2.pdf
index d5d94cd6d8..4c35d7053e 100644
--- a/macros/latex-dev/base/lb2.pdf
+++ b/macros/latex-dev/base/lb2.pdf
Binary files differ
diff --git a/macros/latex-dev/base/letter.pdf b/macros/latex-dev/base/letter.pdf
index fb5d1b851e..139eb554c7 100644
--- a/macros/latex-dev/base/letter.pdf
+++ b/macros/latex-dev/base/letter.pdf
Binary files differ
diff --git a/macros/latex-dev/base/lgc2.pdf b/macros/latex-dev/base/lgc2.pdf
index 161aa93503..b1af720e50 100644
--- a/macros/latex-dev/base/lgc2.pdf
+++ b/macros/latex-dev/base/lgc2.pdf
Binary files differ
diff --git a/macros/latex-dev/base/lppl.pdf b/macros/latex-dev/base/lppl.pdf
index 4b4c6fa326..c3b3b75bc7 100644
--- a/macros/latex-dev/base/lppl.pdf
+++ b/macros/latex-dev/base/lppl.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltclass.dtx b/macros/latex-dev/base/ltclass.dtx
index f6d5994d3f..bb52148508 100644
--- a/macros/latex-dev/base/ltclass.dtx
+++ b/macros/latex-dev/base/ltclass.dtx
@@ -33,7 +33,7 @@
%<*driver>
% \fi
\ProvidesFile{ltclass.dtx}
- [2022/11/16 v1.5f LaTeX Kernel (Class & Package Interface)]
+ [2023/04/14 v1.5h LaTeX Kernel (Class & Package Interface)]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{ltclass.dtx}
@@ -324,6 +324,7 @@
%
% \DescribeMacro\IfPackageAtLeastTF
% \DescribeMacro\IfClassAtLeastTF
+% \DescribeMacro\IfFileAtLeastTF
% \DescribeMacro\@ifpackagelater
% \DescribeMacro\@ifclasslater
% \changes{v1.1i}{2013/07/07}{Correctly describe how the date in
@@ -890,12 +891,14 @@
%
% \begin{macro}{\IfPackageAtLeastTF}
% \begin{macro}{\IfClassAtLeastTF}
+% \begin{macro}{\IfFileAtLeastTF}
% \begin{macro}{\IfFormatAtLeastTF}
% |\IfFormatAtLeastTF{YYYY/MM/DD}{|\meta{true
% code}|}{|\meta{false code}|}|
% Test if the format is later or equal to the given date.
% \changes{v1.3k}{2020/04/07}{Macro added; also in rollback (gh/168)}
% \changes{v1.4e}{2021/07/19}{Drop \cs{@onlypreamble}}
+% \changes{v1.5g}{2023/03/28}{Added \cs{IfFileAtLeastTF} (gh/1015)}
% \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
@@ -904,6 +907,7 @@
\def\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
\let\IfPackageAtLeastTF\@ifpackagelater
\let\IfClassAtLeastTF\@ifclasslater
+\def\IfFileAtLeastTF#1{\expandafter\@ifl@t@r\csname ver@#1\endcsname}
% \end{macrocode}
% For rollback pretend it was available since the beginning of dawn.
% \begin{macrocode}
@@ -914,12 +918,14 @@
%<latexrelease>\def\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
%<latexrelease>\let\IfPackageAtLeastTF\@ifpackagelater
%<latexrelease>\let\IfClassAtLeastTF\@ifclasslater
+%<latexrelease>\def\IfFileAtLeastTF#1{\expandafter\@ifl@t@r\csname ver@#1\endcsname}
%<latexrelease>\EndIncludeInRelease
%<*2ekernel>
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
%
% \begin{macro}{\@ifl@ter}
% \changes{v1.4e}{2021/07/19}{Drop \cs{@onlypreamble}}
@@ -2133,13 +2139,28 @@
% {Reset \cs{CurrentOption}}
% \changes{v1.3d}{2019/10/18}{Initialize \cs{...-h@@k} only when loading
% the package or class (gh/198)}
+% \changes{v1.5h}{2023/04/14}{Define \cs{load@onefilewithoptions} when
+% in \pkg{latexrelease} (gh/992)}
% \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2020/10/01}%
%<latexrelease> {\@onefilewithoptions}{Hooks and unused options issue}%
+% \end{macrocode}
+%
+% Here this macro is called \cs{@onefilewithoptions}, but further
+% ahead in this file it is renamed to \cs{load@onefilewithoptions},
+% and \cs{@onefilewithoptions} becomes a wrapper around this, used for
+% bookkeeping when rolling back. Therefore, when in
+% \pkg{latexrelease}, we need to define \cs{load@onefilewithoptions}
+% instead, thus the extra guarded \cs{def} line below:
+% \begin{macrocode}
+%<*2ekernel>
\def\@onefilewithoptions#1[#2][#3]#4{%
+%</2ekernel>
+%<latexrelease>\def\load@onefilewithoptions#1[#2][#3]#4{%
% \end{macrocode}
+%
% We have to sanitise file names, so that something like
% \begin{verbatim}
% \usepackage{some/local/path/array}
diff --git a/macros/latex-dev/base/ltcmd.dtx b/macros/latex-dev/base/ltcmd.dtx
index 78a5a389ae..5f019cdc2a 100644
--- a/macros/latex-dev/base/ltcmd.dtx
+++ b/macros/latex-dev/base/ltcmd.dtx
@@ -1,7 +1,7 @@
% \iffalse meta-comment
%
% Copyright (C) 1999 Frank Mittelbach, Chris Rowley, David Carlisle
-% Copyright (C) 2004-2008 Frank Mittelbach, The LaTeX3 Project
+% Copyright (C) 2004-2008 Frank Mittelbach, The LaTeX Project
% Copyright (C) 2009-2023
% 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.1b}
-\def\ltcmddate{2022-11-29}
+\def\ltcmdversion{v1.1d}
+\def\ltcmddate{2023-04-13}
% \end{macrocode}
%
%<*driver>
@@ -2123,8 +2123,8 @@
% and possibly another auxiliary
% \cs{\meta{cmd}\textvisiblespace\textvisiblespace}, if the command
% has both long and short arguments. Then, its signature also has
-% several specific bits that are unique to that command; this is in contrast to
-% non-expandable commands, which use a common set of parsing functions.
+% several specific bits that are unique to that command; this is in contrast
+% to non-expandable commands, which use a common set of parsing functions.
%
% We start by copying the basics, then call
% \cs{@@_copy_expandable_signature:NnNNNNnnn} to parse the signature
@@ -2132,7 +2132,24 @@
% then we call \cs{@@_copy_expandable:NnNNNNnnn} that will copy the
% top-level definition of the command, with the proper internal
% renames.
+%
% \begin{macrocode}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_copy:NN}%
+%<latexrelease> {Support~\NewCommandCopy~in~ltcmd}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \changes{v1.1c}{2023/03/12}
+% {Distinguish (non-expandable) document commands starting with
+% \cs{@@_start_expandable:nNNNNn}}
+% There's one variant: a command begins with \cs{@@_start_expandable:nNNNNn}
+% may still be un-expandable/protected if it's defined by
+% \cs{NewDocumentCommand} and friends, with empty or only m-type arguments.
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_copy_expandable:nnNN}%
+%<latexrelease> {Distinguish~non-expandable~document~commands}
\cs_new_protected:Npn \@@_copy_expandable:nnNN #1 #2 #3 #4
{
\cs_set_eq:cc { #1 ~ code } { #2 ~ code }
@@ -2140,9 +2157,36 @@
\@@_set_eq_if_exist:cc { #1 ~ \c_space_tl } { #2 ~ \c_space_tl }
\@@_set_eq_if_exist:cc { #1 ~ defaults } { #2 ~ defaults }
\exp_after:wN \@@_copy_expandable_signature:NnNNNNnnn #4 {#1} {#2}
- \cs_set_nopar:Npx #3
+ \token_if_protected_macro:NTF #4
+ { \cs_set_protected_nopar:Npx }{ \cs_set_nopar:Npx }
+ #3
{ \exp_after:wN \@@_copy_expandable:NnNNNNnnn #4 {#1} {#2} }
}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2021/11/15}{\@@_copy_expandable:nnNN}%
+%<latexrelease> {Support~\NewCommandCopy~in~ltcmd}
+%<latexrelease>\cs_new_protected:Npn \@@_copy_expandable:nnNN #1 #2 #3 #4
+%<latexrelease> {
+%<latexrelease> \cs_set_eq:cc { #1 ~ code } { #2 ~ code }
+%<latexrelease> \@@_set_eq_if_exist:cc { #1 ~ } { #2 ~ }
+%<latexrelease> \@@_set_eq_if_exist:cc { #1 ~ \c_space_tl } { #2 ~ \c_space_tl }
+%<latexrelease> \@@_set_eq_if_exist:cc { #1 ~ defaults } { #2 ~ defaults }
+%<latexrelease> \exp_after:wN \@@_copy_expandable_signature:NnNNNNnnn #4 {#1} {#2}
+%<latexrelease> \cs_set_nopar:Npx #3
+%<latexrelease> { \exp_after:wN \@@_copy_expandable:NnNNNNnnn #4 {#1} {#2} }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_copy_expandable:nnNN}%
+%<latexrelease> {Support~\NewCommandCopy~in~ltcmd}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2021/11/15}{\@@_copy:NN (part 2)}%
+%<latexrelease> {Support~\NewCommandCopy~in~ltcmd}
+% \end{macrocode}
+%
+% \begin{macrocode}
\cs_new:Npn \@@_copy_expandable:NnNNNNnnn #1 #2 #3 #4 #5 #6 #7 #8 #9
{
\exp_not:N #1 \exp_not:n { {#2} }
@@ -2355,7 +2399,7 @@
% worth it.
% \begin{macrocode}
%<latexrelease>\EndIncludeInRelease
-%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_copy:NN}%
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_copy:NN (part 2)}%
%<latexrelease> {Support~\NewCommandCopy~in~ltcmd}
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
@@ -2418,11 +2462,47 @@
}
\cs_new_protected:Npn \@@_show_expandable:N #1
{ \exp_after:wN \@@_show_expandable:NnNNNNnN #1 #1 }
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_show:N}%
+%<latexrelease> {Support~\ShowCommand~in~ltcmd}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \changes{v1.1c}{2023/03/12}
+% {Distinguish (non-expandable) document commands starting with
+% \cs{@@_start_expandable:nNNNNn}}
+% There's one variant: a command begins with \cs{@@_start_expandable:nNNNNn}
+% may still be un-expandable/protected if it's defined by
+% \cs{NewDocumentCommand} and friends, with empty or only m-type arguments.
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_show_expandable:NnNNNNnN}%
+%<latexrelease> {Distinguish~non-expandable~document~commands}
\cs_new_protected:Npn \@@_show_expandable:NnNNNNnN #1 #2 #3 #4 #5 #6 #7 #8
{
- \@@_show_command_aux:NnNNn \tl_show:x
- { expandable~document~command } #8 #5 {#2}
+ \exp_args:NNe \@@_show_command_aux:NnNNn \tl_show:x
+ { \token_if_protected_macro:NF #8 { expandable~ } document~command }
+ #8 #5 {#2}
}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2021/11/15}{\@@_show_expandable:NnNNNNnN}%
+%<latexrelease> {Support~\ShowCommand~in~ltcmd}
+%<latexrelease>\cs_new_protected:Npn \@@_show_expandable:NnNNNNnN #1 #2 #3 #4 #5 #6 #7 #8
+%<latexrelease> {
+%<latexrelease> \@@_show_command_aux:NnNNn \tl_show:x
+%<latexrelease> { expandable~document~command } #8 #5 {#2}
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_show_expandable:NnNNNNnN}%
+%<latexrelease> {Support~\ShowCommand~in~ltcmd}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2021/11/15}{\@@_show:N (part 2)}%
+%<latexrelease> {Support~\ShowCommand~in~ltcmd}
% \end{macrocode}
%
% Now just print everything in the required format. The auxiliary
@@ -2675,7 +2755,7 @@
% \begin{macrocode}
%<latexrelease>\EndIncludeInRelease
%
-%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_show:N}%
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_show:N (part 2)}%
%<latexrelease> {Support~\ShowCommand~in~ltcmd}
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
@@ -3218,6 +3298,10 @@
% \begin{macro}{\@@_grab_v_long:w}
% \begin{macro}{\@@_grab_v_aux:w}
% \begin{macro}{\@@_grab_v_group_end:}
+% Firstly, it is necessary to change \cs{tex_endlinechar:D} so that
+% newlines in different catcode regimes (e.g., \cs{ExplSyntaxOn}) are
+% not misinterpreted as spaces.
+% \changes{v1.1d}{2023/04/13}{Set \cs{tex_endlinechar:D} earlier (gh/876).}
% The opening delimiter is the first non-space token, and is never
% read verbatim. This is required by consistency with the case where
% the preceding argument was optional and absent: then \TeX{} has
@@ -3251,6 +3335,7 @@
\tl_set:Nn \l_@@_signature_tl {#1}
\group_begin:
\tex_escapechar:D = 92 \scan_stop:
+ \tex_endlinechar:D = `\^^M \scan_stop:
\tl_clear:N \l_@@_v_arg_tl
\peek_remove_spaces:n
{
@@ -3268,8 +3353,8 @@
}
\cs_new_protected:Npn \@@_grab_v_group_end:
{
- \exp_args:NNNo
- \group_end:
+ \exp_args:NNNo
+ \group_end:
\tl_set:Nn \l_@@_v_arg_tl { \l_@@_v_arg_tl }
}
% \end{macrocode}
@@ -3414,7 +3499,6 @@
{
\cs_set_eq:NN \do \char_set_catcode_other:N
\dospecials
- \tex_endlinechar:D = `\^^M \scan_stop:
\bool_if:NTF \l_@@_long_bool
{ \char_set_catcode_other:n { \tex_endlinechar:D } }
{ \char_set_catcode_parameter:n { \tex_endlinechar:D } }
diff --git a/macros/latex-dev/base/ltcmdhooks-code.pdf b/macros/latex-dev/base/ltcmdhooks-code.pdf
index 0dc121d2ce..49e283c6d6 100644
--- a/macros/latex-dev/base/ltcmdhooks-code.pdf
+++ b/macros/latex-dev/base/ltcmdhooks-code.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltcmdhooks-doc.pdf b/macros/latex-dev/base/ltcmdhooks-doc.pdf
index c67f46be25..94caa644c4 100644
--- a/macros/latex-dev/base/ltcmdhooks-doc.pdf
+++ b/macros/latex-dev/base/ltcmdhooks-doc.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltcmdhooks.dtx b/macros/latex-dev/base/ltcmdhooks.dtx
index ccb5a35a71..27907af679 100644
--- a/macros/latex-dev/base/ltcmdhooks.dtx
+++ b/macros/latex-dev/base/ltcmdhooks.dtx
@@ -1,7 +1,8 @@
% \iffalse meta-comment
%
-%% File: ltcmdhooks.dtx (C) Copyright 2020-2021
-%% Frank Mittelbach, Phelype Oleinik, LaTeX Team
+%% File: ltcmdhooks.dtx
+%% Copyright (C) 2020-2023
+%% Frank Mittelbach, Phelype Oleinik, The LaTeX Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -13,8 +14,8 @@
%
%%% From File: ltcmdhooks.dtx
%
-\def\ltcmdhooksversion{v1.0f}
-\def\ltcmdhooksdate{2021/10/20}
+\def\ltcmdhooksversion{v1.0h}
+\def\ltcmdhooksdate{2023/05/21}
%
%
%
@@ -51,20 +52,32 @@
%
% This file implements generic hooks for (arbitrary) commands.
% In theory every command \tn[no-index]{\meta{name}} offers now two
-% associated hooks to which code can be added using \tn{AddToHook}
-% or \tn{AddToHookNext}.\footnote{In practice this is not supported
+% associated hooks to which code can be added using
+% \tn{AddToHook},\!\footnote{In this documentation, when something is
+% being said about \tn{AddToHook}, the same will be valid for
+% \tn{AddToHookWithArguments}, unless that particular paragraph is
+% highlighting the differences between both. The same is true for
+% the other hook-related functions and their
+% \texttt{\ldots WithArguments} counterparts.}
+% \tn{AddToHookNext}, \tn{AddToHookWithArguments}, and
+% \tn{AddToHookNextWithArguments}.\footnote{In practice this is not
+% supported
% for all types of commands, see section~\ref{sec:look-ahead} for
% the restrictions that apply and what happens if one tries to use
-% this with commands for which this is not supported.} These are
+% this with commands for which this is not supported.} These are:
% \begin{description}
% \item[\hook{cmd/\meta{name}/before}]
%
-% This hook is executed at the very start of the command
-% execution after its arguments (if any) are parsed. The hook
-% \meta{code} is wrapped in the command inside a call to
-% \cs{UseHook}|{cmd/|\meta{name}|/before}|, so the arguments
-% passed to the command are \emph{not} available in the hook
-% \meta{code}.
+% This hook is executed at the very start of the command, right
+% after its arguments (if any) are parsed. The hook \meta{code}
+% runs in the command inside a call to \cs{UseHookWithArguments}.
+% Any code added to this hook using \tn{AddToHookWithArguments}
+% or \tn{AddToHookNextWithArguments} can access the command's
+% arguments using |#1|, |#2|, etc., up to the number of arguments
+% of the command. If \tn{AddToHook} or \tn{AddToHookNext} are
+% used, the arguments cannot be accessed (see the \pkg{lthooks}
+% documentation\footnote{\texttt{texdoc lthooks-doc}} on hooks
+% with arguments).
%
% \item[\hook{cmd/\meta{name}/after}]
%
@@ -74,9 +87,12 @@
% \end{description}
%
% The hooks are not physically present before
-% \verb=\begin{document}= (i.e., using a command in the preamble
-% will never execute them) and if nobody has declared any code for
-% them, then they are not added to the command code ever. For
+% \verb=\begin{document}=\footnote{More specifically, they are
+% inserted in the commands after the \hook{begindocument} hook, so
+% they are also not present while \LaTeX{} is reading the
+% \texttt{.aux} file.} (i.e., using a command in the preamble
+% will never execute the hook) and if nobody has declared any code
+% for them, then they are not added to the command code ever. For
% example, if we have the following definition
%\begin{verbatim}
% \newcommand\foo[2]{Code #1 for #2!}
@@ -90,23 +106,27 @@
%\end{verbatim}
% then, after |\begin{document}| the definition of \cs[no-index]{foo} will be:
%\begin{verbatim}
-% \renewcommand\foo[2]{\UseHook{cmd/foo/before}Code #1 for #2!}
+% \renewcommand\foo[2]{%
+% \UseHookWithArguments{cmd/foo/before}{2}{#1}{#2}%
+% Code #1 for #2!}
%\end{verbatim}
% and similarly \verb=\AddToHook{cmd/foo/after}{<after code>}=
% alters the definition to
%\begin{verbatim}
-% \renewcommand\foo[2]{Code #1 for #2!\UseHook{cmd/foo/after}}
+% \renewcommand\foo[2]{%
+% Code #1 for #2!%
+% \UseHookWithArguments{cmd/foo/after}{2}{#1}{#2}}
%\end{verbatim}
%
% In other words, the mechanism is similar to what \pkg{etoolbox}
% offers with \tn{pretocmd} and \tn{apptocmd} with the important
-% differences
+% differences
% \begin{itemize}
% \item
%
% that code can be prepended or appended (i.e., added to the
% hooks) even if the command itself is not defined, because the
-% defining package has not yet been loaded
+% defining package has not yet been loaded;
%
% \item
%
@@ -197,6 +217,7 @@
%
%
% \section{Package Author Interface}
+% \label{sec:pkg-author}
%
% The \hook{cmd} hooks are, by default, available for all commands
% that can be patched to add the hooks. For some commands, however,
@@ -206,9 +227,10 @@
%
% If you are a package author and you want to add the hooks to your
% own commands in the proper position you can define the command and
-% manually add the \cs{UseHook} calls inside the command in the proper
-% positions, and manually define the hooks with \cs{NewHook} or
-% \cs{NewReversedHook}. When the hooks are explicitly defined,
+% manually add the \cs{UseHookWithArguments} calls inside the command in
+% the proper positions, and manually define the hooks with
+% \cs{NewHookWithArguments} or \cs{NewReversedHookWithArguments}.
+% When the hooks are explicitly defined,
% patching is not attempted so you can make sure your command works
% properly. For example, an (admittedly not really useful) command
% that typesets its contents in a framed box with width optionally
@@ -230,26 +252,27 @@
% \begin{verbatim}
% \newcommand\fancybox{\@ifnextchar({\@fancybox}{\@fancybox(5cm)}}
% \def\@fancybox(#1)#2{\fbox{%
-% \UseHook{cmd/fancybox/before}%
-% \parbox{#1}{#2}%
-% \UseHook{cmd/fancybox/after}}}
-% \NewHook{cmd/fancybox/before}
-% \NewReversedHook{cmd/fancybox/after}
+% \UseHookWithArguments{cmd/fancybox/before}{2}{#1}{#2}%
+% \parbox{#1}{#2}%
+% \UseHookWithArguments{cmd/fancybox/after}{2}{#1}{#2}}}
+% \NewHookWithArguments{cmd/fancybox/before}{2}
+% \NewReversedHookWithArguments{cmd/fancybox/after}{2}
% \end{verbatim}
% then the hooks will be executed where they should and no patching
% will be attempted. It is important that the hooks are declared with
-% \cs{NewHook} or \cs{NewReversedHook}, otherwise the command hook
+% \cs{NewHookWithArguments} or \cs{NewReversedHookWithArguments},
+% otherwise the command hook
% code will try to patch the command. Note also that the call to
-% |\UseHook{cmd/fancybox/before}| does not need to be in the
-% definition of \cs[no-index]{fancybox}, but anywhere it makes sense
+% |\UseHookWithArguments{cmd/fancybox/before}| does not need to be in
+% the definition of \cs[no-index]{fancybox}, but anywhere it makes sense
% to insert it (in this case in the internal
% \cs[no-index]{@fancybox}).
%
% Alternatively, if for whatever reason your command does not support
% the generic hooks provided here, you can disable a hook with
-% \cs{DisableHook}\footnote{Please use \cs{DisableHook} if at all, only
-% on hooks that you \enquote{own}, i.e., for commands that your
-% package or class defines and not second guess
+% \cs{DisableGenericHook}\footnote{Please use \cs{DisableGenericHook} if
+% at all, only on hooks that you \enquote{own}, i.e., for commands
+% your package or class defines and not second guess
% whether or not hooks of other packages should get disabled!}, so
% that when someone tries to add code to it they will get an error.
% Or if you don't want the error, you can simply declare the hook with
@@ -270,6 +293,55 @@
% If you do that then both hooks automatically work and are patched
% into the right places.
%
+% \subsection{Arguments and redefining commands}
+% \label{sec:redef-warn}
+%
+% The code in \pkg{ltcmdhooks} does its best to find out how many
+% arguments a given command has, and to insert the appropriate call to
+% \cs{UseHookWithArguments}, so that the arguments seen by the hook are
+% exactly those grabbed by the command (the hook, after all, is a macro
+% call, so the arguments have to be placed in the right order, or they
+% won't match).
+%
+% When using the package writer interface, as discussed in
+% section~\ref{sec:pkg-author}, to change the position of the hooks in
+% your commands, you are also free to change how the hook code in your
+% command sees its arguments. When a \hook{cmd} hook is declared with
+% \cs{NewHook} (or \cs{NewHookWithArguments} or other variations of
+% that), it loses its \enquote{generic} nature and works as a regular
+% hook. This means that you may choose to declare it without
+% arguments regardless if the command takes arguments or not, or
+% declare it with arguments, even if the command takes none.
+%
+% However, this flexibility should not be abused. When using a
+% nonstandard configuration for the hook arguments, think reasonably:
+% a user will expect that the argument \verb|#1| in the hook corresponds
+% to the argument's first argument, and so on. Any other configuration
+% is likely to cause confusion and, if used, will have to be well
+% documented.
+%
+% This flexibility, however, allows you to \enquote{correct} the
+% arguments for the hooks. For example, \LaTeX's \cs{refstepcounter}
+% has a single argument, the name of the counter. The \pkg{cleveref}
+% package adds an optional argument to \cs{refstepcounter}, making the
+% name of the counter argument \verb|#2|. If the author of
+% \pkg{cleveref} wanted, for whatever reason, to add hooks to
+% \cs{refstepcounter}, to preserve compatibility he could write
+% something along the lines of:
+% \begin{verbatim}
+% \NewHookWithArguments{cmd/refstepcounter/before}{1}
+% \renewcommand\refstepcounter[2][<default>]{%
+% \UseHookWithArguments{cmd/refstepcounter/before}{1}{#2}%
+% <code for \refstepcounter>}
+% \end{verbatim}
+% so that the mandatory argument, which is arg \verb|#2| in the
+% definition, would still be seen as \verb|#1| in the hook code.
+%
+% Another possibility would be to place the optional argument as the
+% second argument for the hook, so that people looking for it would be
+% able to use it. In either case, it would have to be well documented
+% to cause as little confusion as possible.
+%
% \MaybeStop{\setlength\IndexMin{200pt} \PrintIndex }
%
%
@@ -366,10 +438,13 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\c_@@_hash_tl}
-% A constant token list that contains two parameter tokens.
+% \begin{macro}{\c_@@_hash_tl,\c_@@_hashes_tl}
+% Two constant token lists that contain one and two parameter tokens.
+% \changes{v1.0g}{2023/04/06}
+% {Rename to \cs{c_@@_hashes_tl} and add \cs{c_@@_hash_tl} (hook-args).}
% \begin{macrocode}
-\tl_const:Nn \c_@@_hash_tl { # # }
+\tl_const:Nn \c_@@_hash_tl { # }
+\tl_const:Nn \c_@@_hashes_tl { # # }
% \end{macrocode}
% \end{macro}
%
@@ -702,7 +777,7 @@
%
% \changes{v1.0f}{2021/10/20}
% {Correct patching by expansion+redefinition when the macro
-% contains a parameter tokens (gh/697).}
+% contains a parameter token (gh/697).}
% Patching with expansion+redefinition is trickier than it looks like
% at first glance. Suppose the simple definition:
% \begin{verbatim}
@@ -756,6 +831,8 @@
% parameter token, so that this case can be handled like the previous
% one.
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_patch_expand_redefine:NNnn}
+%<latexrelease> {cmd~hooks~with~args}
\cs_new_protected:Npn \@@_patch_expand_redefine:NNnn #1 #2 #3 #4
{
\@@_patch_debug:x { ++~command~can~be~patched~without~rescanning }
@@ -779,14 +856,14 @@
% should be identical to the \meta{parameter text} used when
% originally defining that macro.
% \item[\cs{l_@@_replace_text_tl}] will contain braced pairs of
-% \cs{c_@@_hash_tl}\meta{num} to feed to the macro when expanded.
+% \cs{c_@@_hashes_tl}\meta{num} to feed to the macro when expanded.
% This token list as well as the previous will have the first item
% surrounded by |[|\ldots|]| in the case of an optional argument.
% \end{description}
%
-% The use of \cs{c_@@_hash_tl} here is to differentiate actual
+% The use of \cs{c_@@_hashes_tl} here is to differentiate actual
% parameters in the macro from parameter tokens in the original
-% definition of the macro. Later on, \cs{c_@@_hash_tl} is either
+% definition of the macro. Later on, \cs{c_@@_hashes_tl} is either
% replaced by actual parameter tokens, or expanded into them.
% \begin{macrocode}
\int_compare:nNnTF { \l_@@_patch_num_args_int } > { \c_zero_int }
@@ -795,7 +872,7 @@
% We'll first check if the command has any parameter token in its
% definition (feeding it empty arguments), and set \cs{@@_exp_not:n}
% accordingly. \cs{@@_exp_not:n} will be used later to either leave
-% \cs{c_@@_hash_tl} or expand it, and also to remember the result of
+% \cs{c_@@_hashes_tl} or expand it, and also to remember the result of
% \cs{@@_if_has_hash:nTF} to avoid testing twice (the test can be
% rather slow).
% \begin{macrocode}
@@ -814,20 +891,22 @@
% \end{macrocode}
% Here we'll conditionally add |[|\ldots|]| around the first
% parameter:
+% \changes{v1.0g}{2023/04/06}
+% {Rename to \cs{c_@@_hashes_tl} (hook-args).}
% \begin{macrocode}
\bool_if:NTF #1
- { \@@_tmp:w \tl_set:Nx { [ \c_@@_hash_tl 1 ] } }
- { \@@_tmp:w \tl_set:Nx { { \c_@@_hash_tl 1 } } }
+ { \@@_tmp:w \tl_set:Nx { [ \c_@@_hashes_tl 1 ] } }
+ { \@@_tmp:w \tl_set:Nx { { \c_@@_hashes_tl 1 } } }
% \end{macrocode}
% Then, for every parameter from the second, just add it normally:
% \begin{macrocode}
\int_step_inline:nnn { 2 } { \l_@@_patch_num_args_int }
- { \@@_tmp:w \tl_put_right:Nx { { \c_@@_hash_tl ##1 } } }
+ { \@@_tmp:w \tl_put_right:Nx { { \c_@@_hashes_tl ##1 } } }
% \end{macrocode}
% Now, if the command has any parameter token in its definition
% (then \cs{@@_exp_not:n} is \cs{exp_not:n}), call
% \cs{@@_double_hashes:n} to double them, and replace every
-% \cs{c_@@_hash_tl} by |#|:
+% \cs{c_@@_hashes_tl} by |#|:
% \begin{macrocode}
\tl_set:Nx \l_@@_replace_text_tl
{ \exp_not:N #2 \exp_not:V \l_@@_replace_text_tl }
@@ -875,22 +954,110 @@
{ \exp_not:N \@@_make_prefixes:w \cs_prefix_spec:N #2 / / }
}
% \end{macrocode}
-% Finally, call \cs{@@_redefine_with_hooks:Nnnn} with the macro being
+% Here we redefine the hook to have the right number of arguments.
+% Disabling the hook, undefining the \verb|parameter| token list then
+% calling \cs{@@_make_usable:nn} are enough to redefine the hook to
+% the extent we want. Code stored in the hook and other metadata
+% about it are not lost in the process.
+% \changes{v1.0h}{2023/05/21}
+% {Changes to allow support arguments in cmd hooks (cmd-args).}
+% \begin{macrocode}
+ \@@_disable:n { cmd / #3 / #4 }
+ \cs_undefine:c { c_@@_cmd / #3 / #4_parameter_tl }
+ \@@_make_usable:nn { cmd / #3 / #4 } { \l_@@_patch_num_args_int }
+% \end{macrocode}
+% Now call \cs{@@_redefine_with_hooks:Nnnn} with the macro being
% redefined in |#1|, then \cs{UseHook}|{cmd/<name>/before}| in |#2| or
% \cs{UseHook}|{cmd/<name>/after}| in |#3| (one is always empty), and
% in |#4| the \meta{replacement text} of the macro.
% \begin{macrocode}
- \use:x
+ \use:e
{
\@@_redefine_with_hooks:Nnnn \exp_not:N #2
\str_if_eq:nnTF {#4} { after }
{ \use_ii_i:nn }
{ \use:nn }
- { { \@@_exp_not:NN \exp_not:N \UseHook { cmd / #3 / #4 } } }
+ { {
+ \@@_exp_not:NN \exp_not:N \UseHookWithArguments
+ { cmd / #3 / #4 } { \int_use:N \l_@@_patch_num_args_int }
+ \@@_braced_parameter:n { cmd / #3 / #4 }
+ } }
{ { } }
{ \@@_exp_not:NN \exp_not:V \l_@@_replace_text_tl }
}
+% \end{macrocode}
+% Finally, update the hook code.
+% \begin{macrocode}
+ \@@_update_hook_code:n { cmd / #3 / #4 }
}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2021/06/01}{\@@_patch_expand_redefine:NNnn}
+%<latexrelease> {cmd~hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \@@_patch_expand_redefine:NNnn #1 #2 #3 #4
+%<latexrelease> {
+%<latexrelease> \@@_patch_debug:x { ++~command~can~be~patched~without~rescanning }
+%<latexrelease> \int_set:Nn \l_@@_patch_num_args_int
+%<latexrelease> {
+%<latexrelease> \exp_args:Nf \str_count:n { \cs_argument_spec:N #2 } / 2
+%<latexrelease> \bool_if:NT #1 { -1 }
+%<latexrelease> }
+%<latexrelease> \int_compare:nNnTF { \l_@@_patch_num_args_int } > { \c_zero_int }
+%<latexrelease> {
+%<latexrelease> \tl_set:Nx \l_@@_tmpa_tl { \bool_if:NTF #1 { [ ] } { { } } }
+%<latexrelease> \int_step_inline:nnn { 2 } { \l_@@_patch_num_args_int }
+%<latexrelease> { \tl_put_right:Nn \l_@@_tmpa_tl { { } } }
+%<latexrelease> \exp_args:NNo \exp_args:No \@@_if_has_hash:nTF
+%<latexrelease> { \exp_after:wN #2 \l_@@_tmpa_tl }
+%<latexrelease> { \cs_set_eq:NN \@@_exp_not:n \exp_not:n }
+%<latexrelease> { \cs_set_eq:NN \@@_exp_not:n \use:n }
+%<latexrelease> \cs_set_protected:Npn \@@_tmp:w ##1 ##2
+%<latexrelease> {
+%<latexrelease> ##1 \l_@@_param_text_tl { \use:n ##2 }
+%<latexrelease> ##1 \l_@@_replace_text_tl { \@@_exp_not:n {##2} }
+%<latexrelease> }
+%<latexrelease> \bool_if:NTF #1
+%<latexrelease> { \@@_tmp:w \tl_set:Nx { [ \c_@@_hash_tl 1 ] } }
+%<latexrelease> { \@@_tmp:w \tl_set:Nx { { \c_@@_hash_tl 1 } } }
+%<latexrelease> \int_step_inline:nnn { 2 } { \l_@@_patch_num_args_int }
+%<latexrelease> { \@@_tmp:w \tl_put_right:Nx { { \c_@@_hash_tl ##1 } } }
+%<latexrelease> \tl_set:Nx \l_@@_replace_text_tl
+%<latexrelease> { \exp_not:N #2 \exp_not:V \l_@@_replace_text_tl }
+%<latexrelease> \tl_set:Nx \l_@@_replace_text_tl
+%<latexrelease> {
+%<latexrelease> \token_if_eq_meaning:NNTF \@@_exp_not:n \exp_not:n
+%<latexrelease> { \exp_args:NNV \exp_args:No \@@_double_hashes:n }
+%<latexrelease> { \exp_args:NV \exp_not:o }
+%<latexrelease> \l_@@_replace_text_tl
+%<latexrelease> }
+%<latexrelease> \cs_set_eq:NN \@@_def_cmd:w \tex_gdef:D
+%<latexrelease> \cs_set_eq:NN \@@_exp_not:NN \prg_do_nothing:
+%<latexrelease> }
+%<latexrelease> {
+%<latexrelease> \tl_clear:N \l_@@_param_text_tl
+%<latexrelease> \tl_set_eq:NN \l_@@_replace_text_tl #2
+%<latexrelease> \cs_set_eq:NN \@@_def_cmd:w \tex_xdef:D
+%<latexrelease> \cs_set:Npn \@@_exp_not:NN ##1 { \exp_not:N ##1 \exp_not:N }
+%<latexrelease> }
+%<latexrelease> \group_begin:
+%<latexrelease> \int_set:Nn \tex_escapechar:D { `\/ }
+%<latexrelease> \use:x
+%<latexrelease> {
+%<latexrelease> \group_end:
+%<latexrelease> \tl_set:Nx \exp_not:N \l_@@_patch_prefixes_tl
+%<latexrelease> { \exp_not:N \@@_make_prefixes:w \cs_prefix_spec:N #2 / / }
+%<latexrelease> }
+%<latexrelease> \use:x
+%<latexrelease> {
+%<latexrelease> \@@_redefine_with_hooks:Nnnn \exp_not:N #2
+%<latexrelease> \str_if_eq:nnTF {#4} { after }
+%<latexrelease> { \use_ii_i:nn }
+%<latexrelease> { \use:nn }
+%<latexrelease> { { \@@_exp_not:NN \exp_not:N \UseHook { cmd / #3 / #4 } } }
+%<latexrelease> { { } }
+%<latexrelease> { \@@_exp_not:NN \exp_not:V \l_@@_replace_text_tl }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
%
% Now that all the needed tools are ready, without further ado we'll
@@ -973,7 +1140,7 @@
% }
% \cs{@@_double_hashes:n} loops through the token list |#1| and
% duplicates any catcode~6 token, and expands tokens \cs{ifx}-equal to
-% \cs{c_@@_hash_tl}, and leaves all other tokens \cs{notexpanded} with
+% \cs{c_@@_hashes_tl}, and leaves all other tokens \cs{notexpanded} with
% \cs{exp_not:N}. Unfortunately pairs of explicit catcode~1 and
% catcode~2 character tokens are normalised to |{|$_1$ and |}|$_1$
% because it's not feasible to expandably detect the character code
@@ -1000,26 +1167,32 @@
% \end{macrocode}
%
% \cs{@@_double_hashes_output:N} checks for the end of the token list,
-% then checks if the token is \cs{c_@@_hash_tl}, and if so just leaves
+% then checks if the token is \cs{c_@@_hashes_tl}, and if so just leaves
% it.
+% \changes{v1.0g}{2023/04/06}
+% {Add case for \cs{c_@@_hashes_tl} (hook-args).}
% \begin{macrocode}
\cs_new:Npn \@@_double_hashes_output:N #1
{
\if_meaning:w \q_@@_recursion_tail #1
\@@_double_hashes_stop:w
\fi:
- \if_meaning:w \c_@@_hash_tl #1
+ \if:w ?
+ \if_meaning:w \c_@@_hash_tl #1 ! \fi:
+ \if_meaning:w \c_@@_hashes_tl #1 ! \fi:
+ ?
+ \else:
% \end{macrocode}
% (this \cs{use_i:nnnn} uses \cs{fi:} and consumes \cs{use:n}, the
% whole \cs{if_catcode:w} block, and the \cs{exp_not:N}, leaving just
-% |#1| which is \cs{c_@@_hash_tl}.)
+% |#1| which is \cs{c_@@_hashes_tl}.)
% \begin{macrocode}
\use_i:nnnn
\fi:
\use:n
{
% \end{macrocode}
-% If |#1| is not \cs{c_@@_hash_tl}, then check if its catcode is~6,
+% If |#1| is not \cs{c_@@_hashes_tl}, then check if its catcode is~6,
% and if so, leave it doubled in \cs{exp_not:n} and consume the
% following |\exp_not:N #1|.
% \begin{macrocode}
@@ -1080,10 +1253,10 @@
% \begin{macrocode}
\cs_new_protected:Npn \@@_retokenize_patch:Nnn #1 #2 #3
{
- \@@_patch_debug:x { ..~command~can~only~be~patched~by~rescanning }
\str_if_eq:eeTF { \cs_argument_spec:N #1 } { }
{ \@@_patch_expand_redefine:NNnn \c_false_bool #1 {#2} {#3} }
{
+ \@@_patch_debug:x { ..~command~can~only~be~patched~by~rescanning }
% \end{macrocode}
%
% Otherwise, we start the actual patching by retokenization job. The
@@ -1144,6 +1317,8 @@
% \cs{@@_cmd_if_scanable:NnTF} and \cs{@@_patch_retokenize:Nnnn} if
% the former returns \meta{true}, plus some debug messages.
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_try_patch_with_catcodes:Nnnnw}
+%<latexrelease> {cmd~hooks~with~args}
\cs_new_protected:Npn \@@_try_patch_with_catcodes:Nnnnw #1 #2 #3 #4
{
\quark_if_recursion_tail_stop_do:nn {#4} { \use:n }
@@ -1152,7 +1327,7 @@
{
\@@_patch_debug:x { ++~macro~can~be~retokenized~cleanly }
\@@_patch_debug:x { ==~retokenizing~macro~now }
- \@@_patch_retokenize:Nnnn #1 {#2} {#3} {#4}
+ \@@_patch_retokenize:Nnnn #1 { cmd / #2 / #3 } {#3} {#4}
\use_i_delimit_by_q_recursion_stop:nw \use_none:n
}
{
@@ -1160,6 +1335,26 @@
\@@_try_patch_with_catcodes:Nnnnw #1 {#2} {#3}
}
}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2021/06/01}{\@@_try_patch_with_catcodes:Nnnnw}
+%<latexrelease> {cmd~hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \@@_try_patch_with_catcodes:Nnnnw #1 #2 #3 #4
+%<latexrelease> {
+%<latexrelease> \quark_if_recursion_tail_stop_do:nn {#4} { \use:n }
+%<latexrelease> \@@_patch_debug:x { ++~trying~to~patch~by~retokenization }
+%<latexrelease> \@@_cmd_if_scanable:NnTF {#1} {#4}
+%<latexrelease> {
+%<latexrelease> \@@_patch_debug:x { ++~macro~can~be~retokenized~cleanly }
+%<latexrelease> \@@_patch_debug:x { ==~retokenizing~macro~now }
+%<latexrelease> \@@_patch_retokenize:Nnnn #1 {#2} {#3} {#4}
+%<latexrelease> \use_i_delimit_by_q_recursion_stop:nw \use_none:n
+%<latexrelease> }
+%<latexrelease> {
+%<latexrelease> \@@_patch_debug:x { --~macro~cannot~be~retokenized~cleanly }
+%<latexrelease> \@@_try_patch_with_catcodes:Nnnnw #1 {#2} {#3}
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
@@ -1267,15 +1462,86 @@
% \end{macro}
%
%
+% \begin{macro}{\@@_guess_arg_count:NN}
+% \begin{macro}{\@@_guess_arg_count:wN}
+% \begin{macro}{\@@_guess_arg_count:nw}
+% Looks at the parameter text of a macro, and counts the parameters
+% by looking at the number after a \verb|#|, and checking if they are
+% sequential. This macro assumes that all parameters are marked with
+% hashes, and not other characters, and that there is no
+% \enquote{trick parameter}.
+% \changes{v1.0h}{2023/05/21}
+% {Macro added (cmd-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_guess_arg_count:NN}
+%<latexrelease> {cmd~hooks~with~args}
+\cs_new_protected:Npn \@@_guess_arg_count:NN #1
+ {
+ \exp_after:wN \@@_guess_arg_count:wN
+ \token_to_meaning:N #1 \s_@@_mark
+ }
+\exp_last_unbraced:NNNNo
+\cs_new_protected:Npx \@@_guess_arg_count:wN
+ #1 { \tl_to_str:n { macro: } } #2 \s_@@_mark #3
+ {
+ \int_set:Nn #3
+ {
+ \exp_not:N \@@_guess_arg_count:nw { 0 } #2
+ \c_hash_str 0 \s_@@_mark
+ }
+ }
+\use:e
+ { \cs_new:Npn \exp_not:N \@@_guess_arg_count:nw #1 #2 \c_hash_str #3 }
+ {
+ \int_compare:nNnTF { #1 + 1 } = {#3}
+ { \@@_guess_arg_count:nw {#3} }
+ { #1 \@@_use_none_delimit_by_s_mark:w }
+ }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2021/06/01}{\@@_guess_arg_count:NN}
+%<latexrelease> {cmd~hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_guess_arg_count:NN
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
%
% \begin{macro}{\@@_patch_retokenize:Nnnn}
% Then, if \cs{@@_cmd_if_scanable:NnTF} returned true, we can go on
% and patch the command.
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_patch_retokenize:Nnnn}
+%<latexrelease> {cmd~hooks~with~args}
\cs_new_protected:Npn \@@_patch_retokenize:Nnnn #1 #2 #3 #4
{
+% Here, when patching by retokenization, we can only guess the number
+% of arguments of the macro.
+% \changes{v1.0h}{2023/05/21}
+% {Changes to allow support arguments in cmd hooks (cmd-args).}
+% \begin{macrocode}
+ \@@_guess_arg_count:NN #1 \l_@@_patch_num_args_int
% \end{macrocode}
-% Start off by making some things \tn{relax} to avoid lots of
+%
+% Then we redefine the hook to have the right number of arguments.
+% Disabling the hook, undefining the \verb|parameter| token list then
+% calling \cs{@@_make_usable:nn} are enough to redefine the hook to
+% the extent we want. Code stored in the hook and other metadata
+% about it are not lost in the process.
+% \begin{macrocode}
+ \@@_disable:n {#2}
+ \cs_undefine:c { c_@@_#2_parameter_tl }
+ \@@_make_usable:nn {#2} { \l_@@_patch_num_args_int }
+ \tl_set:Ne \l_@@_tmpa_tl
+ { \exp_args:Ne \tl_to_str:n { \@@_braced_parameter:n {#2} } }
+ \use:x
+ {
+ \str_replace_all:Nnn \exp_not:N \l_@@_tmpa_tl
+ { #### } { \c_hash_str }
+ }
+% \end{macrocode}
+% Then, make make some things \tn{relax} to avoid lots of
% \tn{noexpand} below.
% \begin{macrocode}
\cs_set_eq:NN \kerneltmpDoNotUse \scan_stop:
@@ -1301,10 +1567,18 @@
####1 \def \kerneltmpDoNotUse ####2
{
\str_if_eq:nnT {#3} { before }
- { \token_to_str:N \UseHook { cmd / #2 / #3 } }
+ {
+ \token_to_str:N \UseHookWithArguments {#2}
+ { \int_use:N \l_@@_patch_num_args_int }
+ \l_@@_tmpa_tl
+ }
####3
\str_if_eq:nnT {#3} { after }
- { \token_to_str:N \UseHook { cmd / #2 / #3 } }
+ {
+ \token_to_str:N \UseHookWithArguments {#2}
+ { \int_use:N \l_@@_patch_num_args_int }
+ \l_@@_tmpa_tl
+ }
}
}
% \end{macrocode}
@@ -1328,7 +1602,39 @@
% {Make patching of commands a global operation (gh/674)}
% \begin{macrocode}
\cs_gset_eq:NN #1 \kerneltmpDoNotUse
+% \end{macrocode}
+% Finally, update the hook code.
+% \begin{macrocode}
+ \@@_update_hook_code:n {#2}
}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2021/06/01}{\@@_patch_retokenize:Nnnn}
+%<latexrelease> {cmd~hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \@@_patch_retokenize:Nnnn #1 #2 #3 #4
+%<latexrelease> {
+%<latexrelease> \cs_set_eq:NN \kerneltmpDoNotUse \scan_stop:
+%<latexrelease> \cs_set_eq:NN \@@_tmp:w \scan_stop:
+%<latexrelease> \use:x
+%<latexrelease> {
+%<latexrelease> \cs_set:Npn \@@_tmp:w
+%<latexrelease> ####1 \tl_to_str:n { macro: } ####2 -> ####3 \s_@@_mark
+%<latexrelease> {
+%<latexrelease> ####1 \def \kerneltmpDoNotUse ####2
+%<latexrelease> {
+%<latexrelease> \str_if_eq:nnT {#3} { before }
+%<latexrelease> { \token_to_str:N \UseHook { cmd / #2 / #3 } }
+%<latexrelease> ####3
+%<latexrelease> \str_if_eq:nnT {#3} { after }
+%<latexrelease> { \token_to_str:N \UseHook { cmd / #2 / #3 } }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> \tl_set:Nx \exp_not:N \l_@@_tmpa_tl
+%<latexrelease> { \exp_not:N \@@_tmp:w \token_to_meaning:N #1 \s_@@_mark }
+%<latexrelease> }
+%<latexrelease> \tl_rescan:nV { #4 \@@_patch_required_catcodes: } \l_@@_tmpa_tl
+%<latexrelease> \cs_gset_eq:NN #1 \kerneltmpDoNotUse
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
diff --git a/macros/latex-dev/base/ltfilehook-code.pdf b/macros/latex-dev/base/ltfilehook-code.pdf
index c0f1ed5dbe..f8d5cc6817 100644
--- a/macros/latex-dev/base/ltfilehook-code.pdf
+++ b/macros/latex-dev/base/ltfilehook-code.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltfilehook-doc.pdf b/macros/latex-dev/base/ltfilehook-doc.pdf
index c24b2321a9..f1006dec78 100644
--- a/macros/latex-dev/base/ltfilehook-doc.pdf
+++ b/macros/latex-dev/base/ltfilehook-doc.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltfilehook.dtx b/macros/latex-dev/base/ltfilehook.dtx
index d43ffc857d..e10a5416e5 100644
--- a/macros/latex-dev/base/ltfilehook.dtx
+++ b/macros/latex-dev/base/ltfilehook.dtx
@@ -1,7 +1,7 @@
% \iffalse meta-comment
%
% Copyright (C) 2020-2023
-% Frank Mittelbach, Phelype Oleinik & LaTeX Team
+% Frank Mittelbach, Phelype Oleinik and The LaTeX Project
%
% This file is part of the LaTeX base system.
% -------------------------------------------
@@ -31,8 +31,8 @@
%%% From File: ltfilehook.dtx
%
% \begin{macrocode}
-\providecommand\ltfilehookversion{v1.0n}
-\providecommand\ltfilehookdate{2022/08/18}
+\providecommand\ltfilehookversion{v1.0o}
+\providecommand\ltfilehookdate{2023/04/02}
% \end{macrocode}
%
%<*driver>
@@ -1229,8 +1229,10 @@
% This auxiliary compares \cs{\meta{filename}} with
% \cs{csname\cs{endcsname}} to check if the empty |.tex| file was
% requested.
+% \changes{v1.0o}{2023/04/02}
+% {Make \cs{@set@curr@file@aux} \cs{long} gh/942}
% \begin{macrocode}
-\def\@set@curr@file@aux#1{%
+\long\def\@set@curr@file@aux#1{%
\expandafter\ifx\csname\endcsname#1%
.tex\else\string#1\fi}
% \end{macrocode}
diff --git a/macros/latex-dev/base/ltfiles.dtx b/macros/latex-dev/base/ltfiles.dtx
index 042565299a..3bac7ea0b2 100644
--- a/macros/latex-dev/base/ltfiles.dtx
+++ b/macros/latex-dev/base/ltfiles.dtx
@@ -32,7 +32,7 @@
%<*driver>
% \fi
\ProvidesFile{ltfiles.dtx}
- [2023/01/05 v1.2s LaTeX Kernel (File Handling)]
+ [2023/05/17 v1.2t LaTeX Kernel (File Handling)]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{ltfiles.dtx}
@@ -1202,6 +1202,9 @@
% \changes{v1.0t}{1995/05/25}{(CAR) added \cs{long}}
% \changes{v1.2d}{2019/10/26}{quote on openin}
% \changes{v1.2k}{2021/03/12}{Allow unbalanced conditionals (gh/530)}
+% \changes{v1.2t}{2023/05/15}{Use \pkg{expl3} file existence test}
+% \begin{macro}{\IfFileExists@}
+% \changes{v1.2t}{2023/05/15}{Macro added}
% Argument |#1| is |\@curr@file| so catcode 12 string with no quotes.
%
% The original definition picked up arguments |#2| and |#3| in a
@@ -1211,23 +1214,35 @@
% \cs{secondoftwo}. However, that changes how |#| is interpreted
% and so we can't do that nowaways without invalidating a lot of
% code. Therefore the somewhat curious construction near the end.
+%
+% Earlier versions used |\openin| here, but this led to two
+% code paths, one in \pkg{expl3} and one here. To avoid that,
+% and as the \pkg{expl3} approach works by expansion, we use
+% that here. As we need the file name to include the path,
+% the actual \pkg{expl3} function used is not the file existence
+% test!
% \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
-%<latexrelease>\IncludeInRelease{2021/06/01}%
-%<latexrelease> {\IfFileExists@}{manage unbalanced conditionals}
+%<latexrelease>\IncludeInRelease{2023/05/01}%
+%<latexrelease> {\IfFileExists@}{IfFileExists}
\long\def \IfFileExists@#1#2#3{%
- \openin\@inputcheck"#1" %
- \ifeof\@inputcheck
- \ifx\input@path\@undefined
- \let\reserved@a\@secondoftwo
+ \edef\@filef@und{\IfFileExists@@{#1}}%
+% \end{macrocode}
+% The \pkg{expl3} function regards an empty argument as nothing at all,
+% but the \LaTeXe{} convention is that this is equal to the special
+% \texttt{.tex} file.
+% \begin{macrocode}
+ \ifx\@filef@und\@empty
+ \if\relax\detokenize{#1}\relax
+ \let\reserved@a\@firstoftwo
+ \def\@filef@und{".tex" }%
\else
- \def\reserved@a{\@iffileonpath{#1}}%
+ \let\reserved@a\@secondoftwo
\fi
\else
- \closein\@inputcheck
- \edef\@filef@und{"#1" }%
\let\reserved@a\@firstoftwo
+ \edef\@filef@und{"\@filef@und" }%
\fi
% \end{macrocode}
% This is just there so that any |#| inside |#2| or |#3| needs
@@ -1236,10 +1251,35 @@
\expandafter\def\expandafter\reserved@a
\expandafter{\reserved@a{#2}{#3}}%
\reserved@a}
+\ExplSyntaxOn
+\cs_new_eq:NN \IfFileExists@@ \file_full_name:n
+\ExplSyntaxOff
%</2ekernel|latexrelease>
%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2021/06/01}%
+%<latexrelease> {\IfFileExists@}{IfFileExists}
+%<latexrelease>
+%<latexrelease>\long\def \IfFileExists@#1#2#3{%
+%<latexrelease> \openin\@inputcheck"#1" %
+%<latexrelease> \ifeof\@inputcheck
+%<latexrelease> \ifx\input@path\@undefined
+%<latexrelease> \let\reserved@a\@secondoftwo
+%<latexrelease> \else
+%<latexrelease> \def\reserved@a{\@iffileonpath{#1}}%
+%<latexrelease> \fi
+%<latexrelease> \else
+%<latexrelease> \closein\@inputcheck
+%<latexrelease> \edef\@filef@und{"#1" }%
+%<latexrelease> \let\reserved@a\@firstoftwo
+%<latexrelease> \fi
+%<latexrelease> \expandafter\def\expandafter\reserved@a
+%<latexrelease> \expandafter{\reserved@a{#2}{#3}}%
+%<latexrelease>\reserved@a}
+%<latexrelease>\let\IfFileExists@@\@undefined
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>
%<latexrelease>\IncludeInRelease{2019/10/01}%
-%<latexrelease> {\IfFileExists@}{manage unbalanced conditionals}
+%<latexrelease> {\IfFileExists@}{IfFileExists}
%<latexrelease>
%<latexrelease>\long\def \IfFileExists@#1#2#3{%
%<latexrelease> \openin\@inputcheck"#1" %
@@ -1257,7 +1297,7 @@
%<latexrelease> \reserved@a}
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{0000/00/00}%
-%<latexrelease> {\IfFileExists@}{manage unbalanced conditionals}
+%<latexrelease> {\IfFileExists@}{IfFileExists}
%<latexrelease>
%<latexrelease>\let\IfFileExists@\@undefined
%<latexrelease>
@@ -1266,7 +1306,7 @@
%<*2ekernel>
% \end{macrocode}
% \end{macro}
-%
+% \end{macro}
%
%
%
diff --git a/macros/latex-dev/base/ltfinal.dtx b/macros/latex-dev/base/ltfinal.dtx
index 9fa6bbc856..1e39e293e0 100644
--- a/macros/latex-dev/base/ltfinal.dtx
+++ b/macros/latex-dev/base/ltfinal.dtx
@@ -33,7 +33,7 @@
%<*driver>
% \fi
\ProvidesFile{ltfinal.dtx}
- [2022/11/30 v2.2y LaTeX Kernel (Final Settings)]
+ [2023/04/20 v2.3b LaTeX Kernel (Final Settings)]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{ltfinal.dtx}
@@ -1062,6 +1062,24 @@
\fi % End of reset block for 8-bit engines
% \end{macrocode}
%
+% \begin{macro}{\BCPdata}
+% \changes{v2.3a}{2023/04/16}{Command added}
+% A stub for use by \pkg{babel}, \pkg{polyglossia}, etc.
+% \begin{macrocode}
+\ExplSyntaxOn
+\newcommand*\BCPdata[1]{
+ \str_case:nn {#1}
+ {
+ { language } { en }
+ { region } { US }
+ { script } { Latn }
+ { tag } { en-US }
+ }
+}
+\ExplSyntaxOff
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\MakeUppercase}
% \begin{macro}{\MakeLowercase}
% \begin{macro}{\MakeTitlecase}
@@ -1069,6 +1087,9 @@
% \begin{macro}{\AddToNoCaseChangeList}
% \begin{macro}{\CaseSwitch}
% \begin{macro}{\DeclareCaseChangeEquivalent}
+% \begin{macro}{\DeclareLowercaseMapping}
+% \begin{macro}{\DeclareTitlecaseMapping}
+% \begin{macro}{\DeclareUppercaseMapping}
% \begin{macro}{\@uclclist}
%
%
@@ -1088,6 +1109,7 @@
% \changes{v2.2x}{2022/10/26}{Introduce optional argument for case-changing commands}
% \changes{v2.2x}{2022/10/26}{Make case changing commands language-aware}
% \changes{v2.2x}{2022/10/26}{Auto-detect \pkg{babel} locale}
+% \changes{v2.3a}{2023/04/11}{Use new generic mechanism to detect locale}
% Wrappers around the L3 case changing functions.
% |\protected| to make them mostly safe as replacements for |uppercase|
% and |\lowercase|.
@@ -1121,33 +1143,24 @@
{
\cs_set_nopar:Npn \reserved@a { }
\tl_if_blank:nTF {#2}
- { \@@text@case@aux@ }
- { \keys_set:nn { __kernel } {#2} }
- \use:c { text_ #1 case:Vn } \reserved@a {#3}
- }
-\cs_new_protected:Npn \@@text@case@aux@ { }
-\tl_gput_right:Nn \@kernel@after@begindocument
- {
- \@ifpackageloaded { babel }
{
- \@ifpackagelater { babel } { 2020-01-15 }
+ \str_set:Nx \reserved@a
+ { \BCPdata { casing } }
+ \str_if_empty:NT \reserved@a
{
- \cs_gset_protected:Npn \@@text@case@aux@
- {
- \str_set:Nx \reserved@a
- { \localeinfo* { tag.bcp47 } }
- }
+ \str_set:Nx \reserved@a
+ { \BCPdata { language } }
}
- { }
}
- { }
+ { \keys_set:nn { __kernel } {#2} }
+ \use:c { text_ #1 case:Vn } \reserved@a {#3}
}
-\exp_args_generate:n { cnx }
% \end{macrocode}
% The odd use of \emph{three} spaces here is needed as \pkg{ltcmd} uses the
% name with one and two spaces to give a `friendly' error message for a runaway
% argument: that means we can't use it here.
% \begin{macrocode}
+\exp_args_generate:n { cnx }
\cs_set_protected:Npn \reserved@a #1
{
\cs_generate_variant:cn { text_ \str_lowercase:n {#1} case:nn } { V }
@@ -1161,36 +1174,33 @@
\reserved@a { Title }
% \end{macrocode}
% \changes{v2.2y}{2022/11/30}{Set \cs{oe}/\cs{OE} equal to act as a marker for \pkg{babel}}
+% \changes{v2.2z}{2023/03/28}{Use groups for gh/1021}
% Currently, \pkg{babel} uses the equivalence of \cs{oe} and \cs{OE} to force casing of
% some material, most notably in \cs{today}. To enable that to work, we have to set those
% commands equal even though the current case changing code does not work using this
% approach.
% \begin{macrocode}
\cs_new_protected:cpn { MakeLowercase \c_space_tl \c_space_tl \c_space_tl } [#1] #2
- {
- \let \kernel@saved@OE \OE
+ {{
\let \OE \oe
\@@text@case@aux { lower } {#1} {#2}
- \let \OE \kernel@saved@OE
- }
+ }}
\cs_new_protected:cpn { MakeUppercase \c_space_tl \c_space_tl \c_space_tl } [#1] #2
- {
- \let \kernel@saved@oe \oe
+ {{
\let \oe \OE
\@@text@case@aux { upper } {#1} {#2}
- \let \oe \kernel@saved@oe
- }
+ }}
\cs_new_protected:cpn { MakeTitlecase \c_space_tl \c_space_tl \c_space_tl } [#1] #2
- {
- \let \kernel@saved@oe \oe
+ {{
\let \oe \OE
\@@text@case@aux { title } {#1} {#2}
- \let \oe \kernel@saved@oe
- }
+ }}
% \end{macrocode}
%
% \changes{v2.2u}{2022/06/02}{Add \cs{NoCaseChange}}
% \changes{v2.2u}{2022/06/30}{Add \cs{AddToNoCaseChangeList}}
+% \changes{v2.3b}{2023/04/19}{Add \cs{DeclareLowercaseMapping},
+% \cs{DeclareTitlecaseMapping} and \cs{DeclareUppercaseMapping}}
% |\NoCaseChange| protects its argument from the case change functions.
%
% |\AddToNoCaseChangeList| Allows new commands to protect their arguments, eg
@@ -1204,6 +1214,27 @@
\cs_new_eq:NN \CaseSwitch \text_case_switch:nnnn
\cs_new_eq:NN \DeclareCaseChangeEquivalent
\text_declare_case_equivalent:Nn
+\NewDocumentCommand \DeclareLowercaseMapping { o m m }
+ {
+ \IFNoValueTF {#1}
+ { \text_declare_lowercase_mapping:nn }
+ { \text_declare_lowercase_mapping:nnn {#1} }
+ {#2} {#3}
+ }
+\NewDocumentCommand \DeclareTitlecaseMapping { o m m }
+ {
+ \IFNoValueTF {#1}
+ { \text_declare_titlecase_mapping:nn }
+ { \text_declare_titlecase_mapping:nnn {#1} }
+ {#2} {#3}
+ }
+\NewDocumentCommand \DeclareUppercaseMapping { o m m }
+ {
+ \IFNoValueTF {#1}
+ { \text_declare_uppercase_mapping:nn }
+ { \text_declare_uppercase_mapping:nnn {#1} }
+ {#2} {#3}
+ }
\ExplSyntaxOff
% \end{macrocode}
%
@@ -1222,6 +1253,9 @@
% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
%
% \changes{v1.0h}{1994/05/13}{Added output enc stuff}
% \changes{v1.0i}{1994/05/16}{moved output enc stuff to lfonts}
diff --git a/macros/latex-dev/base/ltfssbas.dtx b/macros/latex-dev/base/ltfssbas.dtx
index 019fca9aba..fda3d1ca4b 100644
--- a/macros/latex-dev/base/ltfssbas.dtx
+++ b/macros/latex-dev/base/ltfssbas.dtx
@@ -35,7 +35,7 @@
%
%
\ProvidesFile{ltfssbas.dtx}
- [2022/07/04 v3.2k LaTeX Kernel (NFSS Basic Macros)]
+ [2023/04/01 v3.2l LaTeX Kernel (NFSS Basic Macros)]
% \iffalse
\documentclass{ltxdoc}
\begin{document}
@@ -1050,11 +1050,22 @@
% {\cs{def} $\to$ \cs{edef} for \cs{math@version}.}
% \changes{v1.2g}{1990/02/16}{\cs{@nomath} added.}
% \changes{v2.1a}{1994/01/17}{New math font setup}
+% \changes{v3.2l}{2023/04/01}{Reset frozen mathversion gh/1028}
% \begin{macrocode}
\DeclareRobustCommand\mathversion[1]
{\@nomath\mathversion
\expandafter\ifx\csname mv@#1\endcsname\relax
\@latex@error{Math version `#1' is not defined}\@eha\else
+% \end{macrocode}
+% If there has been a frozen math version reset locally. See GH 1028.
+% \begin{macrocode}
+ \ifcsname mv@\math@version @frozen\endcsname
+ \expandafter\let
+ \csname mv@\math@version @frozen\expandafter\endcsname
+ \csname mv@\math@version\endcsname
+ \fi
+% \end{macrocode}
+% \begin{macrocode}
\edef\math@version{#1}%
% \end{macrocode}
% We need to force a math font setup both now and at the point
diff --git a/macros/latex-dev/base/lthooks-code.pdf b/macros/latex-dev/base/lthooks-code.pdf
index d2bd8ee0a1..eb59fc8bbc 100644
--- a/macros/latex-dev/base/lthooks-code.pdf
+++ b/macros/latex-dev/base/lthooks-code.pdf
Binary files differ
diff --git a/macros/latex-dev/base/lthooks-doc.pdf b/macros/latex-dev/base/lthooks-doc.pdf
index e9954e43f7..4c07148e48 100644
--- a/macros/latex-dev/base/lthooks-doc.pdf
+++ b/macros/latex-dev/base/lthooks-doc.pdf
Binary files differ
diff --git a/macros/latex-dev/base/lthooks.dtx b/macros/latex-dev/base/lthooks.dtx
index 1255c63a8c..c0efe2c903 100644
--- a/macros/latex-dev/base/lthooks.dtx
+++ b/macros/latex-dev/base/lthooks.dtx
@@ -1,7 +1,7 @@
% \iffalse meta-comment
%
% Copyright (C) 2020-2023
-% Frank Mittelbach, Phelype Oleinik & LaTeX Team
+% Frank Mittelbach, Phelype Oleinik, The LaTeX Project
%
% This file is part of the LaTeX base system.
% -------------------------------------------
@@ -31,8 +31,8 @@
%%% From File: lthooks.dtx
%
% \begin{macrocode}
-\def\lthooksversion{v1.0v}
-\def\lthooksdate{2022/06/15}
+\def\lthooksversion{v1.1d}
+\def\lthooksdate{2023/05/21}
% \end{macrocode}
%
%<*driver>
@@ -148,7 +148,6 @@
% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
-%
% \begin{function}{\NewMirroredHookPair}
% \begin{syntax}
% \cs{NewMirroredHookPair} \Arg{hook-1} \Arg{hook-2}
@@ -156,7 +155,45 @@
% A shorthand for
% \cs{NewHook}\Arg{hook-1}\cs{NewReversedHook}\Arg{hook-2}.
%
-% The \meta{hooks} can be specified using the dot-syntax to denote
+% The \meta{hook} can be specified using the dot-syntax to denote
+% the current package name. See section~\ref{sec:default-label}.
+% \end{function}
+%
+%
+% \begin{function}{\NewHookWithArguments}
+% \begin{syntax}
+% \cs{NewHookWithArguments} \Arg{hook} \Arg{number}
+% \end{syntax}
+% Creates a new \meta{hook} whose code takes \meta{number} arguments,
+% and otherwise works exactly like \cs{NewHook}.
+% Section~\ref{sec:hook-args} explains hooks with arguments.
+%
+% The \meta{hook} can be specified using the dot-syntax to denote
+% the current package name. See section~\ref{sec:default-label}.
+% \end{function}
+%
+% \begin{function}{\NewReversedHookWithArguments}
+% \begin{syntax}
+% \cs{NewReversedHookWithArguments} \Arg{hook} \Arg{number}
+% \end{syntax}
+% Like \cs{NewReversedHook}, but creates a hook whose code takes
+% \meta{number} arguments.
+% Section~\ref{sec:hook-args} explains hooks with arguments.
+%
+% The \meta{hook} can be specified using the dot-syntax to denote
+% the current package name. See section~\ref{sec:default-label}.
+% \end{function}
+%
+% \begin{function}{\NewMirroredHookPairWithArguments}
+% \begin{syntax}
+% \cs{NewMirroredHookPairWithArguments} \Arg{hook-1} \Arg{hook-2} \Arg{number}
+% \end{syntax}
+% A shorthand for
+% \cs{NewHookWithArguments}\Arg{hook-1}\Arg{number}\\
+% \cs{NewReversedHookWithArguments}\Arg{hook-2}\Arg{number}.
+% Section~\ref{sec:hook-args} explains hooks with arguments.
+%
+% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
@@ -173,9 +210,9 @@
% \begin{syntax}
% \cs{DisableGenericHook} \Arg{hook}
% \end{syntax}
-% After this declaration\footnotemark{} the \meta{hook} is no longer usable: Any
-% attempt to add further code to it will result in an error and any
-% use, e.g., via \cs{UseHook}, will simply do nothing.
+% After this declaration\footnotemark{} the \meta{hook} is no longer
+% usable: Any further attempt to add code to it will result in an
+% error and any use, e.g., via \cs{UseHook}, will simply do nothing.
%
% This is intended to be used with generic command hooks (see
% \texttt{ltcmdhooks-doc}) as depending on the definition of the
@@ -215,7 +252,7 @@
% \begin{syntax}
% \cs{UseHook} \Arg{hook}
% \end{syntax}
-% Execute the hook code inside a command or environment.
+% Execute the code stored in the \meta{hook}.
%
% Before \verb=\begin{document}= the fast execution code for a hook
% is not set up, so in order to use a hook there it is explicitly
@@ -227,14 +264,30 @@
% A leading |.| is treated literally.
% \end{function}
%
+% \begin{function}{\UseHookWithArguments}
+% \begin{syntax}
+% \cs{UseHookWithArguments} \Arg{hook} \Arg{number} \Arg{arg_1} \ldots \Arg{arg_n}
+% \end{syntax}
+% Execute the code stored in the \meta{hook} and pass the arguments
+% \Arg{arg_1} through \Arg{arg_n} to the \meta{hook}. Otherwise, it
+% works exactly like \cs{UseHook}.
+% The \meta{number} should be the number of arguments declared for
+% the hook. If the hook is not declared, this command does nothing
+% and it will remove \meta{number} items from the input.
+% Section~\ref{sec:hook-args} explains hooks with arguments.
+%
+% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
+% A leading |.| is treated literally.
+% \end{function}
+%
% \begin{function}{\UseOneTimeHook}
% \begin{syntax}
% \cs{UseOneTimeHook} \Arg{hook}
% \end{syntax}
% Some hooks are only used (and can be only used) in one place, for
% example, those in \verb=\begin{document}= or
-% \verb=\end{document}=. Once we have passed that point adding to
-% the hook through a defined \cs[no-index]{\meta{addto-cmd}} command (e.g.,
+% \verb=\end{document}=. From that point onwards, adding to the hook
+% through a defined \cs[no-index]{\meta{addto-cmd}} command (e.g.,
% \cs{AddToHook} or \cs{AtBeginDocument}, etc.\@) would have no
% effect (as would the use of such a command inside the hook code
% itself). It is therefore customary to redefine
@@ -250,15 +303,30 @@
% section~\ref{sec:default-label} for details.
%
% Using \cs{UseOneTimeHook} several times with the same
-% \Arg{hook} means that it only executes the first time it is used.
+% \Arg{hook} means that it only executes the first time it is used.
% For example, if it is used in a command that can be called several times
-% then the hook executes during only the \emph{first} invocation of that
+% then the hook executes during only the \emph{first} invocation of that
% command; this allows its use as an \enquote{initialization hook}.
%
% Mixing \cs{UseHook} and \cs{UseOneTimeHook} for the same
% \Arg{hook} should be avoided, but if this is done then neither will execute
% after the first \cs{UseOneTimeHook}.
+% \end{function}
%
+% \begin{function}{\UseOneTimeHookWithArguments}
+% \begin{syntax}
+% \cs{UseOneTimeHookWithArguments} \Arg{hook} \Arg{number} \Arg{arg_1} \ldots \Arg{arg_n}
+% \end{syntax}
+% Works exactly like \cs{UseOneTimeHook}, but passes arguments
+% \Arg{arg_1} through \Arg{arg_n} to the \meta{hook}.
+% The \meta{number} should be the number of arguments declared for
+% the hook. If the hook is not declared, this command does nothing
+% and it will remove \meta{number} items from the input.
+%
+% It should be noted that after a one-time hook is used, it is no
+% longer possible to use \cs{AddToHookWithArguments} or similar with
+% that hook. \cs{AddToHook} continues to work as normal.
+% Section~\ref{sec:hook-args} explains hooks with arguments.
% \end{function}
%
%
@@ -294,6 +362,34 @@
% See section~\ref{sec:default-label}.
% \end{function}
%
+% \begin{function}{\AddToHookWithArguments}
+% \begin{syntax}
+% \cs{AddToHookWithArguments} \Arg{hook}\oarg{label}\Arg{code}
+% \end{syntax}
+% Works exactly like \cs{AddToHook}, except that the \meta{code} can
+% access the arguments passed to the hook using \verb|#1|, \verb|#2|,
+% \ldots, \verb|#n| (up to the number of arguments declared for the
+% hook). If the \meta{code} should contain \emph{parameter tokens}
+% (\verb|#|) that are not supposed to be understood as the arguments
+% of the hook, such tokens should be doubled. For example, with
+% \cs{AddToHook} one can write:
+%\begin{verbatim}
+% \AddToHook{myhook}{\def\foo#1{Hello, #1!}}
+%\end{verbatim}
+% but to achieve the same with \cs{AddToHookWithArguments}, one should
+% write:
+%\begin{verbatim}
+% \AddToHookWithArguments{myhook}{\def\foo##1{Hello, ##1!}}
+%\end{verbatim}
+% because in the latter case, \verb|#1| refers to the first argument
+% of the hook \hook{myhook}.
+% Section~\ref{sec:hook-args} explains hooks with arguments.
+%
+% The \meta{hook} and \meta{label} can be specified using the
+% dot-syntax to denote the current package name.
+% See section~\ref{sec:default-label}.
+% \end{function}
+%
% \begin{function}{\RemoveFromHook}
% \begin{syntax}
% \cs{RemoveFromHook} \Arg{hook}\oarg{label}
@@ -403,6 +499,19 @@
% \end{function}\footnotetext{There is
% no mechanism to reorder such code chunks (or delete them).}
%
+% \begin{function}{\AddToHookNextWithArguments}
+% \begin{syntax}
+% \cs{AddToHookNextWithArguments} \Arg{hook}\Arg{code}
+% \end{syntax}
+% Works exactly like \cs{AddToHookNext}, but the \meta{code} can
+% contain references to the arguments of the \meta{hook} as described
+% for \cs{AddToHookWithArguments} above.
+% Section~\ref{sec:hook-args} explains hooks with arguments.
+%
+% The \meta{hook} can be specified using the dot-syntax to denote
+% the current package name. See section~\ref{sec:default-label}.
+% \end{function}
+%
%
%
% \begin{function}{\ClearHookNext}
@@ -511,10 +620,10 @@
% package's hooks, so the dot-syntax doesn't make much sense.
%
% In some cases, for example in large packages, one may want to separate
-% it in logical parts, but still use the main package name as
+% the code in logical parts, but still use the main package name as the
% \meta{label}, then the \meta{default label} can be set using
-% \cs{SetDefaultHookLabel} or
-% \cs{PushDefaultHookLabel}\verb={..}=\,\ldots\cs{PopDefaultHookLabel}.
+% \cs{PushDefaultHookLabel}\verb={...}=\,\ldots\cs{PopDefaultHookLabel}
+% or \cs{SetDefaultHookLabel}\verb={...}=.
%
% \begin{function}{\PushDefaultHookLabel,\PopDefaultHookLabel}
% \begin{syntax}
@@ -906,8 +1015,11 @@
% section even in \texttt{expl3} packages, but the choice is yours.
%
%
-% \begin{function}
-% {\hook_new:n,\hook_new_reversed:n,\hook_new_pair:nn}
+% \begin{function}{
+% \hook_new:n,
+% \hook_new_reversed:n,
+% \hook_new_pair:nn
+% }
% \begin{syntax}
% \cs{hook_new:n} \Arg{hook}
% \cs{hook_new_reversed:n} \Arg{hook}
@@ -923,6 +1035,27 @@
% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
+% \begin{function}{
+% \hook_new_with_args:nn,
+% \hook_new_reversed_with_args:nn,
+% \hook_new_pair_with_args:nnn
+% }
+% \begin{syntax}
+% \cs{hook_new_with_args:nn} \Arg{hook} \Arg{number}
+% \cs{hook_new_reversed_with_args:nn} \Arg{hook} \Arg{number}
+% \cs{hook_new_pair_with_args:nnn} \Arg{hook-1} \Arg{hook-2} \Arg{number}
+% \end{syntax}
+% Creates a new \meta{hook} with normal or reverse ordering of code
+% chunks, that takes \meta{number} arguments from the input stream
+% when it is used. \cs{hook_new_pair_with_args:nn} creates a pair of
+% such hooks with \Arg{hook-2} being a reversed hook.
+% If a hook name is already taken, an error is raised and the hook
+% is not created.
+%
+% The \meta{hook} can be specified using the dot-syntax to denote
+% the current package name. See section~\ref{sec:default-label}.
+% \end{function}
+%
%
%
% \begin{function}{\hook_disable_generic:n}
@@ -958,37 +1091,62 @@
%
%
%
-% \begin{function}{\hook_use:n}
+% \begin{function}{\hook_use:n,\hook_use:nnw}
% \begin{syntax}
% \cs{hook_use:n} \Arg{hook}
+% \cs{hook_use:nnw} \Arg{hook} \Arg{number} \Arg{arg_1} \ldots \Arg{arg_n}
% \end{syntax}
% Executes the \Arg{hook} code followed (if set up) by the code for next
% invocation only, then empties that next invocation code.
+% \cs{hook_use:nnw} should be used for hooks declared with arguments,
+% and should be followed by as many brace groups as the declared
+% number of arguments.
+% The \meta{number} should be the number of arguments declared for
+% the hook. If the hook is not declared, this command does nothing
+% and it will remove \meta{number} items from the input.
%
% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
% A leading |.| is treated literally.
% \end{function}
%
-% \begin{function}{\hook_use_once:n}
+% \begin{function}{\hook_use_once:n,\hook_use_once:nnw}
% \begin{syntax}
% \cs{hook_use_once:n} \Arg{hook}
+% \cs{hook_use_once:nnw} \Arg{hook} \Arg{number} \Arg{arg_1} \ldots \Arg{arg_n}
% \end{syntax}
% Changes the \Arg{hook} status so that from now on any addition to
% the hook code is executed immediately. Then execute any
% \Arg{hook} code already set up.
+% \cs{hook_use_once:nnw} should be used for hooks declared with arguments,
+% and should be followed by as many brace groups as the declared
+% number of arguments.
+% The \meta{number} should be the number of arguments declared for
+% the hook. If the hook is not declared, this command does nothing
+% and it will remove \meta{number} items from the input.
%
% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
% A leading |.| is treated literally.
% \end{function}
%
-% \begin{function}{\hook_gput_code:nnn}
+% \begin{function}{
+% \hook_gput_code:nnn,
+% \hook_gput_code_with_args:nnn
+% }
% \begin{syntax}
% \cs{hook_gput_code:nnn} \Arg{hook} \Arg{label} \Arg{code}
+% \cs{hook_gput_code_with_args:nnn} \Arg{hook} \Arg{label} \Arg{code}
% \end{syntax}
% Adds a chunk of \meta{code} to the \meta{hook} labeled
% \meta{label}. If the label already exists the \meta{code} is
% appended to the already existing code.
%
+% If \cs{hook_gput_code_with_args:nnn} is used, the \meta{code}
+% can access the arguments passed to \cs{hook_use:nnw}
+% (or~\cs{hook_use_once:nnw}) with \verb|#1|, \verb|#2|, \ldots,
+% \verb|#n| (up to the number of arguments declared for the hook).
+% In that case, if an actual parameter token should be added to the
+% code, it should be doubled.
+%
% If code is added to an external \meta{hook} (of the kernel or
% another package) then the convention is to use the package name
% as the \meta{label} not some internal module name or some other
@@ -999,18 +1157,26 @@
% See section~\ref{sec:default-label}.
% \end{function}
%
-% \begin{function}
-% {\hook_gput_next_code:nn}
+% \begin{function}{
+% \hook_gput_next_code:nn,
+% \hook_gput_next_code_with_args:nn,
+% }
% \begin{syntax}
% \cs{hook_gput_next_code:nn} \Arg{hook} \Arg{code}
% \end{syntax}
% Adds a chunk of \meta{code} for use only in the next invocation of the
% \meta{hook}. Once used it is gone.
%
+% If \cs{hook_gput_next_code_with_args:nn} is used, the \meta{code}
+% can access the arguments passed to \cs{hook_use:nnw}
+% (or~\cs{hook_use_once:nnw}) with \verb|#1|, \verb|#2|, \ldots,
+% \verb|#n| (up to the number of arguments declared for the hook).
+% In that case, if an actual parameter token should be added to the
+% code, it should be doubled.
+%
% This is simpler than \cs{hook_gput_code:nnn}, the code is simply
% appended to the hook in the order of declaration at the very end,
% i.e., after all standard code for the hook got executed.
-%
% Thus if one needs to undo what the standard does one has to do
% that as part of \meta{code}.
%
@@ -1019,8 +1185,7 @@
% \end{function}
%
%
-% \begin{function}
-% {\hook_gclear_next_code:n}
+% \begin{function}{\hook_gclear_next_code:n}
% \begin{syntax}
% \cs{hook_gclear_next_code:n} \Arg{hook}
% \end{syntax}
@@ -1240,7 +1405,7 @@
% \begin{itshape}\begin{color}{blue} ...
% \end{itshape}\end{color}
%\end{verbatim}
-% and an error message that \verb=\begin{color}= ended by
+% and an error message saying that \verb=\begin{color}= was ended by
% \verb=\end{itshape}=.
% With \hook{env/quote/after} declared as a reversed hook the
% execution order is reversed and so all environments are closed in
@@ -1377,9 +1542,9 @@
% you typically do not know what kind of variable parts may come up
% in real documents.
%
-% For example, \pkg{babel} may want to provide hooks such as
-% \hook{babel/\meta{language}/afterextras}. Language support in
-% \pkg{babel} is often done through external language
+% For example, \pkg{babel} provides hooks such as
+% \hook{babel/\meta{language}/afterextras}. However, language
+% support in \pkg{babel} is often done through external language
% packages. Thus doing the activation for all languages inside the
% core \pkg{babel} code is not a viable approach. Instead it needs
% to be done by each language package (or by the user who wants to
@@ -1396,6 +1561,125 @@
% conciderably.
%
%
+% \subsection{Hooks with arguments}
+% \label{sec:hook-args}
+%
+% Sometimes it is necessary to pass contextual information to a hook,
+% and, for one reason or another, it is not feasible to store such
+% information in macros. To serve this purpose, hooks can be
+% declared with arguments, so that the programmer can pass along the
+% data necessary for the code in the hook to function properly.
+%
+% A hook with arguments works mostly like a regular hook, and most
+% commands that work for regular hooks, also work for hooks that take
+% arguments. The differences are when the hook is declared
+% (\cs{NewHookWithArguments} is used instead of \cs{NewHook}), then
+% code can be added with both \cs{AddToHook} and
+% \cs{AddToHookWithArguments}, and when the hook is used
+% (\cs{UseHookWithArguments} instead of \cs{UseHook}).
+%
+% \medskip
+%
+% A hook with arguments must be declared as such (before it is first
+% used, as all regular hooks) using
+% \cs{NewHookWithArguments}\Arg{hook}\Arg{number}. All code added to
+% that hook can then use \verb|#1| to access the first argument,
+% \verb|#2| to access the second, and so forth up to the number of
+% arguments declared. However, it is still possible to add code with
+% references to the arguments of a hook that was not yet declared
+% (we will discuss that later). At their core, hooks are macros, so
+% \TeX's limit of 9~arguments applies, and a low-level \TeX{} error
+% is raised if you try to reference an argument number that doesn't
+% exist.
+%
+% \medskip
+%
+% To use a hook with arguments, just write
+% \cs{UseHookWithArguments}\Arg{hook}\Arg{number} followed by a
+% braced list of the arguments. For example, if the hook \hook{test}
+% takes three arguments, write:
+%\begin{verbatim}
+% \UseHookWithArguments{test}{3}{arg-1}{arg-2}{arg-3}
+%\end{verbatim}
+% then, in the \meta{code} of the hook, all instances of \verb|#1|
+% will be replaced by \verb|arg-1|, \verb|#2| by \verb|arg-2| and so
+% on. If, at the point of usage, the programmer provides more
+% arguments than the hook is declared to take, the excess arguments
+% are simply ignored by the hook. Behaviour is
+% unpredictable\footnote
+% {The hook \emph{will} take the declared number of arguments, and
+% what will happen depends on what was grabbed, and what the hook
+% code does with its arguments.}
+% if too few arguments are provided. If the hook isn't declared,
+% \meta{number} arguments are removed from the input stream.
+%
+% \medskip
+%
+% Adding code to a hook with arguments can be done with
+% \cs{AddToHookWithArguments} as well as with the regular
+% \cs{AddToHook}, to achieve different outcomes. The main difference
+% when it comes to adding code to a hook, in this case, is firstly
+% the possibility of accessing a hook's arguments, of course, and
+% second, how parameter tokens (\verb|#|$_6$) are treated.
+%
+% Using \cs{AddToHook} in a hook that takes arguments will work as it
+% does for all other hooks. This allows a package developer to add
+% arguments to a hook that otherwise had none without having to worry
+% about compatibility. This means that, for example:
+%\begin{verbatim}
+% \AddToHook{test}{\def\foo#1{Hello, #1!}}
+%\end{verbatim}
+% will define the same macro \cs[no-index]{foo} regardless if the
+% hook \hook{test} takes arguments or not.
+%
+% Using \cs{AddToHookWithArguments} allows the \meta{code} added to
+% access the arguments of the hook with \verb|#1|, \verb|#2|, and so
+% forth, up to the number of the arguments declared in the hook.
+% This means that if one wants to add a \verb|#|$_6$ to the
+% \meta{code} that token must be doubled in the input. The same
+% definition from above, using \cs{AddToHookWithArguments}, needs to
+% be rewritten:
+%\begin{verbatim}
+% \AddToHookWithArguments{test}{\def\foo##1{Hello, ##1!}}
+%\end{verbatim}
+%
+% Extending the above example to use the hook arguments, we could
+% rewrite something like (now from declaration to usage, to get the
+% whole picture):
+%\begin{verbatim}
+% \NewHookWithArguments{test}{1}
+% \AddToHookWithArguments{test}{%
+% \typeout{Defining foo with "#1"}
+% \def\foo##1{Hello, ##1! Some text after: #1}%
+% }
+% \UseHook{test}{Howdy!}
+% \ShowCommand\foo
+%\end{verbatim}
+% Running the code above prints in the terminal:
+%\begin{verbatim}
+% Defining foo with "Howdy!"
+% > \foo=macro:
+% #1->Hello, #1! Some text after: Howdy!.
+%\end{verbatim}
+% Note how \verb|##1| in the call to \cs{AddToHookWithArguments}
+% became \verb|#1|, and the \verb|#1| was replaced by the argument
+% passed to the hook. Should the hook be used again, with a
+% different argument, the definition would naturally change.
+%
+% \bigskip
+%
+% It is possible to add code referencing a hook's arguments before
+% such hook is declared and the number of hooks is fixed. However,
+% if some code is added to the hook, that references more arguments
+% than will be declared for the hook, there will be a low-level
+% \TeX{} error about an \enquote{Illegal parameter number} at the
+% time the hook is declared, which will be hard to track down because
+% at that point \TeX{} can't know whence the offending code came
+% from. Thus it is important that package writers explicitly
+% document how many arguments (if any) each hook can take, so users
+% of those packages know how many arguments can be referenced, and
+% equally important, what each argument means.
+%
% \subsection{Private \LaTeX{} kernel hooks}
%
% There are a few places where it is absolutely essential for
@@ -1461,7 +1745,7 @@
% package/class name if called inside such a file
% (see section~\ref{sec:default-label}).
%
-% This way one can add further code to the hook using
+% This way one can add code to the hook using
% \cs{AddToHook} or \cs{AtBeginDocument} using a different label
% and explicitly order the code chunks as necessary, e.g., run some
% code before or after another package's code. When using the
@@ -1746,10 +2030,10 @@
%
% \subsection{Hooks provided by \cs{end}\texttt{\{document\}}}
%
-% \LaTeXe{} always provided \cs{AtEndDocument} to add code to the
-% execution of \verb=\end{document}= just in front of the code that
+% \LaTeXe{} has always provided \cs{AtEndDocument} to add code to the
+% \verb=\end{document}=, just in front of the code that
% is normally executed there. While this was a big improvement over
-% the situation in \LaTeX\,2.09 it was not flexible enough for a
+% the situation in \LaTeX\,2.09, it was not flexible enough for a
% number of use cases and so packages, such as \pkg{etoolbox},
% \pkg{atveryend} and others patched \cs{enddocument} to add
% additional points where code could be hooked into.
@@ -2095,13 +2379,37 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[int]{\tl_gremove_once:Nx,\tl_show:x,\tl_log:x}
+% \begin{macro}{\c_@@_empty_tl}
+% \begin{macro}{\c_@@_nine_parameters_tl}
+% An empty token list, and one containing nine parameters.
+% \changes{v1.1a}{2023/04/06}
+% {Add auxiliary token lists (hook-args).}
+% \begin{macrocode}
+\tl_const:Nn \c_@@_empty_tl { }
+\tl_const:Nn \c_@@_nine_parameters_tl { #1#2#3#4#5#6#7#8#9 }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}[int]{
+% \tl_gremove_once:Nx,
+% \tl_show:x,
+% \tl_log:x,
+% \tl_set:Ne,
+% \cs_replacement_spec:c,
+% \prop_put:Nne,
+% \str_count:e
+% }
% Some variants of \pkg{expl3} functions.
% \fmiinline{should probably be moved to expl3}
% \begin{macrocode}
\cs_generate_variant:Nn \tl_gremove_once:Nn { Nx }
\cs_generate_variant:Nn \tl_show:n { x }
\cs_generate_variant:Nn \tl_log:n { x }
+\cs_generate_variant:Nn \tl_set:Nn { Ne }
+\cs_generate_variant:Nn \cs_replacement_spec:N { c }
+\cs_generate_variant:Nn \prop_put:Nnn { Nne }
+\cs_generate_variant:Nn \str_count:n { e }
% \end{macrocode}
% \end{macro}
%
@@ -2112,15 +2420,20 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@@_clean_to_scan:w}
+% \begin{macro}{
+% \@@_use_none_delimit_by_s_mark:w,
+% \@@_use_i_delimit_by_s_mark:nw
+% }
% Removes tokens until the next \cs{s_@@_mark}.
+% \changes{v1.1a}{2023/04/06}
+% {Use standard naming scheme (hook-args).}
% \begin{macrocode}
-\cs_new:Npn \@@_clean_to_scan:w #1 \s_@@_mark { }
+\cs_new:Npn \@@_use_none_delimit_by_s_mark:w #1 \s_@@_mark { }
+\cs_new:Npn \@@_use_i_delimit_by_s_mark:nw #1 #2 \s_@@_mark {#1}
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@@_tl_set:Nn,\@@_tl_set:Nx,
-% \@@_tl_set:cn,\@@_tl_set:cx}
+% \begin{macro}{\@@_tl_set:cn}
% Private copies of a few \pkg{expl3} functions. \pkg{l3debug} will
% only add debugging to the public names, not to these copies, so we
% don't have to use \cs{debug_suspend:} and \cs{debug_resume:}
@@ -2130,44 +2443,43 @@
% copied because in \pkg{expl3} they use
% \cs[no-index]{__kernel_tl_(g)set:Nx}, which is also patched by
% \pkg{l3debug}.
-% \changes{v1.0h}{2021/01/07}{Manually define some \pkg{l3tl} commands
+% \changes{v1.0h}{2021/01/07}{Manually define some \pkg{l3tl} commands
% to work around \pkg{expl3} changes}
+% \changes{v1.1a}{2023/04/06}
+% {Clean-up unused variants (hook-args).}
% \begin{macrocode}
-\cs_new_protected:Npn \@@_tl_set:Nn #1#2
- { \cs_set_nopar:Npx #1 { \__kernel_exp_not:w {#2} } }
-\cs_new_protected:Npn \@@_tl_set:Nx #1#2
- { \cs_set_nopar:Npx #1 {#2} }
-\cs_generate_variant:Nn \@@_tl_set:Nn { c }
-\cs_generate_variant:Nn \@@_tl_set:Nx { c }
+\cs_new_protected:Npn \@@_tl_set:cn #1#2
+ { \cs_set_nopar:cpx {#1} { \__kernel_exp_not:w {#2} } }
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@@_tl_gset:Nn,\@@_tl_gset:No,\@@_tl_gset:Nx,
+% \begin{macro}{\@@_tl_gset:Nn,\@@_tl_gset:Nx,
% \@@_tl_gset:cn,\@@_tl_gset:co,\@@_tl_gset:cx}
% Same as above.
% \begin{macrocode}
\cs_new_protected:Npn \@@_tl_gset:Nn #1#2
{ \cs_gset_nopar:Npx #1 { \__kernel_exp_not:w {#2} } }
-\cs_new_protected:Npn \@@_tl_gset:No #1#2
- { \cs_gset_nopar:Npx #1 { \__kernel_exp_not:w \exp_after:wN {#2} } }
\cs_new_protected:Npn \@@_tl_gset:Nx #1#2
{ \cs_gset_nopar:Npx #1 {#2} }
-\cs_generate_variant:Nn \@@_tl_gset:Nn { c }
-\cs_generate_variant:Nn \@@_tl_gset:No { c }
+\cs_generate_variant:Nn \@@_tl_gset:Nn { c, co }
\cs_generate_variant:Nn \@@_tl_gset:Nx { c }
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@@_tl_gput_right:Nn,\@@_tl_gput_right:No,\@@_tl_gput_right:cn}
+% \begin{macro}{
+% \@@_tl_gput_right:Nn,
+% \@@_tl_gput_right:Ne,
+% \@@_tl_gput_right:cn,
+% }
% Same as above.
% \begin{macrocode}
\cs_new_protected:Npn \@@_tl_gput_right:Nn #1#2
{ \@@_tl_gset:Nx #1 { \__kernel_exp_not:w \exp_after:wN { #1 #2 } } }
-\cs_generate_variant:Nn \@@_tl_gput_right:Nn { No, cn }
+\cs_generate_variant:Nn \@@_tl_gput_right:Nn { Ne, cn }
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@@_tl_gput_left:Nn,\@@_tl_gput_left:No}
+% \begin{macro}{\@@_tl_gput_left:Nn}
% Same as above.
% \begin{macrocode}
\cs_new_protected:Npn \@@_tl_gput_left:Nn #1#2
@@ -2175,7 +2487,6 @@
\@@_tl_gset:Nx #1
{ \__kernel_exp_not:w {#2} \__kernel_exp_not:w \exp_after:wN {#1} }
}
-\cs_generate_variant:Nn \@@_tl_gput_left:Nn { No }
% \end{macrocode}
% \end{macro}
%
@@ -2202,7 +2513,11 @@
%
% \DescribeMacro{\g_@@_\meta{hook}_code_prop}
% \DescribeMacro{\@@\textvisiblespace\meta{hook}}
+% \DescribeMacro{\g_@@_\meta{hook}_reversed_tl}
+% \DescribeMacro{\g_@@_\meta{hook}_declared_tl}
+% \DescribeMacro{\g_@@_\meta{hook}_parameter_tl}
% \DescribeMacro{\@@_next\textvisiblespace\meta{hook}}
+% \DescribeMacro{\@@_toplevel\textvisiblespace\meta{hook}}
% Hooks have a name (called \meta{hook} in the description below)
% and for each hook we have to
% provide a number of data structures. These are
@@ -2232,12 +2547,17 @@
% so that it can be identified. The |-| character is used because
% $\meta{reversed}1$ is $+1$ for normal hooks and $-1$ for reversed
% ones.
-
+%
% \item[{\cs[no-index]{g_@@_\meta{hook}_declared_tl}}] This token
-% list serves as marker for the hook being officially declared. Its
+% list serves as a marker for the hook being officially declared. Its
% existence is tested to raise an error in case another declaration
% is attempted.
%
+% \item[{\cs[no-index]{c_@@_\meta{hook}_parameter_tl}}] This token
+% list stores the parameter text for a declared hook (its existence
+% almost completely intersects the token list above), which is used
+% for managing hooks with arguments.
+%
% \item[\cs{@@_toplevel\textvisiblespace\meta{hook}}] This token list stores the code
% inserted in the hook from the user's document, in the |top-level|
% label. This label is special, and doesn't participate in sorting.
@@ -2367,45 +2687,92 @@
% \subsubsection{Setting hooks up}
%
%
-% \begin{macro}{\hook_new:n,\@@_new:n}
+% \begin{macro}{
+% \hook_new:n,
+% \hook_new_with_args:nn
+% }
+% \begin{macro}{@@_new:nn}
% The \cs{hook_new:n} declaration declares a new hook and expects
% the hook \meta{name} as its argument, e.g.,
% \hook{begindocument}.
+% \changes{v1.1a}{2023/04/06}
+% {Add \cs{hook_new_with_args:nn} (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_new_with_args:nn}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \hook_new:n #1
- { \@@_normalize_hook_args:Nn \@@_new:n {#1} }
+ { \@@_normalize_hook_args:Nn \@@_new:nn {#1} { 0 } }
+\cs_new_protected:Npn \hook_new_with_args:nn #1 #2
+ { \@@_normalize_hook_args:Nn \@@_new:nn {#1} {#2} }
% \end{macrocode}
%
% \begin{macrocode}
-\cs_new_protected:Npn \@@_new:n #1
+\cs_new_protected:Npn \@@_new:nn #1 #2
{
% \end{macrocode}
% We check if the hook was already \emph{explicitly} declared with
% \cs{hook_new:n}, and if it already exists we complain, otherwise set
% the \enquote{created} flag for the hook so that it errors next time
% \cs{hook_new:n} is used.
+% \changes{v1.1d}{2023/05/21}
+% {Changes to allow support arguments in cmd hooks (cmd-args).}
% \begin{macrocode}
\@@_if_declared:nTF {#1}
{ \msg_error:nnn { hooks } { exists } {#1} }
{
\tl_new:c { g_@@_#1_declared_tl }
- \@@_make_usable:n {#1}
+ \cs_undefine:c { @@~#1 }
+ \cs_undefine:c { c_@@_#1_parameter_tl }
+ \@@_make_usable:nn {#1} {#2}
+% \end{macrocode}
+% In case there is already code in a hook, but it's undeclared, run
+% \cs{@@_update_hook_code:n} to make it ready to be executed (see test
+% \texttt{lthooks-034}).
+% \changes{v1.1a}{2023/04/06}
+% {Update hook code after declaring.}
+% \begin{macrocode}
+ \@@_update_hook_code:n {#1}
}
}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_new_with_args:nn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \hook_new:n #1
+%<latexrelease> { \@@_normalize_hook_args:Nn \@@_new:n {#1} }
+%<latexrelease>\cs_undefine:N \@@_new:nn
+%<latexrelease>\cs_gset_protected:Npn \@@_new:n #1
+%<latexrelease> {
+%<latexrelease> \@@_if_declared:nTF {#1}
+%<latexrelease> { \msg_error:nnn { hooks } { exists } {#1} }
+%<latexrelease> {
+%<latexrelease> \tl_new:c { g_@@_#1_declared_tl }
+%<latexrelease> \@@_make_usable:n {#1}
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\cs_gset_protected:Npn \hook_new_with_args:nn #1 { }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
%
%
-% \begin{macro}{\@@_make_usable:n}
+% \begin{macro}{\@@_make_usable:nn}
%
% This initializes all hook data structures for the hook but if
% used on its own doesn't mark the hook as declared (as
% \cs{hook_new:n} does, so a later \cs{hook_new:n} on that hook will
% not result in an error. This command is internally used by
-% \cs{hook_gput_code:n} when adding code to a generic hook.
+% \cs{hook_gput_code:nnn} when adding code to a generic hook.
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
-\cs_new_protected:Npn \@@_make_usable:n #1
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_make_usable:nn}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \@@_make_usable:nn #1 #2
{
% \end{macrocode}
% Now we check if the hook's data structure can be safely created
@@ -2414,29 +2781,70 @@
% allocate the necessary data structures for the new hook,
% otherwise just do nothing.
% \begin{macrocode}
- \tl_if_exist:cF { @@~#1 }
+ \@@_if_usable:nF {#1}
{
\seq_gput_right:Nn \g_@@_all_seq {#1}
% \end{macrocode}
+% Here we'll define the \cs[no-index]{c_@@_\meta{hook}_parameter_tl}
+% to hold a run of parameters up to the number of arguments of the
+% hook (\verb|#2|).
+% \begin{macrocode}
+ \__kernel_cs_parm_from_arg_count:nnF
+ { \tl_const:cn { c_@@_#1_parameter_tl } } {#2}
+ {
+ \msg_error:nnnn { hooks } { too-many-args } {#1} {#2}
+ \tl_const:cx { c_@@_#1_parameter_tl }
+ { \exp_not:V \c_@@_nine_parameters_tl }
+ }
+% \end{macrocode}
+% After that, use \cs{@@_normalise_cs_args:nn} to correct the number
+% of parameters of the macros
+% \cs[no-index]{@@_toplevel\textvisiblespace\meta{hook}} and
+% \cs[no-index]{@@_next\textvisiblespace\meta{hook}}. We need to be
+% able to add
+% code with arguments to a hook without prior knowledge of the number
+% of arguments of that hook, so \pkg{lthooks} assumes~9 until the
+% hook is properly declared and the number of arguments is known.
+% \cs{@@_normalise_cs_args:nn} does the normalisation by using the
+% \cs[no-index]{c_@@_\meta{hook}_parameter_tl} defined just above.
+% \begin{macrocode}
+ \@@_normalise_cs_args:nn { _toplevel } {#1}
+ \@@_normalise_cs_args:nn { _next } {#1}
+% \end{macrocode}
% This is only used by the actual code of the current hook, so
% declare it normally:
% \begin{macrocode}
- \tl_new:c { @@~#1 }
+ \@@_code_gset:nn {#1} { }
% \end{macrocode}
% Now ensure that the base data structure for the hook exists:
% \begin{macrocode}
\@@_init_structure:n {#1}
% \end{macrocode}
+% The call to \cs{@@_normalise_code_pool:n} will correct any improper
+% reference to arguments that don't exist in the hook, raising a
+% low-level \TeX{} error and doubling the offending parameter tokens.
+% It has to be done after \cs{@@_init_structure:n} because it
+% operates on \cs[no-index]{g_@@_\meta{hook}_code_prop}.
+% \begin{macrocode}
+ \@@_normalise_code_pool:n {#1}
+% \end{macrocode}
% The \cs{g_@@_\meta{hook}_labels_clist} holds the sorted list of
% labels (once it got sorted). This is used only for debugging.
+% These are defined conditionally, in case \cs{@@_make_usable:nn}
+% is being used to redefine a hook.
+% \changes{v1.1d}{2023/05/21}
+% {Changes to allow support arguments in cmd hooks (cmd-args).}
% \begin{macrocode}
- \clist_new:c { g_@@_#1_labels_clist }
+ \clist_if_exist:cF { g_@@_#1_labels_clist }
+ {
+ \clist_new:c { g_@@_#1_labels_clist }
% \end{macrocode}
% Some hooks should reverse the default order of code chunks. To
% signal this we have a token list which is empty for normal hooks
% and contains a \verb=-= for reversed hooks.
% \begin{macrocode}
- \tl_new:c { g_@@_#1_reversed_tl }
+ \tl_new:c { g_@@_#1_reversed_tl }
+ }
% \end{macrocode}
% The above is all in L3 convention, but we also provide an
% interface to legacy \LaTeXe{} hooks of the form \cs{@...hook},
@@ -2454,9 +2862,28 @@
\@@_include_legacy_code_chunk:n {#1}
}
}
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
-% \end{macro}
%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_make_usable:nn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_make_usable:nn
+%<latexrelease>\cs_gset_protected:Npn \@@_make_usable:n #1
+%<latexrelease> {
+%<latexrelease> \tl_if_exist:cF { @@~#1 }
+%<latexrelease> {
+%<latexrelease> \seq_gput_right:Nn \g_@@_all_seq {#1}
+%<latexrelease> \tl_new:c { @@~#1 }
+%<latexrelease> \@@_init_structure:n {#1}
+%<latexrelease> \clist_new:c { g_@@_#1_labels_clist }
+%<latexrelease> \tl_new:c { g_@@_#1_reversed_tl }
+%<latexrelease> \@@_include_legacy_code_chunk:n {#1}
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
%
%
% \begin{macro}{\@@_init_structure:n}
@@ -2472,49 +2899,124 @@
% \cs{@@_init_structure:n} the first time anything is added to it.
% Initializing a hook just with \cs{@@_init_structure:n} will not
% make it usable with \cs{hook_use:n}.
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_init_structure:n}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \@@_init_structure:n #1
{
\@@_if_structure_exist:nF {#1}
{
\prop_new:c { g_@@_#1_code_prop }
- \tl_new:c { @@_toplevel~#1 }
- \tl_new:c { @@_next~#1 }
+ \@@_toplevel_gset:nn {#1} { }
+ \@@_next_gset:nn {#1} { }
}
}
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
-% \end{macro}
-%
%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_init_structure:n}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \@@_init_structure:n #1
+%<latexrelease> {
+%<latexrelease> \@@_if_structure_exist:nF {#1}
+%<latexrelease> {
+%<latexrelease> \prop_new:c { g_@@_#1_code_prop }
+%<latexrelease> \tl_new:c { @@_toplevel~#1 }
+%<latexrelease> \tl_new:c { @@_next~#1 }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
%
-% \begin{macro}{\hook_new_reversed:n,\@@_new_reversed:n}
+% \begin{macro}{
+% \hook_new_reversed:n,
+% \hook_new_reversed_with_args:nn
+% }
+% \begin{macro}{\@@_new_reversed:nn}
%
% Declare a new hook. The default ordering of code chunks is
% reversed, signaled by setting the token list to a minus sign.
+% \changes{v1.1a}{2023/04/06}
+% {Add \cs{hook_new_reversed_with_args:nn} (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_new_reversed_with_args:nn}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \hook_new_reversed:n #1
- { \@@_normalize_hook_args:Nn \@@_new_reversed:n {#1} }
-\cs_new_protected:Npn \@@_new_reversed:n #1
+ { \@@_normalize_hook_args:Nn \@@_new_reversed:nn {#1} { 0 } }
+\cs_new_protected:Npn \hook_new_reversed_with_args:nn #1 #2
+ { \@@_normalize_hook_args:Nn \@@_new_reversed:nn {#1} {#2} }
+\cs_new_protected:Npn \@@_new_reversed:nn #1 #2
{
- \@@_new:n {#1}
+ \@@_if_declared:nTF {#1}
+ { \msg_error:nnn { hooks } { exists } {#1} }
+ {
+ \@@_new:nn {#1} {#2}
+ \tl_gset:cn { g_@@_#1_reversed_tl } { - }
+ }
+ }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
-% If the hook already exists the above will generate an error
-% message, so the next line should be executed (but it is --- too
-% bad).
+%
% \begin{macrocode}
- \tl_gset:cn { g_@@_#1_reversed_tl } { - }
- }
+%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_new_reversed_with_args:nn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \hook_new_reversed:n #1
+%<latexrelease> { \@@_normalize_hook_args:Nn \@@_new_reversed:n {#1} }
+%<latexrelease>\cs_undefine:N \@@_new_reversed:nn
+%<latexrelease>\cs_gset_protected:Npn \@@_new_reversed:n #1
+%<latexrelease> {
+%<latexrelease> \@@_new:n {#1}
+%<latexrelease> \tl_gset:cn { g_@@_#1_reversed_tl } { - }
+%<latexrelease> }
+%<latexrelease>\cs_undefine:N \@@_new_reversed:nn
+%<latexrelease>\cs_gset_protected:Npn \hook_new_reversed_with_args:nn #1 #2 { }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
+% \end{macro}
%
-%
-%
-%
-% \begin{macro}{\hook_new_pair:nn}
+% \begin{macro}{\hook_new_pair:nn,\hook_new_pair_with_args:nnn}
% A shorthand for declaring a normal and a (matching) reversed hook in one go.
+% \changes{v1.1a}{2023/04/06}
+% {Add \cs{hook_new_pair_with_args:nnn} (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_new_pair_with_args:nnn}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \hook_new_pair:nn #1#2
- { \hook_new:n {#1} \hook_new_reversed:n {#2} }
+ { \@@_normalize_hook_args:Nnn \@@_new_pair:nnn {#1} {#2} { 0 } }
+\cs_new_protected:Npn \hook_new_pair_with_args:nnn #1#2#3
+ { \@@_normalize_hook_args:Nnn \@@_new_pair:nnn {#1} {#2} {#3} }
+\cs_new_protected:Npn \@@_new_pair:nnn #1 #2 #3
+ {
+ \@@_if_declared:nTF {#1}
+ { \msg_error:nnn { hooks } { exists } {#1} }
+ {
+ \@@_if_declared:nTF {#2}
+ { \msg_error:nnn { hooks } { exists } {#2} }
+ {
+ \@@_new:nn {#1} {#3}
+ \@@_new_reversed:nn {#2} {#3}
+ }
+ }
+ }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_new_pair_with_args:nnn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \hook_new_pair:nn #1#2
+%<latexrelease> {
+%<latexrelease> \hook_new:n {#1}
+%<latexrelease> \hook_new_reversed:n {#2}
+%<latexrelease> }
+%<latexrelease>\cs_gset_protected:Npn \hook_new_pair_with_args:nnn #1#2#3
+%<latexrelease> { }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
@@ -2531,6 +3033,8 @@
% \textbf{Warning: this support will vanish in future releases!}
% \end{quote}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_include_legacy_code_chunk:n}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \@@_include_legacy_code_chunk:n #1
{
% \end{macrocode}
@@ -2538,15 +3042,27 @@
% needs to be done.
% \begin{macrocode}
\tl_if_exist:cT { @#1hook }
+ {
% \end{macrocode}
% Of course if the legacy hook exists but is empty, there is no need
% to add anything under \texttt{legacy} the legacy label.
% \begin{macrocode}
- {
\tl_if_empty:cF { @#1hook }
{
- \exp_args:Nnnv \@@_hook_gput_code_do:nnn {#1}
- { legacy } { @#1hook }
+% \end{macrocode}
+% Here we set \cs{@@_replacing_args_false:} because no legacy code
+% will reference hook arguments.
+% \changes{v1.1b}{2023/04/16}
+% {\cs{@@_replacing_args_false:} in
+% \cs{@@_include_legacy_code_chunk:n}.}
+% \begin{macrocode}
+ \@@_replacing_args_false:
+ \use:e
+ {
+ \@@_hook_gput_code_do:nnn {#1} { legacy }
+ { \exp_not:v { @#1hook } }
+ }
+ \@@_replacing_args_reset:
% \end{macrocode}
% Once added to the hook, we need to clear it otherwise it might
% get added again later if the hook data gets updated.
@@ -2555,6 +3071,22 @@
}
}
}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_include_legacy_code_chunk:n}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \@@_include_legacy_code_chunk:n #1
+%<latexrelease> {
+%<latexrelease> \tl_if_exist:cT { @#1hook }
+%<latexrelease> {
+%<latexrelease> \tl_if_empty:cF { @#1hook }
+%<latexrelease> {
+%<latexrelease> \exp_args:Nnnv \@@_hook_gput_code_do:nnn
+%<latexrelease> {#1} { legacy } { @#1hook }
+%<latexrelease> \@@_tl_gclear:c { @#1hook }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
@@ -2579,8 +3111,8 @@
% if the hook is disabled.
%
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2021/06/01}%
-%<latexrelease> {\hook_disable_generic:n}{Disable~hooks}
+%<latexrelease>\IncludeInRelease{2021/06/01}{\hook_disable_generic:n}
+%<latexrelease> {Disable~hooks}
% \end{macrocode}
%
% \begin{macrocode}
@@ -2595,7 +3127,7 @@
{
\bool_lazy_and:nnTF
{ \tl_if_exist_p:c { g_@@_#1_declared_tl } }
- { ! \tl_if_exist_p:c { @@~#1 } }
+ { ! \cs_if_exist_p:c { @@~#1 } }
{ \prg_return_true: }
{ \prg_return_false: }
}
@@ -2603,8 +3135,8 @@
% \end{macrocode}
%
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2020/10/01}
-%<latexrelease> {\hook_disable_generic:n}{Disable~hooks}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_disable_generic:n}
+%<latexrelease> {Disable~hooks}
%<latexrelease>
%<latexrelease>\cs_new_protected:Npn \hook_disable_generic:n #1 {}
%<latexrelease>
@@ -2619,9 +3151,11 @@
% The \cs{hook_activate_generic:n} declaration declares a new hook if it
% wasn't declared already, in which case it only checks that the
% already existing hook is not a reversed hook.
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2021/06/01}%
-%<latexrelease> {\hook_activate_generic:n}{Providing~hooks}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_activate_generic:n}
+%<latexrelease> {Providing~hooks}
% \end{macrocode}
%
% \begin{macrocode}
@@ -2646,7 +3180,7 @@
\@@_if_declared:nF {#1}
{
\tl_new:c { g_@@_#1_declared_tl }
- \@@_make_usable:n {#1}
+ \@@_make_usable:nn {#1} { 0 }
\tl_gset:cx { g_@@_#1_reversed_tl }
{ \@@_if_generic_reversed:nT {#1} { - } }
% \end{macrocode}
@@ -2660,21 +3194,40 @@
}
}
% \end{macrocode}
-% \end{macro}
-% \end{macro}
%
% \begin{macrocode}
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
%
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2020/10/01}
-%<latexrelease> {\hook_activate_generic:n}{Providing~hooks}
-%<latexrelease>
-%<latexrelease>\cs_new_protected:Npn \hook_activate_generic:n #1 {}
-%<latexrelease>
+%<latexrelease>\IncludeInRelease{2021/06/01}{\hook_activate_generic:n}
+%<latexrelease> {Providing~hooks}
+%<latexrelease>\cs_gset_protected:Npn \@@_activate_generic:nn #1 #2
+%<latexrelease> {
+%<latexrelease> \@@_if_disabled:nTF {#1}
+%<latexrelease> { \msg_warning:nnn { hooks } { activate-disabled } {#1} }
+%<latexrelease> {
+%<latexrelease> \@@_if_declared:nF {#1}
+%<latexrelease> {
+%<latexrelease> \tl_new:c { g_@@_#1_declared_tl }
+%<latexrelease> \@@_make_usable:n {#1}
+%<latexrelease> \tl_gset:cx { g_@@_#1_reversed_tl }
+%<latexrelease> { \@@_if_generic_reversed:nT {#1} { - } }
+%<latexrelease> \@@_update_hook_code:n {#1}
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_activate_generic:n}
+%<latexrelease> {Providing~hooks}
+%<latexrelease>\cs_gset_protected:Npn \hook_activate_generic:n #1 { }
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
+% \end{macro}
+% \end{macro}
%
%
% \subsection{Parsing a label}
@@ -2965,63 +3518,109 @@
%
% \subsection{Adding or removing hook code}
%
-% \begin{macro}{\hook_gput_code:nnn}
-% \begin{macro}{\@@_gput_code:nnn,\@@_hook_gput_code_do:nnn}
+% \begin{macro}{\hook_gput_code:nnn,\hook_gput_code_with_args:nnn}
+% \begin{macro}{
+% \@@_gput_code:nnn,
+% \@@_gput_code_store:nnn,
+% \@@_hook_gput_code_do:nnn,
+% \@@_prop_gput_labeled_cleanup:nnn,
+% \@@_prop_gput_labeled_do:Nnnn
+% }
%
% With \cs{hook_gput_code:nnn}\Arg{hook}\Arg{label}\Arg{code} a
% chunk of \meta{code} is added to an existing \meta{hook} labeled
% with \meta{label}.
% \changes{v1.0o}{2021/07/22}{Do not queue removals (gh/625)}
+% \changes{v1.1a}{2023/04/06}
+% {Add \cs{hook_gput_code_with_args:nnn} (hook-args).}
% \begin{macrocode}
-\cs_new_protected:Npn \hook_gput_code:nnn #1 #2
- { \@@_normalize_hook_args:Nnn \@@_gput_code:nnn {#1} {#2} }
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_gput_code_with_args:nnn}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \hook_gput_code:nnn #1 #2 #3
+ {
+ \@@_replacing_args_false:
+ \@@_normalize_hook_args:Nnn \@@_gput_code:nnn {#1} {#2} {#3}
+ \@@_replacing_args_reset:
+ }
+\cs_new_protected:Npn \hook_gput_code_with_args:nnn #1 #2 #3
+ {
+ \@@_replacing_args_true:
+ \@@_normalize_hook_args:Nnn \@@_gput_code:nnn {#1} {#2} {#3}
+ \@@_replacing_args_reset:
+ }
% \end{macrocode}
%
+% If \cs{AddToHookWithArguments} was used, do some sanity checking,
+% and if it's not possible to use arguments at this point, fall back
+% to regular \cs{AddToHook} by using \cs{@@_replacing_args_false:}.
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
\cs_new_protected:Npn \@@_gput_code:nnn #1 #2 #3
{
+ \@@_chk_args_allowed:nn {#1} { AddToHook }
% \end{macrocode}
-% First check if the code should be executed immediately, rather than
+% Then check if the code should be executed immediately, rather than
% stored:
% \changes{v1.0r}{2021/09/06}{Use dedicated conditional (gh/606)}
% \begin{macrocode}
\@@_if_execute_immediately:nTF {#1}
- {#3}
{
% \end{macrocode}
+% \cs{AddToHookWithArguments} can't be used on one-time hooks (that
+% were already used).
+% \begin{macrocode}
+ \@@_if_replacing_args:TF
+ {
+ \msg_error:nnnn { hooks } { one-time-args }
+ {#1} { AddToHook }
+ }
+ { }
+ \use:n
+ }
+ { \@@_gput_code_store:nnn {#1} {#2} }
+ {#3}
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_gput_code_store:nnn #1 #2 #3
+ {
+% \end{macrocode}
% Then check if the hook is usable.
% \begin{macrocode}
- \@@_if_usable:nTF {#1}
+ \@@_if_usable:nTF {#1}
% \end{macrocode}
% If so we simply add (or append) the new code to the property list
% holding different chunks for the hook. At \verb=\begin{document}=
% this is then sorted into a token list for fast execution.
% \begin{macrocode}
- {
- \@@_hook_gput_code_do:nnn {#1} {#2} {#3}
+ {
+ \@@_hook_gput_code_do:nnn {#1} {#2} {#3}
% \end{macrocode}
% However, if there is an update within the document we need to alter
% this execution code which is done by
% \cs{@@_update_hook_code:n}. In the preamble this does nothing.
% \begin{macrocode}
- \@@_update_hook_code:n {#1}
- }
+ \@@_update_hook_code:n {#1}
+ }
% \end{macrocode}
%
% If the hook is not usable, before giving up, check if it's not
% disabled and otherwise try to declare it as a generic hook, if its
% name matches one of the valid patterns.
% \begin{macrocode}
- {
- \@@_if_disabled:nTF {#1}
- { \msg_error:nnn { hooks } { hook-disabled } {#1} }
- { \@@_try_declaring_generic_hook:nnn {#1} {#2} {#3} }
- }
+ {
+ \@@_if_disabled:nTF {#1}
+ { \msg_error:nnn { hooks } { hook-disabled } {#1} }
+ { \@@_try_declaring_generic_hook:nnn {#1} {#2} {#3} }
}
}
% \end{macrocode}
%
% This macro will unconditionally add a chunk of code to the given hook.
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
\cs_new_protected:Npn \@@_hook_gput_code_do:nnn #1 #2 #3
{
@@ -3046,31 +3645,161 @@
\str_if_eq:eeTF { top-level } { \@@_currname_or_default: }
{
% \end{macrocode}
-% If the hook's basic structure does not exist, we need to declare it
-% with \cs{@@_init_structure:n}.
+% If the hook's basic structure does not exist, we need to declare it
+% with \cs{@@_init_structure:n}.
% \begin{macrocode}
\@@_init_structure:n {#1}
- \@@_tl_gput_right:cn { @@_toplevel~#1 } {#3}
+% \end{macrocode}
+% Then append to the \verb|_toplevel| container for the hook.
+% \begin{macrocode}
+ \@@_cs_gput_right:nnn { _toplevel } {#1} {#3}
}
{ \msg_error:nnn { hooks } { misused-top-level } {#1} }
}
{
- \prop_get:cnNTF { g_@@_#1_code_prop } {#2} \l_@@_return_tl
+% \end{macrocode}
+% When adding to the code pool, we have to double hashes if
+% \cs{AddToHook} was used (\verb|replacing_args| is false), so that
+% later it is turned into a single parameter token, rather than a
+% parameter to the hook macro.
+% \begin{macrocode}
+ \exp_args:Nx \@@_prop_gput_labeled_cleanup:nnn
{
- \prop_gput:cno { g_@@_#1_code_prop } {#2}
- { \l_@@_return_tl #3 }
+ \@@_if_replacing_args:TF
+ { \exp_not:n }
+ { \@@_double_hashes:n }
+ {#3}
}
- { \prop_gput:cnn { g_@@_#1_code_prop } {#2} {#3} }
+ {#1} {#2}
}
}
% \end{macrocode}
+%
+% Adds code to a hook's code pool.
+% \changes{v1.1a}{2023/04/06}
+% {Macro added (hook-args).}
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_prop_gput_labeled_cleanup:nnn #1 #2 #3
+ {
+ \tl_set:Nn \l_@@_return_tl {#1}
+ \@@_if_replacing_args:TF
+ {
+ \@@_if_usable:nT {#2}
+ {
+ \@@_set_normalise_fn:nn {#2}
+ { Invalid~code~added~\msg_line_context: }
+ \@@_normalise_fn:nn {#3} {#1}
+ \prop_get:NnN \l_@@_work_prop {#3} \l_@@_return_tl
+ }
+ }
+ { }
+ \exp_args:NcV \@@_prop_gput_labeled_do:Nnn
+ { g_@@_#2_code_prop } \l_@@_return_tl {#3}
+ }
+\cs_new_protected:Npn \@@_prop_gput_labeled_do:Nnn #1 #2 #3
+ {
+ \prop_get:NnNTF #1 {#3} \l_@@_return_tl
+ { \prop_gput:Nno #1 {#3} { \l_@@_return_tl #2 } }
+ { \prop_gput:Nnn #1 {#3} {#2} }
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_gput_code:nnn}
+%<latexrelease> {Providing~hooks}
+%<latexrelease>\cs_gset_protected:Npn \hook_gput_code:nnn #1 #2
+%<latexrelease> { \@@_normalize_hook_args:Nnn \@@_gput_code:nnn {#1} {#2} }
+%<latexrelease>\cs_gset_protected:Npn \@@_gput_code:nnn #1 #2 #3
+%<latexrelease> {
+%<latexrelease> \@@_if_execute_immediately:nTF {#1}
+%<latexrelease> {#3}
+%<latexrelease> {
+%<latexrelease> \@@_if_usable:nTF {#1}
+%<latexrelease> {
+%<latexrelease> \@@_hook_gput_code_do:nnn {#1} {#2} {#3}
+%<latexrelease> \@@_update_hook_code:n {#1}
+%<latexrelease> }
+%<latexrelease> {
+%<latexrelease> \@@_if_disabled:nTF {#1}
+%<latexrelease> { \msg_error:nnn { hooks } { hook-disabled } {#1} }
+%<latexrelease> { \@@_try_declaring_generic_hook:nnn {#1} {#2} {#3} }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\cs_gset_protected:Npn \@@_hook_gput_code_do:nnn #1 #2 #3
+%<latexrelease> {
+%<latexrelease> \@@_debug:n{\iow_term:x{****~ Add~ to~
+%<latexrelease> \@@_if_usable:nF {#1} { undeclared~ }
+%<latexrelease> hook~ #1~ (#2)
+%<latexrelease> \on@line\space <-~ \tl_to_str:n{#3}} }
+%<latexrelease> \str_if_eq:nnTF {#2} { top-level }
+%<latexrelease> {
+%<latexrelease> \str_if_eq:eeTF { top-level } { \@@_currname_or_default: }
+%<latexrelease> {
+%<latexrelease> \@@_init_structure:n {#1}
+%<latexrelease> \@@_tl_gput_right:cn { @@_toplevel~#1 } {#3}
+%<latexrelease> }
+%<latexrelease> { \msg_error:nnn { hooks } { misused-top-level } {#1} }
+%<latexrelease> }
+%<latexrelease> {
+%<latexrelease> \prop_get:cnNTF { g_@@_#1_code_prop } {#2} \l_@@_return_tl
+%<latexrelease> {
+%<latexrelease> \prop_gput:cno { g_@@_#1_code_prop } {#2}
+%<latexrelease> { \l_@@_return_tl #3 }
+%<latexrelease> }
+%<latexrelease> { \prop_gput:cnn { g_@@_#1_code_prop } {#2} {#3} }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\cs_gset_protected:Npn \hook_gput_code_with_args:nnn #1#2#3 { }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
% \end{macro}
% \end{macro}
%
+% \begin{macro}{\@@_chk_args_allowed:nn}
+% This macro checks if it is possible to add code with references to
+% a hook's arguments for hook \verb|#1|. It only does something if
+% the function being run is \verb|replacing_args|. This macro will
+% error if the hook is declared and takes no arguments, then it will
+% set \cs{@@_replacing_args_false:} so that the macro which called it
+% will add the code normally.
+% \changes{v1.1a}{2023/04/06}
+% {Macro added (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_chk_args_allowed:nn}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \@@_chk_args_allowed:nn #1 #2
+ {
+ \@@_if_replacing_args:TF
+ {
+ \@@_if_declared:nT {#1}
+ { \tl_if_empty:cT { c_@@_#1_parameter_tl } { \use_ii:nn } }
+ \use_none:n
+ {
+ \msg_error:nnnn { hooks } { without-args } {#1} {#2}
+ \@@_replacing_args_false:
+ }
+ }
+ { }
+ }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_chk_args_allowed:nn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_chk_args_allowed:nn
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\@@_gput_undeclared_hook:nnn}
% Often it may happen that a package $A$ defines a hook \verb=foo=,
% but package $B$, that adds code to that hook, is loaded before $A$.
% In such case we need to add code to the hook before its declared.
+% An implicitly declared hook doesn't have arguments (in principle),
+% so use \cs{c_false_bool} here.
% \begin{macrocode}
\cs_new_protected:Npn \@@_gput_undeclared_hook:nnn #1 #2 #3
{
@@ -3098,24 +3827,43 @@
% \cs{hook_gput_next_code:nn} if the generic hook was declared, or
% to \cs{@@_gput_next_do:nn} otherwise.
% \changes{v1.0p}{2021/08/25}{Standardise generic hook names (gh/648)}
+% \changes{v1.1d}{2023/05/21}
+% {Changes to allow support arguments in cmd hooks (cmd-args).}
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2021/11/15}{\@@_try_declaring_generic_hook:nnn}
-%<latexrelease> {Standardise~generic~hook~names}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_try_declaring_generic_hook:nnn}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \@@_try_declaring_generic_hook:nnn #1
{
\@@_try_declaring_generic_hook:wnTF #1 / / / \scan_stop: {#1}
- \hook_gput_code:nnn
+ \@@_gput_code:nnn
\@@_gput_undeclared_hook:nnn
{#1}
}
\cs_new_protected:Npn \@@_try_declaring_generic_next_hook:nn #1
{
\@@_try_declaring_generic_hook:wnTF #1 / / / \scan_stop: {#1}
- \hook_gput_next_code:nn
+ \@@_gput_next_code:nn
\@@_gput_next_do:nn
{#1}
}
%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2021/11/15}{\@@_try_declaring_generic_hook:nnn}
+%<latexrelease> {Standardise~generic~hook~names}
+%<latexrelease>\cs_gset_protected:Npn \@@_try_declaring_generic_hook:nnn #1
+%<latexrelease> {
+%<latexrelease> \@@_try_declaring_generic_hook:wnTF #1 / / / \scan_stop: {#1}
+%<latexrelease> \hook_gput_code:nnn
+%<latexrelease> \@@_gput_undeclared_hook:nnn
+%<latexrelease> {#1}
+%<latexrelease> }
+%<latexrelease>\cs_gset_protected:Npn \@@_try_declaring_generic_next_hook:nn #1
+%<latexrelease> {
+%<latexrelease> \@@_try_declaring_generic_hook:wnTF #1 / / / \scan_stop: {#1}
+%<latexrelease> \hook_gput_next_code:nn
+%<latexrelease> \@@_gput_next_do:nn
+%<latexrelease> {#1}
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_try_declaring_generic_hook:nnn}
%<latexrelease> {Standardise~generic~hook~names}
%<latexrelease>\cs_new_protected:Npn \@@_try_declaring_generic_hook:nnn #1
@@ -3170,9 +3918,11 @@
% \end{macro}
%
% \begin{macro}[TF]{\@@_try_declaring_generic_hook:wn}
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2021/11/15}{\@@_try_declaring_generic_hook:wn}%
-%<latexrelease> {Standardise~generic~hook~names}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_try_declaring_generic_hook:wn}
+%<latexrelease> {Hooks~with~args}
\prg_new_protected_conditional:Npnn \@@_try_declaring_generic_hook:wn
#1 / #2 / #3 / #4 \scan_stop: #5 { TF }
{
@@ -3188,18 +3938,25 @@
% For some commands this will not be possible, in which case
% \cs{@@_patch_cmd_or_delay:Nnn} (defined in \texttt{ltcmdhooks})
% will generate an appropriate error message.
+% \changes{v1.1d}{2023/05/21}
+% {Changes to allow support arguments in cmd hooks (cmd-args).}
% \begin{macrocode}
\str_if_eq:nnT {#1} { cmd }
- { \@@_try_put_cmd_hook:n {#5} }
+ {
+ \@@_try_put_cmd_hook:n {#5}
+ \@@_make_usable:nn {#5} { 9 }
+ \use_none:nnn
+ }
% \end{macrocode}
%
% Declare the hook always even if it can't really be used (error
% message generated elsewhere).
%
-% Here we use \cs{@@_make_usable:n}, so that a \cs{hook_new:n} is still
-% possible later.
+% Here we use \cs{@@_make_usable:nn}, so that a \cs{hook_new:n} is
+% still possible later. Generic hooks (except \hook{cmd} hooks) take
+% no arguments, so use zero as the second argument.
% \begin{macrocode}
- \@@_make_usable:n {#5}
+ \@@_make_usable:nn {#5} { 0 }
}
\@@_if_generic_reversed:nT {#5}
{ \tl_gset:cn { g_@@_#5_reversed_tl } { - } }
@@ -3285,6 +4042,37 @@
% \end{macro}
%
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2021/11/15}{\@@_try_declaring_generic_hook:wn}
+%<latexrelease> {Standardise~generic~hook~names}
+%<latexrelease>\prg_new_protected_conditional:Npnn \@@_try_declaring_generic_hook:wn
+%<latexrelease> #1 / #2 / #3 / #4 \scan_stop: #5 { TF }
+%<latexrelease> {
+%<latexrelease> \@@_if_generic:nTF {#5}
+%<latexrelease> {
+%<latexrelease> \@@_if_usable:nF {#5}
+%<latexrelease> {
+%<latexrelease> \str_if_eq:nnT {#1} { cmd }
+%<latexrelease> { \@@_try_put_cmd_hook:n {#5} }
+%<latexrelease> \@@_make_usable:n {#5}
+%<latexrelease> }
+%<latexrelease> \@@_if_generic_reversed:nT {#5}
+%<latexrelease> { \tl_gset:cn { g_@@_#5_reversed_tl } { - } }
+%<latexrelease> \prg_return_true:
+%<latexrelease> }
+%<latexrelease> {
+%<latexrelease> \@@_if_deprecated_generic:nTF {#5}
+%<latexrelease> {
+%<latexrelease> \@@_deprecated_generic_warn:n {#5}
+%<latexrelease> \exp_after:wN \@@_declare_deprecated_generic:NNn
+%<latexrelease> \exp:w % \exp_end:
+%<latexrelease> }
+%<latexrelease> { \prg_return_false: }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
%<latexrelease>\IncludeInRelease{2021/06/01}{\@@_try_declaring_generic_hook:wn}
%<latexrelease> {Support~cmd~hooks}
%<latexrelease>\prg_new_protected_conditional:Npnn \@@_try_declaring_generic_hook:wn
@@ -3316,7 +4104,7 @@
% \end{macrocode}
%
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_try_declaring_generic_hook:wn}%
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_try_declaring_generic_hook:wn}
%<latexrelease> {Support~cmd~hooks}
%<latexrelease>\prg_new_protected_conditional:Npnn \@@_try_declaring_generic_hook:wn
%<latexrelease> #1 / #2 / #3 / #4 \scan_stop: #5 { TF }
@@ -3338,7 +4126,6 @@
%<latexrelease> { \prg_return_false: }
%<latexrelease> }
%<latexrelease> }
-%<latexrelease>
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
@@ -3350,24 +4137,10 @@
% |file/foo.tex/before|). If it is a file-specific hook, then it
% executes the \meta{true} branch, otherwise \meta{false}.
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2021/11/15}{\@@_if_file_hook:w}%
+%<latexrelease>\IncludeInRelease{2021/11/15}{\@@_if_file_hook:w}
%<latexrelease> {Standardise~generic~hook~names}
-\prg_new_conditional:Npnn \@@_if_file_hook:w
- #1 / #2 \s_@@_mark #3 { TF }
- {
- \@@_if_generic:nTF {#3}
- {
- \str_if_eq:nnTF {#1} { file }
- { \prg_return_true: }
- { \prg_return_false: }
- }
- { \prg_return_false: }
- }
%<latexrelease>\EndIncludeInRelease
-% \end{macrocode}
-%
-% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_if_file_hook:w}%
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_if_file_hook:w}
%<latexrelease> {Standardise~generic~hook~names}
%<latexrelease>\prg_new_conditional:Npnn \@@_if_file_hook:w
%<latexrelease> #1 / #2 / #3 \s_@@_mark { TF }
@@ -3394,7 +4167,7 @@
% \begin{macro}[EXP]{\@@_strip_double_slash:n,\@@_strip_double_slash:w}
%
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2021/11/15}{\@@_file_hook_normalize:n}%
+%<latexrelease>\IncludeInRelease{2021/11/15}{\@@_file_hook_normalize:n}
%<latexrelease> {Standardise~generic~hook~names}
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
@@ -3406,7 +4179,7 @@
% like \verb|\def\input@path{{./mypath/}}|, in which case a hook would
% have to be \verb|\AddToHook{file/./mypath//file.tex/after}|.
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_file_hook_normalize:n}%
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_file_hook_normalize:n}
%<latexrelease> {Standardise~generic~hook~names}
%<latexrelease>\cs_new:Npn \@@_file_hook_normalize:n #1
%<latexrelease> { \@@_strip_double_slash:n {#1} }
@@ -3453,7 +4226,7 @@
% The generic hooks used when loading a file
% \end{description}
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2021/11/15}{\c_@@_generics_prop}%
+%<latexrelease>\IncludeInRelease{2021/11/15}{\c_@@_generics_prop}
%<latexrelease> {Standardise~generic~hook~names}
\clist_map_inline:nn { cmd , env , file , package , class , include }
{
@@ -3482,7 +4255,7 @@
% \end{macrocode}
%
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2020/10/01}{\c_@@_generics_prop}%
+%<latexrelease>\IncludeInRelease{2020/10/01}{\c_@@_generics_prop}
%<latexrelease> {Standardise~generic~hook~names}
%<latexrelease>\prop_const_from_keyval:Nn \c_@@_generics_prop
%<latexrelease> {cmd=,env=,file=,package=,class=,include=}
@@ -3496,13 +4269,13 @@
% The following generic hooks are supposed to use reverse ordering
% (the |ii| and |iii| names are kept for the deprecation cycle):
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2021/11/15}{\c_@@_generics_reversed_ii_prop}%
+%<latexrelease>\IncludeInRelease{2021/11/15}{\c_@@_generics_reversed_ii_prop}
%<latexrelease> {Standardise~generic~hook~names}
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
%
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2020/10/01}{\c_@@_generics_reversed_ii_prop}%
+%<latexrelease>\IncludeInRelease{2020/10/01}{\c_@@_generics_reversed_ii_prop}
%<latexrelease> {Standardise~generic~hook~names}
%<latexrelease>\prop_const_from_keyval:Nn \c_@@_generics_reversed_ii_prop {after=,end=}
%<latexrelease>\prop_const_from_keyval:Nn \c_@@_generics_reversed_iii_prop {after=}
@@ -3511,13 +4284,46 @@
% \end{macrocode}
% \end{macro}
%
+%
+% \begin{macro}{
+% \c_@@_parameter_cmd/./before_tl,\c_@@_parameter_cmd/./after_tl,
+% }
+% Token lists defining the number of arguments for a given type of
+% generic hook.
+% \changes{v1.1d}{2023/05/21}
+% {Token lists added (cmd-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\c_@@_parameter_cmd/./before_tl}
+%<latexrelease> {Hooks~with~args}
+% \end{macrocode}
+%
+% \hook{cmd} hooks are declared with 9 arguments because they have a
+% variable number of arguments (depending on the command they are
+% attached to), so we use the maximum here.
+% \begin{macrocode}
+\tl_const:cn { c_@@_parameter_cmd/./before_tl } { #1#2#3#4#5#6#7#8#9 }
+\tl_const:cn { c_@@_parameter_cmd/./after_tl } { #1#2#3#4#5#6#7#8#9 }
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\c_@@_parameter_cmd/./before_tl}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\hook_gremove_code:nn}
% \begin{macro}{\@@_gremove_code:nn}
%
% With \cs{hook_gremove_code:nn}\Arg{hook}\Arg{label} any code
% for \meta{hook} stored under \meta{label} is removed.
% \changes{v1.0o}{2021/07/22}{Do not queue removals (gh/625)}
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_gremove_code:nn}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \hook_gremove_code:nn #1 #2
{ \@@_normalize_hook_args:Nnn \@@_gremove_code:nn {#1} {#2} }
\cs_new_protected:Npn \@@_gremove_code:nn #1 #2
@@ -3542,8 +4348,8 @@
\str_if_eq:nnTF {#2} {*}
{
\prop_gclear:c { g_@@_#1_code_prop }
- \@@_tl_gclear:c { @@_toplevel~#1 }
- \@@_tl_gclear:c { @@_next~#1 }
+ \@@_toplevel_gset:nn {#1} { }
+ \@@_next_gset:nn {#1} { }
}
{
% \end{macrocode}
@@ -3551,7 +4357,7 @@
% there is under the same label.
% \begin{macrocode}
\str_if_eq:nnTF {#2} { top-level }
- { \@@_tl_gclear:c { @@_toplevel~#1 } }
+ { \@@_toplevel_gset:nn {#1} { } }
{
\prop_gpop:cnNF { g_@@_#1_code_prop } {#2} \l_@@_return_tl
{ \msg_warning:nnnn { hooks } { cannot-remove } {#1} {#2} }
@@ -3576,14 +4382,542 @@
{ \msg_warning:nnnn { hooks } { cannot-remove } {#1} {#2} }
}
}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_gremove_code:nn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_new_protected:Npn \@@_gremove_code:nn #1 #2
+%<latexrelease> {
+%<latexrelease> \@@_if_structure_exist:nTF {#1}
+%<latexrelease> {
+%<latexrelease> \str_if_eq:nnTF {#2} {*}
+%<latexrelease> {
+%<latexrelease> \prop_gclear:c { g_@@_#1_code_prop }
+%<latexrelease> \@@_tl_gclear:c { @@_toplevel~#1 }
+%<latexrelease> \@@_tl_gclear:c { @@_next~#1 }
+%<latexrelease> }
+%<latexrelease> {
+%<latexrelease> \str_if_eq:nnTF {#2} { top-level }
+%<latexrelease> { \@@_tl_gclear:c { @@_toplevel~#1 } }
+%<latexrelease> {
+%<latexrelease> \prop_gpop:cnNF { g_@@_#1_code_prop } {#2} \l_@@_return_tl
+%<latexrelease> { \msg_warning:nnnn { hooks } { cannot-remove } {#1} {#2} }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> \@@_if_usable:nT {#1}
+%<latexrelease> { \@@_update_hook_code:n {#1} }
+%<latexrelease> }
+%<latexrelease> {
+%<latexrelease> \@@_if_deprecated_generic:nTF {#1}
+%<latexrelease> {
+%<latexrelease> \@@_deprecated_generic_warn:n {#1}
+%<latexrelease> \@@_do_deprecated_generic:Nn \@@_gremove_code:nn {#1} {#2}
+%<latexrelease> }
+%<latexrelease> { \msg_warning:nnnn { hooks } { cannot-remove } {#1} {#2} }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_cs_gput_right:nnn}
+% \begin{macro}{\@@_code_gset_auxi:nnnn,\@@_code_gset_auxi:eeen}
+% This macro is used to append code to the \verb|toplevel| and
+% \verb|next| token lists, trating them correctly depending on their
+% number of arguments, and depending if the code being added should
+% have parameter tokens understood as parameters, or doubled to be
+% stored as parameter tokens.
+% \changes{v1.1a}{2023/04/06}
+% {Macro added (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_cs_gput_right:nnn}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \@@_cs_gput_right:nnn #1 #2 #3
+ {
+% \end{macrocode}
+% The auxiliary \cs{@@_code_gset_auxi:eeen} just does the assignment
+% at the end. Its first argument is the parameter text of the macro,
+% which is chosen here depending if
+% \cs[no-index]{c_@@_\meta{hook}_parameter_tl} exists, if the hook is
+% declared, and if it's a generic hook.
+% \begin{macrocode}
+ \cs_if_exist:cF { @@#1~#2 }
+ { \@@_code_gset_aux:nnn {#1} {#2} { } }
+ \@@_code_gset_auxi:eeen
+ {
+ \@@_if_declared:nTF {#2}
+ { \tl_use:c { c_@@_#2_parameter_tl } }
+ {
+ \@@_if_generic:nTF {#2}
+ { \@@_generic_parameter:n {#2} }
+ { \c_@@_nine_parameters_tl }
+ }
+ }
+% \end{macrocode}
+% Here we take the existing code in the macro, expand it with as many
+% arguments as it takes, then double the hashes so the code can be
+% reused. \pho{Maybe can be improved. The case of adding to an empty
+% cs can be optimised by quickly checking \cs{cs_replacement_spec}.}
+% \begin{macrocode}
+ {
+ \exp_args:NNo \exp_args:No \@@_double_hashes:n
+ {
+ \cs:w @@#1~#2 \exp_last_unbraced:Ne \cs_end:
+ { \@@_braced_cs_parameter:n { @@#1~#2 } }
+ }
+ }
+% \end{macrocode}
+% Now the new code: if we are replacing arguments, then hashes are
+% left untouched, otherwise they are doubled.
+% \begin{macrocode}
+ {
+ \@@_if_replacing_args:TF
+ { \exp_not:n }
+ { \@@_double_hashes:n }
+ {#3}
+ }
+% \end{macrocode}
+% And finally, the csname which we'll define with all the above.
+% \begin{macrocode}
+ { @@#1~#2 }
+ }
+% \end{macrocode}
+%
+% And as promised, the auxiliary that does the definition.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_code_gset_auxi:nnnn #1 #2 #3 #4
+ { \cs_gset:cpn {#4} #1 { #2 #3 } }
+\cs_generate_variant:Nn \@@_code_gset_auxi:nnnn { eeen }
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_cs_gput_right:nnn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_cs_gput_right:nnn
+%<latexrelease>\cs_undefine:N \@@_code_gset_auxi:nnnn
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{
+% \@@_code_gset:nn,\@@_code_gset:ne,
+% \@@_toplevel_gset:nn,
+% \@@_next_gset:nn,
+% \@@_code_gset_aux:nnn
+% }
+% These macros define
+% \cs[no-index]{@@\meta{type}\textvisiblespace\meta{hook}} (with
+% \meta{type} being \verb|_next|, \verb|_toplevel|, or empty) with the
+% given code and the parameters stored in
+% \cs[no-index]{c_@@_\meta{hook}_parameter_tl} (or none, if that
+% doesn't exist).
+% \changes{v1.1a}{2023/04/06}
+% {Macro added (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_code_gset:nn}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \@@_code_gset:nn
+ { \@@_code_gset_aux:nnn { } }
+\cs_new_protected:Npn \@@_toplevel_gset:nn
+ { \@@_code_gset_aux:nnn { _toplevel } }
+\cs_new_protected:Npn \@@_next_gset:nn
+ { \@@_code_gset_aux:nnn { _next } }
+\cs_new_protected:Npn \@@_code_gset_aux:nnn #1 #2 #3
+ {
+ \cs_gset:cpn { @@#1~#2 \exp_last_unbraced:Ne }
+ { \@@_parameter:n {#2} }
+ {#3}
+ }
+\cs_generate_variant:Nn \@@_code_gset:nn { ne }
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_code_gset:nn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_code_gset:nn
+%<latexrelease>\cs_undefine:N \@@_toplevel_gset:nn
+%<latexrelease>\cs_undefine:N \@@_next_gset:nn
+%<latexrelease>\cs_undefine:N \@@_code_gset_aux:nnn
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_normalise_cs_args:nn}
+% This macro normalises the parameters of the macros
+% \cs[no-index]{@@\meta{type}\textvisiblespace\meta{hook}} to take the
+% right number of arguments after a hook is declared. At this point
+% we know \cs[no-index]{c_@@_\meta{hook}_parameter_tl} exists, so use
+% that to count the arguments and use that as \meta{parameter text}
+% for the newly (re)defined macro.
+% \changes{v1.1a}{2023/04/06}
+% {Macro added (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_normalise_cs_args:nn}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \@@_normalise_cs_args:nn #1 #2
+ {
+ \cs_if_exist:cT { @@#1~#2 }
+ {
+ \@@_code_gset_auxi:eeen
+ { \tl_use:c { c_@@_#2_parameter_tl } }
+ {
+ \exp_args:NNo \exp_args:No \@@_double_hashes:n
+ {
+ \cs:w @@#1~#2 \exp_last_unbraced:Ne \cs_end:
+ { \@@_braced_cs_parameter:n { @@#1~#2 } }
+ }
+ }
+ { }
+ { @@#1~#2 }
+ }
+ }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_normalise_cs_args:nn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_normalise_cs_args:nn
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_normalise_code_pool:n}
+% \begin{macro}{\@@_set_normalise_fn:nn}
+% This one's a bit of a hack. It takes a hook, and iterates over its
+% code pool (\cs[no-index]{g_@@_\meta{hook}_code_prop}), redefining
+% each code label to use only valid arguments. This is used when, for
+% example, a code is added referencing arguments \verb|#1| and
+% \verb|#2|, but the hook has only \verb|#1|. In this example, every
+% reference to \verb|#2| is changed to \verb|##2|. This is done
+% because otherwise \TeX{} will throw a low-level error every time
+% some change happens to the hook (code is added, a rule is set, etc),
+% which can get quite repetitive for no good reason.
+% \changes{v1.1a}{2023/04/06}
+% {Macro added (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_normalise_code_pool:n}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \@@_normalise_code_pool:n #1
+ {
+% \end{macrocode}
+% First, call \cs{@@_set_normalise_fn:nn} with the hook name to set
+% everything up, then we'll loop over the
+% hook's code pool applying the normalisation above. After that's
+% done, copy the temporary property list back to the hook's.
+% \begin{macrocode}
+ \@@_set_normalise_fn:nn {#1} { Offending~label:~'##1' }
+ \prop_clear:N \l_@@_work_prop
+ \prop_map_function:cN { g_@@_#1_code_prop } \@@_normalise_fn:nn
+ \prop_gset_eq:cN { g_@@_#1_code_prop } \l_@@_work_prop
+ }
+% \end{macrocode}
+%
+% The sole purpose of this function is to define
+% \cs{@@_normalise_fn:nn}, which will then do the correcting of the
+% code being added to the hook.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_set_normalise_fn:nn #1 #2
+ {
+% \end{macrocode}
+% To start, we define two auxiliary token lists.
+% \cs[no-index]{l_@@_tmpb_tl} contains:
+%\begin{verbatim}
+% {\c__hook_hashes_tl 1}
+% {\c__hook_hashes_tl 2}
+% ...
+% {\c__hook_hashes_tl 9}
+%\end{verbatim}
+% \begin{macrocode}
+ \cs_set:Npn \@@_tmp:w ##1##2##3##4##5##6##7##8##9 { }
+ \tl_set:Ne \l_@@_tmpb_tl
+ { \@@_braced_cs_parameter:n { @@_tmp:w } }
+ \group_begin:
+ \@@_tl_set:cn { c_@@_hash_tl } { \exp_not:N \c_@@_hashes_tl }
+ \use:e
+ {
+ \group_end:
+ \tl_set:Nn \exp_not:N \l_@@_tmpb_tl { \l_@@_tmpb_tl }
+ }
+% \end{macrocode}
+% And \cs[no-index]{l_@@_tmpa_tl} contains:
+%\begin{verbatim}
+% {\c__hook_hash_tl 1}
+% {\c__hook_hash_tl 2}
+% ...
+% {\c__hook_hash_tl <n>}
+%\end{verbatim}
+% with \meta{n} being the number of arguments declared for the hook.
+% \begin{macrocode}
+ \exp_last_unbraced:NNf
+ \cs_set:Npn \@@_tmp:w { \@@_parameter:n {#1} } { }
+ \tl_set:Ne \l_@@_tmpa_tl { \@@_braced_cs_parameter:n { @@_tmp:w } }
+% \end{macrocode}
+% Now this function does the fun part. It is meant to be used with
+% \cs{prop_map_function:NN}, taking a label name in \verb|##1| and the
+% code stored in that label in \verb|##2|.
+% \begin{macrocode}
+ \cs_gset_protected:Npx \@@_normalise_fn:nn ##1 ##2
+ {
+% \end{macrocode}
+% Here we'll define two auxiliary macros: the first one throws an
+% error when it detects an invalid argument reference. It piggybacks
+% on \TeX's low-level \enquote{Illegal parameter number} error, but it
+% defines a weirdly-named control sequence so that the error comes out
+% nicely formatted. For example, if the label \enquote{badpkg} adds
+% some code that references argument \verb|#3| in the hook
+% \enquote{foo}, which takes only two arguments, the error will be:
+%\begin{verbatim}
+% ! Illegal parameter number in definition of hook 'foo'.
+% (hooks) Offending label: 'badpkg'.
+% <to be read again>
+% 3
+%\end{verbatim}
+% At the point of this definition, the error is raised if the code
+% happens to reference an invalid argument. If it was possible to
+% detect that this definition raised no error, the next step would be
+% unnecessary. We'll do all this in a group so this weird definition
+% doesn't leak out, and set \cs{tex_escapechar:D} to $-1$ so this hack
+% shows up extra nice in the case of an error.
+% \begin{macrocode}
+ \group_begin:
+ \int_set:Nn \tex_escapechar:D { -1 }
+ \cs_set:cpn
+ {
+ hook~'#1'. ^^J
+ (hooks) \prg_replicate:nn { 13 } { ~ }
+ #2 % more message text
+ }
+ \exp_not:v { c_@@_#1_parameter_tl }
+ {##2}
+ \group_end:
+% \end{macrocode}
+% This next macro, with a much less fabulous name, takes always nine
+% arguments, and it just transfers the code \verb|##2| under the label
+% \verb|##1| to the temporary property list. The first \meta{n}
+% arguments are taken from \cs[no-index]{l_@@_tmpa_tl}, and the other
+% $9-\meta{n}$ taken from \cs[no-index]{l_@@_tmpb_tl} (which contains
+% twice as many \verb|#| tokens as the former). Then,
+% \cs{@@_double_hashes:n} is used to double non-argument hashes, and
+% expand the \cs{c_@@_hash_tl} and \cs{c_@@_hashes_tl} to the actual
+% parameter tokens.
+% \begin{macrocode}
+ \cs_set:Npn \exp_not:N \@@_tmp:w
+ \exp_not:V \c_@@_nine_parameters_tl
+ {
+ \prop_put:Nne \exp_not:N \l_@@_work_prop
+ {##1} { \exp_not:N \@@_double_hashes:n {##2} }
+ }
+% \end{macrocode}
+% This next macro, with a much less fabulous name, takes always nine
+% arguments, and it just transfers the code \verb|##2| under the label
+% \verb|##1| to the temporary property list. The first \meta{n}
+% arguments are taken from \cs[no-index]{l_@@_tmpa_tl}, and the other
+% $9-\meta{n}$ taken from \cs[no-index]{l_@@_tmpb_tl} (which contains
+% twice as many \verb|#| tokens as the former). Then,
+% \cs{@@_double_hashes:n} is used to double non-argument hashes, and
+% expand the \cs{c_@@_hash_tl} and \cs{c_@@_hashes_tl} to the actual
+% parameter tokens.
+% \begin{macrocode}
+ \exp_not:N \@@_tmp:w
+ \exp_not:V \l_@@_tmpa_tl
+ \exp_args:No \exp_not:o
+ { \exp_after:wN \@@_tmp:w \l_@@_tmpb_tl }
+ }
+ }
+\cs_new_eq:NN \@@_normalise_fn:nn ?
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_normalise_code_pool:n}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_normalise_code_pool:n
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[pTF]{\@@_cs_if_empty:c}
+% Check if the expansion of a control sequence is empty by looking at
+% its replacement text.
+% \changes{v1.1a}{2023/04/06}
+% {Macro added (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_cs_if_empty:c}
+%<latexrelease> {Hooks~with~args}
+\prg_new_conditional:Npnn \@@_cs_if_empty:c #1 { p, T, F, TF }
+ {
+ \if:w \scan_stop: \@@_replacement_spec:c {#1} \scan_stop:
+ \prg_return_true:
+ \else:
+ \prg_return_false:
+ \fi:
+ }
+\cs_new:Npn \@@_replacement_spec:c #1
+ {
+ \exp_args:Nc \token_if_macro:NT {#1}
+ { \cs_replacement_spec:c {#1} }
+ }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_cs_if_empty:c}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_cs_if_empty:c
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_braced_cs_parameter:n}
+% \begin{macro}{\@@_braced_hidden_loop:w}
+% \begin{macro}{\@@_cs_parameter_count:N}
+% \begin{macro}{\@@_cs_parameter_count:w,\@@_cs_end:w}
+% Looks at the \meta{parameter text} of a control sequence, and
+% returns a run of \enquote{hidden} braced parameters for that macro.
+% This works as long as the macros take a simple run of zero to nine
+% arguments. The parameters are \enquote{hidden} because the
+% parameter tokens are returned inside \cs{c_@@_hash_tl} instead of
+% explicitly, so that \cs{@@_double_hashes:n} won't touch these.
+% \changes{v1.1a}{2023/04/06}
+% {Macro added (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_braced_cs_parameter:n}
+%<latexrelease> {Hooks~with~args}
+\cs_new:Npn \@@_braced_cs_parameter:n #1
+ {
+ \exp_last_unbraced:Ne \@@_braced_hidden_loop:w
+ { \exp_args:Nc \@@_cs_parameter_count:N {#1} } ? \s_@@_mark
+ }
+\cs_new:Npn \@@_braced_hidden_loop:w #1
+ {
+ \if:w ? #1
+ \@@_use_i_delimit_by_s_mark:nw
+ \fi:
+ { \exp_not:N \c_@@_hash_tl #1 }
+ \@@_braced_hidden_loop:w
+ }
+\cs_new:Npn \@@_cs_parameter_count:N #1
+ {
+ \exp_last_unbraced:Nf \@@_cs_parameter_count:w
+ { \token_if_macro:NT #1 { \cs_parameter_spec:N #1 } }
+ ? \@@_cs_end:w ? \@@_cs_end:w ? \@@_cs_end:w
+ ? \@@_cs_end:w ? \@@_cs_end:w ? \@@_cs_end:w
+ ? \@@_cs_end:w ? \@@_cs_end:w ? \@@_cs_end:w
+ \s_@@_mark
+ }
+\cs_new:Npn \@@_cs_parameter_count:w #1#2 #3#4 #5#6 #7#8
+ { #2 #4 #6 #8 \@@_cs_parameter_count:w }
+\cs_new:Npn \@@_cs_end:w #1 \s_@@_mark { }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% This function can't be undefined when rolling back because it's used
+% at the end of this module to adequate the hook data structures to
+% previous versions.
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_braced_cs_parameter:n}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_braced_parameter:n}
+% \begin{macro}{\@@_braced_real_loop:w}
+% This one is used in simpler cases, where no special handling of
+% hashes is required. This is used only inside
+% \cs{@@_initialize_hook_code:n}, so it assumes
+% \cs[no-index]{c_@@_\meta{hook}_parameter_tl} is defined, but should
+% work otherwise.
+% \changes{v1.1a}{2023/04/06}
+% {Macro added (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_braced_parameter:n}
+%<latexrelease> {Hooks~with~args}
+\cs_new:Npn \@@_braced_parameter:n #1
+ {
+ \if_case:w
+ \int_eval:n
+ { \exp_args:Nv \str_count:n { c_@@_#1_parameter_tl } / 3 }
+ \exp_stop_f:
+ \or: {##1}
+ \or: {##1} {##2}
+ \or: {##1} {##2} {##3}
+ \or: {##1} {##2} {##3} {##4}
+ \or: {##1} {##2} {##3} {##4} {##5}
+ \or: {##1} {##2} {##3} {##4} {##5} {##6}
+ \or: {##1} {##2} {##3} {##4} {##5} {##6} {##7}
+ \or: {##1} {##2} {##3} {##4} {##5} {##6} {##7} {##8}
+ \or: {##1} {##2} {##3} {##4} {##5} {##6} {##7} {##8} {##9}
+ \else:
+ \msg_expandable_error:nnn { latex2e } { should-not-happen }
+ { Invalid~parameter~spec. }
+ \fi:
+ }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_braced_parameter:n}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_braced_parameter:n
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@@_parameter:n}
+% This is just a shortcut to \verb|e|- or \verb|f|-expand to the
+% \meta{parameter text} of the hook.
+% \changes{v1.1a}{2023/04/06}
+% {Macro added (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_parameter:n}
+%<latexrelease> {Hooks~with~args}
+\cs_new:Npn \@@_parameter:n #1
+ {
+ \cs:w c_@@_
+ \tl_if_exist:cTF { c_@@_#1_parameter_tl }
+ { #1_parameter } { empty }
+ _tl \cs_end:
+ }
+\cs_new:Npn \@@_generic_parameter:n #1
+ { \@@_generic_parameter:w #1 / / / \s_@@_mark }
+\cs_new:Npn \@@_generic_parameter:w #1 / #2 / #3 / #4 \s_@@_mark
+ {
+ \cs_if_exist_use:cF { c_@@_parameter_#1/./#3_tl }
+ { \c_@@_empty_tl }
+ }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_parameter:n}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_parameter:n
+%<latexrelease>\cs_undefine:N \@@_generic_parameter:n
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{Setting rules for hooks code}
%
% \begin{macro}{
% \g_@@_??_code_prop,
% \@@~??,
% \g_@@_??_reversed_tl,
+% \c_@@_??_parameter_tl,
% }
%
% Initially these variables simply used an empty ``label'' name (not
@@ -3597,11 +4931,11 @@
% lot, the code should be fast, so this is not done with \texttt{c}
% expansion in the code later on.
%
-% \cs{@@\textvisiblespace??} isn't used, but it has to be defined to trick
-% the code into thinking that \texttt{??} is actually a hook.
+% \cs{@@\textvisiblespace??} isn't used, but it has to be defined to
+% trick the code into thinking that \texttt{??} is actually a hook.
% \begin{macrocode}
-\prop_new:c {g_@@_??_code_prop}
-\prop_new:c {@@~??}
+\prop_new:c { g_@@_??_code_prop }
+\prop_new:c { @@~?? }
% \end{macrocode}
%
% Default rules are always given in normal ordering (never in
@@ -3610,11 +4944,23 @@
% \texttt{after} becomes \texttt{before})
% because those rules are applied first and then the order is reversed.
% \begin{macrocode}
-\tl_new:c {g_@@_??_reversed_tl}
+\tl_new:c { g_@@_??_reversed_tl }
% \end{macrocode}
-% \end{macro}
%
-% \subsection{Setting rules for hooks code}
+% The parameter text for the \enquote{default} hook is empty.
+% \changes{v1.1a}{2023/04/06}
+% {Token list added (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\c_@@_??_parameter_tl}
+%<latexrelease> {Hooks~with~args}
+\tl_const:cn { c_@@_??_parameter_tl } { }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\c_@@_??_parameter_tl}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:c { c_@@_??_parameter_tl }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
%
% \begin{macro}{\hook_gset_rule:nnnn}
% \begin{macro}{\@@_gset_rule:nnnn}
@@ -3645,13 +4991,13 @@
\@@_deprecated_generic_warn:n {#1}
\@@_do_deprecated_generic:Nn \@@_gset_rule:nnnn {#1}
{#2} {#3} {#4}
- \@@_clean_to_scan:w
+ \@@_use_none_delimit_by_s_mark:w
}
\@@_if_execute_immediately:nT {#1}
{
\msg_error:nnnnnn { hooks } { rule-too-late }
{#1} {#2} {#3} {#4}
- \@@_clean_to_scan:w
+ \@@_use_none_delimit_by_s_mark:w
}
% \end{macrocode}
% First we ensure the basic data structure of the hook exists:
@@ -3840,44 +5186,82 @@
% \begin{macro}{\@@_initialize_all:}
% Initialize all known hooks (at \verb=\begin{document}=), i.e.,
% update the fast execution token lists to hold the necessary code
-% in the right order.
+% in the right order.
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
-\cs_new_protected:Npn \@@_initialize_all: {
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_initialize_all:}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \@@_initialize_all:
+ {
% \end{macrocode}
% First we change \cs{@@_update_hook_code:n} which so far was a
% no-op to now initialize one hook. This way any later updates to
% the hook will run that code and also update the execution token
% list.
% \begin{macrocode}
- \cs_gset_eq:NN \@@_update_hook_code:n \@@_initialize_hook_code:n
+ \cs_gset_eq:NN \@@_update_hook_code:n \@@_initialize_hook_code:n
% \end{macrocode}
% Now we loop over all hooks that have been defined and update each
-% of them.
+% of them. Here we have to determine if the hook has arguments so
+% that auxiliaries know what to do with hashes. We look at
+% \cs[no-index]{c_@@_\meta{hook}_parameter_tl}, if it has any
+% parameters, and set \verb|replacing_args| accordingly.
% \begin{macrocode}
- \@@_debug:n { \prop_gclear:N \g_@@_used_prop }
- \seq_map_inline:Nn \g_@@_all_seq
+ \@@_debug:n { \prop_gclear:N \g_@@_used_prop }
+ \seq_map_inline:Nn \g_@@_all_seq
{
+ \tl_if_empty:cTF { c_@@_##1_parameter_tl }
+ { \@@_replacing_args_false: }
+ { \@@_replacing_args_true: }
\@@_update_hook_code:n {##1}
+ \@@_replacing_args_reset:
}
% \end{macrocode}
% If we are debugging we show results hook by hook for all hooks
% that have data.
% \begin{macrocode}
- \@@_debug:n
- { \iow_term:x{^^JAll~ initialized~ (non-empty)~ hooks:}
- \prop_map_inline:Nn \g_@@_used_prop
- { \iow_term:x{^^J~ ##1~ ->~
- \exp_not:v {@@~##1}~ }
- }
- }
+ \@@_debug:n
+ {
+ \iow_term:x { ^^J All~initialized~(non-empty)~hooks: }
+ \prop_map_inline:Nn \g_@@_used_prop
+ {
+ \iow_term:x
+ { ^^J ~ ##1 ~ -> ~ \cs_replacement_spec:c { @@~##1 } ~ }
+ }
+ }
% \end{macrocode}
% After all hooks are initialized we change the ``use'' to just
% call the hook code and not initialize it (as it was done in the
% preamble.
% \begin{macrocode}
- \cs_gset_eq:NN \hook_use:n \@@_use_initialized:n
- \cs_gset_eq:NN \@@_preamble_hook:n \use_none:n
-}
+ \@@_post_initialization_defs:
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_initialize_all:}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \@@_initialize_all:
+%<latexrelease> {
+%<latexrelease> \cs_gset_eq:NN \@@_update_hook_code:n \@@_initialize_hook_code:n
+%<latexrelease> \@@_debug:n { \prop_gclear:N \g_@@_used_prop }
+%<latexrelease> \seq_map_inline:Nn \g_@@_all_seq
+%<latexrelease> { \@@_update_hook_code:n {##1} }
+%<latexrelease> \@@_debug:n
+%<latexrelease> {
+%<latexrelease> \iow_term:x{^^JAll~ initialized~ (non-empty)~ hooks:}
+%<latexrelease> \prop_map_inline:Nn \g_@@_used_prop
+%<latexrelease> {
+%<latexrelease> \iow_term:x
+%<latexrelease> { ^^J ~ ##1 ~ -> ~ \cs_replacement_spec:c { @@~##1 } ~ }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> \cs_gset_eq:NN \hook_use:n \@@_use_initialized:n
+%<latexrelease> \cs_gset_eq:NN \@@_preamble_hook:n \use_none:n
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
@@ -3887,7 +5271,11 @@
% the preamble this is selectively done in case a hook gets used
% and at \verb=\begin{document}= this is done for all hooks and
% afterwards only if the hook code changes.
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_initialize_hook_code:n}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \@@_initialize_hook_code:n #1
{
\@@_debug:n
@@ -3915,10 +5303,15 @@
{
\prop_if_empty:cTF { g_@@_#1_code_prop }
{
- \@@_tl_gset:co { @@~#1 }
+ \@@_code_gset:ne {#1}
{
- \cs:w @@_toplevel~#1 \exp_after:wN \cs_end:
- \cs:w @@_next~#1 \cs_end:
+% \end{macrocode}
+% The hook may take arguments, so we add a run of braced parameters
+% after the \verb|_next| and \verb|_toplevel| macros, so that the
+% arguments passed to the hook are forwarded to them.
+% \begin{macrocode}
+ \exp_not:c { @@_toplevel~#1 } \@@_braced_parameter:n {#1}
+ \exp_not:c { @@_next~#1 } \@@_braced_parameter:n {#1}
}
}
{
@@ -3958,6 +5351,42 @@
}
}
}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_initialize_hook_code:n}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \@@_initialize_hook_code:n #1
+%<latexrelease> {
+%<latexrelease> \@@_debug:n
+%<latexrelease> { \iow_term:x { ^^J Update~code~for~hook~'#1' \on@line :^^J } }
+%<latexrelease> \@@_include_legacy_code_chunk:n {#1}
+%<latexrelease> \@@_if_usable:nT {#1}
+%<latexrelease> {
+%<latexrelease> \prop_if_empty:cTF { g_@@_#1_code_prop }
+%<latexrelease> {
+%<latexrelease> \@@_tl_gset:co { @@~#1 }
+%<latexrelease> {
+%<latexrelease> \cs:w @@_toplevel~#1 \exp_after:wN \cs_end:
+%<latexrelease> \cs:w @@_next~#1 \cs_end:
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> {
+%<latexrelease> \@@_if_reversed:nTF {#1}
+%<latexrelease> { \cs_set_eq:NN \@@_tl_gput:Nn \@@_tl_gput_left:Nn
+%<latexrelease> \cs_set_eq:NN \@@_clist_gput:NV \clist_gput_left:NV }
+%<latexrelease> { \cs_set_eq:NN \@@_tl_gput:Nn \@@_tl_gput_right:Nn
+%<latexrelease> \cs_set_eq:NN \@@_clist_gput:NV \clist_gput_right:NV }
+%<latexrelease> \prop_set_eq:Nc \l_@@_work_prop { g_@@_#1_code_prop }
+%<latexrelease> \@@_initialize_single:ccn
+%<latexrelease> { @@~#1 } { g_@@_#1_labels_clist } {#1}
+%<latexrelease> \@@_debug:n
+%<latexrelease> { \exp_args:NNx \prop_gput:Nnn \g_@@_used_prop {#1} { } }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
@@ -4034,7 +5463,12 @@
% ^^A #1 <- \@@~#1
% ^^A #2 <- \g_@@_#1_labels_clist
% ^^A #3 <- #1
+%
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_initialize_single:NNn}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \@@_initialize_single:NNn #1#2#3
{
% \end{macrocode}
@@ -4181,15 +5615,103 @@
% time execution (\verb=#3=). These should normally be empty. The
% |top-level| code is added with \cs{@@_tl_gput:Nn} as that might
% change for a reversed hook (then |top-level| is the very first code
-% chunk added). The |next| code is always added last.
-% \begin{macrocode}
- \exp_args:NNo \@@_tl_gput:Nn #1 { \cs:w @@_toplevel~#3 \cs_end: }
- \@@_tl_gput_right:No #1 { \cs:w @@_next~#3 \cs_end: }
+% chunk added). The |next| code is always added last (to the right).
+% The hook may take arguments, so we add a run of braced parameters
+% after the \verb|_next| and \verb|_toplevel| macros, so that the
+% arguments passed to the hook are forwarded to them.
+% \begin{macrocode}
+ \exp_args:NNe \@@_tl_gput:Nn #1
+ { \exp_not:c { @@_toplevel~#3 } \@@_braced_parameter:n {#3} }
+ \@@_tl_gput_right:Ne #1
+ { \exp_not:c { @@_next~#3 } \@@_braced_parameter:n {#3} }
+ \use:e
+ {
+ \cs_gset:cpn { @@~#3 } \use:c { c_@@_#3_parameter_tl }
+ { \exp_not:V #1 }
+ }
}
% \end{macrocode}
%
% \begin{macrocode}
\cs_generate_variant:Nn \@@_initialize_single:NNn { cc }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_initialize_single:NNn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_new_protected:Npn \@@_initialize_single:NNn #1#2#3
+%<latexrelease> {
+%<latexrelease> \seq_clear:N \l_@@_labels_seq
+%<latexrelease> \int_zero:N \l_@@_labels_int
+%<latexrelease> \tl_set:Nn \l_@@_cur_hook_tl {#3}
+%<latexrelease> \prop_map_inline:Nn \l_@@_work_prop
+%<latexrelease> {
+%<latexrelease> \int_incr:N \l_@@_labels_int
+%<latexrelease> \seq_put_right:Nn \l_@@_labels_seq {##1}
+%<latexrelease> \@@_tl_set:cn { \@@_tl_csname:n {##1} } { 0 }
+%<latexrelease> \seq_clear_new:c { \@@_seq_csname:n {##1} }
+%<latexrelease> }
+%<latexrelease> \prop_map_inline:Nn \l_@@_work_prop
+%<latexrelease> {
+%<latexrelease> \prop_map_inline:Nn \l_@@_work_prop
+%<latexrelease> {
+%<latexrelease> \@@_if_label_case:nnnnn {##1} {####1}
+%<latexrelease> { \prop_map_break: }
+%<latexrelease> { \@@_apply_label_pair:nnn {##1} {####1} }
+%<latexrelease> { \@@_apply_label_pair:nnn {####1} {##1} }
+%<latexrelease> {#3}
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> \@@_debug:n { \@@_debug_label_data:N \l_@@_work_prop }
+%<latexrelease> \tl_set:Nn \l_@@_rear_tl { 0 }
+%<latexrelease> \tl_set:cn { \@@_tl_csname:n { 0 } } { 0 }
+%<latexrelease> \seq_map_inline:Nn \l_@@_labels_seq
+%<latexrelease> {
+%<latexrelease> \int_compare:nNnT { \cs:w \@@_tl_csname:n {##1} \cs_end: } = 0
+%<latexrelease> {
+%<latexrelease> \tl_set:cn { \@@_tl_csname:n { \l_@@_rear_tl } }{##1}
+%<latexrelease> \tl_set:Nn \l_@@_rear_tl {##1}
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> \tl_set_eq:Nc \l_@@_front_tl { \@@_tl_csname:n { 0 } }
+%<latexrelease> \@@_tl_gclear:N #1
+%<latexrelease> \clist_gclear:N #2
+%<latexrelease> \bool_while_do:nn { ! \str_if_eq_p:Vn \l_@@_front_tl { 0 } }
+%<latexrelease> {
+%<latexrelease> \int_decr:N \l_@@_labels_int
+%<latexrelease> \prop_get:NVN \l_@@_work_prop \l_@@_front_tl \l_@@_return_tl
+%<latexrelease> \exp_args:NNV \@@_tl_gput:Nn #1 \l_@@_return_tl
+%<latexrelease> \@@_clist_gput:NV #2 \l_@@_front_tl
+%<latexrelease> \@@_debug:n{ \iow_term:x{Handled~ code~ for~ \l_@@_front_tl} }
+%<latexrelease> \seq_map_inline:cn { \@@_seq_csname:n { \l_@@_front_tl } }
+%<latexrelease> {
+%<latexrelease> \tl_set:cx { \@@_tl_csname:n {##1} }
+%<latexrelease> { \int_eval:n
+%<latexrelease> { \cs:w \@@_tl_csname:n {##1} \cs_end: - 1 }
+%<latexrelease> }
+%<latexrelease> \int_compare:nNnT
+%<latexrelease> { \cs:w \@@_tl_csname:n {##1} \cs_end: } = 0
+%<latexrelease> {
+%<latexrelease> \tl_set:cn { \@@_tl_csname:n { \l_@@_rear_tl } } {##1}
+%<latexrelease> \tl_set:Nn \l_@@_rear_tl {##1}
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> \tl_set_eq:Nc \l_@@_front_tl
+%<latexrelease> { \@@_tl_csname:n { \l_@@_front_tl } }
+%<latexrelease> }
+%<latexrelease> \int_compare:nNnF \l_@@_labels_int = 0
+%<latexrelease> {
+%<latexrelease> \iow_term:x{====================}
+%<latexrelease> \iow_term:x{Error:~ label~ rules~ are~ incompatible:}
+%<latexrelease> \@@_debug_label_data:N \l_@@_work_prop
+%<latexrelease> \iow_term:x{====================}
+%<latexrelease> }
+%<latexrelease> \exp_args:NNo \@@_tl_gput:Nn #1 { \cs:w @@_toplevel~#3 \cs_end: }
+%<latexrelease> \@@_tl_gput_right:No #1 { \cs:w @@_next~#3 \cs_end: }
+%<latexrelease> }
+%<latexrelease>\cs_generate_variant:Nn \@@_tl_gput_right:Nn { No }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
@@ -4444,7 +5966,11 @@
{ \@@_log_cmd:x { >~\@spaces #1 } }
% \end{macrocode}
%
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_log:nN}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \@@_log:nN #1 #2
{
\@@_if_deprecated_generic:nT {#1}
@@ -4455,7 +5981,20 @@
}
\@@_preamble_hook:n {#1}
\@@_log_cmd:x
- { ^^J ->~The~ \@@_if_generic:nT {#1} { generic~ } hook~'#1': }
+ {
+ ^^J ->~The~
+ \@@_if_generic:nT {#1} { generic~ }
+ hook~'#1'
+ \@@_if_disabled:nF {#1}
+ {
+ \exp_args:Nf \@@_print_args:nn {#1}
+ {
+ \int_eval:n
+ { \str_count:e { \@@_parameter:n {#1} } / 3 }
+ }
+ }
+ :
+ }
% \end{macrocode}
%
% \begin{macrocode}
@@ -4471,7 +6010,12 @@
{ \@@_log_line_indent:x { --- } }
{
\prop_map_inline:cn { g_@@_#1_code_prop }
- { \@@_log_line_indent:x { ##1~->~\tl_to_str:n {##2} } }
+ {
+ \exp_after:wN \cs_set:Npn \exp_after:wN \@@_tmp:w
+ \c_@@_nine_parameters_tl {##2}
+ \@@_log_line_indent:x
+ { ##1~->~\cs_replacement_spec:N \@@_tmp:w }
+ }
}
% \end{macrocode}
%
@@ -4485,9 +6029,9 @@
}
\@@_log_line_indent:x
{
- \tl_if_empty:cTF { @@_toplevel~#1 }
+ \@@_cs_if_empty:cTF { @@_toplevel~#1 }
{ --- }
- { -> ~ \exp_args:Nv \tl_to_str:n { @@_toplevel~#1 } }
+ { -> ~ \cs_replacement_spec:c { @@_toplevel~#1 } }
}
% \end{macrocode}
%
@@ -4495,7 +6039,7 @@
\@@_log_line:x { Extra~code~for~next~invocation: }
\@@_log_line_indent:x
{
- \tl_if_empty:cTF { @@_next~#1 }
+ \@@_cs_if_empty:cTF { @@_next~#1 }
{ --- }
% \end{macrocode}
%
@@ -4503,7 +6047,10 @@
% the first tokens (the code to clear itself) so we call a helper
% command to get rid of them.
% \begin{macrocode}
- { ->~ \exp_args:Nv \@@_log_next_code:n { @@_next~#1 } }
+ {
+ -> ~ \exp_last_unbraced:Nf \@@_log_next_code:w
+ { \cs_replacement_spec:c { @@_next~#1 } }
+ }
}
% \end{macrocode}
%
@@ -4549,7 +6096,7 @@
\@spaces
\clist_if_empty:cTF { g_@@_#1_labels_clist }
{ --- }
- { \clist_use:cn {g_@@_#1_labels_clist} { ,~ } }
+ { \clist_use:cn { g_@@_#1_labels_clist } { ,~ } }
}
}
{
@@ -4563,15 +6110,139 @@
}
}
}
+%<latexrelease>\EndIncludeInRelease
+%
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_log:nN}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_new_protected:Npn \@@_log:nN #1 #2
+%<latexrelease> {
+%<latexrelease> \@@_if_deprecated_generic:nT {#1}
+%<latexrelease> {
+%<latexrelease> \@@_deprecated_generic_warn:n {#1}
+%<latexrelease> \@@_do_deprecated_generic:Nn \@@_log:nN {#1} #2
+%<latexrelease> \exp_after:wN \use_none:nnnnnnnnn \use_none:nnnnn
+%<latexrelease> }
+%<latexrelease> \@@_preamble_hook:n {#1}
+%<latexrelease> \@@_log_cmd:x
+%<latexrelease> { ^^J ->~The~ \@@_if_generic:nT {#1} { generic~ } hook~'#1': }
+%<latexrelease> \@@_if_usable:nF {#1}
+%<latexrelease> { \@@_log_line:x { The~hook~is~not~declared. } }
+%<latexrelease> \@@_if_disabled:nT {#1}
+%<latexrelease> { \@@_log_line:x { The~hook~is~disabled. } }
+%<latexrelease> \hook_if_empty:nTF {#1}
+%<latexrelease> { #2 { The~hook~is~empty } }
+%<latexrelease> {
+%<latexrelease> \@@_log_line:x { Code~chunks: }
+%<latexrelease> \prop_if_empty:cTF { g_@@_#1_code_prop }
+%<latexrelease> { \@@_log_line_indent:x { --- } }
+%<latexrelease> {
+%<latexrelease> \prop_map_inline:cn { g_@@_#1_code_prop }
+%<latexrelease> { \@@_log_line_indent:x { ##1~->~\tl_to_str:n {##2} } }
+%<latexrelease> }
+%<latexrelease> \@@_log_line:x
+%<latexrelease> {
+%<latexrelease> Document-level~(top-level)~code
+%<latexrelease> \@@_if_usable:nT {#1}
+%<latexrelease> { ~(executed~\@@_if_reversed:nTF {#1} {first} {last} ) } :
+%<latexrelease> }
+%<latexrelease> \@@_log_line_indent:x
+%<latexrelease> {
+%<latexrelease> \tl_if_empty:cTF { @@_toplevel~#1 }
+%<latexrelease> { --- }
+%<latexrelease> { -> ~ \exp_args:Nv \tl_to_str:n { @@_toplevel~#1 } }
+%<latexrelease> }
+%<latexrelease> \@@_log_line:x { Extra~code~for~next~invocation: }
+%<latexrelease> \@@_log_line_indent:x
+%<latexrelease> {
+%<latexrelease> \tl_if_empty:cTF { @@_next~#1 }
+%<latexrelease> { --- }
+%<latexrelease> { ->~ \exp_args:Nv \@@_log_next_code:n { @@_next~#1 } }
+%<latexrelease> }
+%<latexrelease> \@@_log_line:x { Rules: }
+%<latexrelease> \bool_set_true:N \l_@@_tmpa_bool
+%<latexrelease> \@@_list_rules:nn {#1}
+%<latexrelease> {
+%<latexrelease> \bool_set_false:N \l_@@_tmpa_bool
+%<latexrelease> \@@_log_line_indent:x
+%<latexrelease> {
+%<latexrelease> ##2~ with~
+%<latexrelease> \str_if_eq:nnT {##3} {??} { default~ }
+%<latexrelease> relation~ ##1
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> \bool_if:NT \l_@@_tmpa_bool
+%<latexrelease> { \@@_log_line_indent:x { --- } }
+%<latexrelease> \bool_lazy_and:nnTF
+%<latexrelease> { \@@_if_usable_p:n {#1} }
+%<latexrelease> { ! \hook_if_empty_p:n {#1} }
+%<latexrelease> {
+%<latexrelease> \@@_log_line:x
+%<latexrelease> {
+%<latexrelease> Execution~order
+%<latexrelease> \bool_if:NTF \l_@@_tmpa_bool
+%<latexrelease> { \@@_if_reversed:nT {#1} { ~(after~reversal) } }
+%<latexrelease> { ~(after~
+%<latexrelease> \@@_if_reversed:nT {#1} { reversal~and~ }
+%<latexrelease> applying~rules)
+%<latexrelease> } :
+%<latexrelease> }
+%<latexrelease> #2 % \tl_show:n
+%<latexrelease> {
+%<latexrelease> \@spaces
+%<latexrelease> \clist_if_empty:cTF { g_@@_#1_labels_clist }
+%<latexrelease> { --- }
+%<latexrelease> { \clist_use:cn { g_@@_#1_labels_clist } { ,~ } }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> {
+%<latexrelease> \@@_log_line:x { Execution~order: }
+%<latexrelease> #2
+%<latexrelease> {
+%<latexrelease> \@spaces Not~set~because~the~hook~ \@@_if_usable:nTF {#1}
+%<latexrelease> { code~pool~is~empty }
+%<latexrelease> { is~\@@_if_disabled:nTF {#1} {disabled} {undeclared} }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
%
% \begin{macro}{\@@_log_next_code:n}
% To display the code for next invocation only (i.e., from
-% \cs{AddToHookNext} we have to remove the first two tokens at the
-% front which are \cs{tl_gclear:N} and the token list to clear.
+% \cs{AddToHookNext} we have to remove the string
+% \cs{@@_clear_next:n}\Arg{hook}, so the simplest is to use a macro
+% delimited by a \verb|}|$_12$.
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_log_next_code:n}
+%<latexrelease> {Hooks~with~args}
+\exp_last_unbraced:NNNNo
+\cs_new:Npn \@@_log_next_code:w #1 \c_right_brace_str { }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_log_next_code:n}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset:Npn \@@_log_next_code:n #1
+%<latexrelease> { \exp_args:No \tl_to_str:n { \use_none:nn #1 } }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_print_args:n}
+% Pretty-prints the number of arguments of a hook.
% \begin{macrocode}
-\cs_new:Npn \@@_log_next_code:n #1
- { \exp_args:No \tl_to_str:n { \use_none:nn #1 } }
+\cs_new:Npn \@@_print_args:nn #1 #2
+ {
+ \int_compare:nNnT {#2} > { 0 }
+ {
+ \@@_if_declared:nT {#1} { \use_none:nnn }
+ \@@_if_cmd_hook:nT {#1}
+ { \use_i:nnn { ~ (unknown ~ } }
+ \use:n { ~ (#2 ~ }
+ argument \int_compare:nNnT {#2} > { 1 } { s } )
+ }
+ }
% \end{macrocode}
% \end{macro}
%
@@ -4656,15 +6327,34 @@
% \subsection{Specifying code for next invocation}
%
% \begin{macro}{\hook_gput_next_code:nn}
+% \changes{v1.1a}{2023/04/06}
+% {Add \cs{hook_gput_next_code_with_args:nn} (hook-args).}
% \begin{macrocode}
-\cs_new_protected:Npn \hook_gput_next_code:nn #1
- { \@@_normalize_hook_args:Nn \@@_gput_next_code:nn {#1} }
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_gput_next_code:nn}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \hook_gput_next_code:nn #1 #2
+ {
+ \@@_replacing_args_false:
+ \@@_normalize_hook_args:Nn \@@_gput_next_code:nn {#1} {#2}
+ \@@_replacing_args_reset:
+ }
+\cs_new_protected:Npn \hook_gput_next_code_with_args:nn #1 #2
+ {
+ \@@_replacing_args_true:
+ \@@_normalize_hook_args:Nn \@@_gput_next_code:nn {#1} {#2}
+ \@@_replacing_args_reset:
+ }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_gput_next_code:nn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \hook_gput_next_code:nn #1
+%<latexrelease> { \@@_normalize_hook_args:Nn \@@_gput_next_code:nn {#1} }
+%<latexrelease>\cs_gset_protected:Npn \hook_gput_next_code_with_args:nn #1 #2 { }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@@_gput_next_code:nn,
-% \@@_gput_next_do:nn,
-% \@@_gput_next_do:Nnn}
+% \begin{macro}{\@@_gput_next_code:nn}
% \begin{macrocode}
\cs_new_protected:Npn \@@_gput_next_code:nn #1 #2
{
@@ -4672,20 +6362,17 @@
{ \msg_error:nnn { hooks } { hook-disabled } {#1} }
{
\@@_if_structure_exist:nTF {#1}
- { \@@_gput_next_do:nn {#1} {#2} }
- { \@@_try_declaring_generic_next_hook:nn {#1} {#2} }
+ { \@@_gput_next_do:nn }
+ { \@@_try_declaring_generic_next_hook:nn }
+ {#1} {#2}
}
}
% \end{macrocode}
+% \end{macro}
%
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_gput_next_do:nn #1
- {
- \exp_args:Nc \@@_gput_next_do:Nnn
- { @@_next~#1 } {#1}
- }
-% \end{macrocode}
-% First check if the ``next code'' token list is empty: if so we need
+% \begin{macro}{\@@_gput_next_do:nn}
+% Start by sanity-checking with \cs{@@_chk_args_allowed:nn}.
+% Then check if the ``next code'' token list is empty: if so we need
% to add a \cs{tl_gclear:c} to clear it, so the code lasts for one
% usage only. The token list is cleared early so that nested usages
% don't get lost. \cs{tl_gclear:c} is used instead of
@@ -4694,38 +6381,74 @@
% that would make an infinite loop. Also in case the main code token
% list is empty, the hook code has to be updated to add the next
% execution token list.
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
+% \changes{v1.1c}{2023/04/19}
+% {Initialise hook structure when adding 'next' code (gh/1052).}
% \begin{macrocode}
-\cs_new_protected:Npn \@@_gput_next_do:Nnn #1 #2
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_gput_next_do:nn}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \@@_gput_next_do:nn #1
{
- \tl_if_empty:cT { @@~#2 }
- { \@@_update_hook_code:n {#2} }
- \tl_if_empty:NT #1
- { \@@_tl_gset:Nn #1 { \@@_clear_next:n {#2} } }
- \@@_tl_gput_right:Nn #1
+ \@@_init_structure:n {#1}
+ \@@_chk_args_allowed:nn {#1} { AddToHookNext }
+ \@@_cs_if_empty:cT { @@~#1 }
+ { \@@_update_hook_code:n {#1} }
+ \@@_cs_if_empty:cT { @@_next~#1 }
+ { \@@_next_gset:nn {#1} { \@@_clear_next:n {#1} } }
+ \@@_cs_gput_right:nnn { _next } {#1}
}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_gput_next_do:nn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \@@_gput_next_do:nn #1
+%<latexrelease> {
+%<latexrelease> \exp_args:Nc \@@_gput_next_do:Nnn
+%<latexrelease> { @@_next~#1 } {#1}
+%<latexrelease> }
+%<latexrelease>\cs_gset_protected:Npn \@@_gput_next_do:Nnn #1 #2
+%<latexrelease> {
+%<latexrelease> \tl_if_empty:cT { @@~#2 }
+%<latexrelease> { \@@_update_hook_code:n {#2} }
+%<latexrelease> \tl_if_empty:NT #1
+%<latexrelease> { \@@_tl_gset:Nn #1 { \@@_clear_next:n {#2} } }
+%<latexrelease> \@@_tl_gput_right:Nn #1
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
-%
-%
-% \begin{macro}{\hook_gclear_next_code:n,\@@_clear_next:n}
+% \begin{macro}{\hook_gclear_next_code:n}
% Discard anything set up for next invocation of the hook.
% \changes{v1.0o}{2021/07/27}{Macro made public}
% \begin{macrocode}
\cs_new_protected:Npn \hook_gclear_next_code:n #1
{ \@@_normalize_hook_args:Nn \@@_clear_next:n {#1} }
-\cs_new_protected:Npn \@@_clear_next:n #1
- { \cs_gset_eq:cN { @@_next~#1 } \c_empty_tl }
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\@@_clear_next:n}
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_clear_next:n}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \@@_clear_next:n #1
+ { \@@_next_gset:nn {#1} { } }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_clear_next:n}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \@@_clear_next:n #1
+%<latexrelease> { \cs_gset_eq:cN { @@_next~#1 } \c_empty_tl }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
%
%
% \subsection{Using the hook}
%
% \begin{macro}{\hook_use:n}
% \begin{macro}[EXP]{\@@_use_initialized:n}
-% \begin{macro}{\@@_use_undefined:w,\@@_use_end:}
% \begin{macro}{\@@_preamble_hook:n}
% \cs{hook_use:n} as defined here is used in the preamble, where
% hooks aren't initialized by default. \cs{@@_use_initialized:n} is
@@ -4750,24 +6473,50 @@
% \verb=\csname ...\endcsname= construct \cs{tl_if_exist:c} is
% careful to avoid this.
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2021/11/15}{\hook_use:n}
-%<latexrelease> {Standardise~generic~hook~names}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_use:n}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \hook_use:n #1
{
- \tl_if_exist:cT { @@~#1 }
- {
- \@@_preamble_hook:n {#1}
- \cs:w @@~#1 \cs_end:
- }
+ \@@_preamble_hook:n {#1}
+ \@@_use_initialized:n {#1}
}
\cs_new:Npn \@@_use_initialized:n #1
{
\if_cs_exist:w @@~#1 \cs_end:
- \cs:w @@~#1 \exp_after:wN \cs_end:
+ \cs:w @@~#1 \use_i:nn
\fi:
+ \use_none:n
+ \cs_end:
}
\cs_new_protected:Npn \@@_preamble_hook:n #1
- { \@@_initialize_hook_code:n {#1} }
+ {
+ \if_cs_exist:w @@~#1 \cs_end:
+ \@@_initialize_hook_code:n {#1}
+ \fi:
+ }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2021/11/15}{\hook_use:n}
+%<latexrelease> {Standardise~generic~hook~names}
+%<latexrelease>\cs_new_protected:Npn \hook_use:n #1
+%<latexrelease> {
+%<latexrelease> \tl_if_exist:cT { @@~#1 }
+%<latexrelease> {
+%<latexrelease> \@@_preamble_hook:n {#1}
+%<latexrelease> \cs:w @@~#1 \cs_end:
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\cs_new:Npn \@@_use_initialized:n #1
+%<latexrelease> {
+%<latexrelease> \if_cs_exist:w @@~#1 \cs_end:
+%<latexrelease> \cs:w @@~#1 \exp_after:wN \cs_end:
+%<latexrelease> \fi:
+%<latexrelease> }
+%<latexrelease>\cs_new_protected:Npn \@@_preamble_hook:n #1
+%<latexrelease> { \@@_initialize_hook_code:n {#1} }
+%<latexrelease>\cs_new:Npn \hook_use:nnw #1 { }
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
%
@@ -4799,13 +6548,69 @@
%<latexrelease>\cs_new_protected:Npn \@@_preamble_hook:n #1
%<latexrelease> { \@@_initialize_hook_code:n {#1} }
%<latexrelease>\cs_new_eq:NN \@@_use_end: \cs_end:
+%<latexrelease>\cs_new:Npn \hook_use:nnw #1 { }
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
+%
+%
+% \begin{macro}{\hook_use:nnw}
+% \begin{macro}[EXP]{\@@_use_initialized:nnw}
+% \changes{v1.1a}{2023/04/06}
+% {Add \cs{hook_use:nnw} (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_use:nnw}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \hook_use:nnw #1
+ {
+ \@@_preamble_hook:n {#1}
+ \@@_use_initialized:nnw {#1}
+ }
+\cs_new:Npn \@@_use_initialized:nnw #1 #2
+ {
+ \cs:w
+ \if_cs_exist:w @@~#1 \cs_end:
+ @@~#1
+ \else:
+ use_none: \prg_replicate:nn {#2} { n }
+ \fi:
+ \cs_end:
+ }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_use:nnw}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset:Npn \hook_use:nnw #1 #2
+%<latexrelease> { \use:c { use_none: \prg_replicate:nn {#2} { n } } }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\@@_post_initialization_defs:}
+% \changes{v1.1a}{2023/04/06}
+% {Macro added (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_post_initialization_defs:}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \@@_post_initialization_defs:
+ {
+ \cs_gset_eq:NN \hook_use:n \@@_use_initialized:n
+ \cs_gset_eq:NN \hook_use:nnw \@@_use_initialized:nnw
+ \cs_gset_eq:NN \@@_preamble_hook:n \use_none:n
+ \cs_gset_eq:NN \@@_post_initialization_defs: \prg_do_nothing:
+ }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_post_initialization_defs:}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_post_initialization_defs:
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
% \end{macro}
%
+%
% \begin{macro}[EXP]{\@@_use:wn}
% \begin{macro}{\@@_try_file_hook:n,\@@_if_usable_use:n}
% \cs{@@_use:wn} does a quick check to test if the current hook is a
@@ -4861,8 +6666,7 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\hook_use_once:n}
-% \begin{macro}{\@@_use_once:n}
+% \begin{macro}{\hook_use_once:n,\hook_use_once:nnw}
% For hooks that can and should be used only once we have a special
% use command that further inhibits the hook from getting more code
% added to it. This has the effect that any
@@ -4874,20 +6678,80 @@
% documented to not trim spaces.
%
% \changes{v1.0r}{2021/09/06}{Clean up after \cs{UseOneTimeHook} (gh/606)}
+% \changes{v1.1a}{2023/04/06}
+% {Add \cs{hook_use_once:nnw} (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_use_once:nnw}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \hook_use_once:n #1
{
\@@_if_execute_immediately:nF {#1}
- { \@@_normalize_hook_args:Nn \@@_use_once:n { \use:n {#1} } }
+ { \@@_normalize_hook_args:Nn \@@_use_once:nn { \use:n {#1} } { 0 } }
}
-\cs_new_protected:Npn \@@_use_once:n #1
+\cs_new_protected:Npn \hook_use_once:nnw #1 #2
+ {
+ \@@_if_execute_immediately:nF {#1}
+ { \@@_normalize_hook_args:Nn \@@_use_once:nn { \use:n {#1} } {#2} }
+ }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_use_once:nnw}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \hook_use_once:n #1
+%<latexrelease> {
+%<latexrelease> \@@_if_execute_immediately:nF {#1}
+%<latexrelease> { \@@_normalize_hook_args:Nn \@@_use_once:n { \use:n {#1} } }
+%<latexrelease> }
+%<latexrelease>\cs_gset:Npn \hook_use_once:nnw #1 #2
+%<latexrelease> { \use:c { use_none: \prg_replicate:nn {#2} { n } } }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macro}{\@@_use_once:nn}
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_use_once:nn}
+%<latexrelease> {Hooks~with~args}
+\cs_new_protected:Npn \@@_use_once:nn #1 #2
{
\@@_preamble_hook:n {#1}
\@@_use_once_set:n {#1}
- \@@_use_initialized:n {#1}
- \@@_use_once_clear:n {#1}
+% \end{macrocode}
+% When a hook has arguments, the call to \cs{@@_use_initialized:n},
+% should be the very last thing to happen, otherwise the arguments
+% grabbed will be wrong. So, to clean up after the hook we need to
+% cheat a bit and sneak the cleanup code at the end of the hook,
+% along with the next execution code.
+% \begin{macrocode}
+ \@@_replacing_args_false:
+ \@@_cs_gput_right:nnn { _next } {#1} { \@@_use_once_clear:n {#1} }
+ \@@_replacing_args_reset:
+ \@@_if_usable:nTF {#1}
+ { \@@_use_initialized:n {#1} }
+ {
+ \int_compare:nNnT {#2} > { 0 }
+ { \use:c { use_none: \prg_replicate:nn {#2} { n } } }
+ }
}
+%<latexrelease>\EndIncludeInRelease
+%
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_use_once:nn}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_gset_protected:Npn \@@_use_once:n #1
+%<latexrelease> {
+%<latexrelease> \@@_preamble_hook:n {#1}
+%<latexrelease> \@@_use_once_set:n {#1}
+%<latexrelease> \@@_use_initialized:n {#1}
+%<latexrelease> \@@_use_once_clear:n {#1}
+%<latexrelease> }
+%<latexrelease>\cs_undefine:N \@@_use_once:nn
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
+% \end{macro}
%
% \begin{macro}{\@@_use_once_set:n}
% \begin{macro}{\@@_use_once_clear:n}
@@ -4900,43 +6764,60 @@
% \cs{hook_use_once:n} will expand to nothing.
% \changes{v1.0r}{2021/09/06}{Clean up after \cs{UseOneTimeHook} (gh/606)}
% \changes{v1.0u}{2022/05/13}{Check if prop exists to avoid l3debug error}
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_use_once_clear:n}
+%<latexrelease> {Hooks~with~args}
\cs_new_protected:Npn \@@_use_once_set:n #1
{ \@@_tl_gset:cn { g_@@_#1_reversed_tl } { I } }
\cs_new_protected:Npn \@@_use_once_clear:n #1
{
- \@@_tl_gclear:c { @@~#1 }
- \@@_tl_gclear:c { @@_next~#1 }
- \@@_tl_gclear:c { @@_toplevel~#1 }
+ \@@_code_gset:nn {#1} { }
+ \@@_next_gset:nn {#1} { }
+ \@@_toplevel_gset:nn {#1} { }
\prop_gclear_new:c { g_@@_#1_code_prop }
}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_use_once_clear:n}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_new_protected:Npn \@@_use_once_clear:n #1
+%<latexrelease> {
+%<latexrelease> \@@_tl_gclear:c { @@~#1 }
+%<latexrelease> \@@_tl_gclear:c { @@_next~#1 }
+%<latexrelease> \@@_tl_gclear:c { @@_toplevel~#1 }
+%<latexrelease> \prop_gclear_new:c { g_@@_#1_code_prop }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
-% \end{macro}
-% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[pTF]{\@@_if_execute_immediately:n}
-% To check whether the code being added should be executed immediately (that
-% is, if the hook is a one-time hook), we check if it's usable (it
-% can't be one-time if it was not already usable), then we check that
+% To check whether the code being added should be executed immediately
+% (that is, if the hook is a one-time hook), we check if
% \cs[no-index]{g_@@_\meta{hook}_reversed_tl} is |I|. The gymnastics
% around \cs{if:w} is there to allow the |reversed| token list to be
% empty.
% \changes{v1.0r}{2021/09/06}{Macro added (gh/606)}
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
% \begin{macrocode}
\prg_new_conditional:Npnn \@@_if_execute_immediately:n #1 { T, F, TF }
{
- \@@_if_usable:nTF {#1}
- {
- \exp_after:wN \@@_clean_to_scan:w
- \if:w I \cs:w g_@@_#1_reversed_tl \cs_end:
- \s_@@_mark \prg_return_true:
- \else:
- \s_@@_mark \prg_return_false:
+ \exp_after:wN \@@_use_none_delimit_by_s_mark:w
+ \if:w I
+ \if_cs_exist:w g_@@_#1_reversed_tl \cs_end:
+ \cs:w g_@@_#1_reversed_tl \exp_after:wN \cs_end:
\fi:
- }
- { \prg_return_false: }
+ X
+ \s_@@_mark \prg_return_true:
+ \else:
+ \s_@@_mark \prg_return_false:
+ \fi:
}
% \end{macrocode}
% \end{macro}
@@ -4963,30 +6844,57 @@
%
% All other states can only be queried with internal tests as the
% different states are irrelevant for package code.
-
+%
% \begin{macro}[pTF]{\hook_if_empty:n}
% Test if a hook is empty (that is, no code was added to that hook).
% A \meta{hook} being empty means that all three of its
% \cs{g_@@_\meta{hook}_code_prop}, its
% \cs{@@_toplevel\textvisiblespace\meta{hook}} and its
% \cs{@@_next\textvisiblespace\meta{hook}} are empty.
+% \changes{v1.1a}{2023/04/06}
+% {Changes to add hook arguments (hook-args).}
+% \changes{v1.1c}{2023/04/19}
+% {Simpler and faster version (gh/1052).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\hook_if_empty:n}
+%<latexrelease> {Hooks~with~args}
\prg_new_conditional:Npnn \hook_if_empty:n #1 { p , T , F , TF }
{
- \@@_if_structure_exist:nTF {#1}
- {
- \bool_lazy_and:nnTF
- { \prop_if_empty_p:c { g_@@_#1_code_prop } }
- {
- \bool_lazy_and_p:nn
- { \tl_if_empty_p:c { @@_toplevel~#1 } }
- { \tl_if_empty_p:c { @@_next~#1 } }
- }
- { \prg_return_true: }
- { \prg_return_false: }
- }
- { \prg_return_true: }
+ \if:w
+ T
+ \prop_if_exist:cT { g_@@_#1_code_prop }
+ { \prop_if_empty:cF { g_@@_#1_code_prop } { F } }
+ \@@_cs_if_empty:cF { @@_toplevel~#1 } { F }
+ \@@_cs_if_empty:cF { @@_next~#1 } { F }
+ T
+ \prg_return_true:
+ \else:
+ \prg_return_false:
+ \fi:
}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\hook_if_empty:n}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\prg_new_conditional:Npnn \hook_if_empty:n #1 { p , T , F , TF }
+%<latexrelease> {
+%<latexrelease> \@@_if_structure_exist:nTF {#1}
+%<latexrelease> {
+%<latexrelease> \bool_lazy_and:nnTF
+%<latexrelease> { \prop_if_empty_p:c { g_@@_#1_code_prop } }
+%<latexrelease> {
+%<latexrelease> \bool_lazy_and_p:nn
+%<latexrelease> { \tl_if_empty_p:c { @@_toplevel~#1 } }
+%<latexrelease> { \tl_if_empty_p:c { @@_next~#1 } }
+%<latexrelease> }
+%<latexrelease> { \prg_return_true: }
+%<latexrelease> { \prg_return_false: }
+%<latexrelease> }
+%<latexrelease> { \prg_return_true: }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
@@ -4994,15 +6902,15 @@
% \begin{macro}[pTF]{\@@_if_usable:n}
% A hook is usable if the
% token list that stores the sorted code for that hook,
-% \cs[no-index]{@@~\meta{hook}}, exists. The property list
-% \cs[no-index]{g_@@_\meta{hook}_code_prop} cannot be used here
+% \cs[no-index]{@@\textvisiblespace\meta{hook}}, exists. The property
+% list \cs[no-index]{g_@@_\meta{hook}_code_prop} cannot be used here
% because often it is necessary to add code to a hook without knowing
% if such hook was already declared, or even if it will ever be
% (for example, in case the package that defines it isn't loaded).
% \begin{macrocode}
\prg_new_conditional:Npnn \@@_if_usable:n #1 { p , T , F , TF }
{
- \tl_if_exist:cTF { @@~#1 }
+ \cs_if_exist:cTF { @@~#1 }
{ \prg_return_true: }
{ \prg_return_false: }
}
@@ -5046,7 +6954,7 @@
% \begin{macrocode}
\prg_new_conditional:Npnn \@@_if_reversed:n #1 { p , T , F , TF }
{
- \exp_after:wN \@@_clean_to_scan:w
+ \exp_after:wN \@@_use_none_delimit_by_s_mark:w
\if:w - \cs:w g_@@_#1_reversed_tl \cs_end:
\s_@@_mark \prg_return_true:
\else:
@@ -5086,6 +6994,37 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}[pTF]{\@@_if_cmd_hook:n}
+% \begin{macro}[pTF]{\@@_if_cmd_hook:w}
+% An internal conditional that checks if a given hook is a valid
+% generic \hook{cmd} hook.
+% \changes{v1.1d}{2023/05/21}
+% {Changes to allow support arguments in cmd hooks (cmd-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\@@_if_cmd_hook:n}
+%<latexrelease> {Hooks~with~args}
+\prg_new_conditional:Npnn \@@_if_cmd_hook:n #1 { T }
+ { \@@_if_cmd_hook:w #1 / / / \s_@@_mark }
+\cs_new:Npn \@@_if_cmd_hook:w #1 / #2 / #3 / #4 \s_@@_mark
+ {
+ \if:w Y
+ \str_if_eq:nnF {#1} { cmd } { N }
+ \tl_if_exist:cF { c_@@_generic_#1/./#3_tl } { N }
+ Y
+ \prg_return_true:
+ \else:
+ \prg_return_false:
+ \fi:
+ }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_if_cmd_hook:n}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_undefine:N \@@_if_cmd_hook:nT
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
% \begin{macro}[pTF]{\@@_if_generic_reversed:n}
% An internal conditional that checks if a name belongs to a generic
% reversed hook.
@@ -5103,6 +7042,50 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}[EXP]{\@@_if_replacing_args:TF}
+% \begin{macro}[EXP]{\@@_misused_if_replacing_args:nn}
+% \begin{macro}{\@@_replacing_args_true:}
+% \begin{macro}{\@@_replacing_args_false:}
+% \begin{macro}{\@@_replacing_args_reset:}
+% \begin{macro}{\g_@@_replacing_stack_seq}
+% An internal conditional that checks if the code being added to the
+% hook contains arguments.
+% \changes{v1.1a}{2023/04/06}
+% {Macro added (hook-args).}
+% \begin{macrocode}
+\seq_new:N \g_@@_replacing_stack_seq
+\cs_new:Npn \@@_misused_if_replacing_args:nn #1 #2
+ {
+ \msg_expandable_error:nnn { latex2e } { should-not-happen }
+ { Misused~\@@_if_replacing_args:. }
+ }
+\cs_new:Npn \@@_if_replacing_args:TF
+ { \@@_misused_if_replacing_args:nn }
+\cs_new_protected:Npn \@@_replacing_args_true:
+ {
+ \seq_gpush:No \g_@@_replacing_stack_seq
+ { \@@_if_replacing_args:TF }
+ \cs_set:Npn \@@_if_replacing_args:TF { \use_i:nn }
+ }
+\cs_new_protected:Npn \@@_replacing_args_false:
+ {
+ \seq_gpush:No \g_@@_replacing_stack_seq
+ { \@@_if_replacing_args:TF }
+ \cs_set:Npn \@@_if_replacing_args:TF { \use_ii:nn }
+ }
+\cs_new_protected:Npn \@@_replacing_args_reset:
+ {
+ \seq_gpop:NN \g_@@_replacing_stack_seq \l_@@_return_tl
+ \cs_gset_eq:NN \@@_if_replacing_args:TF \l_@@_return_tl
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
% \subsection{Messages}
%
% Hook errors are LaTeX kernel errors:
@@ -5137,6 +7120,55 @@
Please~ use~ a~ different~ name~ for~ your~ hook.}
% \end{macrocode}
%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{too-many-args}
+%<latexrelease> {Hooks~with~args}
+% \end{macrocode}
+%
+% \changes{v1.1a}{2023/04/06}
+% {Messages 'too-many-args', 'without-args' and 'one-time-args' added (hook-args).}
+% \begin{macrocode}
+\msg_new:nnnn { hooks } { too-many-args }
+ { Too~many~arguments~for~hook~'#1'. }
+ {
+ You~tried~to~declare~a~hook~with~#2~arguments,~but~a~
+ hook~can~only~have~up~to~nine.~LaTeX~will~define~this~
+ hook~with~nine~arguments.
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+\msg_new:nnnn { hooks } { without-args }
+ { Hook~'#1'~has~no~arguments. }
+ {
+ You~tried~to~use~\iow_char:N\\#2WithArguments~
+ on~a~hook~that~takes~no~arguments.\\
+ Check~the~usage~of~the~hook~or~use~\iow_char:N\\#2~instead.\\
+ \\
+ LaTeX~will~use~\iow_char:N\\#2.
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+\msg_new:nnnn { hooks } { one-time-args }
+ { You~can't~have~arguments~in~used~one-time~hook~'#1'. }
+ {
+ You~tried~to~use~\iow_char:N\\#2WithArguments~
+ on~a~one-time~hook~that~has~already~been~used.~
+ You~have~to~add~the~code~before~the~hook~is~used,~
+ or~add~the~code~without~arguments~using~\iow_char:N\\#2~instead.\\
+ \\
+ LaTeX~will~use~\iow_char:N\\#2.
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{too-many-args}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
%
% \begin{macrocode}
\msg_new:nnnn { hooks } { hook-disabled }
@@ -5278,17 +7310,49 @@
% \begin{macro}{\NewHook,\NewReversedHook,\NewMirroredHookPair}
% Declaring new hooks \ldots
% \begin{macrocode}
-\NewDocumentCommand \NewHook { m }{ \hook_new:n {#1} }
-\NewDocumentCommand \NewReversedHook { m }{ \hook_new_reversed:n {#1} }
-\NewDocumentCommand \NewMirroredHookPair { mm }{ \hook_new_pair:nn {#1}{#2} }
+\NewDocumentCommand \NewHook { m }
+ { \hook_new:n {#1} }
+\NewDocumentCommand \NewReversedHook { m }
+ { \hook_new_reversed:n {#1} }
+\NewDocumentCommand \NewMirroredHookPair { mm }
+ { \hook_new_pair:nn {#1}{#2} }
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{
+% \NewHookWithArguments,
+% \NewReversedHookWithArguments,
+% \NewMirroredHookPairWithArguments
+% }
+% Declaring new hooks with arguments\ldots
+% \changes{v1.1a}{2023/04/06}
+% {Add \cs{NewHookWithArguments} (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\NewHookWithArguments}
+%<latexrelease> {Hooks~with~args}
+\NewDocumentCommand \NewHookWithArguments { mm }
+ { \hook_new_with_args:nn {#1} {#2} }
+\NewDocumentCommand \NewReversedHookWithArguments { mm }
+ { \hook_new_reversed_with_args:nn {#1} {#2} }
+\NewDocumentCommand \NewMirroredHookPairWithArguments { mmm }
+ { \hook_new_pair_with_args:nnn {#1} {#2} {#3} }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2023/06/01}{\NewHookWithArguments}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_new_protected:Npn \NewHookWithArguments #1 #2 { }
+%<latexrelease>\cs_new_protected:Npn \NewReversedHookWithArguments #1 #2 { }
+%<latexrelease>\cs_new_protected:Npn \NewMirroredHookPairWithArguments #1 #2 #3 { }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{macrocode}
-%<latexrelease>\IncludeInRelease{2021/06/01}%
-%<latexrelease> {\hook_activate_generic:n}{Providing~hooks}
+%<latexrelease>\IncludeInRelease{2021/06/01}{\ActivateGenericHook}
+%<latexrelease> {Providing~hooks}
% \end{macrocode}
%
% \begin{macro}{\ActivateGenericHook}
@@ -5296,7 +7360,8 @@
% \changes{v1.0m}{2021/04/29}{Add \cs{ProvideHook} etc.}
% \changes{v1.0o}{2021/08/02}{Change name}
% \begin{macrocode}
-\NewDocumentCommand \ActivateGenericHook { m }{ \hook_activate_generic:n {#1} }
+\NewDocumentCommand \ActivateGenericHook { m }
+ { \hook_activate_generic:n {#1} }
% \end{macrocode}
% \end{macro}
%
@@ -5304,32 +7369,57 @@
% Disabling a generic hook.
% \changes{v1.0o}{2021/08/02}{Change name}
% \begin{macrocode}
-\NewDocumentCommand \DisableGenericHook { m }{ \hook_disable_generic:n {#1} }
+\NewDocumentCommand \DisableGenericHook { m }
+ { \hook_disable_generic:n {#1} }
% \end{macrocode}
% \end{macro}
%
% \begin{macrocode}
%<latexrelease>\EndIncludeInRelease
-%<latexrelease>\IncludeInRelease{2020/10/01}
-%<latexrelease> {\hook_activate_generic:n}{Providing~hooks}
-%<latexrelease>
-%<latexrelease>\def \ActivateGenericHook#1{}
-%<latexrelease>
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}{\ActivateGenericHook}
+%<latexrelease> {Providing~hooks}
+%<latexrelease>\def \ActivateGenericHook #1 { }
+%<latexrelease>\def \DisableGenericHook #1 { }
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
%
%
-% \begin{macro}{\AddToHook}
+% \begin{macro}{\AddToHook,\AddToHookWithArguments}
+% \changes{v1.1a}{2023/04/06}
+% {Add \cs{AddToHookWithArguments} (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\AddToHookWithArguments}
+%<latexrelease> {Hooks~with~args}
\NewDocumentCommand \AddToHook { m o +m }
{ \hook_gput_code:nnn {#1} {#2} {#3} }
+\NewDocumentCommand \AddToHookWithArguments { m o +m }
+ { \hook_gput_code_with_args:nnn {#1} {#2} {#3} }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\AddToHookWithArguments}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_new_protected:Npn \AddToHookWithArguments #1 #2 #3 { }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\AddToHookNext}
+% \begin{macro}{\AddToHookNext,\AddToHookNextWithArguments}
+% \changes{v1.1a}{2023/04/06}
+% {Add \cs{AddToHookNextWithArguments} (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\AddToHookNextWithArguments}
+%<latexrelease> {Hooks~with~args}
\NewDocumentCommand \AddToHookNext { m +m }
{ \hook_gput_next_code:nn {#1} {#2} }
+\NewDocumentCommand \AddToHookNextWithArguments { m +m }
+ { \hook_gput_next_code_with_args:nn {#1} {#2} }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\AddToHookNextWithArguments}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_new_protected:Npn \AddToHookNextWithArguments #1 #2 { }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
@@ -5396,12 +7486,29 @@
%
%
%
-% \begin{macro}{\UseHook,\UseOneTimeHook}
+% \begin{macro}{
+% \UseHook,
+% \UseOneTimeHook,
+% \UseHookWithArguments,
+% \UseOneTimeHookWithArguments,
+% }
% Avoid the overhead of \pkg{xparse} and its protection that we
% don't want here (since the hook should vanish without trace if empty)!
+% \changes{v1.1a}{2023/04/06}
+% {Add \cs{UseHookWithArguments} (hook-args).}
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2023/06/01}{\UseHookWithArguments}
+%<latexrelease> {Hooks~with~args}
\cs_new:Npn \UseHook { \hook_use:n }
\cs_new:Npn \UseOneTimeHook { \hook_use_once:n }
+\cs_new:Npn \UseHookWithArguments { \hook_use:nnw }
+\cs_new:Npn \UseOneTimeHookWithArguments { \hook_use_once:nnw }
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\UseHookWithArguments}
+%<latexrelease> {Hooks~with~args}
+%<latexrelease>\cs_new:Npn \UseHookWithArguments #1 #2 { }
+%<latexrelease>\cs_new:Npn \UseOneTimeHookWithArguments #1 #2 { }
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
@@ -5462,7 +7569,7 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[EXP]{\IfHookExistsTF}
+% \begin{macro}[EXP,int]{\IfHookExistsTF}
% Marked for removal and no longer documented in the doc section!
% \phoinline{\cs{IfHookExistsTF} is used in \texttt{jlreq.cls},
% \texttt{pxatbegshi.sty}, \texttt{pxeverysel.sty},
@@ -5484,7 +7591,7 @@
% \changes{v1.0p}{2021/08/20}{Added deprecation warnings for
% old generic hook commands (gh/638)}
%
-% \begin{macro}{
+% \begin{macro}[int]{
% \hook_disable:n,
% \hook_provide:n,
% \hook_provide_reversed:n,
@@ -5529,7 +7636,7 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{
+% \begin{macro}[int]{
% \DisableHook,
% \ProvideHook,
% \ProvideReversedHook,
@@ -5596,8 +7703,10 @@
%<@@=>
% \end{macrocode}
%
-% \begin{macro}{\@expl@@@initialize@all@@,
-% \@expl@@@hook@curr@name@pop@@}
+% \begin{macro}[int]{
+% \@expl@@@initialize@all@@,
+% \@expl@@@hook@curr@name@pop@@
+% }
%
% \InternalDetectionOff
% \begin{macrocode}
@@ -5620,8 +7729,8 @@
% to be for \cs{AddToHook} vice versa (gh/401)}
% \begin{macrocode}
%
-%<latexrelease>\IncludeInRelease{0000/00/00}%
-%<latexrelease> {lthooks}{The~hook~management}%
+%<latexrelease>\IncludeInRelease{0000/00/00}{lthooks}
+%<latexrelease> {The~hook~management}%
%<latexrelease>
%<latexrelease>\def \NewHook#1{}
%<latexrelease>\def \NewReversedHook#1{}
@@ -5656,10 +7765,56 @@
%<latexrelease>\long\def \IfHookEmptyTF #1#2#3{#2}
%<latexrelease>
%<latexrelease>\EndModuleRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<@@=hook>
+% \end{macrocode}
+%
+% \changes{v1.1a}{2023/04/06}
+% {Add dedicated rollback code to revert data structures (hook-args).}
+% \begin{macrocode}
+%<latexrelease>\cs:w @@_rollback_tidying: \cs_end:
+%<latexrelease>\bool_lazy_and:nnT
+%<latexrelease> { \int_compare_p:nNn { \sourceLaTeXdate } > { 20230600 } }
+%<latexrelease> { \int_compare_p:nNn { \requestedLaTeXdate } < { 20230601 } }
+%<latexrelease> {
+%<latexrelease> \cs_gset_protected:Npn \@@_rollback_tidying:
+%<latexrelease> {
+%<latexrelease> \@latex@error { Rollback~code~executed~twice }
+%<latexrelease> {
+%<latexrelease> Something~went~wrong~(unless~this~was~
+%<latexrelease> done~on~purpose~in~a~testing~environment).
+%<latexrelease> }
+%<latexrelease> \use_none:nnnn
+%<latexrelease> }
+%<latexrelease> \cs_set:Npn \@@_tmp:w #1 #2
+%<latexrelease> {
+%<latexrelease> \@@_tl_gset:cx { @@#1~#2 }
+%<latexrelease> {
+%<latexrelease> \exp_args:No \exp_not:o
+%<latexrelease> {
+%<latexrelease> \cs:w @@#1~#2 \exp_last_unbraced:Ne \cs_end:
+%<latexrelease> { \@@_braced_cs_parameter:n { @@#1~#2 } }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease> \seq_map_inline:Nn \g_@@_all_seq
+%<latexrelease> {
+%<latexrelease> \exp_after:wN \cs_gset_nopar:Npn
+%<latexrelease> \cs:w g_@@_#1_code_prop \exp_args:NNo \exp_args:No
+%<latexrelease> \cs_end: { \cs:w g_@@_#1_code_prop \cs_end: }
+%<latexrelease> \@@_tmp:w { _toplevel } {#1}
+%<latexrelease> \@@_tmp:w { _next } {#1}
+%<latexrelease> }
+%<latexrelease> }
\ExplSyntaxOff
%</2ekernel|latexrelease>
% \end{macrocode}
%
+% \begin{macrocode}
+%<@@=>
+% \end{macrocode}
%
% \Finale
%
diff --git a/macros/latex-dev/base/ltlists.dtx b/macros/latex-dev/base/ltlists.dtx
index afde14e070..d43df93a54 100644
--- a/macros/latex-dev/base/ltlists.dtx
+++ b/macros/latex-dev/base/ltlists.dtx
@@ -31,7 +31,7 @@
%<*driver>
% \fi
\ProvidesFile{ltlists.dtx}
- [2020/12/05 v1.0t LaTeX Kernel (List Environments)]
+ [2023/05/17 v1.0t LaTeX Kernel (List Environments)]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{ltlists.dtx}
@@ -68,7 +68,6 @@
% \begin{quote}
% |\list|\marg{LABEL}\marg{COMMANDS} ... |\endlist|
% \end{quote}
-%
% which can be invoked by the user as the list environment. The LABEL
% argument specifies item labeling. COMMANDS contains commands for
% changing the horizontal and vertical spacing parameters.
@@ -187,7 +186,7 @@
% |\hsize|.
%
% Here are the parameters of a list that can be set by commands in
-% the |\list|'s COMMANDS argument. These parameters are all TeX
+% the |\list|'s COMMANDS argument. These parameters are all \TeX{}
% skips or dimensions (defined by |\newskip| or |\newdimen|), so the
% usual \TeX\ or \LaTeX\ commands can be used to set them. The
% commands will be executed in vmode if and only if the |\list| was
@@ -228,7 +227,7 @@
% label.
% \item[\cs{labelwidth}:] nominal width of box that contains the label.
% If the natural width of the
-% label $< =$ \cs{labelwidth},
+% label $\leq$ \cs{labelwidth},
% then the label is flushed right inside a box
% of width \cs{labelwidth} (with an \cs{hfil}).
% Otherwise,
diff --git a/macros/latex-dev/base/ltluatex.pdf b/macros/latex-dev/base/ltluatex.pdf
index 855095c6ef..a2c7bdc1dc 100644
--- a/macros/latex-dev/base/ltluatex.pdf
+++ b/macros/latex-dev/base/ltluatex.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltmarks-code.pdf b/macros/latex-dev/base/ltmarks-code.pdf
index 54c2703531..22470e7814 100644
--- a/macros/latex-dev/base/ltmarks-code.pdf
+++ b/macros/latex-dev/base/ltmarks-code.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltmarks-doc.pdf b/macros/latex-dev/base/ltmarks-doc.pdf
index cf70d21cae..b3a84ca9f7 100644
--- a/macros/latex-dev/base/ltmarks-doc.pdf
+++ b/macros/latex-dev/base/ltmarks-doc.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltmarks.dtx b/macros/latex-dev/base/ltmarks.dtx
index 3dc4b493ac..677534dd27 100644
--- a/macros/latex-dev/base/ltmarks.dtx
+++ b/macros/latex-dev/base/ltmarks.dtx
@@ -1,7 +1,8 @@
% \iffalse meta-comment
%
-%% File: ltmarks.dtx (C) Copyright 2022
-% Frank Mittelbach, LaTeX Team
+%% File: ltmarks.dtx
+%% Copyright (C) 2022-2023
+%% Frank Mittelbach, The LaTeX Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
diff --git a/macros/latex-dev/base/ltmath.dtx b/macros/latex-dev/base/ltmath.dtx
index 746a3077fb..3b1518dd2e 100644
--- a/macros/latex-dev/base/ltmath.dtx
+++ b/macros/latex-dev/base/ltmath.dtx
@@ -38,7 +38,7 @@
%<*driver>
% \fi
\ProvidesFile{ltmath.dtx}
- [2022/09/07 v1.2m LaTeX Kernel (Math Setup)]
+ [2023/05/13 v1.2n LaTeX Kernel (Math Setup)]
% \iffalse
%</driver>
%
@@ -1132,9 +1132,29 @@
\fi
% \end{macrocode}
%
+% \begin{macro}{\eqno}
+% \begin{macro}{\leqno}
+% \changes{v1.2n}{2023/05/13}{add \cs{ignorespaces} gh/1059}
+% Ensure the (deprecated) \verb|$$..\eqno 1 $$| ignores spaces.
% \begin{macrocode}
%</2ekernel>
+%<*2ekernel|latexrelease>
+%<latexrelease>\IncludeInRelease{2023/06/01}%
+%<latexrelease> {\eqno}{add ignorespaces to eqno}%
+\let\@kernel@eqno\eqno
+\let\@kernel@leqno\leqno
+\protected\def\eqno{\@kernel@eqno\aftergroup\ignorespaces}
+\protected\def\leqno{\@kernel@leqno\aftergroup\ignorespaces}
+%</2ekernel|latexrelease>
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{0000/00/00}%
+%<latexrelease> {\eqno}{add ignorespaces to eqno}%
+%<latexrelease>\let\eqno\@kernel@eqno
+%<latexrelease>\let\leqno\@kernel@leqno
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
+% \end{macro}
+% \end{macro}
%
%
%
@@ -1322,6 +1342,5 @@
% \end{environment}
%
%
-%
% \Finale
%
diff --git a/macros/latex-dev/base/ltmeta.dtx b/macros/latex-dev/base/ltmeta.dtx
index 31c5d8dbee..daaa71626b 100644
--- a/macros/latex-dev/base/ltmeta.dtx
+++ b/macros/latex-dev/base/ltmeta.dtx
@@ -1,7 +1,8 @@
% \iffalse meta-comment
%
-%% File: ltmeta.dtx (C) Copyright 2021, 2022
-% Frank Mittelbach, LaTeX Team
+%% File: ltmeta.dtx
+%% Copyright (C) 2021-2023
+%% Frank Mittelbach, The LaTeX Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
diff --git a/macros/latex-dev/base/ltnews.cls b/macros/latex-dev/base/ltnews.cls
index f55165d436..a57d9fc673 100644
--- a/macros/latex-dev/base/ltnews.cls
+++ b/macros/latex-dev/base/ltnews.cls
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 1993-2020
+% Copyright (C) 1993-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
diff --git a/macros/latex-dev/base/ltnews.pdf b/macros/latex-dev/base/ltnews.pdf
index bc1b2d7b36..20e9915fb0 100644
--- a/macros/latex-dev/base/ltnews.pdf
+++ b/macros/latex-dev/base/ltnews.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews01.pdf b/macros/latex-dev/base/ltnews01.pdf
index 618176aa56..a7f0341632 100644
--- a/macros/latex-dev/base/ltnews01.pdf
+++ b/macros/latex-dev/base/ltnews01.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews02.pdf b/macros/latex-dev/base/ltnews02.pdf
index 423dd7db37..35984fad28 100644
--- a/macros/latex-dev/base/ltnews02.pdf
+++ b/macros/latex-dev/base/ltnews02.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews03.pdf b/macros/latex-dev/base/ltnews03.pdf
index a43f3c2ffc..447d1674df 100644
--- a/macros/latex-dev/base/ltnews03.pdf
+++ b/macros/latex-dev/base/ltnews03.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews04.pdf b/macros/latex-dev/base/ltnews04.pdf
index 95683443c7..cc15094d78 100644
--- a/macros/latex-dev/base/ltnews04.pdf
+++ b/macros/latex-dev/base/ltnews04.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews05.pdf b/macros/latex-dev/base/ltnews05.pdf
index 91ba9c3669..0e70b1e807 100644
--- a/macros/latex-dev/base/ltnews05.pdf
+++ b/macros/latex-dev/base/ltnews05.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews06.pdf b/macros/latex-dev/base/ltnews06.pdf
index 57c9abe6a9..59abf02bd7 100644
--- a/macros/latex-dev/base/ltnews06.pdf
+++ b/macros/latex-dev/base/ltnews06.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews07.pdf b/macros/latex-dev/base/ltnews07.pdf
index a587a13ac7..82a2540ab1 100644
--- a/macros/latex-dev/base/ltnews07.pdf
+++ b/macros/latex-dev/base/ltnews07.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews08.pdf b/macros/latex-dev/base/ltnews08.pdf
index c57077ac14..f32fb2cad0 100644
--- a/macros/latex-dev/base/ltnews08.pdf
+++ b/macros/latex-dev/base/ltnews08.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews09.pdf b/macros/latex-dev/base/ltnews09.pdf
index 7dff0aaeb5..4ca9012f17 100644
--- a/macros/latex-dev/base/ltnews09.pdf
+++ b/macros/latex-dev/base/ltnews09.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews10.pdf b/macros/latex-dev/base/ltnews10.pdf
index 9911e7cc2e..5fca7346e9 100644
--- a/macros/latex-dev/base/ltnews10.pdf
+++ b/macros/latex-dev/base/ltnews10.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews11.pdf b/macros/latex-dev/base/ltnews11.pdf
index 9d35abb5ea..6627ca370a 100644
--- a/macros/latex-dev/base/ltnews11.pdf
+++ b/macros/latex-dev/base/ltnews11.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews12.pdf b/macros/latex-dev/base/ltnews12.pdf
index 71aa27bcfc..8bd9137660 100644
--- a/macros/latex-dev/base/ltnews12.pdf
+++ b/macros/latex-dev/base/ltnews12.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews13.pdf b/macros/latex-dev/base/ltnews13.pdf
index 1940689968..dd8b6c663e 100644
--- a/macros/latex-dev/base/ltnews13.pdf
+++ b/macros/latex-dev/base/ltnews13.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews14.pdf b/macros/latex-dev/base/ltnews14.pdf
index 66821fc4d0..83c326971d 100644
--- a/macros/latex-dev/base/ltnews14.pdf
+++ b/macros/latex-dev/base/ltnews14.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews15.pdf b/macros/latex-dev/base/ltnews15.pdf
index 0dfe862498..5f4eae06f9 100644
--- a/macros/latex-dev/base/ltnews15.pdf
+++ b/macros/latex-dev/base/ltnews15.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews16.pdf b/macros/latex-dev/base/ltnews16.pdf
index 0c8934029d..5e7ee0cd0b 100644
--- a/macros/latex-dev/base/ltnews16.pdf
+++ b/macros/latex-dev/base/ltnews16.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews17.pdf b/macros/latex-dev/base/ltnews17.pdf
index 2d5500ff62..637d049e40 100644
--- a/macros/latex-dev/base/ltnews17.pdf
+++ b/macros/latex-dev/base/ltnews17.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews18.pdf b/macros/latex-dev/base/ltnews18.pdf
index b88c8a5401..badbfac892 100644
--- a/macros/latex-dev/base/ltnews18.pdf
+++ b/macros/latex-dev/base/ltnews18.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews19.pdf b/macros/latex-dev/base/ltnews19.pdf
index b6a132732e..5f857220a2 100644
--- a/macros/latex-dev/base/ltnews19.pdf
+++ b/macros/latex-dev/base/ltnews19.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews20.pdf b/macros/latex-dev/base/ltnews20.pdf
index 3c79e0d9be..2cd03fc389 100644
--- a/macros/latex-dev/base/ltnews20.pdf
+++ b/macros/latex-dev/base/ltnews20.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews20.tex b/macros/latex-dev/base/ltnews20.tex
index aeab3fae60..b233f92dc4 100644
--- a/macros/latex-dev/base/ltnews20.tex
+++ b/macros/latex-dev/base/ltnews20.tex
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 1993--2019
+% Copyright (C) 1993-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
diff --git a/macros/latex-dev/base/ltnews21.pdf b/macros/latex-dev/base/ltnews21.pdf
index c6528cfbea..fbf13d47b8 100644
--- a/macros/latex-dev/base/ltnews21.pdf
+++ b/macros/latex-dev/base/ltnews21.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews21.tex b/macros/latex-dev/base/ltnews21.tex
index 7b363447d9..a48cd0b199 100644
--- a/macros/latex-dev/base/ltnews21.tex
+++ b/macros/latex-dev/base/ltnews21.tex
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 2019
+% Copyright (C) 2019-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
diff --git a/macros/latex-dev/base/ltnews22.pdf b/macros/latex-dev/base/ltnews22.pdf
index 625a3af16e..f107f51d4d 100644
--- a/macros/latex-dev/base/ltnews22.pdf
+++ b/macros/latex-dev/base/ltnews22.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews23.pdf b/macros/latex-dev/base/ltnews23.pdf
index 2d591ff424..0b1a540118 100644
--- a/macros/latex-dev/base/ltnews23.pdf
+++ b/macros/latex-dev/base/ltnews23.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews24.pdf b/macros/latex-dev/base/ltnews24.pdf
index bea89f1051..e7ee535ed4 100644
--- a/macros/latex-dev/base/ltnews24.pdf
+++ b/macros/latex-dev/base/ltnews24.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews25.pdf b/macros/latex-dev/base/ltnews25.pdf
index aa027c430c..735abd907e 100644
--- a/macros/latex-dev/base/ltnews25.pdf
+++ b/macros/latex-dev/base/ltnews25.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews26.pdf b/macros/latex-dev/base/ltnews26.pdf
index fe7d100e0d..d62efe0af4 100644
--- a/macros/latex-dev/base/ltnews26.pdf
+++ b/macros/latex-dev/base/ltnews26.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews27.pdf b/macros/latex-dev/base/ltnews27.pdf
index 29da354bf3..487ee60ee4 100644
--- a/macros/latex-dev/base/ltnews27.pdf
+++ b/macros/latex-dev/base/ltnews27.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews28.pdf b/macros/latex-dev/base/ltnews28.pdf
index ee61704ae6..23876fc9d9 100644
--- a/macros/latex-dev/base/ltnews28.pdf
+++ b/macros/latex-dev/base/ltnews28.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews29.pdf b/macros/latex-dev/base/ltnews29.pdf
index 807dc2f7c2..19b4de4a57 100644
--- a/macros/latex-dev/base/ltnews29.pdf
+++ b/macros/latex-dev/base/ltnews29.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews30.pdf b/macros/latex-dev/base/ltnews30.pdf
index 0e1203352a..b8f3672842 100644
--- a/macros/latex-dev/base/ltnews30.pdf
+++ b/macros/latex-dev/base/ltnews30.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews30.tex b/macros/latex-dev/base/ltnews30.tex
index 74d7659512..8183f7eabb 100644
--- a/macros/latex-dev/base/ltnews30.tex
+++ b/macros/latex-dev/base/ltnews30.tex
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 2019
+% Copyright (C) 2019-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
diff --git a/macros/latex-dev/base/ltnews31.pdf b/macros/latex-dev/base/ltnews31.pdf
index 878583bfb2..d46eff87c9 100644
--- a/macros/latex-dev/base/ltnews31.pdf
+++ b/macros/latex-dev/base/ltnews31.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews31.tex b/macros/latex-dev/base/ltnews31.tex
index 1dff72986c..44bf494142 100644
--- a/macros/latex-dev/base/ltnews31.tex
+++ b/macros/latex-dev/base/ltnews31.tex
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 2019-2020
+% Copyright (C) 2019-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
diff --git a/macros/latex-dev/base/ltnews32.pdf b/macros/latex-dev/base/ltnews32.pdf
index 35069ceab5..76a4a10cbe 100644
--- a/macros/latex-dev/base/ltnews32.pdf
+++ b/macros/latex-dev/base/ltnews32.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews32.tex b/macros/latex-dev/base/ltnews32.tex
index 28f3bf88b4..c64cd97958 100644
--- a/macros/latex-dev/base/ltnews32.tex
+++ b/macros/latex-dev/base/ltnews32.tex
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 2019-2020
+% Copyright (C) 2019-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
diff --git a/macros/latex-dev/base/ltnews33.pdf b/macros/latex-dev/base/ltnews33.pdf
index e42df53c30..f255b9d1ef 100644
--- a/macros/latex-dev/base/ltnews33.pdf
+++ b/macros/latex-dev/base/ltnews33.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews33.tex b/macros/latex-dev/base/ltnews33.tex
index 39af4f1b72..0b98a707ba 100644
--- a/macros/latex-dev/base/ltnews33.tex
+++ b/macros/latex-dev/base/ltnews33.tex
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 2019-2021
+% Copyright (C) 2019-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
diff --git a/macros/latex-dev/base/ltnews34.pdf b/macros/latex-dev/base/ltnews34.pdf
index 0707a1e9a2..5523ac2cd6 100644
--- a/macros/latex-dev/base/ltnews34.pdf
+++ b/macros/latex-dev/base/ltnews34.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews34.tex b/macros/latex-dev/base/ltnews34.tex
index 517856834a..d3a9202b56 100644
--- a/macros/latex-dev/base/ltnews34.tex
+++ b/macros/latex-dev/base/ltnews34.tex
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 2019-2021
+% Copyright (C) 2019-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
diff --git a/macros/latex-dev/base/ltnews35.pdf b/macros/latex-dev/base/ltnews35.pdf
index bef895d098..a68acbd83f 100644
--- a/macros/latex-dev/base/ltnews35.pdf
+++ b/macros/latex-dev/base/ltnews35.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews35.tex b/macros/latex-dev/base/ltnews35.tex
index 0230ef6e58..8d49bf1984 100644
--- a/macros/latex-dev/base/ltnews35.tex
+++ b/macros/latex-dev/base/ltnews35.tex
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 2021-2022
+% Copyright (C) 2021-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
@@ -322,7 +322,6 @@ has been refined, such that
\ProcessKeyOptions
\end{verbatim}
will now automatically pick up the package name as the key \emph{family},
-%unless explicitly given as an optional argument.
unless explicitly given as an optional argument:
\begin{verbatim}
\ProcessKeyOptions[family]
@@ -378,9 +377,7 @@ syntax are described in \file{usrguide3.pdf}. The command \cs{fpeval}
offers a rich syntax allowing 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.
peculiarities and limitations in expressiveness.
-% \newcommand\calulateheight[1]{%
\begin{verbatim}
\newcommand\calculateheight[1]{%
\setlength\textheight{\dimeval{\topskip
@@ -698,7 +695,7 @@ Source files containing \textlangle\ or \textrangle\ directly written
as Unicode codepoints U+2329 and U+232A no longer break when the
source file gets normalized under Unicode normalization rules.
%
-\githubissue{gh/714}
+\githubissue{714}
@@ -907,7 +904,6 @@ For details and further examples, see \file{mathcolor.pdf}.
\subsection{Fix locating files with \cs{graphicspath}}
-%
If a call to \cs{includegraphics} asked for a file (say, \file{image})
without extension, and if both \file{A/image.pdf} and \file{B/image.tex}
@@ -953,22 +949,10 @@ internal syntax errors due to premature expansion.
\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}
diff --git a/macros/latex-dev/base/ltnews36.pdf b/macros/latex-dev/base/ltnews36.pdf
index acd22fa631..13802736fd 100644
--- a/macros/latex-dev/base/ltnews36.pdf
+++ b/macros/latex-dev/base/ltnews36.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews36.tex b/macros/latex-dev/base/ltnews36.tex
index b3f66564cb..5dee958747 100644
--- a/macros/latex-dev/base/ltnews36.tex
+++ b/macros/latex-dev/base/ltnews36.tex
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 2021-2022
+% Copyright (C) 2021-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
diff --git a/macros/latex-dev/base/ltnews37.pdf b/macros/latex-dev/base/ltnews37.pdf
index 3b13c3e619..781a244469 100644
--- a/macros/latex-dev/base/ltnews37.pdf
+++ b/macros/latex-dev/base/ltnews37.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltnews37.tex b/macros/latex-dev/base/ltnews37.tex
index a1197e1052..5b2a55dda3 100644
--- a/macros/latex-dev/base/ltnews37.tex
+++ b/macros/latex-dev/base/ltnews37.tex
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 2021-2023
+% Copyright (C) 2021-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
@@ -124,7 +124,8 @@
% \publicationday{01} % change this if it's not released on 1st of a month
\publicationmonth{June}
-\publicationyear{2023 --- DRAFT version for upcoming release}
+%\publicationyear{2023 --- DRAFT version for upcoming release}
+\publicationyear{2023}
\publicationissue{37}
@@ -142,7 +143,8 @@
\medskip
-\section{Introduction}
+%\section{Introduction}
+
\section{New functionality offered as part of the
@@ -150,7 +152,8 @@
We have now enabled new automatic tagging functionality for additional
\LaTeX{} elements, among them most display environments, standard
-sectioning commands and content, figure and table listings. This can
+sectioning commands, content, figure and table listings, floats and graphics and
+bibliographies. This can
be activated through
\begin{verbatim}
\DocumentMetadata{testphase=phase-III}
@@ -168,9 +171,9 @@ alter internals of \LaTeX{}.
Also note that there are still several environments and commands
described in the \LaTeX{} manual that do not have tagging support yet,
-notably tabulars, floats, \texttt{tabbing} and the various math
-environment. They will get this support as part of \texttt{phase-III}
-between now and the June release.
+notably tabulars, \texttt{tabbing}, the various math environment and a
+few others. They will get this support as part of \texttt{phase-III},
+but some of them will be delayed until after the June release.
A prototype for math tagging (including support for the \pkg{amsmath}
environments) is already available, but it is mainly intended for
@@ -194,60 +197,84 @@ be accessed with \verb|texdoc -l latex-lab|.
Feedback is welcome!
Please use \url{https://github.com/latex3/latex2e/discussions/1010}.
-\section{Documentation improvements}
-
-
-\subsection{Displaying the exact release dates for \LaTeX{}}
-
-In some situations it is necessary to find out the exact release dates
-for older version of the \LaTeX{} format, for example, when you need
-to use different code in a package depending on the availablilty of a
-certain feature and you therefore want to use
-\cs{IfFormatAtLeastTF}\texttt\{\meta{date}\texttt\} or the
-rather horrible construction \verb/\@ifl@t@r\fmtversion{/\meta{date}\texttt\},
-if you
-want to cater for formats that are older than 2020.
-
-Or you know that your package is definitely not going to work with a
-format before a certain \meta{date}, in which case you could use
-\verb/\NeedsTeXFormat{LaTeX2e}[/\meta{date}\texttt] to ensure that any
- user is alerted if their format is too old.
-
-The big problem is to know the exact \meta{date} to put into such
-commands and in the past that was not that easy to find. You could have
-looked in the the file \file{changes.txt}, but that is hidden somewhere
-in your installation and if you try
-\verb*/texdoc -l changes.txt/ you get more than thirty results and the
-right file is by no means the first.
-
-Yukai Chou (\textsf{@muzimuzhi}) kindly provided a patch for this, so that we now have
-the exact dates for each \LaTeX{} format listed in an easy to remember
-place: in \file{ltnews.pdf} and that file conveniently also contains all major
-features and changes to \LaTeX{} over the years\Dash one of which is
-most likely the reason you need the \meta{date} date in the first
-place.
-
-It is given in parentheses in the newsletter title, thus this
-newsletter tells you that on
-%
-\makeatletter
-\mbox{\expandafter\@gobblenonyear\@year\@nil
- -\@julianmonthtonum\@month-\two@digits\@day}
-\makeatother
-%
-the command
-\cs{NewEnvironmentCopy}, a new \texttt{shipout} hook, etc.\ was made
-available. And looking into \file{ltnews.pdf} you can now easily find
-out that the \LaTeX3 programming layer was added on 2020-02-02
-(because the date was so nice) and not on the first of the month.
-%
-\githubissue{982}
-
\section{New or improved commands}
+\subsection{Extending hooks to take arguments}
+
+Hooks have always been containers for code whose outcome was entirely
+dependent on the contents of the hook alone. If any type of contextual
+information had to be passed to the hook, it had to be done by setting
+some variable before the hook so that the code in the hook could use
+that. But this is somewhat hard to keep track of, clumsy to implement,
+and it required the programmer to have some kind of \enquote{hook before
+the hook} to do that setup.
+
+To make things a bit easier, \pkg{lthooks} was enhanced to support hooks
+with arguments. Hooks can now be declared and used with arguments, then
+the code added to these hooks can reference the hook's arguments using
+\verb|#1|, \verb|#2|, etc., so now hooks can behave more like macros
+than like \emph{token lists} (using \pkg{expl3} terminology). Regular
+argument-less hooks continue to work exactly like they did before: this
+extension is completely compatible with older documents and packages.
+
+\AddToHook{cmd/verbatim@font/after}[hack]{\small}
+To declare a hook with arguments, use
+\begin{verbatim}
+\NewHookWithArguments {<hook>} {<num args>}
+\end{verbatim}
+then, similarly, to use the code in the hook (supposing a hook declared
+with 2 arguments), write
+\begin{verbatim}
+\UseHookWithArguments {<hook>} {2} {<arg 1>} {<arg 2>}
+\end{verbatim}
+
+Or, if you want to add some code to a hook that takes arguments, write
+\begin{verbatim}
+\AddToHookWithArguments {<hook>} [<label>] {<code>}
+\end{verbatim}
+exactly like you would for regular hooks, except that the \meta{code}
+can use the arguments by referencing \verb|#1|, \verb|#2|, etc. In this
+case, if you want to add an actual parameter token (\verb|#|) to the
+\meta{code}, you have to double it, as usual.
+\RemoveFromHook{cmd/verbatim@font/after}[hack]
+
+Additionally, if you want to add \enquote{regular} code to a hook with
+arguments, you can still use \cs{AddToHook} --- in that case \verb|#|
+tokens are \emph{not} doubled. This means that a package author can
+decide to add arguments to an existing hook without worrying about
+compatibility: \cs{AddToHook} will do the right thing and will not
+mistakenly reference the newly added arguments.
+
+The commands \cs{NewReversedHookWithArguments}, \cs
+{NewMirroredHookPairWithArguments}, \cs
+{AddToHookNextWithArguments}, \cs{UseOneTimeHookWithArguments}, and
+the \pkg{expl3} conterparts of the commands discussed in this section
+were also added. The complete documentation can be found in the
+\pkg{lthooks} documentation \cite{37:lthooks-doc}.
+
+\subsubsection{Generic \texttt{cmd} hooks with arguments}
+
+Along with the possibility to pass arguments to a regular hook as
+discussed above, generic \hook{cmd} hooks now can access the arguments
+of the command they are patched into using the interface described in
+the previous section.
+
+For example, if you were to add some code to the \cs{title} command
+using hooks, you could access the actual title given in the argument.
+For example, to write the title of the document in the terminal you
+could use:
+\begin{verbatim}
+ \AddToHookWithArguments{cmd/title/before}
+ {\typeout{Document title: #1}}
+\end{verbatim}
+As with regular hooks, code added to a \hook{cmd} hook using
+\cs{AddToHook} will not be able to access the command's arguments. This
+means that, as with regular hooks, this change is completely backwards
+compatible, so previous usages of \hook{cmd} hooks will work exactly as
+they did before.
\subsection{Providing copy and show functions for environments}
@@ -279,31 +306,124 @@ following output:
%
\githubissue{963}
+\subsection{\cs{IfFileAtLeastTF}}
+The 2020-10-01 \LaTeX{} release introduced the CamelCase tests
+\cs{IfClassAtLeastTF} and \cs{IfPackageAtLeastTF} for checking class
+and package dates. We have now added \cs{IfFileAtLeastTF} to allow the
+same to happen for generic files which contain a \cs{ProvidesFile}
+line.
+%
+\githubissue{1015}
+
+\subsection{\cs{DeclareLowercaseMapping}, \cs{DeclareTitlecaseMapping}
+ and \cs{DeclareUppercaseMapping}}
+
+The move from a case-changing approach using \cs{lccode} and \cs{uccode} data
+to one where information is stored by a kernel-managed structure left a gap in
+the ability of the user to \emph{tune} the case changing outcomes. This has now
+been addressed by the addition of three commands
+\begin{itemize}
+ \item \cs{DeclareLowercaseMapping}
+ \item \cs{DeclareTitlecaseMapping}
+ \item \cs{DeclareUppercaseMapping}
+\end{itemize}
+which can be used to customise the outcome for codepoints. This can be applied
+generally or to a specific locale (see also the next section). A small number
+of pre-defined customisations have been set up in the kernel where the outcomes
+for \pdfTeX{} should be different for those from Unicode engines. For
+example
+\begin{verbatim}
+ \DeclareUppercaseMapping{"01F0}{\v{J}}
+\end{verbatim}
+allows \v{J} to be produced in 8-bit engines: without this customisation,
+an error would occur as there is no pre-composed \v{J} in Unicode. More detail
+is given in \texttt{usrguide}.
+%
+\githubissue{1033}
+
+\subsection{\cs{BCPdata}}
+
+Improvements in the Unicode handling for case changing have highlighted that
+the kernel has not to-date been locale-aware. The packages \pkg{babel} and
+\pkg{polyglossia} provide comprehensive locale support, but did not have
+an agreed unified interface to pass that information back to other code.
+Following discussion with the maintainers of those two bundles, the kernel
+now defines \cs{BCPdata} as a stub (so it is always defined), and \pkg{babel}
+and \pkg{polyglossia} will redefine it to provide the locale data. An agreed
+set of keywords mean that \cs{BCPdata} can be queried in a structured way
+by both the kernel and any other \enquote{consumer} packages.
+%
+\githubissue{1035}
+
+\subsection{Improve \cs{samepage}}
+
+The \cs{samepage} declaration sets various parameters to
+\texttt{10000} to prevent undesired page breaks. The
+\cs{predisplaypenalty} parameter has already by default a value of
+\texttt{10000} and to save space back in the days it was therefore not
+explicitly set. However, there are a few classes that change the
+parameter and as result the user might experience a page break in
+front of a display formula within the scope of \cs{samepage} when
+using such classes. This has now been corrected and
+\cs{predisplaypenalty} is also explicitly set to \texttt{10000}.
+%
+\githubissue{1022}
+\subsection{Groups in \cs{MakeUppercase}}
+%
+Prior to 2022, \cs{MakeUppercase} and \cs{MakeLowercase} used a brace
+group around their argument so providing a scope for any declarations
+within the argument. This grouping has been restored (also
+for \cs{MakeTitlecase}), although the underlying L3 text case commands do
+not use grouping.
+%
+\githubissue{1021}
+
+\subsection{Extension of the \cs{label} command}
+
+Previously, in standard \LaTeX{}, the \cs{label} command wrote a \cs{newlabel} declaration into
+the \texttt{.aux} file and stored two values in
+second argument of this \cs{newlabel} command:
+\cs{@currentlabel}, which normally contains the state of the current
+counter and \cs{thepage} for the current page number.
+
+The packages \pkg{hyperref} and
+\pkg{nameref} then patched the \cs{label} command to store five values instead.
+In addition to the above they saved \cs{@currentlabelname}, which normally contains the
+current title text and can be retrieved with \cs{nameref}, and
+\cs{@currentHref}, which is the name of the destination needed to create an
+active link. The fifth argument was only used if external
+references were loaded with the \pkg{xr-hyper} package.
+
+Starting with this release, the number of values stored in \cs{newlabel} have been unified.
+\cs{label} now writes a
+\cs{newlabel} command that always contains five values in the second argument (each in a brace group):
+\cs{@currentlabel}, \cs{thepage}, \cs{@currentlabelname},
+\cs{@currentHref}, and \cs{@kernel@reserved@label@data} (which is reserved for the kernel).
+
+Additionally, a hook with the name \texttt{label} has been
+added. It takes one argument: the label string.
+Code added to the hook can refer to this argument with \verb+#1+.
+The hook is executed directly before the \cs{label} command writes to the \texttt{.aux} file
+but \emph{after} the \cs{@bsphack} command has done its spacing magic and it is located \emph{inside} a group, thus its code only affects the write operation.
\section{Code improvements}
-\subsection{\pkg{doc}: Index \texttt{\textbackslash\textvisiblespace} correctly}
-
-\emph{to write}
-%
-\githubissue{943}
+\subsection{Performance in checking file existence}
+The addition of hooks, etc., to file operations had a side-effect in that
+multiple checks were made that the file existed. In larger documents using
+lots of files, these file system operations caused non-trivial performance
+impact. We now cache the existence of files, such that these repeated filesystem
+calls are avoided.
-\subsection{Default definition for \cs{do}}
+\subsection{\pkg{doc}: Handle \texttt{\textbackslash\textvisiblespace} correctly in the index}
-The command \cs{do} with its nice public name is in reality an
-internal command inherited from plain \TeX{} for list
-processing. However, it only got a definition when
-\verb=\begin{document}= was executed, with a result that a user
-definition in the preamble was unconditionally overwritten at this
-point. To properly alert the user that this command is not freely
-available we now already provide a definition in the format so that
-\cs{newcommand} and friends produce a proper error message instead of
-providing a definition that doesn't last.
+Due to some problems in the code it wasn't possible to prevent
+\verb*=\ = from showing up in the index\Dash \verb=\DoNotIndex{\ }=, etc.\ had no effect. This has now been corrected.
%
-\githubissue{975}
+\githubissue{943}
\subsection{\pkg{doc}: Support the \pkg{upquote} package}
@@ -341,6 +461,23 @@ desired effect.
\githubissue{953}
+\subsection{Default definition for \cs{do}}
+
+The command \cs{do} with its nice public name is in reality an
+internal command inherited from plain \TeX{} for list
+processing. However, it only got a definition when
+\verb=\begin{document}= was executed, with a result that a user
+definition in the preamble was unconditionally overwritten at this
+point. To properly alert the user that this command is not freely
+available we now already provide a definition in the format so that
+\cs{newcommand} and friends produce a proper error message instead of
+providing a definition that doesn't last.
+%
+\githubissue{975}
+
+
+
+
\subsection{New key for \env{filecontents}}
The \env{filecontents} environment warns on the terminal if a file
@@ -350,14 +487,13 @@ the warning less noisy in this case we added a new \texttt{nowarn} key
that redirects the overwriting warning to the transcript file. We
think that some record of the action is still required to help with
debugging, thus it is not completely silenced. The warning that
-nothing gets written, because the file aready exists (and the
+nothing gets written, because the file already exists (and the
\texttt{force} key was not used), is not altered and still shows up on
the terminal.
%
\githubissue{958}
-
\subsection{A further hook for shipping out pages}
Since October 2020 the shipout process offers a number of hooks to
@@ -429,10 +565,21 @@ group (i.e., any local changes would immediately be revoked, breaking,
for example, \pkg{wrapfig} in that special situation).
%
This got fixed with the 2022-11 PL1 hotfix, so was already corrected in
-the previous release, but only now documented in a newletter.
+the previous release, but only now documented in the newsletter.
%
\githubissue{967}
+\subsection{Ensure that \cs{cs} is defined in \cls{ltxdoc}}
+
+The class \cls{ltxdoc} defined the command \cs{cs} to typeset a
+command name with a backslash in front. This definition was moved to
+the \pkg{doc} package itself. This meant that it was suddenly missing
+when reverting to the old \pkg{doc} package implementation via the
+class option \texttt{doc2}. This has now been corrected.
+%
+\githubissue{981}
+
+
\subsection{Improve spacing at top of \env{minipages}}
@@ -453,15 +600,180 @@ correct.
\githubissue{989}
+\subsection{A fix for \cs{NewCommandCopy} and \cs{ShowCommand}}
+
+When copying and showing definitions of (non-expandable) document commands
+(aka commands defined by \cs{NewDocumentCommand} and friends) containing empty
+or only \texttt{m}-type arguments, these commands were wrongly recognized as
+expandable ones.
+This is fixed in the present \LaTeX{} release.
+%
+\githubissue{1009}
+
+\subsection{Corrections for switching math version}
+Some internal code improvements improve support for switching math version
+when nested within an outer math expression.
+This will improve \cs{boldsymbol} and \cs{bm} and similar commands.
+%
+\githubissue{1028}
+
+\subsection{Allow par as a filename}
+\verb|\input{par}| or \verb|\includegraphics{par}| could give spurious
+errors. This has been fixed by making an internal command \cs{long}.
+%
+\githubissue{942}
+
+\subsection{Correct setting of \cs{endlinechar} in \texttt{+v} arguments}
+In the particular case of a document command with a \texttt{+v}-type
+argument used inside \cs{ExplSyntaxOn}\texttt{/Off}, newlines would be
+misinterpreted as spaces because the value of \cs{endlinechar} was
+set too late. This has been fixed, and now newlines are correctly
+translated to ``\verb|the character ^^M|''.
+%
+\githubissue{876}
+
+\subsection{Correct handling of hooks with only `next' code}
+When \cs{AddToHookNext} was used on a not-yet-declared hook, that hook
+would be incorrectly identified as empty by \cs{ShowHook}. Also, if
+that hook was later declared, that `next' code would not be executed.
+This has been fixed by correctly initializing the hook structure when
+\cs{AddToHookNext} is used.
+%
+\githubissue{1052}
+
+\subsection{Ignoring space after \texttt{\$\$}}
+Space is normally ignored after a closing \texttt{\$\$},
+but internal \LaTeX{} font handling code could interfere if
+\cs{eqno} was used. \cs{eqno} and \cs{leqno} have been redefined
+to add \cs{ignorespaces} after the math group.
+%
+\githubissue{1059}
+
+\section{Documentation improvements}
+
+\subsection{Updates to the guides}
+
+When \LaTeXe{} was released, the team provided documentation for both document
+authors and package/class developers in the two files \texttt{usrguide} and
+\texttt{clsguide}. Over time, the team have augmented these documents as new
+methods have been added to the kernel. However, they retained there structure
+as starting from familiarity with \LaTeX{}~2.09. This meant that for new users,
+there was material which is no longer relevant, and less clarity than desirable
+in what approaches are recommended today.
+
+The two files have now been (partially) re-written, with the versions available
+previously now frozen as \texttt{usrguide-historic} and \texttt{clsguide-historic}.
+More material has been carried forward in the class/package guide than in the
+user guide, but both are worth a re-read by experienced \LaTeX{} users.
+
+
+
+\subsection{Displaying the exact release dates for \LaTeX{}}
-\section{Changes to packages in the \pkg{amsmath} category}
+In some situations it is necessary to find out the exact release dates
+for older version of the \LaTeX{} format, for example, when you need
+to use different code in a package depending on the availability of a
+certain feature and you therefore want to use
+\cs{IfFormatAtLeastTF}\texttt\{\meta{date}\texttt\} or the
+rather horrible construction \verb/\@ifl@t@r\fmtversion{/\meta{date}\texttt\},
+if you
+want to cater for formats that are older than 2020.
-\section{Changes to packages in the \pkg{graphics} category}
+Or you know that your package is definitely not going to work with a
+format before a certain \meta{date}, in which case you could use
+\verb/\NeedsTeXFormat{LaTeX2e}[/\meta{date}\texttt] to ensure that any
+ user is alerted if their format is too old.
+
+The big problem is to know the exact \meta{date} to put into such
+commands and in the past that was not that easy to find. You could have
+looked in the the file \file{changes.txt}, but that is hidden somewhere
+in your installation and if you try
+\verb*/texdoc -l changes.txt/ you get more than thirty results and the %*
+right file is by no means the first.
+
+Yukai Chou (\textsf{@muzimuzhi}) kindly provided a patch for this, so that we now have
+the exact dates for each \LaTeX{} format listed in an easy to remember
+place: in \file{ltnews.pdf} and that file conveniently also contains all major
+features and changes to \LaTeX{} over the years\Dash one of which is
+most likely the reason you need the \meta{date} date in the first
+place.
+
+It is given in parentheses in the newsletter title, thus this
+newsletter tells you that on
+%
+\makeatletter
+\mbox{\expandafter\@gobblenonyear\@year\@nil
+ -\@julianmonthtonum\@month-\two@digits\@day}
+\makeatother
+%
+the command
+\cs{NewEnvironmentCopy}, a new \texttt{shipout} hook, etc.\ was made
+available. And looking into \file{ltnews.pdf} you can now easily find
+out that the \LaTeX3 programming layer was added on 2020-02-02
+(because the date was so nice) and not on the first of the month.
+%
+\githubissue{982}
+
+\subsection{Fresh from the press: \enquote{The \LaTeX{} Companion, third edition} is now in print}
+
+The third edition of \emph{The \LaTeX{} Companion} is now
+available. This is the end of five years of careful work and we hope
+that it will provide our readers with all the information they need to
+successfully navigate the \LaTeX{} ecosystem and efficiently produce
+beautiful documents.
+
+Since the publication of the last edition (2004) a lot has happened in
+the \LaTeX{} world and thus a complete rewrite was necessary. All
+chapters have been thoroughly revised and in many cases largely
+extended to describe new important functionality and features. More
+than 5,000 add-on packages have been analyzed in detail, out of which
+roughly 10\% have been chosen for inclusion in \emph{The \LaTeX{}
+Companion}. All important aspects of these packages are described to
+provide the user once again with a satisfying one-stop–shop experience
+for the decade to come.
+
+To cover what we thought worth describing today, the book nearly
+doubled in size. The print edition is therefore produced as a
+two-volume set and sold as a bundle. Both volumes come as hard-cover
+with ribbons to easily mark pages in the book.
+
+To give you an idea of what is covered in the third edition you can
+find some excerpts at
+\begin{quote}
+\url{https://www.latex-project.org/news/2023/03/17/TLC3}
+\end{quote}
+
+The edition is also available as an eBook (Parts I and II combined)
+consisting of PDF and ePub format without DRM. Finally, the publisher
+offers the combination of the printed books and the digital versions at
+a very attractive price not available anywhere else.
+
+
+%\section{Changes to packages in the \pkg{amsmath} category}
+
+%\section{Changes to packages in the \pkg{graphics} category}
\section{Changes to packages in the \pkg{tools} category}
-\subsection{Fix handling of nested \env{multicols}}
+\subsection{\pkg{multicol}: Better support for CJK languages}
+
+The default minimum depth of each column in a \env{multicols}
+corresponds to the depth of a \enquote{p} in the current font. This
+helps to get some uniformity if rules are used between the columns and
+makes sense for Latin-based languages. Until now it was hard-wired,
+but for CJK (Chinese/Japanese/Korean) languages it is better to use a zero depth, because there
+all characters have the same height and depth. And even with
+Latin-based languages one might want to use the depth of a \cs{strut}
+or that of a parenthesis. So we now offer a way to adjust this while
+maintaining backward compatibility. Just redefine
+\cs{multicolmindepthstring} to hold whatever you want to get measured
+for its depth (the width is not relevant).
+%
+\githubissue{698}
+
+
+\subsection{\pkg{multicol}: Fix handling of nested environments}
If \env{multicols} environments have been nested into each other (the
inner one boxed) it could fail if the boxed environment appeared near a
@@ -484,6 +796,10 @@ page. This has now been fixed.
\emph{The \texttt{\upshape ltshipout} documentation}.\\
Run \texttt{texdoc} \texttt{ltshipout-doc} to view.
+\bibitem{37:lthooks-doc} Frank Mittelbach, Phelype Oleinik, \LaTeX{}~Project~Team:
+ \emph{\LaTeX's hook management}.\\
+ Run \texttt{texdoc} \texttt{lthooks-doc} to view.
+
%\bibitem{37: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/}
diff --git a/macros/latex-dev/base/ltpara-code.pdf b/macros/latex-dev/base/ltpara-code.pdf
index 7813560129..9085a887da 100644
--- a/macros/latex-dev/base/ltpara-code.pdf
+++ b/macros/latex-dev/base/ltpara-code.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltpara-doc.pdf b/macros/latex-dev/base/ltpara-doc.pdf
index fec25ce942..cd675c22bf 100644
--- a/macros/latex-dev/base/ltpara-doc.pdf
+++ b/macros/latex-dev/base/ltpara-doc.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltpara.dtx b/macros/latex-dev/base/ltpara.dtx
index 7c96c72fc7..9c1a95ee61 100644
--- a/macros/latex-dev/base/ltpara.dtx
+++ b/macros/latex-dev/base/ltpara.dtx
@@ -1,7 +1,8 @@
% \iffalse meta-comment
%
-%% File: ltpara.dtx (C) Copyright 2020-2023
-% Frank Mittelbach, LaTeX Team
+%% File: ltpara.dtx
+%% Copyright (C) 2020-2023
+%% Frank Mittelbach, The LaTeX Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
diff --git a/macros/latex-dev/base/ltplain.dtx b/macros/latex-dev/base/ltplain.dtx
index 1bdff344f7..89e5017300 100644
--- a/macros/latex-dev/base/ltplain.dtx
+++ b/macros/latex-dev/base/ltplain.dtx
@@ -32,7 +32,7 @@
%<*driver>
% \fi
\ProvidesFile{ltplain.dtx}
- [2022/01/25 v2.3h LaTeX Kernel (Plain TeX)]
+ [2023/04/15 v2.3i LaTeX Kernel (Plain TeX)]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{ltplain.dtx}
@@ -660,6 +660,10 @@
\def\extrafloats#1{%
\ifnum#1>\z@
\count@\numexpr\float@count-1\relax
+% \end{macrocode}
+% \changes{v2.3i}{2023/04/15}{Protect box 255 in lualatex gh/1041}
+% \begin{macrocode}
+ \ifnum\count@<266 \ch@ck0\m@ne\insert\fi
\ch@ck0\count@\count
\ch@ck1\count@\dimen
\ch@ck2\count@\skip
@@ -668,8 +672,12 @@
\global\expandafter\e@alloc@chardef
\csname bx@\the\float@count\endcsname\float@count
\@cons\@freelist{\csname bx@\the\float@count\endcsname}%
-\expandafter
-\extrafloats\expandafter{\numexpr#1-1\relax}%
+% \end{macrocode}
+% \changes{v2.3i}{2023/04/15}{unwind numexpr and ifnum nesting}
+% \begin{macrocode}
+\expandafter\extrafloats\expandafter{\the\numexpr#1-1\expandafter}%
+% \end{macrocode}
+% \begin{macrocode}
\fi}%
% \end{macrocode}
%
@@ -880,7 +888,6 @@
% but the code is commented out if no special value needs to be set.
% INITEX makes all parameters zero except where noted.
%
-% \begin{oldcomments}
% \begin{macrocode}
\pretolerance=100
\tolerance=200 % INITEX sets this to 10000
@@ -897,10 +904,14 @@
\brokenpenalty=100
\predisplaypenalty=10000
% \end{macrocode}
+%
+% \begin{macrocode}
% \postdisplaypenalty=0
% \interlinepenalty=0
% \floatingpenalty=0, set during \insert
% \outputpenalty=0, set before TeX enters \output
+% \end{macrocode}
+%
% \begin{macrocode}
\doublehyphendemerits=10000
\finalhyphendemerits=5000
@@ -971,6 +982,8 @@
% \begin{macrocode}
\uchyph=1
% \end{macrocode}
+%
+% \begin{macrocode}
% \lefthyphenmin=2 \righthyphenmin=3 set below
% \globaldefs=0
% \maxdeadcycles=25 % INITEX does this
@@ -978,21 +991,29 @@
% \fam=0
% \mag=1000 % INITEX does this
% \escapechar=`\\ % INITEX does this
+% \end{macrocode}
+%
% \begin{macrocode}
\defaulthyphenchar=`\-
\defaultskewchar=-1
% \end{macrocode}
+%
+% \begin{macrocode}
% \endlinechar=`\^^M % INITEX does this
% \newlinechar=-1 \LaTeX\ sets this in ltdefns.dtx.
+% \end{macrocode}
+%
% \begin{macrocode}
\delimiterfactor=901
% \end{macrocode}
+%
+% \begin{macrocode}
% \time=now % TeX does this at beginning of job
% \day=now % TeX does this at beginning of job
% \month=now % TeX does this at beginning of job
% \year=now % TeX does this at beginning of job
+% \end{macrocode}
%
-% \end{oldcomments}
% In \LaTeX{} we don't want box information in the transcript
% unless we do a full tracing.
% \changes{v1.0g}{1994/04/28}{Turn off overfull box tracing in log}
@@ -1012,26 +1033,36 @@
\boxmaxdepth=\maxdimen
% \end{macrocode}
%
-% \begin{oldcomments}
+% \begin{macrocode}
% \lineskiplimit=0pt, changed by \normalbaselines
+% \end{macrocode}
+%
% \begin{macrocode}
\delimitershortfall=5pt
\nulldelimiterspace=1.2pt
\scriptspace=0.5pt
% \end{macrocode}
+%
+% \begin{macrocode}
% \mathsurround=0pt
% \predisplaysize=0pt, set before TeX enters $$
% \displaywidth=0pt, set before TeX enters $$
% \displayindent=0pt, set before TeX enters $$
+% \end{macrocode}
+%
% \begin{macrocode}
\parindent=20pt
% \end{macrocode}
+%
+% \begin{macrocode}
% \hangindent=0pt, zeroed by TeX after each paragraph
% \hoffset=0pt
% \voffset=0pt
%
% \baselineskip=0pt, changed by \normalbaselines
% \lineskip=0pt, changed by \normalbaselines
+% \end{macrocode}
+%
% \begin{macrocode}
\parskip=0pt plus 1pt
\abovedisplayskip=12pt plus 3pt minus 9pt
@@ -1039,19 +1070,26 @@
\belowdisplayskip=12pt plus 3pt minus 9pt
\belowdisplayshortskip=7pt plus 3pt minus 4pt
% \end{macrocode}
+%
+% \begin{macrocode}
% \leftskip=0pt
% \rightskip=0pt
+% \end{macrocode}
+%
% \begin{macrocode}
\topskip=10pt
\splittopskip=10pt
% \end{macrocode}
+%
+% \begin{macrocode}
% \tabskip=0pt
% \spaceskip=0pt
% \xspaceskip=0pt
+% \end{macrocode}
+%
% \begin{macrocode}
\parfillskip=0pt plus 1fil
% \end{macrocode}
-% \end{oldcomments}
%
%
% \begin{macro}{\normalbaselineskip}
@@ -1215,7 +1253,7 @@
\gdef\obeylines{\catcode`\^^M\active%
\let^^M\obeyedline%
% \end{macrocode}
-%
+%
% The next line ending the definition is rather curious and it took
% me awhile to understand why rollback fails. The problem is the
% following: if \texttt{latexrelease} is used, then blocks of
diff --git a/macros/latex-dev/base/ltshipout-code.pdf b/macros/latex-dev/base/ltshipout-code.pdf
index 79b27f4984..c9209dbbb0 100644
--- a/macros/latex-dev/base/ltshipout-code.pdf
+++ b/macros/latex-dev/base/ltshipout-code.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltshipout-doc.pdf b/macros/latex-dev/base/ltshipout-doc.pdf
index 131c5251a0..b05bab812e 100644
--- a/macros/latex-dev/base/ltshipout-doc.pdf
+++ b/macros/latex-dev/base/ltshipout-doc.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltshipout.dtx b/macros/latex-dev/base/ltshipout.dtx
index 1b3cabcfc8..b19814a6fd 100644
--- a/macros/latex-dev/base/ltshipout.dtx
+++ b/macros/latex-dev/base/ltshipout.dtx
@@ -1,7 +1,7 @@
% \iffalse meta-comment
%%
%% Copyright (C) 2020-2023
-%% Frank Mittelbach, LaTeX Team
+%% Frank Mittelbach, The LaTeX Project
%%
%
% This file is part of the LaTeX base system.
diff --git a/macros/latex-dev/base/ltspace.dtx b/macros/latex-dev/base/ltspace.dtx
index 672ab92729..1dbfefc7b1 100644
--- a/macros/latex-dev/base/ltspace.dtx
+++ b/macros/latex-dev/base/ltspace.dtx
@@ -32,7 +32,7 @@
%<*driver>
% \fi
\ProvidesFile{ltspace.dtx}
- [2022/11/28 v1.3o LaTeX Kernel (spacing)]
+ [2023/03/22 v1.3p LaTeX Kernel (spacing)]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{ltspace.dtx}
@@ -308,8 +308,10 @@
% \end{macro}
%
% \begin{macro}{\samepage}
+% \changes{v1.3p}{2023/03/22}{Add \cs{predisplaypenalty} setting (gh/1022)}
% \begin{macrocode}
\DeclareRobustCommand\samepage{\interlinepenalty\@M
+ \predisplaypenalty\@M
\postdisplaypenalty\@M
\interdisplaylinepenalty\@M
\@beginparpenalty\@M
diff --git a/macros/latex-dev/base/ltvers.dtx b/macros/latex-dev/base/ltvers.dtx
index da131765ac..beed347903 100644
--- a/macros/latex-dev/base/ltvers.dtx
+++ b/macros/latex-dev/base/ltvers.dtx
@@ -115,7 +115,7 @@
{2023-06-01}
%</2ekernel|latexrelease>
%<*2ekernel>
-\def\patch@level{-2}
+\def\patch@level{-3}
% \end{macrocode}
%
% \begin{macro}{\development@branch@name}
diff --git a/macros/latex-dev/base/ltx3info.pdf b/macros/latex-dev/base/ltx3info.pdf
index ccdd69abd9..b69198d99f 100644
--- a/macros/latex-dev/base/ltx3info.pdf
+++ b/macros/latex-dev/base/ltx3info.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltxdoc.dtx b/macros/latex-dev/base/ltxdoc.dtx
index 78b6de4bcc..e147c9d22f 100644
--- a/macros/latex-dev/base/ltxdoc.dtx
+++ b/macros/latex-dev/base/ltxdoc.dtx
@@ -30,7 +30,7 @@
%
%<class>\NeedsTeXFormat{LaTeX2e}
%<class>\ProvidesClass{ltxdoc}
-%<class> [2022/06/22 v2.1i Standard LaTeX documentation class]
+%<class> [2023/03/28 v2.1j Standard LaTeX documentation class]
%
%<*driver>
\documentclass{ltxdoc}
@@ -182,9 +182,13 @@
%
% Support rolling back \pkg{doc} to version 2:
% \changes{v2.1e}{2022/05/27}{Support rolling back doc to version 2}
+% \changes{v2.1j}{2023/03/28}{Define \cs{cs} if doc is rolled back to v2 (gh/981)}
% \begin{macrocode}
\let\ltxdoc@doc@version\@empty % use current version by default
-\DeclareOption{doc2}{\def\ltxdoc@doc@version{=v2}}
+\DeclareOption{doc2}{%
+ \def\ltxdoc@doc@version{=v2}%
+ \DeclareRobustCommand\cs[1]{\texttt{\bslash #1}}%
+}
% \end{macrocode}
%
% \begin{macrocode}
@@ -670,8 +674,10 @@ Bug reports can be opened (category \texttt{#1}) at\\%
% kernel sources.
%
%
-% Copyright 2006, 2007, 2011 Heiko Oberdiek
-% Copyright 2014-2021 The LaTeX Project
+% Copyright 2006, 2007, 2011
+% Heiko Oberdiek
+% Copyright (C) 2014-2023
+% The LaTeX Project
%
\ProvidesFile{ltxdoc.cfg}%
diff --git a/macros/latex-dev/base/ltxdoc.pdf b/macros/latex-dev/base/ltxdoc.pdf
index 188d833aeb..b820c58deb 100644
--- a/macros/latex-dev/base/ltxdoc.pdf
+++ b/macros/latex-dev/base/ltxdoc.pdf
Binary files differ
diff --git a/macros/latex-dev/base/ltxguide.cls b/macros/latex-dev/base/ltxguide.cls
index b743fd9cda..778f7e993e 100644
--- a/macros/latex-dev/base/ltxguide.cls
+++ b/macros/latex-dev/base/ltxguide.cls
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 1993-2019
+% Copyright (C) 1993-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
diff --git a/macros/latex-dev/base/ltxref.dtx b/macros/latex-dev/base/ltxref.dtx
index dcfebf0e7e..0f842e4312 100644
--- a/macros/latex-dev/base/ltxref.dtx
+++ b/macros/latex-dev/base/ltxref.dtx
@@ -33,7 +33,7 @@
%<*driver>
% \fi
\ProvidesFile{ltxref.dtx}
- [2022/04/12 v1.1p LaTeX Kernel (Cross Referencing)]
+ [2023/05/16 v1.1q LaTeX Kernel (Cross Referencing)]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{ltxref.dtx}
@@ -93,6 +93,15 @@
% to align with the use of \pkg{hyperref}. Without \pkg{hyperref} (or some
% other package using the starred form) the star is simply ignored.
%
+% Note: starting with 2023-06-01 |\label| stores also the current value
+% of |\@currentlabelname| which should typically contain a (sanitized) title.
+% (A reference command |\nameref| is provided by the \pkg{nameref} package.)
+% |\label| also stores |\@currentHref| which if set should refer to a target name
+% for links. This value is set and used by \pkg{hyperref}. Unlike the other values
+% |\@currentHref| should be set globally. A fifth value |\@kernel@reserved@label@data|
+% is reserved for the kernel to allow future extensions of the cross-reference
+% system.
+%
%
% \MaybeStop{}
%
@@ -108,7 +117,8 @@
% incremented by the command \refstepcounter{CNT} , which sets
% \@currentlabel == {CNT}{eval(\p@cnt\theCNT)}. The command
% \label{FOO} then writes the following on file \@auxout :
-% \newlabel{FOO}{{eval(\@currentlabel)}{eval(\thepage)}}
+% \newlabel{FOO}{{eval(\@currentlabel)}{eval(\thepage)}%
+% {eval(\@currentlabelname)}{eval(\@currentHref)}{eval(\@kernel@reserved@label@data)}}
%
% \ref{FOO} ==
% BEGIN
@@ -228,6 +238,10 @@
%
% RmS 93/09/08: Added setting of refundefined switch.
% \begin{macrocode}
+%</2ekernel>
+%<*2ekernel|latexrelease>
+%<latexrelease>\IncludeInRelease{2023/06/01}%
+%<latexrelease> {\@kernel@sref}{store five arguments}%
\def\@setref#1#2#3{%
\ifx#1\relax
\protect\G@refundefinedtrue
@@ -235,19 +249,53 @@
\@latex@warning{Reference `#3' on page \thepage \space
undefined}%
\else
- \expandafter#2#1\null
+ \expandafter#2#1\@empty\@empty\@empty\null
\fi}
% \end{macrocode}
% \begin{macrocode}
-%</2ekernel>
-%<*2ekernel|latexrelease>
+\long\def\@firstoffive#1#2#3#4#5{#1}
+\long\def\@secondoffive#1#2#3#4#5{#2}
+\def\@kernel@sref#1{\expandafter\@setref\csname r@#1\endcsname\@firstoffive{#1}}
+\def\@kernel@spageref#1{\expandafter\@setref\csname r@#1\endcsname
+ \@secondoffive{#1}}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2022/06/01}%
+%<latexrelease> {\@kernel@sref}{store five arguments}%
+%<latexrelease>\def\@setref#1#2#3{%
+%<latexrelease> \ifx#1\relax
+%<latexrelease> \protect\G@refundefinedtrue
+%<latexrelease> \nfss@text{\reset@font\bfseries ??}%
+%<latexrelease> \@latex@warning{Reference `#3' on page \thepage \space
+%<latexrelease> undefined}%
+%<latexrelease> \else
+%<latexrelease> \expandafter#2#1\null
+%<latexrelease> \fi}
+%<latexrelease>\let\@firstoffive\undefined
+%<latexrelease>\let\@secondoffive\undefined
+%<latexrelease>\def\@kernel@sref#1{\expandafter\@setref\csname r@#1\endcsname\@firstoftwo{#1}}
+%<latexrelease>\def\@kernel@spageref#1{\expandafter\@setref\csname r@#1\endcsname
+%<latexrelease> \@secondoftwo{#1}}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{0000/00/00}%
+%<latexrelease> {\@kernel@sref}{store five arguments}%
+%<latexrelease>\def\@setref#1#2#3{%
+%<latexrelease> \ifx#1\relax
+%<latexrelease> \protect\G@refundefinedtrue
+%<latexrelease> \nfss@text{\reset@font\bfseries ??}%
+%<latexrelease> \@latex@warning{Reference `#3' on page \thepage \space
+%<latexrelease> undefined}%
+%<latexrelease> \else
+%<latexrelease> \expandafter#2#1\null
+%<latexrelease> \fi}
+%<latexrelease>\let\@firstoffive\undefined
+%<latexrelease>\let\@secondoffive\undefined
+%<latexrelease>\let\@kernel@sref\undefined
+%<latexrelease>\let\@kernel@spageref\undefined
+%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{2022/06/01}%
%<latexrelease> {\ref}{Add starred reference commands}%
% \end{macrocode}
% \begin{macrocode}
-\def\@kernel@sref#1{\expandafter\@setref\csname r@#1\endcsname\@firstoftwo{#1}}
-\def\@kernel@spageref#1{\expandafter\@setref\csname r@#1\endcsname
- \@secondoftwo{#1}}
\let\@kernel@ref\@kernel@sref
\let\@kernel@pageref\@kernel@spageref
\NewDocumentCommand\ref{s}
@@ -334,6 +382,8 @@
% \begin{macro}{\label}
% \changes{v1.1d}{1994/11/04}{(ASAJ)Added \cs{protected@write}}
% \changes{v1.1d}{1994/11/04}{(ASAJ)Added \cs{protected@edef}}
+% \changes{v1.1q}{2023/05/12}{(UFi)extended to store five arguments}
+% \changes{v1.1q}{2023/05/12}{(UFi)added a hook with argument}
% The commands |\label| and |\refstepcounter| have been changed to
% allow |\protect|'ed commands to work properly. For example,
%\begin{verbatim}
@@ -343,16 +393,27 @@
% to something like |\foo{4.d}|. Change made 20 Jul 88.
%
% \begin{macrocode}
+%</2ekernel>
+%<*2ekernel|latexrelease>
+%<latexrelease>\IncludeInRelease{2023/06/01}%
+%<latexrelease> {\label}{store five label arguments}%
+\providecommand\@currentlabelname{}
+\providecommand\@currentHref{}
+\providecommand\@kernel@reserved@label@data{}
+\NewHookWithArguments{label}{1}
\def\label#1{\@bsphack
+ \begingroup
+ \UseHookWithArguments{label}{1}{#1}%
\protected@write\@auxout{}%
- {\string\newlabel{#1}{{\@currentlabel}{\thepage}}}%
+ {\string\newlabel{#1}{{\@currentlabel}{\thepage}%
+ {\@currentlabelname}{\@currentHref}{\@kernel@reserved@label@data}}}%
+ \endgroup
\@esphack}
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
% \begin{macrocode}
-%</2ekernel>
-%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2022/06/01}%
%<latexrelease> {\Ref}{Add starred version}%
% \end{macrocode}
@@ -432,6 +493,16 @@
% \begin{macrocode}
%</2ekernel|latexrelease>
%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{0000/00/00}%
+%<latexrelease> {\label}{store five label arguments}%
+%<latexrelease>\let\@currenttitle\@undefined
+%<latexrelease>\let\@currenttarget\@undefined
+%<latexrelease>\let\@kernel@currentdata\@undefined
+%<latexrelease>\def\label#1{\@bsphack
+%<latexrelease> \protected@write\@auxout{}%
+%<latexrelease> {\string\newlabel{#1}{{\@currentlabel}{\thepage}}}%
+%<latexrelease> \@esphack}
+%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{2020/10/01}%
%<latexrelease> {\Ref}{Add starred version}%
%<latexrelease>\def\@currentcounter{}
diff --git a/macros/latex-dev/base/makeindx.pdf b/macros/latex-dev/base/makeindx.pdf
index 8d714a1cf1..39caa9b4cb 100644
--- a/macros/latex-dev/base/makeindx.pdf
+++ b/macros/latex-dev/base/makeindx.pdf
Binary files differ
diff --git a/macros/latex-dev/base/manifest.txt b/macros/latex-dev/base/manifest.txt
index d63945fa0e..22791a2494 100644
--- a/macros/latex-dev/base/manifest.txt
+++ b/macros/latex-dev/base/manifest.txt
@@ -27,7 +27,8 @@
% sample2e.tex -- Sample LaTeX input file.
% small2e.tex -- Small sample LaTeX input file.
%
-% clsguide.tex -- How to write class files.
+% clsguide.tex -- How to write class files.
+% clsguide-historic.tex -- How to write class files with a focus on moving from 2.09.
% cfgguide.tex -- Guide to using `.cfg' files to configure LaTeX.
% cyrguide.tex -- Guide to using cyrillic languages in LaTeX.
% encguide.tex -- Guide to font encodings.
@@ -71,12 +72,15 @@
% 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.
+% ltnews36.tex -- What was new in the release dated 2022/11.
+% ltnews37.tex -- What was new in the release dated 2023/06.
%
% ltx3info.tex -- Information about the LaTeX3 project.
%
% lamport-manual.err -- Errata for the LaTeX Manual book, second edition.
% tlc2.err -- Errata for the LaTeX Companion, second edition.
+% tlc3.err -- Errata for the LaTeX Companion, third edition.
% lb2.err -- Errata for the LaTeX-Begleiter, 2te erw. Auflage (German).
% lgc2.err -- Errata for the LaTeX Graphics Companion, second edition.
% webcomp.err -- Errata for the LaTeX Web Companion.
diff --git a/macros/latex-dev/base/minimal.cls b/macros/latex-dev/base/minimal.cls
index 9024a23bca..89c233c30f 100644
--- a/macros/latex-dev/base/minimal.cls
+++ b/macros/latex-dev/base/minimal.cls
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 1993-2019
+% Copyright (C) 1993-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
diff --git a/macros/latex-dev/base/modguide.pdf b/macros/latex-dev/base/modguide.pdf
index d484bf783b..6c5e0ef3e5 100644
--- a/macros/latex-dev/base/modguide.pdf
+++ b/macros/latex-dev/base/modguide.pdf
Binary files differ
diff --git a/macros/latex-dev/base/nfssfont.pdf b/macros/latex-dev/base/nfssfont.pdf
index cb2d37b3c3..a6455d33ad 100644
--- a/macros/latex-dev/base/nfssfont.pdf
+++ b/macros/latex-dev/base/nfssfont.pdf
Binary files differ
diff --git a/macros/latex-dev/base/proc.pdf b/macros/latex-dev/base/proc.pdf
index dc5c8e3a67..3e75484000 100644
--- a/macros/latex-dev/base/proc.pdf
+++ b/macros/latex-dev/base/proc.pdf
Binary files differ
diff --git a/macros/latex-dev/base/slides.pdf b/macros/latex-dev/base/slides.pdf
index 49a2fbf7be..0b7fbe33b6 100644
--- a/macros/latex-dev/base/slides.pdf
+++ b/macros/latex-dev/base/slides.pdf
Binary files differ
diff --git a/macros/latex-dev/base/slifonts.fdd b/macros/latex-dev/base/slifonts.fdd
index ec8b802596..5b66975095 100644
--- a/macros/latex-dev/base/slifonts.fdd
+++ b/macros/latex-dev/base/slifonts.fdd
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 1993-2019
+% Copyright (C) 1993-2023
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
diff --git a/macros/latex-dev/base/slifonts.pdf b/macros/latex-dev/base/slifonts.pdf
index 4707b8a219..411d29444c 100644
--- a/macros/latex-dev/base/slifonts.pdf
+++ b/macros/latex-dev/base/slifonts.pdf
Binary files differ
diff --git a/macros/latex-dev/base/source2e.pdf b/macros/latex-dev/base/source2e.pdf
index f84a84ea72..153a370981 100644
--- a/macros/latex-dev/base/source2e.pdf
+++ b/macros/latex-dev/base/source2e.pdf
Binary files differ
diff --git a/macros/latex-dev/base/syntonly.pdf b/macros/latex-dev/base/syntonly.pdf
index 24da1cf460..bafd004837 100644
--- a/macros/latex-dev/base/syntonly.pdf
+++ b/macros/latex-dev/base/syntonly.pdf
Binary files differ
diff --git a/macros/latex-dev/base/tlc2.pdf b/macros/latex-dev/base/tlc2.pdf
index e21a6fb104..af4dda256a 100644
--- a/macros/latex-dev/base/tlc2.pdf
+++ b/macros/latex-dev/base/tlc2.pdf
Binary files differ
diff --git a/macros/latex-dev/base/tlc3.err b/macros/latex-dev/base/tlc3.err
new file mode 100644
index 0000000000..f790c6d791
--- /dev/null
+++ b/macros/latex-dev/base/tlc3.err
@@ -0,0 +1,829 @@
+\newcommand\erratafiledate{2023-05-16}
+
+\def\comando#1{\texttt{\string#1}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% To produce a printed version of this errata file run this file through
+% LaTeX. It will unpack a small class file (if not already present) and
+% a configuration file with the extension .cfg. You might want to modify
+% the setting in this configuration file to print only a partial errata
+% suitable for your printed revision of this book, see details in the
+% .cfg file.
+%
+% The current version of this file can be found at:
+%
+% https://www.latex-project.org/help/books/
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+\begin{filecontents}{ttcterrata.cls}
+%%
+%% Copyright (C) 1997-2021 Frank Mittelbach
+%% This class file is licenced under LPPL latest version;
+%% see https://www.latex-project.org/lppl
+%
+%
+% It sets up a few commands used to format the errata entries for books in the
+% Addison-Wesley Series:
+%
+% Tools and Techniques for Computer Typesetting
+%
+% hence the name. However, anybody who likes to use it is free to apply it for
+% errata files of other books.
+%
+% Changes:
+%
+% v1.0a - changed name from errata.cls to ttcterrata.cls
+% v1.0b - added \arraybackslash
+% v1.0c - and took it out again and used \tabularnewline instead
+
+\ProvidesClass{ttcterrata}
+ [2021/08/03 v1.0c Mini class for errata files; subject to change (FMi)]
+
+\LoadClass{article}
+
+\setcounter{secnumdepth}{-1}
+\addtolength\textwidth{5cm}
+\addtolength\oddsidemargin{-3cm}
+
+\addtolength\textheight{36pt}
+
+\RequirePackage{shortvrb}
+\MakeShortVerb{\|}
+
+\RequirePackage{array,longtable}
+\RequirePackage{multicol}
+
+
+\newcommand\erratagetnumber{}
+\def\erratagetnumber#1/#2/#3\erratagetnumber{#1#2#3}
+
+
+\newcommand\gobbleerrata{%
+ \setbox\@tempboxa\vbox\bgroup
+ \let\endgobble\egroup
+ \let\hideamp\relax
+ \let\\\relax
+ \let\tabularnewline\relax
+ \let\par\@@par}
+
+\newcommand*\hideamp{&}
+
+\let\endgobble\relax
+
+
+\newcommand\erratastartdate{}
+\newcommand\myprinting{1}
+
+
+\newcommand\doweprint[2]{%
+ \ifnum \myprinting < \if!#2!1000 \else \ifx s#2 1000\else#2 \fi\fi
+ \ifnum \expandafter\erratagetnumber\erratastartdate\erratagetnumber <
+ \erratagetnumber#1\erratagetnumber \relax
+ \@tempswatrue
+ \else
+ \@tempswafalse
+ \fi
+ \else
+ \@tempswafalse
+ \fi
+}
+
+
+
+\newcommand\includedentries{entries after = \erratastartdate}
+\newcommand\printedentries{between \erratastartdate\space and}
+
+\newcommand\showallerrors{%
+ \renewcommand\includedentries{all errata entries}%
+ \renewcommand\printedentries{up to}
+ \renewcommand\doweprint[2]{\@tempswatrue}}
+
+
+\newcommand\displayrevisionfix[2]{%
+ \if!#2!\textbf{#1}\else\textit{#1}\rlap{\textsuperscript{#2}}\fi}
+
+\newcommand\norevisionnumbers{%
+ \renewcommand\displayrevisionfix[2]{\textbf{##1}}}
+
+\IfFileExists{\jobname.cfg}
+ {
+ \input{\jobname.cfg}
+ \typeout{***************************************************}
+ \typeout{*}
+ \typeout{* Configuration file for \jobname.err found }
+ \typeout{*}
+ \typeout{***************************************************}
+ \AtEndDocument{
+ \typeout{***************************************************}
+ \typeout{*}
+ \typeout{* If you wish to generate an errata listing}
+ \typeout{* containing only errors found after a certain revision}
+ \typeout{* and/or only errors found after a certain date}
+ \typeout{* modify the information stored in \jobname.cfg}
+ \typeout{*}
+ \typeout{* Current settings are:}
+ \typeout{*}
+ \typeout{* \@spaces printing of your book = \myprinting}
+ \typeout{* \@spaces include \includedentries}
+ \typeout{*}
+ \typeout{***************************************************}
+ }}
+ {}
+
+%% \erroronpage <page> <line info> <contributor> <date> <fixed in revision>
+
+\newcommand\erroronpage[5]{%
+ \endgobble
+ \doweprint{#4}{#5}%
+ \if@tempswa
+ \typeout{Typesetting entry #1 #2 #3 #4}%
+ \else
+ \typeout{Ignoring entry #1 #2 #3 #4}%
+ \expandafter\gobbleerrata
+ \fi
+ \hideamp \tabularnewline
+ \displayrevisionfix{#1}{#5}
+ \hideamp #2 \hideamp (\textsf{#3}) \hideamp
+}
+
+\newcommand\seriouserroronpage[5]{%
+ \endgobble
+ \doweprint{#4}{#5}%
+ \if@tempswa
+ \typeout{Typesetting entry #1 #2 #3 #4}%
+ \else
+ \typeout{Ignoring entry #1 #2 #3 #4}%
+ \expandafter\gobbleerrata
+ \fi
+ \hideamp \tabularnewline
+ \fbox{\bfseries !!}\hfill
+ \displayrevisionfix{#1}{#5}
+ \hideamp #2 \hideamp (\textsf{#3}) \hideamp
+}
+
+\newcommand\CHAPTER[1]{\endgobble
+ &\tabularnewline[4pt]%
+ \multicolumn{4}{l}{\framebox[10cm][l]{\textbf{\normalsize\strut#1}}} \tabularnewline}
+
+\newenvironment{erratalist}
+ {\begin{longtable}{r>{\raggedright}p{2cm}l>{\raggedright}p{10cm}l}}
+ {\endgobble\end{longtable}}
+
+\newcommand\erratatitle[2]
+ {\begin{center}\LARGE\bfseries
+ Errata list for #1\\[5pt](\myprinting.\ printing)\\[10pt]
+ \small Includes all entries found \printedentries\space #2\\
+ (For other periods/print runs reprocess this document
+ with different config settings)
+ \end{center}%
+ \markright{Errata for #1 (\printedentries\space #2)}%
+ \thispagestyle{plain}%
+ \vspace{20pt}}
+
+\pagestyle{myheadings}
+
+\AtBeginDocument{\small}
+
+\setlength\parindent{0pt}
+\setlength\parskip{2pt}
+
+\newcommand\contributor[2]{\makebox[1cm][l]{\sffamily#1} #2\par}
+
+% some special shortcuts overwriting existing commands:
+
+\let\u\underline
+\renewcommand\>{$\to$}
+
+%%% some code suggested by Thorsten Hansen to count the number of
+%%% contributions by individuals (will work only if we do not get
+%%% too many :-)
+
+\def\count@contributors#1/#2/#3\@nil{
+ \@ifundefined{c@#1}{\newcounter{#1}}{}\stepcounter{#1}%
+%%% also count secondary:
+%%% \@ifundefined{c@#2}{\newcounter{#2}}{}\stepcounter{#2}%
+}
+
+\renewcommand\erroronpage[5]{%
+ \count@contributors#3/secondary/\@nil
+ \endgobble
+ \doweprint{#4}{#5}%
+ \if@tempswa
+ \typeout{Typesetting entry #1 #2 #3 #4}%
+ \else
+ \typeout{Ignoring entry #1 #2 #3 #4}%
+ \expandafter\gobbleerrata
+ \fi
+ \hideamp \tabularnewline
+ \displayrevisionfix{#1}{#5}
+ \hideamp #2 \hideamp (\textsf{#3}) \hideamp
+}
+
+\renewcommand\seriouserroronpage[5]{%
+ \count@contributors#3/secondary/\@nil
+ \endgobble
+ \doweprint{#4}{#5}%
+ \if@tempswa
+ \typeout{Typesetting entry #1 #2 #3 #4}%
+ \else
+ \typeout{Ignoring entry #1 #2 #3 #4}%
+ \expandafter\gobbleerrata
+ \fi
+ \hideamp \tabularnewline
+ \fbox{\bfseries !!}\hfill
+ \displayrevisionfix{#1}{#5}
+ \hideamp #2 \hideamp (\textsf{#3}) \hideamp
+}
+
+\renewcommand\contributor[2]{\makebox[1cm][l]{%
+ \sffamily#1} #2\@ifundefined{c@#1}{}{ (\arabic{#1})}\par}
+
+\end{filecontents}
+
+
+\begin{filecontents}{\jobname.cfg}
+%
+%
+% Configuration file for the errata listing of
+%
+% The LaTeX Companion, Third Edition, Parts I & II
+%
+%
+% \erratastartdate
+%
+% Specifies the date from which on errata entries should be listed.
+%
+% The format is YYYY/MM/DD.
+%
+% The default below ensures that all entries for a particular
+% printing are typeset.
+%
+
+\renewcommand\erratastartdate{2023/04/01}
+
+
+%
+% \myprinting
+%
+% Specifies which (revised) printing you own. For example, if you
+% have the second printing set this to 2 so that errors already
+% corrected in that printing will not appear in your errata
+% listing.
+%
+% The default below ensures that all entries relevant to the x-th
+% printing are typeset.
+%
+%
+
+\renewcommand\myprinting{1}
+
+%
+% \norevisionnumbers
+%
+% Specifies that all page numbers in the errata are shown in the same
+% format (bold face) irregardless of whether or not they are fixed
+% in some revision. The default is to print corrected errors in
+% italic and add the revision number as a superscript.
+
+%
+% \showallerrors
+%
+% With this command you tell the program that all errata entries are
+% supposed to be generated. This makes \myprinting and
+% \erratastartdate basically obsolete so this isn't turned on by
+% default.
+%
+%
+\endinput
+\end{filecontents}
+
+
+\documentclass{ttcterrata}[2005/11/10] % we want new class
+
+\usepackage[T1]{fontenc}
+\let\u\underline % shortcut for this file
+\newcommand\meta[1]{$\langle$\textit{#1\/}$\rangle$}
+
+\usepackage{textcomp}
+
+\usepackage{url}
+
+\begin{document}
+
+\erratatitle{The \LaTeX{} Companion, Third Edition, Parts I \& II}{\erratafiledate}
+
+
+\begin{verbatim}
+@book(A-W:MF:2023,
+ author = {Frank Mittelbach and Ulrike Fischer},
+ title = {The {\LaTeX} Companion},
+ edition = 3,
+ note = {With contributions by Javier Bezos, Johannes Braams, and Joseph Wright},
+ series = {Tools and Techniques for Computer Typesetting},
+ publisher = {Addison-Wesley},
+ address = {Boston, Massachusetts},
+ year = 2023,
+ pagenums = {976 (Part I) and 1008 (Part II)},
+ bibliography = {yes},
+ index = {yes},
+ isbn = {978-0-13-816648-9},
+)
+\end{verbatim}
+
+
+\begin{list}{}{\setlength\leftmargin{0cm}\setlength\rightmargin{3cm}}
+\item[]
+
+This file (\texttt{\jobname.err}) can be found as part of the \LaTeX{}
+distribution and its latest version is maintained on the \LaTeX{}
+project site at \texttt{https://www.latex-project.org/help/books/\jobname.err}
+where you will also find extracts of the book.
+
+The first column in the table shows the page number of the errata
+entry. Superscript numbers in the first column refer to the printed
+revision in which this entry was corrected (\textit{s} indicates a
+correction in the sources only). The second
+column gives the precise location (negative line or paragraph numbers
+are counted from the bottom of the page). The third column shows the
+first finder of the problem.
+
+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
+\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 5
+periods) 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
+the authors do not count.
+
+Each prize is a free choice of any single computing book found on the
+Addison-Wesley/Pearson web site:
+\texttt{https://www.informit.com} (that
+is, no boxed sets or multiple volume offers).
+
+
+As usual, the authors and publisher reserve the right to make various
+decisions such as whether a reported feature is an error for
+competitive purposes or whether similar features count as a single or
+multiple errors. ---
+Good luck!
+
+\begin{center}
+\begin{tabular}{clr}
+Contest period ends & Winner \\[4pt]
+2023/?? & & ??? suggestions\\
+\end{tabular}
+\end{center}
+
+
+Due to its size the third edition of \textit{The \LaTeX{} Companion} is printed
+as a two-volume set. The digital version, however, is provided as a
+single PDF or ePub. This means that a small fraction of the digital
+content differs from that of the printed version: there is only a
+single font matter, a single bibliography, and a single index, whereas
+in the printed books these are separated out. However, all versions share the main
+matter (down to the page numbering) so most of the errata applies to
+all versions, but to a few only to the digital and others only to the
+printed version. Thus, we end up with three separate lists.
+
+
+\end{list}
+
+%\newpage
+
+
+%<--------------------------
+
+\newcommand\BibTeX{\textsc{Bib}\TeX}
+\newcommand\cs[1]{\texttt{\textbackslash #1}}
+\newcommand\env[1]{\texttt{#1}}
+\newcommand\pkg[1]{\textsf{#1}}
+
+\section*{Errata for the print version (not applicable to the digital version)}
+
+The printed books differ from the digital version in that the
+biligraphy is split across both volumes (with a few repeats) and that
+the font matter of each volume has its own table of contents and list
+of figures and tables. Therefore these parts have different page
+numbers and you will see similar errata entries for both print and
+digital differing only in that respect.
+
+\begin{erratalist}
+
+\CHAPTER{Front matter (Part I)}
+
+\erroronpage{I-ix\ldots I-xvi}{}{FMi}{2023/04/04}{s}
+Dot leaders have been changed on all sections.
+
+\erroronpage{I-xvii}{chapter head}{FMi}{2023/04/04}{s}
+formulas \> \u{F}ormulas
+
+\erroronpage{I-xvii}{chapter head}{FMi}{2023/04/04}{s}
+documents \> \u{D}ocuments
+
+\erroronpage{I-xvii}{chapter head}{FMi}{2023/04/04}{s}
+beyond \> \u{B}yond
+
+\erroronpage{I-xx\ldots I-xxi}{}{FMi}{2023/04/04}{s}
+Dot leaders have been changed on all sections.
+
+\CHAPTER{Bibliography (Part I)}
+
+\erroronpage{I-783}{[55], l.-2}{FMi}{2023/04/04}{s}
+all \> \u{them} all
+
+\erroronpage{I-785}{[73], l.-2}{kb/bb}{2023/04/04}{s}
+the go-forward way for \LaTeX-coding \> \\
+the way for \LaTeX{} coding going forward
+
+\erroronpage{I-786}{[87], l.2}{kb/bb}{2023/04/04}{s}
+p. \> pp.
+
+\erroronpage{I-786}{[88], l.2}{kb/bb}{2023/04/04}{s}
+p. \> pp.
+
+\erroronpage{I-787}{[92], l.2}{kb/bb}{2023/04/04}{s}
+Add: Vancouver, 1999
+
+\erroronpage{I-788}{[100], l.3}{kb/bb}{2023/04/04}{s}
+Publishing \> Publishing\u{,}
+
+\erroronpage{I-790}{[122], l.1}{kb/bb}{2023/04/04}{s}
+In \u{ACM editor} ``Proceedings \> In ``PODC'01: Proceedings
+
+\erroronpage{I-790}{[122], l.1}{kb/bb}{2023/04/04}{s}
+In \u{Unicode Consortium, editor} \> In
+
+
+\CHAPTER{Front matter (Part II)}
+
+\erroronpage{II-x\ldots II-xxviii}{}{FMi}{2023/04/04}{s}
+Dot leaders have been changed on all sections.
+
+\erroronpage{II-xiv}{heading}{bb/FMi}{2023/04/04}{s}
+Multiple alignments: \env{align} \u{and \env{flalign}}
+\>\\
+Multiple alignments: \env{align}\u{, \env{flalign}, and \env{alignat}}
+
+\erroronpage{II-xv}{chapter head}{FMi}{2023/04/04}{s}
+formulas \> \u{F}ormulas
+
+\erroronpage{II-xvi}{chapter head}{FMi}{2023/04/04}{s}
+documents \> \u{D}ocuments
+
+\erroronpage{II-xxi}{chapter head}{FMi}{2023/04/04}{s}
+beyond \> \u{B}yond
+
+
+
+\CHAPTER{Bibliography (Part II)}
+
+\erroronpage{II-799}{[43], l.-2}{FMi}{2023/04/04}{s}
+all \> \u{them} all
+
+\erroronpage{II-801}{[62], l.-2}{kb/bb}{2023/04/04}{s}
+the go-forward way for \LaTeX-coding \>\\
+the way for \LaTeX{} coding going forward
+
+\erroronpage{II-802}{[71], l.2}{kb/bb}{2023/04/04}{s}
+p. \> pp.
+
+\erroronpage{II-802}{[72], l.2}{kb/bb}{2023/04/04}{s}
+p. \> pp.
+
+\erroronpage{II-803}{[80], l.3}{kb/bb}{2023/04/04}{s}
+Publishing \> Publishing\u{,}
+
+
+
+
+\end{erratalist}
+
+
+%<--------------------------
+
+\section*{Errata for the digital version (not applicable to the print version)}
+
+All known errors to the digital version have already been incorporated in the product as distributed.
+
+%\begin{erratalist}
+%
+%\CHAPTER{General}
+%
+%\CHAPTER{Front matter}
+%
+%\end{erratalist}
+
+
+%<--------------------------
+
+
+\section*{Errata common to the print and digital versions}
+
+The main matter is identical (also in page numbers) in the print and
+the digital versions. Therefore most errata entries appear in this
+section.
+
+\begin{erratalist}
+
+
+\CHAPTER{General}
+
+\erroronpage{}{}{FMi}{2023/04/04}{s}
+Some corrections result in index changes. These are not tracked here;
+the index is always fully regenerated for new printings.
+
+\CHAPTER{Chapter 1 --- Introduction}
+
+\erroronpage{I-5}{para 4, l.4}{kb}{2023/04/04}{s}
+\u{of} the bugs \> \u{with} the bugs
+\\ Already corrected in the digital version.
+
+
+\erroronpage{I-5}{para 5, l.5}{kb}{2023/04/04}{s}
+not least \> \u{but} not least
+\\ Already corrected in the digital version.
+
+
+\CHAPTER{Chapter 2 --- The Structure of a \LaTeX{} Document}
+
+\erroronpage{I-34}{l.-1}{FMi}{2023/04/04}{s}
+Moved first line of page 35 to 34.
+\\ Already corrected in the digital version.
+
+\erroronpage{I-35}{l.1}{FMi}{2023/04/04}{s}
+Moved first line of page 35 to 34.
+\\ Already corrected in the digital version.
+
+\erroronpage{I-113}{listing}{FMi}{2023/05/14}{s}
+Situation is the same in the 2023 distributions; listing output updated.
+\\ Already corrected in the digital version.
+
+
+\CHAPTER{Chapter 3 --- Basic Formatting Tools -- Paragraph \ldots}
+
+
+\CHAPTER{Chapter 4 --- Basic Formatting Tools -- Larger \ldots}
+
+
+\CHAPTER{Chapter 5 --- The Layout of the Page}
+
+
+\CHAPTER{Chapter 6 --- Tabular Material}
+
+
+\CHAPTER{Chapter 7 --- Mastering Floats}
+
+
+\CHAPTER{Chapter 8 --- Graphics Generation and Manipulation}
+
+
+\CHAPTER{Chapter 9 --- Font Selection and Encodings}
+
+\erroronpage{I-669}{exa 9-3-11}{FMi}{2023/04/04}{s}
+Changed line breaks in example.
+
+\erroronpage{I-708}{listing}{FMi}{2023/05/14}{s}
+Situation is the same in the 2023 distributions; listing output updated.
+\\ Already corrected in the digital version.
+
+
+\CHAPTER{Chapter 10 --- Text and Symbol Fonts}
+
+\erroronpage{II-114}{table 10.89}{FMi}{2023/04/04}{s}
+Added missing \texttt{U+00Fx} line.
+There was a bug in code generating it.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-117}{table 10.92}{FMi}{2023/04/04}{s}
+Added missing \texttt{U+00Fx} line.
+There was a bug in code generating it.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-121}{table 10.96}{FMi}{2023/04/04}{s}
+Added missing \texttt{U+00Fx} line.
+There was a bug in code generating it.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-122}{table 10.98}{FMi}{2023/04/04}{s}
+Added missing \texttt{U+00Fx} line.
+There was a bug in code generating it.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-122}{table 10.99}{FMi}{2023/04/04}{s}
+Added missing \texttt{U+00Fx} line.
+There was a bug in code generating it.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-123}{table 10.100}{FMi}{2023/04/04}{s}
+Added missing \texttt{U+00Fx} line.
+There was a bug in code generating it.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-124}{table 10.103}{FMi}{2023/04/04}{s}
+Added missing \texttt{U+00Fx} line.
+There was a bug in code generating it.
+\\ Already corrected in the digital version.
+
+
+
+\CHAPTER{Chapter 11 --- Higher Mathematics}
+
+\erroronpage{II-127}{para 1, l.5}{bb/FMi}{2023/04/04}{s}
+\u{The} American Mathematical Society (AMS) \u{provides} a major
+package, \pkg{amsmath}, which \u{makes} \ldots
+\>\\
+\u{In the early nineties the} American Mathematical Society (AMS)
+\u{provided} a major package, \pkg{amsmath}, which \u{made} \ldots
+\\ Already corrected in the digital version.
+
+\erroronpage{II-129}{para -3, l.1}{bb/FMi}{2023/04/04}{s}
+The principal documentation for these packages
+\>\\
+The principal documentation for these \u{two} packages
+\\ Already corrected in the digital version.
+
+
+\erroronpage{II-129}{para -1, l.3}{bb}{2023/04/04}{s}
+\u{lot} additions \> \u{many} additions
+\\ Already corrected in the digital version.
+
+
+\erroronpage{II-132}{table 11.1}{bb/FMi}{2023/04/04}{s}
+Also mention \env{alignat}, \env{alignat*}, and \env{alignedat}.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-133}{para 4,l.2}{bb/FMi}{2023/04/04}{s}
+Add:
+
+Furthermore, they move the equation tag out of the way if it would
+otherwise overprint the formula.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-138}{heading}{bb/FMi}{2023/04/04}{s}
+Multiple alignments: \env{align} \u{and \env{flalign}}
+\>
+Multiple alignments: \env{align}\u{, \env{flalign}, and \env{alignat}}
+\\ Already corrected in the digital version.
+
+\erroronpage{II-138}{}{FMi}{2023/04/04}{s}
+Moved para from 139 to end of this page.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-139}{para 1}{FMi}{2023/04/04}{s}
+Moved para back to page 138.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-139}{bottom}{FMi}{2023/04/04}{s}
+Add:
+
+Sometimes it is more convenient to explicitly specify all the
+horizontal spacing yourself within the formula. For this you can use
+an \env{alignat} environment. It differs from \env{align} in two ways: you have to
+specify the number of \texttt{rl} pairs as an argument to the environment and
+it does not add any spaces between the pairs, e.g.,
+\begin{verbatim}
+\begin{alignat}{3} x &= y &\qquad X &= Y &\qquad a &= b+c \\ ...
+\end{verbatim}
+As usual, equation numbers can be altered with \cs{tag} or suppressed with \cs{notag}.
+\\ Already corrected in the digital version.
+
+
+\erroronpage{II-140}{para 1, l.2}{bb/FMi}{2023/04/04}{s}
+Add:
+
+Do not forget to reset \cs{minalignsep} if you change it in this manner.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-140}{para 2, l.4}{bb/FMi}{2023/04/04}{s}
+Add:
+
+You can think of them as subsidiary environments that can be used
+within any of the display environments discussed so far (below we use
+them inside equation).
+\\ Already corrected in the digital version.
+
+\erroronpage{II-140}{para -1}{FMi}{2023/04/04}{s}
+Paragraph moved to page 141.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-141}{}{FMi}{2023/04/04}{s}
+One paragraph added moved over from page 144.
+\\ Already corrected in the digital version.
+
+\erroronpage{II-144}{para 2, l.-3}{FMi}{2023/04/04}{s}
+the issue \> the \u{spacing} issue
+\\ Already corrected in the digital version.
+
+\erroronpage{II-145}{para 2, l.1}{bb/FMi}{2023/04/04}{s}
+Add:
+
+Another problem is that an empty line introduces an unwanted break
+point in front of the display, thus \cs{predisplaypenalty} is no
+longer honored.
+\\ Already corrected in the digital version.
+
+
+\CHAPTER{Chapter 12 --- Fonts in Formulas}
+
+\erroronpage{II-225}{heading}{FMi}{2023/04/04}{s}
+Chapter title not properly capitalized.
+\\ Already corrected in the digital version.
+
+
+\CHAPTER{Chapter 13 --- Localizing Documents}
+
+\erroronpage{II-297}{heading}{FMi}{2023/04/04}{s}
+Chapter title not properly capitalized.
+\\ Already corrected in the digital version.
+
+
+\CHAPTER{Chapter 14 --- Index Generation}
+
+
+\CHAPTER{Chapter 15 --- Bibliography Generation}
+
+
+\CHAPTER{Chapter 16 --- Managing Citations}
+
+
+\CHAPTER{Chapter 17 --- \LaTeX{} Package Documentation Tools}
+
+
+\CHAPTER{Appendix A --- \LaTeX{} Overview for Preamble, \ldots}
+
+
+\CHAPTER{Appendix B --- Tracing and Resolving Problems}
+
+
+\CHAPTER{Appendix C --- Going Beyond}
+
+\erroronpage{II-297}{heading}{FMi}{2023/04/04}{s}
+Appendix title not properly capitalized.
+\\ Already corrected in the digital version.
+
+\CHAPTER{Biographies}
+
+\CHAPTER{Production Notes}
+
+\end{erratalist}
+
+
+
+
+
+\setcounter{collectmore}{3}
+
+\begin{multicols}{3}[Thanks to all who have found errors or
+ omissions. Listed are the people who found an errata entry first.]
+\contributor{bb}{Barbara Beeton}
+\contributor{FMi}{Frank Mittelbach}
+\contributor{kb}{Karl Berry}
+\end{multicols}
+
+
+Other people have sent us corrections for errors already found.
+Thanks to all of you!
+
+If you find further errors please report them to one of the authors, e.g.,
+\begin{quote}\ttfamily
+ frank.mittelbach@latex-project.org
+\end{quote}
+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 erratum}
+\end{flushleft}
+Here is an example:
+\begin{verbatim}
+\erroronpage{5}{para 3, l.1}{FMi}{2023/06/21}{}
+ \u{LaTeX} \> \u{\LaTeX}
+\end{verbatim}
+\verb=\u= underlines a text fragment and \verb=\>= produces \>.
+\end{document}
+
+
+
+
+\seriouserroronpage{general}{}{FMi}{2004/06/12}{}
+
+ To help you in assessing this errata document we have placed
+ exclamation marks in front of each entry that we consider essential
+ for correctly understanding the book contents.
+
+\erroronpage{general}{}{FMi}{2004/05/14}{}
+
+ Due to the printing process there may be small alignment problems
+ between blue and black text on some pages. These can vary from book
+ to book depending on how the paper was handled between print
+ runs---such is the analog nature of printing on a press.
+
diff --git a/macros/latex-dev/base/tlc3.pdf b/macros/latex-dev/base/tlc3.pdf
new file mode 100644
index 0000000000..df716ea46f
--- /dev/null
+++ b/macros/latex-dev/base/tlc3.pdf
Binary files differ
diff --git a/macros/latex-dev/base/tulm.fdd b/macros/latex-dev/base/tulm.fdd
index 243cbe30cc..c8dd8b95fc 100644
--- a/macros/latex-dev/base/tulm.fdd
+++ b/macros/latex-dev/base/tulm.fdd
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 2016-2021
+% Copyright (C) 2016-2023
% 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
index d2c4ec94d0..3084afc1ab 100644
--- a/macros/latex-dev/base/tulm.pdf
+++ b/macros/latex-dev/base/tulm.pdf
Binary files differ
diff --git a/macros/latex-dev/base/usrguide-historic.pdf b/macros/latex-dev/base/usrguide-historic.pdf
index 3149112b43..b160cc0774 100644
--- a/macros/latex-dev/base/usrguide-historic.pdf
+++ b/macros/latex-dev/base/usrguide-historic.pdf
Binary files differ
diff --git a/macros/latex-dev/base/usrguide.pdf b/macros/latex-dev/base/usrguide.pdf
index c4953d7e33..4f4a8b4e28 100644
--- a/macros/latex-dev/base/usrguide.pdf
+++ b/macros/latex-dev/base/usrguide.pdf
Binary files differ
diff --git a/macros/latex-dev/base/usrguide.tex b/macros/latex-dev/base/usrguide.tex
index f06850afaa..b1039a3595 100644
--- a/macros/latex-dev/base/usrguide.tex
+++ b/macros/latex-dev/base/usrguide.tex
@@ -32,9 +32,10 @@
\usepackage[T1]{fontenc} % needed for \textbackslash in tt
\usepackage{csquotes}
+\usepackage{url}
\title{\LaTeX\ for authors --- current version}
-\author{\copyright~Copyright 2020-2022, \LaTeX\ Project Team.\\
+\author{\copyright~Copyright 2020-2023, \LaTeX\ Project Team.\\
All rights reserved.%
\footnote{This file may be distributed and/or modified under the
conditions of the \LaTeX{} Project Public License, either version 1.3c
@@ -42,7 +43,7 @@
\texttt{usrguide.tex} for full details.}%
}
-\date{2022-07-05}
+\date{2023-05-23}
\NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
\NewDocumentCommand\marg{m}{\arg{#1}}
@@ -340,6 +341,12 @@ in \pkg{amsmath} environments, which in the terms here would be defined as
\NewDocumentCommand\\{!s !o}{ ... }
\end{verbatim}
+Also notable when using optional arguments in the last position is that \TeX{}
+will necessarily look ahead for the argument opening token. This means that
+the value of |\inputlineno| will be `out by one' if such a trailing optional
+argument is \emph{not} present and the command ends a line; it will be one
+greater than the line number containing the last mandatory argument.
+
\subsection{`Embellishments'}
\label{sec:cmd:embellishment}
@@ -636,7 +643,19 @@ processed argument can be further processed using a mapping function
If only a single character \meta{token} is used for the split, any
category code $13$ (active) character matching the \meta{token} will
be replaced before the split takes place.
-Spaces are trimmed at each end of each item parsed.
+Spaces are trimmed at each end of each item parsed. Exactly one set
+of braces will be stripped if an entire item is surrounded by them,
+i.e.~the following inputs and outputs result (each separte item as
+a brace group).
+\begin{verbatim}
+a ==> {a}
+{a} ==> {a}
+{a}b ==> {{a}b}
+a,b ==> {a}{b}
+{a},b ==> {a}{b}
+a,{b} ==> {a}{b}
+a,{b}c ==> {a}{{b}c}
+\end{verbatim}
\begin{decl}
|\ProcessList| \arg{list} \arg{function}
@@ -716,7 +735,7 @@ put that code at the end of the \meta{start code}. Nevertheless this
Environments that use this feature can be nested.
-\subsection{Fully-expandable document commands}
+\subsection{Fully-expandable document commands\label{sec:ltcmd:expandable}}
Document commands created using \cs{NewDocumentCommand}, etc.\@, are normally
created so that they do not expand unexpectedly. This is done using engine
@@ -724,7 +743,7 @@ features, so is more powerful than \LaTeXe{}'s \cs{protect} mechanism. There
are \emph{very rare} occasion when it may be useful to create functions using a
expansion-only grabber. This imposes a number of restrictions on the
nature of the arguments accepted by a function, and the code it implements.
-This facility should only be used when \emph{absolutely necessary}.
+This facility should only be used when \emph{necessary}.
\begin{decl}
|\NewExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
@@ -755,6 +774,25 @@ available:
in the standard version.
\end{itemize}
+\subsection{Commands at the start of tabular cells}
+
+Creating commands that are used at the start of tabular cells imposes
+some restrictions on the underlying implementation. The standard \LaTeX{}
+tabular environments (\texttt{tabular}, etc.) use a mechanism which requires
+that any command wrapping \cs{multicolumn} or similar must be
+`expandable'. This is \emph{not} the case for commands created using
+\cs{NewDocumentCommand}, etc., which as detailed in
+Section~\ref{sec:ltcmd:expandable} use an engine feature which prevents
+such `expansion'. Therefore, to create such wrappers for use at the start
+of tabular cells, you must use \cs{NewExpandableDocumentCommand}, for example
+\begin{verbatim}
+\NewExpandableDocumentCommand\MyMultiCol{m}{\multicolumn{3}{c}{#1}}
+\begin{tabular}{lcr}
+a & b & c \\
+\MyMultiCol{stuff} \\
+\end{tabular}
+\end{verbatim}
+
\subsection{Details about argument delimiters}
In normal (non-expandable) commands, the delimited types look for the
@@ -844,23 +882,23 @@ The argument specifications for document commands and environments are
available for examination and use.
\begin{decl}
- |\GetDocumentCommandArgSpec| \arg{function} \\
+ |\GetDocumentCommandArgSpec| \arg{cmd} \\
|\GetDocumentEnvironmentArgSpec| \arg{environment}
\end{decl}
These functions transfer the current argument specification for the
-requested \meta{function} or \meta{environment} into the token list
-variable \cs{ArgumentSpecification}. If the \meta{function} or
+requested \meta{cmd} or \meta{environment} into the token list
+variable \cs{ArgumentSpecification}. If the \meta{cmd} or
\meta{environment} has no known argument specification then an error
is issued. The assignment to \cs{ArgumentSpecification} is local to
the current \TeX{} group.
\begin{decl}
- |\ShowDocumentCommandArgSpec| \arg{function} \\
+ |\ShowDocumentCommandArgSpec| \arg{cmd} \\
|\ShowDocumentEnvironmentArgSpec| \arg{environment}
\end{decl}
These functions show the current argument specification for the
-requested \meta{function} or \meta{environment} at the terminal. If
-the \meta{function} or \meta{environment} has no known argument
+requested \meta{cmd} or \meta{environment} at the terminal. If
+the \meta{cmd} or \meta{environment} has no known argument
specification then an error is issued.
@@ -1149,11 +1187,11 @@ therefore shows the same syntax peculiars as discussed
above. Nevertheless, in practice they are usually sufficient. For
example
\begin{verbatim}
-\newcommand\calulateheight[1]{%
+\newcommand\calculateheight[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}|
+hold a specific number of text lines. Thus after |\calculateheight{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.
@@ -1216,8 +1254,35 @@ cases
\item Lowercasing
\item Titlecasing (only applies for the start of the input)
\end{itemize}
+
The command \cs{DeclareCaseChangeEquivalent} provides a way to substitute a
command by an alternative version when it is found inside a case changing
-situation.
+situation. There are three commands for customising the case changing of
+codepoints
+\begin{decl}
+ |\DeclareLowercaseMapping| \oarg{locale} \arg{codepoint} \arg{output} \\
+ |\DeclareTitlecaseMapping| \oarg{locale} \arg{codepoint} \arg{output} \\
+ |\DeclareUppercaseMapping| \oarg{locale} \arg{codepoint} \arg{output}
+\end{decl}
+All three take a \meta{codepoint} (as an integer expression) and will
+result in the \meta{output} being produced under the appropriate case changing
+operation. The optional \meta{locale} can be given if the mapping should only
+apply to a specific one: this is given in BCP-47 format
+(\url{https://en.wikipedia.org/wiki/IETF_language_tag}). For example,
+the kernel customises the mapping for U+01F0 (\v{j}) when uppercasing in
+8-bit engines:
+\begin{quotation}
+ |\DeclareUppercaseMapping{"01F0}{\v{J}}|
+\end{quotation}
+as there is no pre-composed \v{J} character, and this is problematic if
+the engine does not support Unicode natively. Similarly, to set a locale
+\texttt{xx} to behave in the same way as Turkish and retain the difference
+between dotted- and dotless-i, one could use for example
+\begin{quotation}
+ |\DeclareLowercaseMapping{xx}{"0049}{\i}|\\
+ |\DeclareLowercaseMapping{xx}{"0130}{i}|\\
+ |\DeclareUppercaseMapping{xx}{"0069}{\.{I}}|\\
+ |\DeclareUppercaseMapping{xx}{"0131}{I}|
+\end{quotation}
\end{document}
diff --git a/macros/latex-dev/base/utf8ienc.pdf b/macros/latex-dev/base/utf8ienc.pdf
index d211ec2de1..d8b84af1b4 100644
--- a/macros/latex-dev/base/utf8ienc.pdf
+++ b/macros/latex-dev/base/utf8ienc.pdf
Binary files differ
diff --git a/macros/latex-dev/base/webcomp.pdf b/macros/latex-dev/base/webcomp.pdf
index a7e1a07aec..86adc3d75f 100644
--- a/macros/latex-dev/base/webcomp.pdf
+++ b/macros/latex-dev/base/webcomp.pdf
Binary files differ
diff --git a/macros/latex-dev/required/amsmath/README.md b/macros/latex-dev/required/amsmath/README.md
index 059ebb7f30..a636bfca30 100644
--- a/macros/latex-dev/required/amsmath/README.md
+++ b/macros/latex-dev/required/amsmath/README.md
@@ -1,7 +1,7 @@
The amsmath bundle for LaTeX
============================
-Release 2023-05-01 pre-release 0
+Release 2023-06-01 pre-release 3
Overview
--------
@@ -77,5 +77,5 @@ version 1.3c or later.
-----
<p>Copyright (C) 2001-2004, 2007, 2008, 2010, 2011, 2013 American Mathematical Society. <br />
-<p>Copyright (C) 2016-2022 The LaTeX Project and American Mathematical Society. <br />
+<p>Copyright (C) 2016-2023 The LaTeX Project and American Mathematical Society. <br />
diff --git a/macros/latex-dev/required/amsmath/amsbsy.ins b/macros/latex-dev/required/amsmath/amsbsy.ins
index c35a72dad6..62b4e9a67c 100644
--- a/macros/latex-dev/required/amsmath/amsbsy.ins
+++ b/macros/latex-dev/required/amsmath/amsbsy.ins
@@ -26,7 +26,7 @@
\preamble
Copyright (C) 1995, 1999 American Mathematical Society.
-Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amsbsy.pdf b/macros/latex-dev/required/amsmath/amsbsy.pdf
index fef1eb8058..6111ecae01 100644
--- a/macros/latex-dev/required/amsmath/amsbsy.pdf
+++ b/macros/latex-dev/required/amsmath/amsbsy.pdf
Binary files differ
diff --git a/macros/latex-dev/required/amsmath/amscd.dtx b/macros/latex-dev/required/amsmath/amscd.dtx
index 1ed5be6b67..85475708cc 100644
--- a/macros/latex-dev/required/amsmath/amscd.dtx
+++ b/macros/latex-dev/required/amsmath/amscd.dtx
@@ -2,7 +2,7 @@
% \iffalse meta-comment
%
% Copyright (C) 1995, 1999 American Mathematical Society.
-% Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+% Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amscd.ins b/macros/latex-dev/required/amsmath/amscd.ins
index 5ecf051583..56aedca375 100644
--- a/macros/latex-dev/required/amsmath/amscd.ins
+++ b/macros/latex-dev/required/amsmath/amscd.ins
@@ -1,6 +1,6 @@
%%
%% Copyright (C) 2010 American Mathematical Society.
-%% Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+%% Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3c
@@ -25,7 +25,7 @@
\preamble
Copyright (C) 1995, 1999 American Mathematical Society.
-Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amscd.pdf b/macros/latex-dev/required/amsmath/amscd.pdf
index 54650bb11d..a2c2ed3461 100644
--- a/macros/latex-dev/required/amsmath/amscd.pdf
+++ b/macros/latex-dev/required/amsmath/amscd.pdf
Binary files differ
diff --git a/macros/latex-dev/required/amsmath/amsgen.dtx b/macros/latex-dev/required/amsmath/amsgen.dtx
index 0493940071..6c4aefed67 100644
--- a/macros/latex-dev/required/amsmath/amsgen.dtx
+++ b/macros/latex-dev/required/amsmath/amsgen.dtx
@@ -2,7 +2,7 @@
% \iffalse meta-comment
%
% Copyright (C) 1995, 1999 American Mathematical Society.
-% Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+% Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amsgen.ins b/macros/latex-dev/required/amsmath/amsgen.ins
index 7d845e61cf..faef4aa275 100644
--- a/macros/latex-dev/required/amsmath/amsgen.ins
+++ b/macros/latex-dev/required/amsmath/amsgen.ins
@@ -25,7 +25,7 @@
\preamble
Copyright (C) 1995, 1999 American Mathematical Society.
-Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amsgen.pdf b/macros/latex-dev/required/amsmath/amsgen.pdf
index 487f9c57dd..d390ea31c1 100644
--- a/macros/latex-dev/required/amsmath/amsgen.pdf
+++ b/macros/latex-dev/required/amsmath/amsgen.pdf
Binary files differ
diff --git a/macros/latex-dev/required/amsmath/amsldoc.pdf b/macros/latex-dev/required/amsmath/amsldoc.pdf
index 75882027b2..e4a1de1d67 100644
--- a/macros/latex-dev/required/amsmath/amsldoc.pdf
+++ b/macros/latex-dev/required/amsmath/amsldoc.pdf
Binary files differ
diff --git a/macros/latex-dev/required/amsmath/amsldoc.tex b/macros/latex-dev/required/amsmath/amsldoc.tex
index 4a8230e39f..5c4b9e0d89 100644
--- a/macros/latex-dev/required/amsmath/amsldoc.tex
+++ b/macros/latex-dev/required/amsmath/amsldoc.tex
@@ -1,6 +1,6 @@
%
% Copyright (C) 1995, 2000, 2013 American Mathematical Society.
-% Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+% Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amsmath.dtx b/macros/latex-dev/required/amsmath/amsmath.dtx
index 34d17b65f0..bf8aa418df 100644
--- a/macros/latex-dev/required/amsmath/amsmath.dtx
+++ b/macros/latex-dev/required/amsmath/amsmath.dtx
@@ -2,7 +2,7 @@
% \iffalse meta-comment
%
% Copyright (C) 1995, 2000, 2013 American Mathematical Society.
-% Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+% Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
@@ -86,7 +86,7 @@ Bug reports can be opened (category \texttt{#1}) at\\%
% \end{macrocode}
%
% \begin{macrocode}
-\ProvidesPackage{amsmath}[2022/04/08 v2.17n AMS math features]
+\ProvidesPackage{amsmath}[2023/05/13 v2.17o AMS math features]
% \end{macrocode}
%
% \section{Catcode defenses}
@@ -6261,9 +6261,10 @@ Cannot use `split' here;\MessageBreak trying to recover with `aligned'}%
% Standard \latex/ provides three environments for one-line equations:
% \cn{[}\cn{]}, \env{equation}, and \env{displaymath}. We add
% \env{equation*} as a synonym for \env{displaymath}.
+% \changes{v2.17o}{2023/05/13}{Do not error if \cs{eqno} not primitive (gh/1059)}
% \begin{macrocode}
-\@saveprimitive\leqno\@@leqno
-\@saveprimitive\eqno\@@eqno
+\let\@@eqno\eqno
+\let\@@leqno\leqno
\def\eqno{\@@eqno\let\eqno\relax\let\leqno\relax}
\def\leqno{\@@leqno\let\leqno\relax\let\eqno\relax}
%
diff --git a/macros/latex-dev/required/amsmath/amsmath.ins b/macros/latex-dev/required/amsmath/amsmath.ins
index 82876ffc5d..f92839f959 100644
--- a/macros/latex-dev/required/amsmath/amsmath.ins
+++ b/macros/latex-dev/required/amsmath/amsmath.ins
@@ -1,6 +1,6 @@
%%
%% Copyright (C) 2010 American Mathematical Society.
-%% Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+%% Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3c
@@ -25,7 +25,7 @@
\preamble
Copyright (C) 1995, 1999, 2000, 2013 American Mathematical Society.
-Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amsmath.pdf b/macros/latex-dev/required/amsmath/amsmath.pdf
index 3f4832c1d9..448b93eb6e 100644
--- a/macros/latex-dev/required/amsmath/amsmath.pdf
+++ b/macros/latex-dev/required/amsmath/amsmath.pdf
Binary files differ
diff --git a/macros/latex-dev/required/amsmath/amsopn.dtx b/macros/latex-dev/required/amsmath/amsopn.dtx
index 110a5fa8be..b089749c17 100644
--- a/macros/latex-dev/required/amsmath/amsopn.dtx
+++ b/macros/latex-dev/required/amsmath/amsopn.dtx
@@ -2,7 +2,7 @@
% \iffalse meta-comment
%
% Copyright (C) 1995, 1999 American Mathematical Society.
-% Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+% Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amsopn.ins b/macros/latex-dev/required/amsmath/amsopn.ins
index 8a57404c1e..859e3d7e5a 100644
--- a/macros/latex-dev/required/amsmath/amsopn.ins
+++ b/macros/latex-dev/required/amsmath/amsopn.ins
@@ -1,6 +1,6 @@
%%
%% Copyright (C) 2010 American Mathematical Society.
-%% Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+%% Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3c
@@ -25,7 +25,7 @@
\preamble
Copyright (C) 1995, 1999 American Mathematical Society.
-Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amsopn.pdf b/macros/latex-dev/required/amsmath/amsopn.pdf
index 03ebc9dcc8..600d07b451 100644
--- a/macros/latex-dev/required/amsmath/amsopn.pdf
+++ b/macros/latex-dev/required/amsmath/amsopn.pdf
Binary files differ
diff --git a/macros/latex-dev/required/amsmath/amstext.dtx b/macros/latex-dev/required/amsmath/amstext.dtx
index 7498040214..a4bc541d34 100644
--- a/macros/latex-dev/required/amsmath/amstext.dtx
+++ b/macros/latex-dev/required/amsmath/amstext.dtx
@@ -2,7 +2,7 @@
% \iffalse meta-comment
%
% Copyright (C) 1995, 1999 American Mathematical Society.
-% Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+% Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amstext.ins b/macros/latex-dev/required/amsmath/amstext.ins
index 3ba3000eb8..11ed56cc3c 100644
--- a/macros/latex-dev/required/amsmath/amstext.ins
+++ b/macros/latex-dev/required/amsmath/amstext.ins
@@ -1,6 +1,6 @@
%%
%% Copyright (C) 2010 American Mathematical Society.
-%% Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+%% Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3c
@@ -25,7 +25,7 @@
\preamble
Copyright (C) 1995, 1999 American Mathematical Society.
-Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amstext.pdf b/macros/latex-dev/required/amsmath/amstext.pdf
index 7478fd056f..22d74846a0 100644
--- a/macros/latex-dev/required/amsmath/amstext.pdf
+++ b/macros/latex-dev/required/amsmath/amstext.pdf
Binary files differ
diff --git a/macros/latex-dev/required/amsmath/amsxtra.dtx b/macros/latex-dev/required/amsmath/amsxtra.dtx
index c2bc4bbd26..a1f2c6686c 100644
--- a/macros/latex-dev/required/amsmath/amsxtra.dtx
+++ b/macros/latex-dev/required/amsmath/amsxtra.dtx
@@ -2,7 +2,7 @@
% \iffalse meta-comment
%
% Copyright (C) 1995, 1999 American Mathematical Society.
-% Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+% Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amsxtra.ins b/macros/latex-dev/required/amsmath/amsxtra.ins
index 70f50c6bcb..4707222513 100644
--- a/macros/latex-dev/required/amsmath/amsxtra.ins
+++ b/macros/latex-dev/required/amsmath/amsxtra.ins
@@ -1,6 +1,6 @@
%%
%% Copyright (C) 2010 American Mathematical Society.
-%% Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+%% Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3c
@@ -25,7 +25,7 @@
\preamble
Copyright (C) 1995, 1999 American Mathematical Society.
-Copyright (C) 2016-2022 LaTeX Project and American Mathematical Society.
+Copyright (C) 2016-2023 LaTeX Project and American Mathematical Society.
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3c
diff --git a/macros/latex-dev/required/amsmath/amsxtra.pdf b/macros/latex-dev/required/amsmath/amsxtra.pdf
index 1c089bcc8b..db5c893578 100644
--- a/macros/latex-dev/required/amsmath/amsxtra.pdf
+++ b/macros/latex-dev/required/amsmath/amsxtra.pdf
Binary files differ
diff --git a/macros/latex-dev/required/amsmath/changes.txt b/macros/latex-dev/required/amsmath/changes.txt
index 83d6c6e3a1..afa03be5dd 100644
--- a/macros/latex-dev/required/amsmath/changes.txt
+++ b/macros/latex-dev/required/amsmath/changes.txt
@@ -2,6 +2,11 @@
All changes above are only part of the development branch for the next release.
================================================================================
+
+2023-05-13 David Carlisle <David.Carlisle@latex-project.org>
+
+ * amsmath.dtx: Adjust the definition of \@@eqno (gh/1059)
+
#########################
# 2022-06-01 Release
#########################
diff --git a/macros/latex-dev/required/amsmath/subeqn.pdf b/macros/latex-dev/required/amsmath/subeqn.pdf
index 396c9f26ea..a57bf08977 100644
--- a/macros/latex-dev/required/amsmath/subeqn.pdf
+++ b/macros/latex-dev/required/amsmath/subeqn.pdf
Binary files differ
diff --git a/macros/latex-dev/required/amsmath/technote.pdf b/macros/latex-dev/required/amsmath/technote.pdf
index ae2549ac2a..fa8c5fb8d3 100644
--- a/macros/latex-dev/required/amsmath/technote.pdf
+++ b/macros/latex-dev/required/amsmath/technote.pdf
Binary files differ
diff --git a/macros/latex-dev/required/amsmath/testmath.pdf b/macros/latex-dev/required/amsmath/testmath.pdf
index a18992e79c..91af9de869 100644
--- a/macros/latex-dev/required/amsmath/testmath.pdf
+++ b/macros/latex-dev/required/amsmath/testmath.pdf
Binary files differ
diff --git a/macros/latex-dev/required/firstaid/changes.txt b/macros/latex-dev/required/firstaid/changes.txt
index 31e2439734..e326957807 100644
--- a/macros/latex-dev/required/firstaid/changes.txt
+++ b/macros/latex-dev/required/firstaid/changes.txt
@@ -1,3 +1,14 @@
+2023-05-20 Ulrike Fischer <Ulrike.Fischer@latex-project.org>
+
+ * latex2e-first-aid-for-external-files.dtx: removed temporary fix for
+ GitHub issue 591, unneeded now and it breaks for luatex the fix for gh 989
+ (minipage/list spacing)
+
+2022-12-06 Ulrike Fischer <Ulrike.Fischer@latex-project.org>
+
+ * latex2e-first-aid-for-external-files.dtx (subsection{the crop package first aid}):
+ A first aid for crop after changes to \rlap and \stockwidth/\stockheight
+
2022-11-28 Ulrike Fischer <Ulrike.Fischer@latex-project.org>
* latex2e-first-aid-for-external-files.dtx (subsection{the songs package first aid}):
diff --git a/macros/latex-dev/required/firstaid/latex2e-first-aid-for-external-files.dtx b/macros/latex-dev/required/firstaid/latex2e-first-aid-for-external-files.dtx
index 0d9ce67bca..90958ed777 100644
--- a/macros/latex-dev/required/firstaid/latex2e-first-aid-for-external-files.dtx
+++ b/macros/latex-dev/required/firstaid/latex2e-first-aid-for-external-files.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-%% File: latex2e-first-aid-for-external-files.dtx (C) Copyright 2020-2022
+%% File: latex2e-first-aid-for-external-files.dtx (C) Copyright 2020-2023
%%
%% The LaTeX Project and any individual authors listed elsewhere
%% in this file.
@@ -65,7 +65,7 @@
%
% For that reason, it is put into a separate bundle so that we can
% update it easily without requiring the CTAN maintainers to
-% install a new full LaTeX system just because we take out (or add)
+% install a new full \LaTeX{} system just because we take out (or add)
% a fix for a package here.
%
% In the best case scenario the file documented here should be
@@ -111,8 +111,8 @@
% \end{macrocode}
%
% \begin{macrocode}
-\def\LaTeXFirstAidDate{2022/11/28}
-\def\LaTeXFirstAidVersion{v1.0w}
+\def\LaTeXFirstAidDate{2023/05/20}
+\def\LaTeXFirstAidVersion{v1.0z}
% \end{macrocode}
%
% \begin{macrocode}
@@ -429,7 +429,7 @@
% \subsection{The \pkg{songs} package first aid}
%
% The songs package uses \cs{obeylines} and redefines \cs{par} for special effect.
-% this no longer works in LaTeX 2022-06-01 (gh issue 367). The following
+% this no longer works in \LaTeX{} 2022-06-01 (gh issue 367). The following
% fixes at least one failure.
% \begin{macrocode}
\AddToHook{file/songs.sty/after}[firstaid]{%
@@ -443,6 +443,41 @@
}
% \end{macrocode}
%
+% \subsection{The \pkg{crop} package first aid}
+%
+% The crop packages fails currently due to two \LaTeX{} changes:
+% It doesn't know that \cs{stockheight} and \cs{stockwidth}
+% are now defined, and doesn't take into account that \cs{rlap}
+% is robust (https://github.com/rrthomas/crop/issues/2).
+% The first is addressed by setting the dimension if they are zero or
+% negative. For the second we locally change the meaning of \cs{protect}
+%
+% \begin{macrocode}
+\AddToHook{file/crop.sty/after}[firstaid]{%
+ \FirstAidNeededT{crop}{sty}{2017/11/19 1.10 crop marks (mf)}%
+ {%
+ \ifdim\stockwidth > 0pt \else \stockwidth\paperwidth \fi
+ \ifdim\stockheight > 0pt \else \stockheight\paperheight \fi
+ \renewcommand*\CROP@genreflect[1]{%
+ \leavevmode
+ \dimen0\CROP@horigin
+ \kern2\dimen0
+ \begingroup
+ \set@typeset@protect %change protect
+ \reflectbox{%
+ \hb@xt@\paperwidth{%
+ \vbox to\paperheight{%
+ #1%
+ \vss
+ }%
+ \hss
+ }%
+ }%
+ \endgroup
+ }
+ }%
+}
+% \end{macrocode}
% \begin{macrocode}
%</kernel>
% \end{macrocode}
@@ -640,63 +675,6 @@
% \end{macrocode}
%
%
-% \subsection[Temporary fixes for the kernel (until the next
-% patch-level release)]
-% {Temporary fixes for the kernel \\
-% (until the next patch-level release)}
-%
-% This fixes GitHub issue 591. It is only needed in Lua\TeX\ and replaces just one
-% instance of \cs{tex\_par:D} with the following version which removes
-% other nodes in the current list first.
-% \begin{macrocode}
-\ExplSyntaxOn
-\sys_if_engine_luatex:T
- {
- \newluafunction \g__para_end_empty_par_id_int
- \exp_args:Nx \everyjob {
- \exp_not:V \everyjob
- \exp_not:N \lua_now:n {
- local~texnest, flush_list, par_token = tex.nest, node.flush_list, token.create'tex_par:D'~
- lua.get_functions_table()[\int_use:N \g__para_end_empty_par_id_int] = function()
- local~nest_level = texnest.top~
- local~cur_head = nest_level.head~
- flush_list(cur_head.next)
- nest_level.tail, cur_head.next = cur_head, nil~
- token.put_next(par_token)
- end
- }
- }
- \protected \luadef \__para_end_empty_par: \g__para_end_empty_par_id_int
- \group_begin:
- \cs_set:Npn \__para_extract_everypar:w #1 \the \toks #2 \s_stop
- {
- \tl_gset:Nn \g__para_standard_everypar_tl {
- \box_gset_to_last:N \g_para_indent_box
- \group_begin:
- \__para_end_empty_par:
- \group_end:
- \tex_everypar:D { \msg_error:nnnn { hooks }{ para-mode }{before}{vertical} }
- \@kernel@before@para@before
- \hook_use:n {para/before}
- \group_begin:
- \tex_everypar:D {}
- \skip_zero:N \tex_parskip:D
- \tex_noindent:D
- \group_end:
- \tex_everypar:D{\g__para_standard_everypar_tl}
- \@kernel@before@para@begin
- \hook_use:n {para/begin}
- \if_mode_horizontal: \else:
- \msg_error:nnnn { hooks }{ para-mode }{begin}{vertical} \fi:
- \__para_handle_indent:
- \the \toks #2
- }
- }
- \exp_last_unbraced:No \__para_extract_everypar:w \g__para_standard_everypar_tl \s_stop
- \group_end:
- }
-\ExplSyntaxOff
-% \end{macrocode}
%
%
% \begin{macrocode}
diff --git a/macros/latex-dev/required/firstaid/latex2e-first-aid-for-external-files.pdf b/macros/latex-dev/required/firstaid/latex2e-first-aid-for-external-files.pdf
index b525f8eea8..991a11ec54 100644
--- a/macros/latex-dev/required/firstaid/latex2e-first-aid-for-external-files.pdf
+++ b/macros/latex-dev/required/firstaid/latex2e-first-aid-for-external-files.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/README.md b/macros/latex-dev/required/tools/README.md
index a7e8675cb8..41e6036b98 100644
--- a/macros/latex-dev/required/tools/README.md
+++ b/macros/latex-dev/required/tools/README.md
@@ -1,7 +1,7 @@
The LaTeX `tools` bundle
========================
-Release 2023-05-01 pre-release 0
+Release 2023-06-01 pre-release 3
Overview
--------
diff --git a/macros/latex-dev/required/tools/afterpage.dtx b/macros/latex-dev/required/tools/afterpage.dtx
index cf949c0aca..b94a85d26d 100644
--- a/macros/latex-dev/required/tools/afterpage.dtx
+++ b/macros/latex-dev/required/tools/afterpage.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/afterpage.ins b/macros/latex-dev/required/tools/afterpage.ins
index 3aa1679f77..6fec5edc6f 100644
--- a/macros/latex-dev/required/tools/afterpage.ins
+++ b/macros/latex-dev/required/tools/afterpage.ins
@@ -3,7 +3,7 @@
%% driver files from the doc files in this package when run through
%% LaTeX or TeX.
%%
-%% Copyright (C) 1993-2022
+%% Copyright (C) 1993-2023
%% The LaTeX Project and any individual authors listed elsewhere
%% in this file.
%%
@@ -45,7 +45,7 @@ The source is maintained by the LaTeX Project team and bug
reports for it can be opened at https://latex-project.org/bugs/
(but please observe conditions on bug reports sent to that address!)
-Copyright (C) 1993-2022
+Copyright (C) 1993-2023
The LaTeX Project and any individual authors listed elsewhere
in this file.
diff --git a/macros/latex-dev/required/tools/afterpage.pdf b/macros/latex-dev/required/tools/afterpage.pdf
index 1b117523cd..6efc9c6d4c 100644
--- a/macros/latex-dev/required/tools/afterpage.pdf
+++ b/macros/latex-dev/required/tools/afterpage.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/array.dtx b/macros/latex-dev/required/tools/array.dtx
index 4b163b5f18..72e2f095e9 100644
--- a/macros/latex-dev/required/tools/array.dtx
+++ b/macros/latex-dev/required/tools/array.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/array.pdf b/macros/latex-dev/required/tools/array.pdf
index 5a62c4c93d..1526176b44 100644
--- a/macros/latex-dev/required/tools/array.pdf
+++ b/macros/latex-dev/required/tools/array.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/bm.dtx b/macros/latex-dev/required/tools/bm.dtx
index daf4dce66b..51ae53f041 100644
--- a/macros/latex-dev/required/tools/bm.dtx
+++ b/macros/latex-dev/required/tools/bm.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/bm.ins b/macros/latex-dev/required/tools/bm.ins
index 51243a6090..a7424a0e67 100644
--- a/macros/latex-dev/required/tools/bm.ins
+++ b/macros/latex-dev/required/tools/bm.ins
@@ -3,7 +3,7 @@
%% driver files from the doc files in this package when run through
%% LaTeX or TeX.
%%
-%% Copyright (C) 1993-2022
+%% Copyright (C) 1993-2023
%% The LaTeX Project and any individual authors listed elsewhere
%% in this file.
%%
@@ -45,7 +45,7 @@ The source is maintained by the LaTeX Project team and bug
reports for it can be opened at https://latex-project.org/bugs/
(but please observe conditions on bug reports sent to that address!)
-Copyright (C) 1993-2022
+Copyright (C) 1993-2023
The LaTeX Project and any individual authors listed elsewhere
in this file.
diff --git a/macros/latex-dev/required/tools/bm.pdf b/macros/latex-dev/required/tools/bm.pdf
index 52ab388d9d..df46ae81bb 100644
--- a/macros/latex-dev/required/tools/bm.pdf
+++ b/macros/latex-dev/required/tools/bm.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/calc.dtx b/macros/latex-dev/required/tools/calc.dtx
index 97ef72e7b9..c243eed8d3 100644
--- a/macros/latex-dev/required/tools/calc.dtx
+++ b/macros/latex-dev/required/tools/calc.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/calc.pdf b/macros/latex-dev/required/tools/calc.pdf
index 21bc238389..e536d9581e 100644
--- a/macros/latex-dev/required/tools/calc.pdf
+++ b/macros/latex-dev/required/tools/calc.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/changes.txt b/macros/latex-dev/required/tools/changes.txt
index 7b3e63dca5..fc1a9fc08b 100644
--- a/macros/latex-dev/required/tools/changes.txt
+++ b/macros/latex-dev/required/tools/changes.txt
@@ -4,6 +4,25 @@ 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.
=======================================================================
+2023-05-11 Ulrike Fischer <Ulrike.Fischer@latex-project.org>
+
+ * showkeys.dtx: Use label hook if format new enough.
+
+2023-04-15 David Carlisle <David.Carlisle@latex-project.org>
+
+ * shellesc.dtx: Normalise use of "." in messages. github/1008
+
+2023-03-30 Frank Mittelbach <Frank.Mittelbach@latex-project.org>
+
+ * multicol.dtx (subsection{The output routines}]):
+ Make column min depth customizable through the command
+ \multicolmindepthstring defaulting to 'p' (gh/698)
+
+2023-02-25 Frank Mittelbach <Frank.Mittelbach@latex-project.org>
+
+ * multicol.dtx:
+ Delay returning boxed multicols so that all parameters get restored first
+ in case the boxed multicols is used into another multicols (gh/1002)
================================================================================
All changes above are only part of the development branch for the next release.
diff --git a/macros/latex-dev/required/tools/dcolumn.dtx b/macros/latex-dev/required/tools/dcolumn.dtx
index 7415e23752..cfb7b4d33e 100644
--- a/macros/latex-dev/required/tools/dcolumn.dtx
+++ b/macros/latex-dev/required/tools/dcolumn.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/dcolumn.pdf b/macros/latex-dev/required/tools/dcolumn.pdf
index 9b5782c333..d1bbbd4576 100644
--- a/macros/latex-dev/required/tools/dcolumn.pdf
+++ b/macros/latex-dev/required/tools/dcolumn.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/delarray.dtx b/macros/latex-dev/required/tools/delarray.dtx
index d8aba52f32..86a1a6203f 100644
--- a/macros/latex-dev/required/tools/delarray.dtx
+++ b/macros/latex-dev/required/tools/delarray.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/delarray.pdf b/macros/latex-dev/required/tools/delarray.pdf
index a2405903fa..7505f08b43 100644
--- a/macros/latex-dev/required/tools/delarray.pdf
+++ b/macros/latex-dev/required/tools/delarray.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/enumerate.dtx b/macros/latex-dev/required/tools/enumerate.dtx
index 89910438e9..49179cfa06 100644
--- a/macros/latex-dev/required/tools/enumerate.dtx
+++ b/macros/latex-dev/required/tools/enumerate.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/enumerate.pdf b/macros/latex-dev/required/tools/enumerate.pdf
index 5a2cb393b3..26b0872cbe 100644
--- a/macros/latex-dev/required/tools/enumerate.pdf
+++ b/macros/latex-dev/required/tools/enumerate.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/fileerr.dtx b/macros/latex-dev/required/tools/fileerr.dtx
index 59c1bbbbec..eef222bb6e 100644
--- a/macros/latex-dev/required/tools/fileerr.dtx
+++ b/macros/latex-dev/required/tools/fileerr.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/fileerr.pdf b/macros/latex-dev/required/tools/fileerr.pdf
index e9000aee21..3d7e0a8d15 100644
--- a/macros/latex-dev/required/tools/fileerr.pdf
+++ b/macros/latex-dev/required/tools/fileerr.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/fontsmpl.dtx b/macros/latex-dev/required/tools/fontsmpl.dtx
index de2b55a608..525065cde5 100644
--- a/macros/latex-dev/required/tools/fontsmpl.dtx
+++ b/macros/latex-dev/required/tools/fontsmpl.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/fontsmpl.pdf b/macros/latex-dev/required/tools/fontsmpl.pdf
index 09a27818c7..c3f711a28f 100644
--- a/macros/latex-dev/required/tools/fontsmpl.pdf
+++ b/macros/latex-dev/required/tools/fontsmpl.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/ftnright.dtx b/macros/latex-dev/required/tools/ftnright.dtx
index 1a7f7f584f..00e98c3f77 100644
--- a/macros/latex-dev/required/tools/ftnright.dtx
+++ b/macros/latex-dev/required/tools/ftnright.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/ftnright.pdf b/macros/latex-dev/required/tools/ftnright.pdf
index 22a7ad4e82..846ae64125 100644
--- a/macros/latex-dev/required/tools/ftnright.pdf
+++ b/macros/latex-dev/required/tools/ftnright.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/hhline.dtx b/macros/latex-dev/required/tools/hhline.dtx
index 74143d1373..49ac1ae208 100644
--- a/macros/latex-dev/required/tools/hhline.dtx
+++ b/macros/latex-dev/required/tools/hhline.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/hhline.pdf b/macros/latex-dev/required/tools/hhline.pdf
index a3912de489..c9068dd180 100644
--- a/macros/latex-dev/required/tools/hhline.pdf
+++ b/macros/latex-dev/required/tools/hhline.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/indentfirst.dtx b/macros/latex-dev/required/tools/indentfirst.dtx
index dff777d29d..295b678fd8 100644
--- a/macros/latex-dev/required/tools/indentfirst.dtx
+++ b/macros/latex-dev/required/tools/indentfirst.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/indentfirst.pdf b/macros/latex-dev/required/tools/indentfirst.pdf
index c2e66c96c8..cf168f8093 100644
--- a/macros/latex-dev/required/tools/indentfirst.pdf
+++ b/macros/latex-dev/required/tools/indentfirst.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/layout.dtx b/macros/latex-dev/required/tools/layout.dtx
index 323705e9ba..fffa6d8e18 100644
--- a/macros/latex-dev/required/tools/layout.dtx
+++ b/macros/latex-dev/required/tools/layout.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/layout.pdf b/macros/latex-dev/required/tools/layout.pdf
index b82b65bb14..0dbc2cc257 100644
--- a/macros/latex-dev/required/tools/layout.pdf
+++ b/macros/latex-dev/required/tools/layout.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/longtable.dtx b/macros/latex-dev/required/tools/longtable.dtx
index 72b8727d81..332a95d224 100644
--- a/macros/latex-dev/required/tools/longtable.dtx
+++ b/macros/latex-dev/required/tools/longtable.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/longtable.ins b/macros/latex-dev/required/tools/longtable.ins
index 7f53df7c5e..5c3ad27063 100644
--- a/macros/latex-dev/required/tools/longtable.ins
+++ b/macros/latex-dev/required/tools/longtable.ins
@@ -3,7 +3,7 @@
%% driver files from the doc files in this package when run through
%% LaTeX or TeX.
%%
-%% Copyright (C) 1993-2022
+%% Copyright (C) 1993-2023
%% The LaTeX Project and any individual authors listed elsewhere
%% in this file.
%%
@@ -45,7 +45,7 @@ The source is maintained by the LaTeX Project team and bug
reports for it can be opened at https://latex-project.org/bugs/
(but please observe conditions on bug reports sent to that address!)
-Copyright (C) 1993-2022
+Copyright (C) 1993-2023
The LaTeX Project and any individual authors listed elsewhere
in this file.
diff --git a/macros/latex-dev/required/tools/longtable.pdf b/macros/latex-dev/required/tools/longtable.pdf
index 8444910b91..23f0d9eaf5 100644
--- a/macros/latex-dev/required/tools/longtable.pdf
+++ b/macros/latex-dev/required/tools/longtable.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/multicol.dtx b/macros/latex-dev/required/tools/multicol.dtx
index aa21d75f07..2676d03aa1 100644
--- a/macros/latex-dev/required/tools/multicol.dtx
+++ b/macros/latex-dev/required/tools/multicol.dtx
@@ -20,7 +20,7 @@
% \iffalse This is a METACOMMENT
%
%% Package `multicol' to use with LaTeX2e
-%% Copyright 1989-2019 Frank Mittelbach
+%% Copyright 1989-2023 Frank Mittelbach
%%
%% In addition to the terms of LPPL any distributed version
%% (unchanged or modified) of multicol has to keep the statement
@@ -99,7 +99,7 @@
%<driver> \ProvidesFile{multicol.drv}
% \fi
% \ProvidesFile{multicol.dtx}
- [2021/11/30 v1.9d multicolumn formatting (FMi)]
+ [2023/03/30 v1.9f multicolumn formatting (FMi)]
%
%
%%
@@ -1760,14 +1760,27 @@
\kept@firstmark
\return@nonemptymark{bot}%
\kept@botmark
- \page@sofar
+% \end{macrocode}
+% When the boxed multicol is returned to the page it can happen
+% that it doesn't fit onto it and \LaTeX{} therefore breaks
+% earlier. The problem in that case is that during the generation
+% \cs{hsize}, etc.\ got changed and this setting is still in effect
+% right now, and if this boxed multicol is within, say,
+% \texttt{multicols*} then its output routine gets very upset. We
+% therefore delay returning the result by saving it in box for now
+% until we have left the group below.
+% \changes{v1.9e}{2023/02/25}{Delay returning boxed multicols (gh/1002)}
+% \begin{macrocode}
+ \global\setbox\mc@boxedresult\vbox{%
+ \page@sofar
% \end{macrocode}
%
% \begin{macrocode}
- \global\let\kept@firstmark
- \l@kept@firstmark
- \global\let\kept@botmark
- \l@kept@botmark
+ \global\let\kept@firstmark
+ \l@kept@firstmark
+ \global\let\kept@botmark
+ \l@kept@botmark
+ }%
%<*marktrace>
\mult@info\tw@
{Restore kept marks to\MessageBreak
@@ -1879,12 +1892,15 @@
% \end{macrocode}
% Now it's time to return any footnotes if we are in unrestricted
% mode. In boxed mode footnotes are kept inside, but in that case
-% we have to write another column status into the \texttt{.aux}
+% we have to first return the saved box to the page and then write
+% another column status into the \texttt{.aux}
% file to support \cs{docolaction} in case we have nested
% environments.
% \changes{v1.8s}{2018/04/20}{Support for \cs{docolaction} (issue/39)}
+% \changes{v1.9e}{2023/02/25}{Delay returning boxed multicols (gh/1002)}
% \begin{macrocode}
\if@boxedmulticols
+ \unvbox\mc@boxedresult
\mc@col@status@write
\else
\reinsert@footnotes
@@ -1949,6 +1965,7 @@
% \SpecialMainIndex{\multicolsep}
% \SpecialMainIndex{\multicolbaselineskip}
% \SpecialMainIndex{\partial@page}
+% \SpecialMainIndex{\mc@boxedresult}
% Let us end this section by allocating all the registers used so
% far.
% \begin{macrocode}
@@ -1970,6 +1987,7 @@
\newskip\multicolbaselineskip
\newbox\partial@page
\newbox\last@line
+\newbox\mc@boxedresult
% \end{macrocode}
% And here are their default values:
% \begin{macrocode}
@@ -2119,8 +2137,9 @@
% of the character ``p'' since that is one of the depths that
% compete for the maximum.
% \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
+% \changes{v1.9f}{2023/03/30}{Make column min depth customizable (gh/698)}
% \begin{macrocode}
- \setbox\z@\hbox{p}\global\dimen\tw@\dp\z@
+ \setbox\z@\hbox{\multicolmindepthstring}\global\dimen\tw@\dp\z@
\moveright\multicol@leftmargin
\hbox to\full@width{%
% \end{macrocode}
@@ -2135,9 +2154,11 @@
% The depths of the columns depend on their last lines. To ensure
% that we will always get a similar look as far as the rules are
% concerned we force the depth to be at least the depth of a
-% letter~`p' (which is what we set |\dimen2| to above).
+% letter~`p' or more exactly \cs{multicolmindepthstring} (which is what
+% we set |\dimen2| to above).
+% \changes{v1.9f}{2023/03/30}{Make column min depth customizable (gh/698)}
% \begin{macrocode}
- \rlap{\phantom p}%
+ \rlap{\phantom \multicolmindepthstring}%
}%
% \end{macrocode}
% The processed material might consist of a last line with a
@@ -2179,6 +2200,23 @@
% \end{macrocode}
% \end{macro}
%
+%
+% \begin{macro}{\multicolmindepthstring}
+% The default minimum depth of each column corresponds to the depth
+% of a `p' in the current font. This makes sense for Latin-based
+% languages and was hard-wired intitially, but for Asian languages
+% it is better to use a zero depth (and alternatively one might
+% want to use the depth of a strut or a parentheses). So we now
+% offer a way to adjust this while maintaining backward
+% compatibility. Use \cs{renewcommand} to alter it.
+% \changes{v1.9f}{2023/03/30}{Make column min depth customizable (gh/698)}
+% \begin{macrocode}
+\def\multicolmindepthstring{p}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
% \begin{macro}{\columnseprulecolor}
% \changes{v1.6f}{2006/09/19}{Make the color of the rule a hook}
% By default the vertical rule between columns will be in |\normalcolor|.
diff --git a/macros/latex-dev/required/tools/multicol.ins b/macros/latex-dev/required/tools/multicol.ins
index 9bbf2780ad..fa561e0bb1 100644
--- a/macros/latex-dev/required/tools/multicol.ins
+++ b/macros/latex-dev/required/tools/multicol.ins
@@ -3,7 +3,7 @@
%% driver files from the doc files in this package when run through
%% LaTeX or TeX.
%%
-%% Copyright (C) 1993-2022
+%% Copyright (C) 1993-2023
%% The LaTeX Project and any individual authors listed elsewhere
%% in this file.
%%
@@ -45,7 +45,7 @@ The source is maintained by the LaTeX Project team and bug
reports for it can be opened at https://latex-project.org/bugs/
(but please observe conditions on bug reports sent to that address!)
-Copyright (C) 1993-2022
+Copyright (C) 1993-2023
The LaTeX Project and any individual authors listed elsewhere
in this file.
diff --git a/macros/latex-dev/required/tools/multicol.pdf b/macros/latex-dev/required/tools/multicol.pdf
index 6aabc7f6a2..2363775dda 100644
--- a/macros/latex-dev/required/tools/multicol.pdf
+++ b/macros/latex-dev/required/tools/multicol.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/rawfonts.dtx b/macros/latex-dev/required/tools/rawfonts.dtx
index cbd1ba89ea..4b930f3ea7 100644
--- a/macros/latex-dev/required/tools/rawfonts.dtx
+++ b/macros/latex-dev/required/tools/rawfonts.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/rawfonts.pdf b/macros/latex-dev/required/tools/rawfonts.pdf
index 57454b23c1..ddbc6bce62 100644
--- a/macros/latex-dev/required/tools/rawfonts.pdf
+++ b/macros/latex-dev/required/tools/rawfonts.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/shellesc.dtx b/macros/latex-dev/required/tools/shellesc.dtx
index 4f60ff8d03..97ec542b66 100644
--- a/macros/latex-dev/required/tools/shellesc.dtx
+++ b/macros/latex-dev/required/tools/shellesc.dtx
@@ -1,6 +1,6 @@
% \iffalse
%% Source File: shellesc.dtx
-%% Copyright (C) 2015-2022
+%% Copyright (C) 2015-2023
%%
%% The LaTeX Project and any individual authors listed elsewhere
%% in this file.
@@ -20,7 +20,7 @@
%<driver> \ProvidesFile{shellesc.drv}
% \fi
% \ProvidesFile{shellesc.dtx}
- [2019/11/08 v1.0c unified shell escape interface for LaTeX]
+ [2023/04/15 v1.0d unified shell escape interface for LaTeX]
%
% \iffalse
%<*driver>
@@ -189,6 +189,7 @@
%
% \begin{macro}{\ShellEscape@Lua}
% \changes{v1.0a}{2019/10/13}{loging for gh/195}
+% \changes{v1.0d}{2023/04/15}{Add dots in messages gh/1008}
% Shared Lua code for \verb|\DelayedShellEscape| and \verb|\ShellEscape|.
% \begin{macrocode}
\ifx\directlua\@undefined\else
@@ -197,15 +198,15 @@ local status, msg = os.execute("\luaescapestring{#1}")%
if status == nil then
texio.write_nl("log",%
"runsystem(" .. "\luaescapestring{#1}"%
- .. ")...(" .. msg .. ")\string\n")
+ .. ")...(" .. msg .. ").\string\n")
elseif status == 0 then
texio.write_nl("log",%
"runsystem(" .. "\luaescapestring{#1}"%
- .. ")...executed\string\n")
+ .. ")...executed.\string\n")
else
texio.write_nl("log",%
"runsystem(" .. "\luaescapestring{#1}"%
- .. ")...failed " .. (msg or "") .. "\string\n")
+ .. ")...failed. " .. (msg or "") .. "\string\n")
end
}}
\fi
diff --git a/macros/latex-dev/required/tools/shellesc.pdf b/macros/latex-dev/required/tools/shellesc.pdf
index 9c2ed782fc..8237a0b24e 100644
--- a/macros/latex-dev/required/tools/shellesc.pdf
+++ b/macros/latex-dev/required/tools/shellesc.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/showkeys.dtx b/macros/latex-dev/required/tools/showkeys.dtx
index 3aed90d304..9841004156 100644
--- a/macros/latex-dev/required/tools/showkeys.dtx
+++ b/macros/latex-dev/required/tools/showkeys.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
@@ -39,7 +39,7 @@
%<driver> \ProvidesFile{showkeys.drv}
% \fi
% \ProvidesFile{showkeys.dtx}
- [2022/04/12 v3.18 Show cite and label keys (DPC, MH)]
+ [2023/05/11 v3.19 Show cite and label keys (DPC, MH)]
%
% \iffalse
%<*driver>
@@ -342,16 +342,20 @@
% \begin{macro}{\label}
% \changes{v3.09}{1996/08/30}
% {Add extra group so brace hack works. Donald Arseneau tools/2147}
+% \changes{v3.19}{2023/05/11}
+% {Use label hook if format is new enough.}
% The new definition, print the argument, and then do the old
% definition.
% \begin{macrocode}
-\def\label#1{%
+\@ifl@t@r\fmtversion{2023-06-01}
+ {\AddToHookWithArguments{label}{\SK@\SK@@label{#1}}}
+ {\def\label#1{%
\@bsphack
\SK@\SK@@label{#1}%
\begingroup
\SK@label{#1}%
\endgroup
- \@esphack}
+ \@esphack}}
% \end{macrocode}
% \end{macro}
%
diff --git a/macros/latex-dev/required/tools/showkeys.pdf b/macros/latex-dev/required/tools/showkeys.pdf
index f017f5fd3b..c155beabae 100644
--- a/macros/latex-dev/required/tools/showkeys.pdf
+++ b/macros/latex-dev/required/tools/showkeys.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/somedefs.dtx b/macros/latex-dev/required/tools/somedefs.dtx
index 24916b4286..02653a1393 100644
--- a/macros/latex-dev/required/tools/somedefs.dtx
+++ b/macros/latex-dev/required/tools/somedefs.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/somedefs.pdf b/macros/latex-dev/required/tools/somedefs.pdf
index 6072dca3c7..e5e16f8701 100644
--- a/macros/latex-dev/required/tools/somedefs.pdf
+++ b/macros/latex-dev/required/tools/somedefs.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/tabularx.dtx b/macros/latex-dev/required/tools/tabularx.dtx
index 0d1cbeac34..177d92f12f 100644
--- a/macros/latex-dev/required/tools/tabularx.dtx
+++ b/macros/latex-dev/required/tools/tabularx.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/tabularx.ins b/macros/latex-dev/required/tools/tabularx.ins
index 0c6d26e940..6e81e93432 100644
--- a/macros/latex-dev/required/tools/tabularx.ins
+++ b/macros/latex-dev/required/tools/tabularx.ins
@@ -3,7 +3,7 @@
%% driver files from the doc files in this package when run through
%% LaTeX or TeX.
%%
-%% Copyright (C) 1993-2022
+%% Copyright (C) 1993-2023
%% The LaTeX Project and any individual authors listed elsewhere
%% in this file.
%%
@@ -45,7 +45,7 @@ The source is maintained by the LaTeX Project team and bug
reports for it can be opened at https://latex-project.org/bugs/
(but please observe conditions on bug reports sent to that address!)
-Copyright (C) 1993-2022
+Copyright (C) 1993-2023
The LaTeX Project and any individual authors listed elsewhere
in this file.
diff --git a/macros/latex-dev/required/tools/tabularx.pdf b/macros/latex-dev/required/tools/tabularx.pdf
index 9dc24cdabf..f237e57663 100644
--- a/macros/latex-dev/required/tools/tabularx.pdf
+++ b/macros/latex-dev/required/tools/tabularx.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/theorem.dtx b/macros/latex-dev/required/tools/theorem.dtx
index 2dc0412efb..58476db07e 100644
--- a/macros/latex-dev/required/tools/theorem.dtx
+++ b/macros/latex-dev/required/tools/theorem.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/theorem.pdf b/macros/latex-dev/required/tools/theorem.pdf
index 8d403092c0..d5e952583f 100644
--- a/macros/latex-dev/required/tools/theorem.pdf
+++ b/macros/latex-dev/required/tools/theorem.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/tools-overview.pdf b/macros/latex-dev/required/tools/tools-overview.pdf
index a0d541c796..8db0f5233f 100644
--- a/macros/latex-dev/required/tools/tools-overview.pdf
+++ b/macros/latex-dev/required/tools/tools-overview.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/tools-overview.tex b/macros/latex-dev/required/tools/tools-overview.tex
index 882a2ae77f..3bc325d67c 100644
--- a/macros/latex-dev/required/tools/tools-overview.tex
+++ b/macros/latex-dev/required/tools/tools-overview.tex
@@ -1,7 +1,7 @@
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile{tools-overview.tex}[2015/03/31 v1.0 Tools overview]
-% Copyright (C) 2006-2022
+% Copyright (C) 2006-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/tools.ins b/macros/latex-dev/required/tools/tools.ins
index b93f649153..6898faead3 100644
--- a/macros/latex-dev/required/tools/tools.ins
+++ b/macros/latex-dev/required/tools/tools.ins
@@ -3,7 +3,7 @@
%% driver files from the doc files in this package when run through
%% LaTeX or TeX.
%%
-%% Copyright (C) 1993-2022
+%% Copyright (C) 1993-2023
%% The LaTeX Project and any individual authors listed elsewhere
%% in this file.
%%
@@ -49,7 +49,7 @@ reports for it can be opened at https://latex-project.org/bugs/
(but please observe conditions on bug reports sent to that address!)
-Copyright (C) 1993-2022
+Copyright (C) 1993-2023
The LaTeX Project and any individual authors listed elsewhere
in this file.
diff --git a/macros/latex-dev/required/tools/trace.dtx b/macros/latex-dev/required/tools/trace.dtx
index 93906eb76b..788f831620 100644
--- a/macros/latex-dev/required/tools/trace.dtx
+++ b/macros/latex-dev/required/tools/trace.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/trace.pdf b/macros/latex-dev/required/tools/trace.pdf
index 1f2fe7f2ca..9fe9d8fff3 100644
--- a/macros/latex-dev/required/tools/trace.pdf
+++ b/macros/latex-dev/required/tools/trace.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/varioref.dtx b/macros/latex-dev/required/tools/varioref.dtx
index 579c411868..e801c54f81 100644
--- a/macros/latex-dev/required/tools/varioref.dtx
+++ b/macros/latex-dev/required/tools/varioref.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/varioref.ins b/macros/latex-dev/required/tools/varioref.ins
index cef11f9c2f..dcc41d0176 100644
--- a/macros/latex-dev/required/tools/varioref.ins
+++ b/macros/latex-dev/required/tools/varioref.ins
@@ -3,7 +3,7 @@
%% driver files from the doc files in this package when run through
%% LaTeX or TeX.
%%
-%% Copyright (C) 1993-2022
+%% Copyright (C) 1993-2023
%% The LaTeX Project and any individual authors listed elsewhere
%% in this file.
%%
@@ -45,7 +45,7 @@ The source is maintained by the LaTeX Project team and bug
reports for it can be opened at https://latex-project.org/bugs/
(but please observe conditions on bug reports sent to that address!)
-Copyright (C) 1993-2022
+Copyright (C) 1993-2023
The LaTeX Project and any individual authors listed elsewhere
in this file.
diff --git a/macros/latex-dev/required/tools/varioref.pdf b/macros/latex-dev/required/tools/varioref.pdf
index faa84a5373..7541e2214d 100644
--- a/macros/latex-dev/required/tools/varioref.pdf
+++ b/macros/latex-dev/required/tools/varioref.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/verbatim.dtx b/macros/latex-dev/required/tools/verbatim.dtx
index 2018e85505..0085f166ea 100644
--- a/macros/latex-dev/required/tools/verbatim.dtx
+++ b/macros/latex-dev/required/tools/verbatim.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/verbatim.pdf b/macros/latex-dev/required/tools/verbatim.pdf
index f4e1365707..fd4b0a264e 100644
--- a/macros/latex-dev/required/tools/verbatim.pdf
+++ b/macros/latex-dev/required/tools/verbatim.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/xr.dtx b/macros/latex-dev/required/tools/xr.dtx
index 33e096c6cd..0dd5f3ad95 100644
--- a/macros/latex-dev/required/tools/xr.dtx
+++ b/macros/latex-dev/required/tools/xr.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/xr.pdf b/macros/latex-dev/required/tools/xr.pdf
index 293437b3ab..3607da5d48 100644
--- a/macros/latex-dev/required/tools/xr.pdf
+++ b/macros/latex-dev/required/tools/xr.pdf
Binary files differ
diff --git a/macros/latex-dev/required/tools/xspace.dtx b/macros/latex-dev/required/tools/xspace.dtx
index 7b29b7b0be..807fc9c5df 100644
--- a/macros/latex-dev/required/tools/xspace.dtx
+++ b/macros/latex-dev/required/tools/xspace.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 1993-2023
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
diff --git a/macros/latex-dev/required/tools/xspace.pdf b/macros/latex-dev/required/tools/xspace.pdf
index 0d8075103d..656970c6c3 100644
--- a/macros/latex-dev/required/tools/xspace.pdf
+++ b/macros/latex-dev/required/tools/xspace.pdf
Binary files differ
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/README.md b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/README.md
index 91f89dbfdf..73958edc29 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/README.md
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/README.md
@@ -1,4 +1,4 @@
-<b>Date of last change: 2023-04-24 to version v1.1m</b>
+<b>Date of last change: 2023-05-24 to version v1.1n</b>
# biblatex-gb7714-2015: a biblatex style package
@@ -1600,6 +1600,8 @@ please see the file 'biblatex-gb7714-2015.pdf' for further information!
* 2022/11/07 v1.1k,ctan,github
* 2023/03/31 v1.1l,ctan,github
* 2023/04/24 v1.1m,ctan,github
+* 2023/05/24 v1.1n,ctan,github
+
---------------------------------------------------------
## Update history:
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015-preamble.tex b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015-preamble.tex
index cdfafd74dd..cae76042ca 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015-preamble.tex
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015-preamble.tex
@@ -33,7 +33,7 @@
%\colorlet{gbemphcolor}{violet}
%定义版面,showframe,
-\usepackage[paperwidth=210mm,paperheight=290mm,left=35mm,right=20mm,top=25mm, bottom=20mm,showcrop]{geometry}%,showframe
+\usepackage[paperwidth=210mm,paperheight=290mm,left=40mm,right=15mm,top=25mm, bottom=20mm,showcrop]{geometry}%,showframe
\renewcommand{\baselinestretch}{1.35}
%页面布局的标尺
\usepackage[type=none]{fgruler}
@@ -96,6 +96,8 @@
\usepackage[colorlinks=true,%
pdfstartview=FitH,allcolors=gbemphcolor,
bookmarksopenlevel=4,%
+bookmarksnumbered=true,
+bookmarksopen=true,
bookmarksdepth=4,]{hyperref}
%linkcolor=gbblue,anchorcolor=gbblue,citecolor=gbblue
%linkcolor=black,linkcolor=green,blue,red,cyan, magenta,
@@ -331,7 +333,7 @@ theorem style=plain,fonttitle=\bfseries\heiti,coltitle=gbforestgreen
%--------------列表环境---------------------------------------------
\usepackage[inline]{enumitem} %重设list环境
-\setlist[enumerate]{label=\bfseries\textcolor{gbemphcolor}{(\arabic*)},topsep=2pt,partopsep=0pt,parsep=0pt,%
+\setlist[enumerate]{label=\textbf{(\arabic*)},topsep=2pt,partopsep=0pt,parsep=0pt,%
align=left,leftmargin=0em,itemsep=0.5em,labelwidth=0.1em,itemindent=2.6em,listparindent=2em}%label=$\triangleright$,itemindent=1em
\setlist[itemize]{topsep=2pt,partopsep=0pt,parsep=0pt,%
leftmargin=3em,itemindent=0em}
@@ -394,13 +396,13 @@ itemsep=0pt,leftmargin=0em,itemindent=0em}%注意,font或format中的最后一
\setlength{\parsep}{0pt}
\setlength{\leftmargin}{0pt}%
\setlength{\itemindent}{0pt}%
-\renewcommand*{\makelabel}[1]{\hss\llap{\footnotesize\color{orange}\bfseries##1}}}}
+\renewcommand*{\makelabel}[1]{\hss\llap{\footnotesize\color{gblabelcolor}\bfseries##1}}}}
{\endlist}
\makeatletter
\newcommand{\updateinfo}[2][\@empty]{%
\par\small\addvspace{2ex plus 1ex}%
-\noindent{\color{gbemphcolor}\rule{\linewidth}{2pt}}
+\noindent{\color{gblabelcolor}\rule{\linewidth}{2pt}}
\vskip -\parskip
\ifx\@empty#1 \begin{marglist} \item #2\end{marglist}
\else \begin{marglist} \item[#1] #2\end{marglist} \fi}
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015.pdf b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015.pdf
index 462c1f0409..23f368025f 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015.pdf
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015.pdf
Binary files differ
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015.tex b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015.tex
index f2aabef29f..962aaae18a 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015.tex
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/biblatex-gb7714-2015.tex
@@ -62,39 +62,39 @@ biblatex-gb7714-2015 宏包是为满足《GB/T 7714-2015~~信息与文献~~参
\pagestyle{fancy}
\section{概述}
-《GB/T 7714-2015~~信息与文献~~参考文献著录规则》是国内科技文档参考文献著录的一般标准,国内多数大学、出版社、期刊编辑部对于学位论文、出版物、期刊论文的参考文献要求通常都基于该标准。对于\LaTeX{}用户来说,参考文献生成是典型的自动化应用,通常有两种方法,一是基于bibtex的传统方法,二是基于biblatex的新方法。生成符合GB/T 7714 标准要求的参考文献,这两条路子都已经实践多年。
-基于biblatex的方法,早期有李志奇(icetea)的gbtstyle实现以及Casper Ti. Vector的caspervector样式,然而由于biblatex宏包升级、样式包维护和完善方面的问题,未能达到精确符合国标要求、且具备高可用性、兼容性和可维护性的理想状态。开发biblatex-gb7714-2015 样式包的初衷首先是基于当时这样的状态,其次也为解决很多实际应用中的问题,因此考虑如下原则:
+《GB/T 7714-2015~~信息与文献~~参考文献著录规则》是国内科技文档参考文献著录的一般标准,国内多数大学、出版社、期刊编辑部对于学位论文、出版物、期刊论文的参考文献要求通常都基于该标准。对于\LaTeX{}用户来说,参考文献生成是典型的自动化应用,主要有两种方法,一是基于bibtex的传统方法,二是基于biblatex的新方法。生成符合GB/T 7714 标准要求的参考文献,这两条路都已经实践多年。
+基于biblatex的方法,早期有李志奇(icetea)的gbtstyle实现以及Casper Ti. Vector的caspervector样式,然而由于biblatex宏包升级、样式包维护和完善等方面的问题,未能达到精确符合国标要求、且具备高可用性、兼容性和可维护性的理想状态。开发biblatex-gb7714-2015 样式包的初衷首先是基于当时这样的状态,其次也为解决很多实际应用中的问题,因此考虑如下原则:
\subsection{设计原则}
\begin{enumerate}
\item 兼容性
-由于biblatex的持续升级,一些接口和功能的变化,会使得样式无法使用或者输出结果产生异变。因此biblatex-gb7714-2015宏包设计之初,就一直秉承兼容性原则,力图兼容各版本的biblatex,希望与biblatex v2.8 (in texlive2014) 以上所有版本适配(注意 ctex 2.9.4 的用户需升级 biblatex)。
+由于biblatex的持续升级,一些接口和功能的变化,会使得样式无法使用或者输出结果产生异变。因此biblatex-gb7714-2015宏包设计之初,就一直秉承兼容性原则,力图兼容各版本的biblatex,希望与biblatex v2.8 (in texlive2014) 以上所有版本适配(注意:使用ctex 2.9.4 套件的用户需升级 biblatex或更换使用最新版 texlive)。
出于兼容一些旧的bib文件的考虑,增加对传统参考文献条目类型比如www/electronic/conference/mastersthsis/phdthsis/techreport/standard等的支持。根据国标要求,考虑增加newspaper(报纸析出的文献)、database(数据库)、dataset(数据集)、 software(软件)、map(舆图)、archive(档案)等类型。也为兼容适用于不同样式的bib数据源,增加对一些自定义域的支持,比如gbt7714宏包的bst样式中mark和medium域。此外,也试图去完善样式在不同文档类包括beamer类中的使用问题。
\item 易用性
-参考文献是\LaTeX{}自动化应用之一,尽可能让其自动完成,减少用户的人工干预,包括数据的准备、格式的调整等等。因此宏包试图减少用户对于bib文件的调整,只需要简单地输入文献本身的信息,或者从各类学术网站或利用zotero等工具下载参考文献数据即可,而不需要为了符合国标格式而去手动增添参考文献类型和载体标识等一些数据域,也不必为了文献语言分集、文献排序等去增加语言、排序关键字等数据域,这些所有工作都由宏包自动完成。
+参考文献是\LaTeX{}自动化应用之一,尽可能让其自动完成,减少用户的人工干预,包括数据的准备、格式的调整等等。因此宏包试图减少用户对于bib文件的调整,只需要简单地输入文献本身的信息,或者从各类学术网站或利用zotero等工具下载参考文献数据即可,而不需要为了符合国标格式而去手动增添参考文献类型和载体标识等一些数据域,也不必为了文献语言分集、文献排序等去增加语言、排序关键字等数据域,所有这些工作都由会宏包自动处理。
-为了符合国标要求以及中文参考文献标注习惯,提供丰富的标注(引用)命令,用户只需熟悉几个命令的特性即能够完成两种编制样式下多样的标注格式,包括:顺序编码制的 \verb|\cite|(上标可设置页码)、 \verb|\parencite|(非上标可设置页码)、 \verb|\pagescite|(上标加自动页码)、 \verb|\textcite|(提供作者为主语加非上标编号)、 \verb|\authornumcite|(提供作者为主语加上标编号)、 \verb|\footfullcite|(脚注方式);著者-年份制的\verb|\cite|(作者加年份用括号包围可设置页码)、 \verb|\pagescite|(作者加年份用括号包围自动页码)、
+为了符合国标要求以及中文参考文献标注习惯,提供丰富的标注(引用)命令,用户只需熟悉几个命令的特性即能够完成两种编制样式下多样的标注格式,包括:顺序编码制的 \verb|\cite|(上标可设置页码)、 \verb|\parencite|(非上标可设置页码)、 \verb|\pagescite|(上标加自动页码)、 \verb|\textcite|(提供作者为主语加非上标编号)、 \verb|\authornumcite|(提供作者为主语加上标编号)、 \verb|\footfullcite|(脚注注释);著者-年份制的\verb|\cite|(作者加年份用括号包围可设置页码)、 \verb|\pagescite|(作者加年份用括号包围自动页码)、
\verb|\yearcite|(提供年份用括号包围)、 \verb|\yearpagescite|(提供年份用括号包围自动页码)、
-\verb|\textcite|(提供主语作者加括号包围年份)、 \verb|\footfullcite|(脚注方式)。
+\verb|\textcite|(提供主语作者加括号包围年份)、 \verb|\footfullcite|(脚注注释)。
-习惯natbib的用户也可以直接使用 \verb|\citet| 和 \verb|\citep| 命令,
-也提供一些习惯使用的命令,比如\verb|\citetns|、\verb|\citepns|、
-\verb|\upcite|、\verb|\inlinecite|等让用户可以无缝衔接从bibtex转到biblatex。
+也提供与natbib宏包常用命令同名的命令 \verb|\citet| 和 \verb|\citep|,
+和一些惯常使用的命令,如\verb|\citetns|、\verb|\citepns|、
+\verb|\upcite|、\verb|\inlinecite|等,让用户可以无缝衔接从bibtex转到biblatex。
另外,增加并完善对多语言混合文献表、多语言对照文献表的支持。不同语言文献可按文献自身语言录入,宏包自动识别语言并通过autolang选项自动完成语言切换,针对多语言对照文献表提供了基于条目集和关联条目概念的两种实现方式。
\item 灵活性
-在考虑实现严格符合GB/T 7714-2015标准的格式外,也希望能够针对用户的特殊格式需求,提供方便灵活的定制方式,比如通过设置选项来达到格式的变化。为此,增加了多个方面的设置选项,使用户可以根据自己的需求灵活地调整。主要包括:
+在考虑实现严格符合GB/T 7714-2015标准的格式外,也希望能够针对用户的特殊格式需求,提供方便的定制方式,比如通过设置选项来达到格式的变化。为此,增加了多个方面的设置选项,使用户可以根据自身需求灵活地调整。主要包括:
著录表排序选项:
-sorting选项值(gb7714-2015支持以语言著者-出版年标题升序排列,gbnytd支持以语言著者-出版年标题降序排列,gbynta支持以语言年份作者标题升序排列,gbyntd支持以语言年份作者标题降序排列)、gblanorder 选项(可以设置不同的文种(语言)文献的排列顺序)、sortlocale 选项(可以设置本地语言的排序调整方案,比如zh\_\_pinyin支持汉字字符以拼音排序,zh\_\_stroke以笔画排序,auto/zh以unicode编码排序,zh\_\_gb2312han 以gb2312编码排序)。使用拼音排序时遇到多音字也可以利用key域解决。
+sorting选项值(gb7714-2015支持以语言著者-出版年标题升序排列,gbnytd支持以语言著者-出版年标题降序排列,gbynta支持以语言年份作者标题升序排列,gbyntd支持以语言年份作者标题降序排列)、gblanorder 选项(可以设置不同的文种(语言)文献的排列顺序)、sortlocale 选项(可以设置本地语言的排序调整方案,比如zh\_\_pinyin支持汉字字符以拼音排序,zh\_\_stroke以笔画排序,auto/zh以unicode编码排序,zh\_\_gb2312han 以gb2312编码排序)。使用拼音排序时遇到多音字也可以利用添加key域或使用修改后的locale文件pinyin.pm解决。
@@ -112,11 +112,11 @@ sorting选项值(gb7714-2015支持以语言著者-出版年标题升序排列,
标签格式控制(gbbiblabel选项,可设置标签数字不同的包围符号)、
条目格式控制(gbstyle选项,利用gb7714-2015ms样式可实现中英文献分设不同格式)、
编制样式设置命令(利用\verb|\setaystylesection|和gb7714-2015mx样式实现不同文献节不同的编制方式)、
-格式命令\verb|\bibauthorfont|可设置作者项字体、
-格式命令\verb|\bibtitlefont|可设置标题项字体、
-格式命令\verb|\bibpubfont|可设置出版项字体、
-格式尺寸\verb|\bibitemindent|和\verb|\bibhang|可设置文献表的缩进、
-文献标题控制(gbctexset选项,可设置标题内容由\verb|\bibname|或\verb|\refname|宏调整);
+文献标题控制(gbctexset选项,可设置标题内容由\verb|\bibname|或\verb|\refname|宏调整)、
+命令\verb|\bibauthorfont|可设置作者项字体等格式、
+命令\verb|\bibtitlefont|可设置标题项字体等格式、
+命令\verb|\bibpubfont|可设置出版项字体等格式、
+尺寸\verb|\bibitemindent|和\verb|\bibhang|可设置文献表的缩进等格式;
编码设置选项:
GBK编码兼容(gbcodegbk选项,可设置GBK编码文档编译)等等。
@@ -126,7 +126,8 @@ GBK编码兼容(gbcodegbk选项,可设置GBK编码文档编译)等等。
\item 可维护性
-宏包的长期使用价值体现在宏包的维护和更新上面,追求宏包具有高的可读性、可理解性、可维护性,可为宏包长期发挥作用提供帮助。由于biblatex已经是一个相当成熟完善的宏包,即便是在样式方面考虑也相当全面,这可能与西方出版界对于参考文献的多样且细致的要求有关。而国内只有一个通用标准就是GB/T 7714标准,且除了一些特殊需求要具体实现外,标准中大多数格式要求的实现完全可以借用biblatex提供的标准样式,因此既不需要重新造轮子,也可以使gb7714-2015样式与biblatex宏包的标准样式保持一致的结构、风格和习惯,这样可以大大增加代码可读性和可维护性。通过在biblatex原有样式基础上增加有限修改的方式,并且对代码加上详细注释,可以使得样式包维护者,只需通过学习biblatex,即可轻松理解gb7714-2015样式做的工作,比如做了哪些修改,为什么这么修改,实现了什么样的效果。
+宏包的长期使用价值体现在宏包的维护和更新上面,追求宏包具有高的可读性、可理解性、可维护性,可为宏包长期发挥作用提供帮助。由于biblatex已经是一个相当成熟完善的宏包,即便是在样式方面考虑也相当全面,这可能与西方出版界对于参考文献的多样且细致的要求有关。而国内只有一个通用标准就是GB/T 7714标准,且除了一些特殊需求要具体实现外,标准中大多数格式要求的实现完全可以借用biblatex提供的标准样式,因此既不需要重新造轮子,也可以使gb7714-2015样式与biblatex宏包的标准样式保持一致的结构、风格和习惯,这样可以大大增加代码可读性和可维护性。通过在biblatex原有样式基础上增加有限修改,并对代码加上详细注释,可使维护者只需通过学习biblatex,即可轻松理解gb7714-2015样式的代码。
+%做的工作,比如做了哪些修改,为什么这么修改,实现了什么样的效果。
另外,为方便用户,样式包提供了全面、详实的说明,包括
@@ -225,13 +226,19 @@ GB/T 7714标准的理解和解释(\ref{sec:gbt:std}节)、
\end{figure}
-
+\section{使用说明}
\subsection{最小示例}
-基于biblatex宏包的参考文献生成方法非常简单,例 \ref{code:doc:structrue} 是一个最小工作示例。示例代码中给出了详细注释,介绍了使用biblatex 的tex源文档基本结构,其中gb7714-2015 样式随biblatex宏包加载,
-参考文献数据文件example.bib利用 \verb|\addbibresource|加载 (注意:bib文件需另外准备,详见\ref{sec:bib:bibtex}节),文献表利用 \verb|\printbibliography| 命令输出(可在正文任意位置)。
+基于biblatex宏包的参考文献生成方法非常简单,例 \ref{code:doc:structrue} 是一个最小工作示例。示例代码中给出了详细注释,介绍了使用biblatex 的tex源文档基本结构,其中:
+\begin{itemize}
+\item gb7714-2015 样式随biblatex宏包加载;
+\item bib(参考文献数据)文件利用 \verb|\addbibresource|加载 (注意:bib文件需另外准备,详见\ref{sec:bib:bibtex}节);
+\item 引用文献则在正文中利用\verb|\cite|等命令带上entrykey(文献唯一标识)参数,
+比如\verb|\cite{entrykey}|,
+\item 打印文献表利用 \verb|\printbibliography| 命令输出(可放在正文任意位置)。
+\end{itemize}
\begin{example}{biblatex参考文献生成的最小工作示例}{code:doc:structrue}
\begin{texlist}
@@ -243,7 +250,7 @@ GB/T 7714标准的理解和解释(\ref{sec:gbt:std}节)、
\usepackage[colorlinks=true,pdfstartview=FitH,linkcolor=blue,anchorcolor=violet,citecolor=magenta]{hyperref}
%参考文献工具,加载biblatex宏包,,其后端backend使用biber,%标注(引用)样式citestyle,著录样式bibstyle都采用gb7714-2015样式,两者相同时可以合并为一个选项style
\usepackage[backend=biber,style=gb7714-2015]{biblatex}
- %biblatex宏包的参考文献数据源加载方式
+ %biblatex宏包的参考文献数据源即bib文件加载方式
\addbibresource[location=local]{example.bib}
\begin{document}%正文区开始:
%正文内容,引用参考文献
@@ -284,13 +291,13 @@ GB/T 7714标准的理解和解释(\ref{sec:gbt:std}节)、
上述最小工作示例的编译结果如图\ref{fig:eg:ref}所示。所有基于 biblatex 生成参考文献的文档无论大小万变不离其宗,
若需更全面了解biblatex及参考文献生成高级功能另可参考:
\href{https://github.com/plk/biblatex}{biblatex宏包手册}
-\footnote{地址:\url{https://github.com/plk/biblatex}}、
+%\footnote{地址:\url{https://github.com/plk/biblatex}}、
\href{https://github.com/hushidong/biblatex-zh-cn}{中文版}
-\footnote{地址:\url{https://github.com/hushidong/biblatex-zh-cn}}
+%\footnote{地址:\url{https://github.com/hushidong/biblatex-zh-cn}}
或者
\href{https://github.com/hushidong/biblatex-solution-to-latex-bibliography}{LaTeX 文档中文参考文献的biblatex解决方案}
-\footnote{地址:%
-\url{https://github.com/hushidong/biblatex-solution-to-latex-bibliography}}。
+%\footnote{地址:%
+%\url{https://github.com/hushidong/biblatex-solution-to-latex-bibliography}}。
\subsection{编译方式}
@@ -311,7 +318,7 @@ latexmk -xelatex jobname.tex
\end{example}
-\section{使用说明}
+
\subsection{样式及选项加载}
@@ -374,8 +381,8 @@ perl gb7714texttobib.pl in=textfilename out=bibfilename
\end{example}
其中,
-v1.0m版本增加的gb7714-2015ms样式文件,主要是为了在一个文献表中针对不同语言使用不同的样式,比如中文文献使用GB/T 7714-2015规定的著录格式,而其它语言文献使用biblatex提供的标准样式。
-v1.0r版本增加了gb7714-2015mx样式,主要是为了在一个文档中针对不同参考文献分节使用不同的参考文献样式,比如某些节使用著者年份制,某些节使用顺序编码制。
+v1.0m版本增加的gb7714-2015ms样式文件,主要是为了在一个文献表中针对不同语言使用不同的样式,即中文文献使用GB/T 7714-2015规定的著录格式,而其它语言文献使用biblatex提供的标准样式。
+v1.0r版本增加了gb7714-2015mx样式,主要是为了在一个文档中针对不同参考文献分节使用不同的样式,比如某些节使用著者年份制,某些节使用顺序编码制。
%尽管这些方式不常用,但偶尔也有需求,所以都做了实现。
尽管国标1987和2005版本已经过时,但仍然有些地方还在使用,所以1.0z版本增加了gb7714-1987和gb7714-2005两个版本的样式,也分顺序编码和著者年份制:
@@ -398,11 +405,11 @@ v1.0r版本增加了gb7714-2015mx样式,主要是为了在一个文档中针
\end{example}
-另外,根据国内大学的学位论文的文献生成需求,增加了几个与国标有明显区别的样式,包括:西北农林(gb7714-NWAFU)、华中师范(gb7714-CCNU)、东南大学(gb7714-SEU)等。其他大学的文献样式与国标基本一致,比如上海交大、浙大、复旦等,直接使用即可。另外一些大学与国标略有差别,可以通过简单的设置满足要求,比如清华、科学院大学、中科大、国防科大等,通常在学位论文模板中实现,在egthesis文件夹内,针对一些大学的学位论文参考文献做了测试。
+另外,根据国内大学的学位论文的文献生成需求,增加了几个与国标有明显区别的样式,包括:西北农林(gb7714-NWAFU)、华中师范(gb7714-CCNU)、东南大学(gb7714-SEU)等。其他大学的文献样式与国标基本一致,比如上海交大、浙大、复旦等,直接使用即可。另外一些大学与国标略有差别,可以通过简单的设置满足要求,比如清华、科学院大学、中科大、国防科大等,通常在学位论文模板中实现。而在egthesis文件夹内则对一些大学的学位论文参考文献做了测试。
此外,根据期刊文献生成需求,为文科类期刊增加了如下样式:
-v1.0r版本增加了chinese-erj样式用于生成经济研究期刊的文献;
-v1.1l版本增加了chinese-css样式用于生成社会科学期刊的脚注注释;
+v1.0r版本增加了chinese-erj样式用于生成经济研究期刊的文献;
+v1.1l版本增加了chinese-css样式用于生成社会科学期刊的脚注注释文献;
v1.1m版本增加了chinese-jmw样式用于生成管理世界期刊的文献。
而理工类期刊文献通常与国标差别不大,部分期刊与国标的最大的差异主要是在双语对照文献中,比如计算机学报等,可以通过简单的设置来满足要求,具体可以参考github上的问题。
@@ -434,8 +441,10 @@ v1.1m版本增加了chinese-jmw样式用于生成管理世界期刊的文献。
\subsubsection{新增选项}\label{sec:added:opt}
-样式包新增了一些选项和命令,新增选项更常用一些,所以在本节集中介绍,而新增命令往往涉及更细节的修改,所以在后面介绍各类格式调整的内容中介绍。
-新增选项用于标签对齐方式、出版项缺省处理、责任者(作者)缺省处理等功能的控制,其使用方式与biblatex宏包选项完全相同:
+样式包新增了一些选项。
+%由于选项更为常用,所以在本节集中介绍。
+%而新增命令往往涉及更细节的修改,所以在后面各类格式调整的内容中介绍。
+新增选项用于处理标签对齐、缺省出版项、缺省责任者(作者)处理等,其使用方式与biblatex宏包选项完全相同,主要包括:
\begin{description}
\pdfbookmark[4]{gbalign}{gbalign}
@@ -443,10 +452,11 @@ v1.1m版本增加了chinese-jmw样式用于生成管理世界期刊的文献。
为控制文献表数字序号标签增加的选项,用于选择是否生成序号标签及其对齐方式。
\begin{itemize}
- \item gbalign=right,数字序号标签,是list环境中的标签右对齐,是gb7714-2015样式的默认选项;
- \item gbalign=left,数字序号标签,是list环境中的标签左对齐;
- \item gbalign=center,数字序号标签,是list环境中的等宽标签,数字在[]内居中;
- \item gbalign=gb7714-2015,数字序号标签,是项对齐方式,即段落环境中标签使用原始宽度,标签与条目内容等间距。
+ \item gbalign=right,是list环境中的右对齐数字序号标签,是gb7714-2015样式的默认选项;
+ \item gbalign=left,是list环境中的左对齐数字序号标签;
+ \item gbalign=center,是list环境中的等宽数字序号标签,数字在[]内居中;
+ \item gbalign=centpos,是list环境中的局中数字序号标签,带括号标签[1]在标签盒子内居中;
+ \item gbalign=gb7714-2015,是项对齐方式数字序号标签,即段落环境中标签使用原始宽度,标签与条目内容等间距。
\item gbalign=gb7714-2015ay,无数字序号标签,是author-year风格的文献表,是gb7714-2015ay样式的默认选项。
\end{itemize}
该选项对\textbf{著者年份制、顺序编码制均有效},也就是说当使用著者年份制时,加上gbalign选项后同样可以实现文献表的顺序序号标签(比如:
@@ -527,6 +537,9 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\begin{itemize}
\item gbbiblabel=bracket,序号数字由方括号包围,比如[1];
\item gbbiblabel=parens,序号数字由圆括号包围,比如(1);
+ \item gbcitelabel=bracketqj,标注标签由全角方括号包围,比如【1】;
+ \item gbcitelabel=parensqj,标注标签由全角圆括号包围,比如(1);
+ \item gbcitelabel=quanjiao,标注标签由全角方括号包围,比如【1】;
\item gbbiblabel=dot,序号数字数字后面加点,比如1.;
\item gbbiblabel=plain,序号数字无装饰,比如1;
\item gbbiblabel=box,序号数字由方框包围,比如\framebox{1};
@@ -561,8 +574,11 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\item gbcitelabel=plain,标注标签无装饰,比如1;
\item gbcitelabel=box,标注标签由方框包围,比如\framebox{1};
\item gbcitelabel=circle,标注标签由圆圈包围,比如\textcircled{1}。
+ \item gbcitelabel=bracketqj,标签由全角方括号包围,比如【作者, 2001】
+ \item gbcitelabel=parensqj,标签由全角圆括号包围,比如(作者, 2001)
+ \item gbcitelabel=quanjiao,标签由全角圆括号包围且内部标点为全角标点,比如(作者,2001)
\end{itemize}
- 顺序编码制和作者年制存在一定的差异,作者年制主要是方括号、圆括号、无括号的选择。
+ 注意顺序编码制和作者年制存在一定的差异,作者年制主要是方括号、圆括号以及全角半角的选择。
顺序编码制默认是方括号,作者年制默认是圆括号。
@@ -940,8 +956,8 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
为实现多种样式并存而增加的选项。仅用于gb7714-2015ms样式中。
\begin{itemize}
- \item gbstyle=true,即默认全部文献使用gb7714-2015样式。
- \item gbstyle=false,仅中文文献使用gb7714-2015样式,其它语言文献使用biblatex默认样式。
+ \item gbstyle=true,即默认全部文献使用国标样式。
+ \item gbstyle=false,仅中文文献使用国标样式,其它语言文献使用biblatex默认样式。
\end{itemize}
该选项的实现原理是把所有国标格式设置局部化到每一条文献打印时,处理时首先判断gbstyle 选项及文献的语言,当满足要求则使用这些局部化格式,否则使用默认的标准样式。这种实现为一篇文档内实现两种样式提供解决思路,尽管目前非中文语言文献的著录格式是标准样式,但只要对标准样式做进一步的修改就可以形成符合某种格式规范的样式,比如像ieee,nature等的样式。因此存在中文使用GB/T 7714-2015 著录格式,而英文文献使用ieee等著录格式的可能性。测试文档见:\href{run:./example/opt-gbstyle.tex}{opt-gbstyle.tex}。
@@ -1021,7 +1037,7 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
注意,若要让脚注计数器与其它计数器比如chapter等关联,那么采用latex的常规方法就能解决,比如使用latex内核常用的\verb|\@addtoreset|命令。
-
+
\item[gbstrict]=\textbf{true},false. \hfill default is true
为避免输出bib文件中多余的域信息而增加选项,目的是为了兼容一些bib文件,因为某些bst样式文件进行中英文判断需要在bib文件中增加类似language这样的域作为支撑,而其中某些域在标准的biblatex样式文件中是默认输出的。
@@ -1042,14 +1058,16 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\end{description}
-\subsubsection{新增的重要命令}\label{sec:add:cmd}
+\subsubsection{新增重要命令}\label{sec:add:cmd}
\begin{description}
- \item[defdoublelangentry] \{entrykey1\}\{entrykey2\}
+ \pdfbookmark[4]{defdblanentry}{defdblanentry}
+ \item[defdblanentry] \{entrykey1\}\{entrykey2\}
- 用于定义双语对照文献,将entrykey2条目和entrykey1条目关联起来,在文献表中对照输出。比如:
+ 用于定义双语对照文献,将entrykey2条目和entrykey1条目关联起来,在文献表中对照输出。比如:\verb|\defdblanentry{entrykey1}{entrykey2}|或
\verb|\defdoublelangentry{entrykey1}{entrykey2}|,若entrykey1条目是中文的文献,entrykey2条目是对应entrykey1条目的英文形式,那么该命令会使得在文献表中,entrykey2的英文内容紧跟在entrykey1的中文内容后对照输出。该命令也只能出现在导言区中。
-
+
+ \pdfbookmark[4]{addEntryField}{addEntryField}
\item[addEntryField] \{entrykey or entrykey comma list\}\{field\}\{fieldvalue\}
用于给指定的文献条目(集)添加域。即将field=\{fieldvalue\}这样的域信息添加到指定的entrykey条目或者entrykey comma list条目集中。比如:
@@ -1058,6 +1076,16 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
将会为author2007en,author2014en两个条目添加nameformat域信息。
该命令也只能出现在导言区中。
+
+
+ \pdfbookmark[4]{setlocalbibstring}{setlocalbibstring}
+ \item[setlocalbibstring] \{bibstringkey\}\{bibstringval\}
+
+ 用于局部调整本地化字符串的内容。比如\verb|\setlocalbibstring{andothersincite}{et al.}|,就是临时将本地化字符串andothersincite的内容调整为“et al.”。
+
+注意:如果要在本地化字符串的内容设置中使用biblatex提供的一些标点命令,比如adddot 等,那么需要对其进行保护,避免直接展开导致命令未定义的错误,比如:
+\verb|\setlocalbibstring{andothersincite}{et al\protect\adddot}|
+
\end{description}
@@ -1199,12 +1227,12 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\subsection{文献引用及标注格式}\label{sec:cbx:usage}
-要生成参考文献,第一步就是在正文中引用参考文献。正文中因引用文献所形成的标注的格式称为参考文献标注样式,也称引用样式或引用标签样式,分为两类: 顺序编码制和著者-出版年(作者年)制。引用文献的基本命令是\verb|\cite|,但为了在一篇文档中实现不同的标签效果,通常还需要使用其它命令,
-比如\verb|\parencite|, \verb|\textcite|, \verb|\pagescite|,\verb|\footfullcite|等。此外为遵循biblatex对于复数形式标注命令的使用习惯,也提供上述命令的复数形式,比如\verb|\cite|命令的复数形式命令\verb|\cites|,便于输出单个文献的页码等前后注信息。
+要生成参考文献,第一步就是在正文中引用参考文献。正文中因引用文献所形成的标注的格式称为参考文献标注样式,也称引用样式或引用标签样式,分为两类: 顺序编码制和著者-出版年(作者年)制。引用文献的基本命令是\verb|\cite|,但为了在一篇文档中实现不同的标签效果,通常还需要使用\verb|\parencite|等其它命令,以及这些命令的复数形式以实现同一处引用多篇文献的附加信息输入。
-熟悉natbib的用户也可以直接使用使用\verb|\citet|, \verb|\citep|命令。
-另外也可以使用一些习惯命令比如\verb|\citetns|、\verb|\citepns|、
-\verb|\upcite|、\verb|\inlinecite|等。
+%比如\verb|\parencite|, \verb|\textcite|, \verb|\pagescite|,\verb|\footfullcite|等。此外为遵循biblatex对于复数形式标注命令的使用习惯,也提供上述命令的复数形式,比如\verb|\cite|命令的复数形式命令\verb|\cites|,便于输出单个文献的页码等前后注信息。
+%熟悉natbib的用户也可以直接使用使用\verb|\citet|, \verb|\citep|命令。
+%另外也可以使用一些惯用命令比如\verb|\citetns|、\verb|\citepns|、
+%\verb|\upcite|、\verb|\inlinecite|等。
\subsubsection{两种编制的标注格式}
@@ -1214,41 +1242,19 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
为使用户免于输入文献作者,完善了\verb|\textcite|命令,提供作者为句子主语,并附带行内非上标的顺序编码,
并增加了\verb|\authornumcite|命令,以输出作者作为句子主语,并附带上标的顺序编码。
增加了\verb|\citec|命令,输出另一种形式的编码压缩标签,比如\textsuperscript{[2]-[4]}区别于一般的\textsuperscript{[2-4]}。
-
其它命令\verb|\citet|、\verb|\citep|、\verb|\citetns|、\verb|\citepns|、
\verb|\upcite|、\verb|\inlinecite|分别等价于
\verb|\authornumcite|、\verb|\cite|、\verb|\textcite|、\verb|\parencite|、
\verb|\cite|、\verb|\parencite|。
-上述命令均可在{bibtexkey}前面的[]内或第二个[]内(当有两个[]时),指定页码用于输出。若不指定页码,则仅有\verb|\pagescite|命令默认提取参考文献的页码信息进行输出。
+上述命令均可指定页码等信息用于输出,即在{entrykey}前面的[]内或第二个[]内(当有两个[]时)给出需要附加输出的信息,比如:\verb|\cite[p. 9]{entrykey}|或\verb|\cite[第九页]{中文entrykey}|。若不指定页码,则仅有\verb|\pagescite|命令默认提取参考文献的页码信息进行输出。
各引用命令的使用方式如表\ref{tab:cite:num}所示。
测试文档见\href{run:example/testallformat.tex}{testallformat.tex}。
-%各命令使用方式如例\ref{eg:citefornumeric}所示。
-%各引用命令的效果如图\ref{fig:cite:num}所示。
-
-\qd{对于一个引用命令中同时给出多个文献bibtexkey的压缩形式,页码只会应用到最后一个参考文献后面,这是不正确的,但这种情况其实本不应出现,因为指定页码本来就需要具体化指向某一文献。使用时请尽可能使用
-\textbackslash pagescite\{key1\}\textbackslash pagescite\{key2\}这种形式
-而不是\textbackslash pagescite\{key1,key2\}|。当然除了多次使用标注命令外,也可以使用对应标注命令的复数形式来为每篇文献提供相应的页码信息。}
-%著者-出版年制的标注样式文件大体使用标准引用样式authoryear的内容。
-\paragraph{\heiti 著者-出版年制的标注样式}
-为满足GB/T 7714-2015第10.2节的要求,
-考虑\verb|\cite|和\verb|\parencite|命令将引用标签用圆括号括起来。增加了\verb|\pagescite|命令,用于自动加页码。增加了\verb|\yearpagescite|, \verb|\yearcite|命令用于处理文中已有作者信息只需要年份和页码的情况(为兼容性考虑,顺序编码制也给出该命令,但作用与
-\verb|\pagescite| 命令相同),也完善了 \verb|\textcite| 命令,提供作者为句子主语,并附带行内非上标的页码,增加了\verb|\authornumcite|命令,以输出作者作为句子主语,并附带上标的页码。
-
-其它命令\verb|\citet|、\verb|\citep|、\verb|\citetns|、\verb|\citepns|、
-\verb|\upcite|、\verb|\inlinecite|分别等价于
-\verb|\authornumcite|、\verb|\cite|、\verb|\textcite|、\verb|\parencite|、
-\verb|\cite|、\verb|\parencite|。
-
-%各命令使用方式如例\ref{eg:citeforauthoryear}所示。
-%各引用命令的效果如图\ref{fig:cite:ay}所示。
-各引用命令的使用方式如表\ref{tab:cite:authoryear}所示。
-测试文档见\href{run:example/testallformat.tex}{testallformat.tex}。
-
%\begin{table}[!htb]
+\medskip
\noindent\begin{minipage}{0.95\linewidth}
\begin{refsection}
\centering
@@ -1282,9 +1288,38 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\end{tabular}
\end{refsection}
\end{minipage}
+\medskip
%\end{table}
+%各命令使用方式如例\ref{eg:citefornumeric}所示。
+%各引用命令的效果如图\ref{fig:cite:num}所示。
+
+注意:对于一个引用命令中同时给出多个文献entrykey的压缩形式,页码只会应用到最后一个参考文献后面。
+%这是不正确的,但这种情况其实本不应出现,因为指定页码本来就需要具体化指向某一文献。
+若要为每篇添加页码信息,则应多次使用标注命令
+\verb|\cite[p.2]{entrykey1}\cite[p.5]{entrykey2}|或使用复数形式的标注命令
+\verb|\cites[p.2]{entrykey1}[p.5]{entrykey2}|,
+而不是\verb|\cite[p.5]{entrykey1,entrykey2}|。
+
+%当然除了这种多次使用标注命令外,也可以使用对应标注命令的复数形式来为每篇文献提供相应的页码信息。
+
+
+%著者-出版年制的标注样式文件大体使用标准引用样式authoryear的内容。
+\paragraph{\heiti 著者-出版年制的标注样式}
+为满足GB/T 7714-2015第10.2节的要求,
+考虑\verb|\cite|和\verb|\parencite|命令将引用标签用圆括号括起来。增加了\verb|\pagescite|命令,用于自动加页码。增加了\verb|\yearpagescite|, \verb|\yearcite|命令用于处理文中已有作者信息只需要年份和页码的情况(为兼容性考虑,顺序编码制也给出该命令,但作用与
+\verb|\pagescite| 命令相同),也完善了 \verb|\textcite| 命令,提供作者为句子主语,并附带行内非上标的页码,增加了\verb|\authornumcite|命令,以输出作者作为句子主语,并附带上标的页码。
+
+其它命令\verb|\citet|、\verb|\citep|、\verb|\citetns|、\verb|\citepns|、
+\verb|\upcite|、\verb|\inlinecite|分别等价于
+\verb|\authornumcite|、\verb|\cite|、\verb|\textcite|、\verb|\parencite|、
+\verb|\cite|、\verb|\parencite|。
+
+%各命令使用方式如例\ref{eg:citeforauthoryear}所示。
+%各引用命令的效果如图\ref{fig:cite:ay}所示。
+各引用命令的使用方式如表\ref{tab:cite:authoryear}所示。
+测试文档见\href{run:example/testallformat.tex}{testallformat.tex}。
@@ -1331,22 +1366,24 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\subsubsection{标注格式局部调整}
-标注在同一个文档中是可能存在不同格式需求的,比如:有的地方需要用上标,有的地方需要用行内,有的地方需要给出作者,有的地方需要给出页码等。一般情况下,不同标注格式可以通过使用不同的标注命令来得到,比如上一小节给出的大量不同的命令,不同命令能够产生独特的标注标签。
+标注在同一个文档中可能存在不同格式需求,比如:有的地方需要用上标,有的地方需要用行内,有的地方需要给出作者,有的地方需要给出页码等。一般情况下,不同标注格式可以通过使用不同的标注命令来得到,比如上一小节给出的不同命令。
+%,不同命令能够产生独特的标注标签。
-除了利用命令来调整标注格式外,还有更多的方法来进行局部格式调整。这利用了tex的编组特性,编组内的局部格式不影响编组外的格式,所以可以利用编组内的局部设置来调整标注的格式,类似的,文献表的著录格式也是可以局部调整的,见下一节。
+除了利用命令来调整标注格式外,还有更多方法可进行局部格式调整。这利用了tex的编组特性,编组内的局部格式不影响编组外的格式,所以可利用编组内的局部设置来调整标注的格式。类似的,文献表的著录格式也可局部调整,详见下一节。
-引用文献所产生标注标签的格式包括很多内容,包括作者数量,标点,本地化字符串等。最常见的局部调整需求是标点和本地化字符串。这里以双语图题中的引用标签的不同本地化字符串需求为例来展示局部调整的方法。
+引用文献所产生标注标签的格式包括很多内容,包括作者数量、标点、本地化字符串等。最常见的局部调整需求是本地化字符串和标点。这里以双语图题中的引用标注标签的不同本地化字符串需求为例来展示局部调整的方法。
-在中科院某类学位论文中,正文的标注标签要求两个英文作者之间用和而不是and连接,多个英文作者截断成一个作者时后面用等.而不是et al.表示。这可以容易通过设置本地化字符串来实现。然而对于双语的图题,英文图题中的出现等与和这样的字符实在不雅,所以又要求在这种全英文的环境中将和与等.更换为英文的表示符号,这就需要利用本地化字符串的局部调整。这种本地化字符串的局部调整其实已经是比较深入的内容,因为biblatex提供的接口DefineBibliographyStrings是全局的设置,如何进行局部调整并没有非常方便的接口,要解决这一需求,需要对biblatex以及gb7714-2015样式有比较深入的了解。
+\paragraph{标注中“等”“和”等本地化字符串调整}
-因为gb7714-2015通过gbcitelocalcase计数器来选择使用中文或英文的本地化字符串,因此通过局部设置gbcitelocalcase可以局部的选择不同语言的本地化字符串,然而因为本地化字符串的内容通常是全局设置的,所以当中文的或者英文的本地化字符串设置都不满足要求时,就需要局部的调整本地化字符串的内容,如\ref{eg:str:localset}所示,对本地化字符串andothersincite的内容做了调整,从全局设置的等.转换为et al.,和转换为and,这种局部设置是通过csdef对保存字符串信息的命令直接做的调整。比如\verb|\csdef{abx@sstr@andothersincite}{et al.}|就是将andothersincite本地化字符串的内容临时调整为et al.。
+在中科院某类学位论文中,正文的标注标签要求两个英文作者之间用“和”而不是“and”连接,多个英文作者则截断成一个作者时后面用“等.”而不是“et al.”表示。这可以容易通过设置本地化字符串来实现。然而对于双语的图题,英文图题中不适合出现“等”与“和”这样的字符,所以又要求在这种全英文的环境中将“和”与“等.”更换为英文符号,这就需要利用本地化字符串的局部调整。这种本地化字符串的局部调整其实已经是比较深入的内容,因为biblatex提供的接口DefineBibliographyStrings是全局的设置,而局部调整则需要使用其它方式。
+%如何进行局部调整并没有非常方便的接口,要解决这一需求,需要对biblatex以及gb7714-2015样式有比较深入的了解。
-为方便用户使用,提供了
-\verb|\setlocalbibstring|命令来替代上述直接定义的csdef命令,比如:
-\verb|\setlocalbibstring{andothersincite}{et al.}|,等价于与前面csdef那条命令。
-另外,如果要在本地化字符串的内容设置中使用biblatex提供的一些标点命令,比如adddot等,那么需要对其进行保护,避免直接展开导致命令未定义的错误,比如:
-\verb|\setlocalbibstring{andothersincite}{et al\protect\adddot}|
+因为gb7714-2015通过gbcitelocalcase计数器来选择使用中文或英文的本地化字符串,因此通过局部设置gbcitelocalcase可以局部的选择不同语言的本地化字符串,比如在一个编组内,局部化设置计数器为:\verb|\defcounter{gbcitelocalcase}{1}|,那么这个编组内的所有本地化字符串会使用默认的中文字符串,反之若设置为2,则本地化字符串会使用默认的英文字符串。
+然而因为本地化字符串的内容通常是全局设置的,所以当中文的或者英文的本地化字符串设置都不满足要求时,就需要局部的调整本地化字符串的内容,如例\ref{eg:str:localset}所示,对本地化字符串andothersincite的内容做了调整,从全局设置的“等.”转换为“et al.”,“和”转换为“and”,这种局部设置可通过csdef对保存字符串信息的命令直接做的调整,比如\verb|\csdef{abx@sstr@andothersincite}{et al.}|就是将andothersincite本地化字符串的内容临时调整为“et al.”。
+但为方便用户使用,提供了
+宏包提供了\verb|\setlocalbibstring|命令来替代上述直接定义的csdef命令,
+如例\ref{eg:str:localset}所示。
具体的测试见\href{egthesis/thesis-ucas-m.tex}{thesis-ucas-m.tex}
\begin{example}{双语图题内的标注标签的本地化字符串局部设置}{eg:str:localset}
@@ -1362,8 +1399,82 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\end{example}
-\paragraph{标注中的全半角标点设置}
+\paragraph{标注中的全半角标点和括号调整}
+
+除了本地化字符串外,标注中的括号和标点也是需要调整的内容。这里两个默认采用英文的半角符号。首先可以通过选项调整,gbcitelabel选项提供了不同的选择,可以设置标注的括号,为全局或半角,同时提供了一个gbcitelabel=quanjiao,可以将标点和括号全部改为全角。
+
+如果选项提供的效果还不够,那么可以局部调整mkbibleftborder和mkbibrightborder,来更换需要的括号。例\ref{eg:parens:localset}中的局部调整可以将标注中的括号改变为『和』。
+
+\begin{example}{局部调整标注标签中的括号}{eg:parens:localset}
+\begin{texlist}
+{\renewrobustcmd{\mkbibleftborder}{『}%
+\renewrobustcmd{\mkbibrightborder}{』}%
+中文段落\cite{Aaa_2018,Aaa_2018a}\cite{Aaa_2021,Aaa_2018}\\
+中文段落\textcite{Aaa_2018,Aaa_2018a},\textcite{Aaa_2021,Aaa_2018} \\
+中文段落\cite{Aaa_2018,Bbb_2019}\parencite{Aaa_2018,Bbb_2019}}
+\end{texlist}
+\end{example}
+
+对于标点来说,若默认的设定不满足要求,则可以在导言区进行调整,
+如例\ref{eg:punct:globalset}中的第一段代码所示,除了其中标点外,有时还需要设置finalnamedelim。这是标签中除姓名外的标点调整,至于姓名内的标点调整则是需要从另外的接口修改,比如:通过gbcaselocalset等来修改revsdnamepunct,bibinitperiod等等,这些在标注标签中通常不太需要修改。
+
+但有的时候,我们需要对中英文文献的标注标签使用不同的符号,比如中文的标签使用中文全角标点,而英文的标签使用英文的标点,那么可以在标点设置时做一个判断,如例
+\ref{eg:punct:globalset}中的第二段代码所示。
+
+而还有的时候,文档中存在独立的中文段落和英文段落,期望在中文段落中使用中文的标点,而在英文段落中则使用英文的标点,此时可以利用gbcitelocal选项的内部设置的计数器gbcitelocalcase来局部化调整。如例
+\ref{eg:punct:globalset}中的第三段代码所示,做如此设置后,那么只要在指定的段落局部化计数器gbcitelocalcase的值就可以达到临时调整标点的目的。
+
+\begin{example}{标注标签中的标点的全局和局部设置}{eg:punct:globalset}
+\begin{texlist}
+%第一段代码:导言区重设标注标签的标点
+\renewcommand*{\multicitedelim}{;}%\addsemicolon\addspace;
+\renewcommand*{\compcitedelim}{,}
+\renewcommand{\compextradelim}{,}
+\DeclareDelimFormat[cite,parencite,pagescite]{nameyeardelim}{,}%\addcomma\space
+\DeclareDelimFormat[textcite]{nameyeardelim}{,}%\addcomma\space
+\DeclareDelimFormat[cite,parencite,pagescite]{andothersdelim}{,}%
+\DeclareDelimFormat[textcite]{andothersdelim}{,}%
+
+%第二段代码:导言区重设标注标签的标点,根据文献的中英文调整标点形式
+\renewcommand*{\multicitedelim}{\iffieldequalstr{userf}{chinese}{;}{\addsemicolon\addspace}}%;
+\renewcommand*{\compcitedelim}{\iffieldequalstr{userf}{chinese}{,}{\addcomma\space}}
+\renewcommand{\compextradelim}{\iffieldequalstr{userf}{chinese}{,}{\addcomma\space}}
+\DeclareDelimFormat[cite,parencite,pagescite,citep]{nameyeardelim}
+{\iffieldequalstr{userf}{chinese}{,}{\addcomma\space}}%
+\DeclareDelimFormat[textcite,authornumcite,citet]{nameyeardelim}
+{\iffieldequalstr{userf}{chinese}{,}{\addcomma\space}}%
+\DeclareDelimFormat[cite,parencite,pagescite,citep]{andothersdelim}
+{\iffieldequalstr{userf}{chinese}{,}{\addcomma\space}}%
+\DeclareDelimFormat[textcite,authornumcite,citet]{andothersdelim}
+{\iffieldequalstr{userf}{chinese}{,}{\addcomma\space}}%
+
+%第二段代码:导言区重设标注标签的标点,可根据计数器gbcitelocalcase局部设置调整中英文标点
+\renewcommand*{\multicitedelim}
+{\ifcase\value{gbcitelocalcase}\iffieldequalstr{userf}{chinese}{;}{\addsemicolon\addspace}%
+\or ;\or\addsemicolon\addspace\fi}%;
+\renewcommand*{\compcitedelim}
+{\ifcase\value{gbcitelocalcase}\iffieldequalstr{userf}{chinese}{,}{\addcomma\space}%
+\or ,\or\addcomma\space\fi}
+\renewcommand{\compextradelim}
+{\ifcase\value{gbcitelocalcase}\iffieldequalstr{userf}{chinese}{,}{\addcomma\space}%
+\or ,\or\addcomma\space\fi}
+\DeclareDelimFormat[cite,parencite,pagescite,citep]{nameyeardelim}
+{\ifcase\value{gbcitelocalcase}\iffieldequalstr{userf}{chinese}{,}{\addcomma\space}%
+\or ,\or\addcomma\space\fi}
+\DeclareDelimFormat[textcite,authornumcite,citet]{nameyeardelim}
+{\ifcase\value{gbcitelocalcase}\iffieldequalstr{userf}{chinese}{,}{\addcomma\space}%
+\or ,\or\addcomma\space\fi}
+\DeclareDelimFormat[cite,parencite,pagescite,citep]{andothersdelim}
+{\ifcase\value{gbcitelocalcase}\iffieldequalstr{userf}{chinese}{,}{\addcomma\space}%
+\or ,\or\addcomma\space\fi}
+\DeclareDelimFormat[textcite,authornumcite,citet]{andothersdelim}
+{\ifcase\value{gbcitelocalcase}\iffieldequalstr{userf}{chinese}{,}{\addcomma\space}%
+\or ,\or\addcomma\space\fi}
+\end{texlist}
+\end{example}
+
+示例可以参考:\href{run:example/test-punct-quanjiao.tex}{test-punct-quanjiao.tex}
参考:\url{https://blog.csdn.net/xenonhu/article/details/124686522}
@@ -1374,15 +1485,18 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
引用文献后,可以在文档需要的位置利用 \verb|\printbibliography| 命令输出文献表。文献表的输出格式称为参考文献著录样式,也称著录表样式或著录格式,也分两类: 顺序编码制和著者-出版年制(作者年制)。
%顺序编码制的参考文献样式基于标准样式numeric-comp/numeric
-\paragraph{\heiti 顺序编码制样式} 中各条参考文献条目以数字序号按引用先后顺序组织。
+\subsubsection{顺序编码制样式}
+
+文献表中各参考文献条目以数字序号按引用先后顺序组织。
著录格式中序号格式见\ref{sec:bib:serialno}节,
各类型文献条目的著录格式见\ref{sec:numeric:data}节,
参考文献条目中各信息域及其录入方式见\ref{sec:bib:bibtex}节。
%著者-出版年制的参考文献样式则基于标准样式authoryear
-\paragraph{\heiti 著者-出版年制样式} 中各条参考文献条目以作者-年为标签以一定的顺序排列。著者-出版年制的著录格式与顺序编码制基本相同,差别仅在于把年份提前到作者后面作为条目的标签。数据源bib文件中各条目的数据录入与顺序编码制完全一致。
+\subsubsection{著者-出版年制样式}
+文献表中各参考文献条目以作者-年为标签以一定的顺序排列。著者-出版年制的著录格式与顺序编码制基本相同,差别仅在于把年份提前到作者后面作为条目的标签。数据源bib文件中各条目的数据录入与顺序编码制完全一致。
-\qd{著者-出版年制有文献按文种集中的要求,因此gb7714-2015ay样式设计了gblanorder选项来配合专用的排序模板,可以方便地设置不同文种的先后顺序,默认文种顺序是中日韩英法俄。如需其他顺序则可利用gblanorder选项重设,设置方法见第\ref{sec:added:opt}节。此外,由于排序需要根据文献所使用的语言判断,因此使用language域,该域由biblatex-gb7714-2015宏包自动判断处理,一般不需过多关注,如果当语言判断出现问题,可以在bib文件中手动设置language域为正确的语言,比如chinese,japanese,english,french等。}
+注意:著者-出版年制有文献按文种集中的要求,因此gb7714-2015ay样式设计了gblanorder选项来配合专用的排序模板,可以方便地设置不同文种的先后顺序,默认文种顺序是中日韩英法俄。如需其他顺序则可利用gblanorder选项重设,设置方法见第\ref{sec:added:opt}节。此外,由于排序需要根据文献所使用的语言判断,因此使用language域,该域由biblatex-gb7714-2015宏包自动判断处理,一般不需过多关注,如果当语言判断出现问题,可以在bib文件中手动设置language域为正确的语言,比如chinese,japanese,english,french等。
%前一段为20190331更新
%\qd{著者-出版年制有分文种文献集中的要求,因此gb7714-2015排序模板以nyt模板为基础,增加 language 作为 name 前的排序域。默认情况下,本样式文件将标题(或作者)为中文的文献的 language 域设置成 chinese,英文的设置成 english。这一设置过程,在biber 处理时自动完成。当出现问题或者有更多文种分集且有特殊顺序时,可以在bib文件中为相应文种文献的 language 域手动设置适合排序的字符串。比如: 中文文献设置为 chinese,英文文献设置为 enlish,法文文献设置为 french,那么排序中,相应的中文文献排在最前面,英文文献在中间,法文文献最后,因为升序情况下字母顺序是c然后e然后f。}
@@ -1406,18 +1520,17 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\end{texlist}
\end{example}
-更多的设置方法,请参考:
-\href{https://github.com/hushidong/biblatex-solution-to-latex-bibliography/blob/master/biblatex-solution-to-latex-bibliography.pdf}%
-{biblatex高级使用方法和样式包设计实现方法}
+%更多的设置方法,请参考:
+%\href{https://github.com/hushidong/biblatex-solution-to-latex-bibliography/blob/master/biblatex-solution-to-latex-bibliography.pdf}%
+%{biblatex高级使用方法和样式包设计实现方法}
\subsubsection{段落格式控制}
\paragraph{\heiti 文献表字体、颜色} 为方便用户改变文献表段落格式、内容字体和颜色等,在 biblatex 提供的 \verb|\bibfont| 命令基础上,
-增加了\verb|\bibauthorfont|、\verb|\bibtitlefont|、\verb|\bibpubfont| 等命令用于控制文献部分著录项的格式,比如作者,标题,出版项等。增加了\verb|\SlashFont|
-用法具体见例\ref{eg:biblist:fontset},结果如图\ref{fig:par:fmt}所示。
+增加了\verb|\bibauthorfont|、\verb|\bibtitlefont|、\verb|\bibpubfont| 等命令用于控制文献部分著录项的格式,比如作者,标题,出版项等。增加了\verb|\SlashFont|用于控制斜杠的字体。
+具体用法见例\ref{eg:biblist:fontset},结果如图\ref{fig:par:fmt}所示。
测试用例见\href{run:example/testfontinbiblio.tex}{testfontinbiblio.tex}。
-
\begin{example}{文献表段落格式、字体、颜色}{eg:biblist:fontset}
\begin{texlist}
% 文献项之间的间隔符控制(比如是否换行)
@@ -1432,7 +1545,7 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\renewcommand{\bibpubfont}{\itshape\color{violet}}%
% url和doi字体
\def\UrlFont{\ttfamily}%\rmfamily %\urlstyle{sf} %\def\UrlFont{\bfseries}
- %斜杠的字体,比如[J/OL]中的斜杠
+ %斜杠的字体,比如[J/OL]或析出文献符号//中的斜杠
\def\SlashFont{\ttfamily}%\rmfamily等
\end{texlist}
\end{example}
@@ -1466,34 +1579,36 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\paragraph{\heiti 文献表水平间距(缩进)控制}
增加了尺寸\verb|\bibitemindent| 用于控制参考文献条目在文献表中的缩进,
其意义与 list 环境中 \verb|\itemindent| 相同。
-文献表的水平缩进控制,两种编制方式下是不同的。
+文献表的水平缩进控制,两种编制方式下是不同的,调整方法见例\ref{eg:biblist:hspace}。
-(a) 对于\emph{著者-出版年}制文献表,bibitemindent表示
+\textbf{(a)} 对于\emph{著者-出版年}制文献表
+
+bibitemindent表示
\emph{一条文献中第一行相对后面各行的缩进},bibhang 表示\emph{页边到文献各行起始位置的距离}。因此要调整缩进则直接设置这两尺寸。
当使用著者-出版年样式又需要使用顺序编码数字标签的文献表时(此时使用gbalign选项),缩进方式与顺序编码制文献表类似,但又略有差异。
数字标签盒子默认宽度为2em,可以调整biblabelextend来增大或缩小(使用正或负的长度)该宽度,数字标签的盒子与文献内容之间的间距为4.5pt,通过直接设置biblabelsep尺寸来调整。
-(b) 对于\emph{顺序编码}制文献表,由于存在数字标签,且其宽度与参考文献数量相关,所以这个宽度是动态变化的,不能提前设定,而是在文献表生成时给出,所以调整缩进需要根据文献表输出环境的情况做针对性处理。
-
-顺序编码样式使用了两类输出环境,所以设定选项也区分两类:
+\textbf{(b)} 对于\emph{顺序编码}制文献表
-一是采用list环境的文献表,即设置gbalign=left、right、center时(即顺序编码标签是左对齐、右对齐和居中对齐的情况)。
+由于存在数字标签,且其宽度与参考文献数量相关,所以这个宽度是动态变化的,不能提前设定,而是在文献表生成时给出,所以调整缩进需要根据文献表输出环境的情况做针对性处理。
-此时文献表环境,数字标签盒子默认宽度为labelnumberwidth,由biblatex根据文献数量自动计算后设定,因此改变缩进主要通过调整biblabelsep和bibitemindent两个尺寸来实现。biblabelsep设置数字标签的盒子与文献内容之间的间距。bibitemindent设置第一行和后面其它行的缩进,默认情况下bibitemindent为0pt,则一条文献内所有行缩进相同,若bibitemindent>0pt则第一行相比后面各行缩进,若bibitemindent<0pt则后面各行相比第一行缩进。
-
-顺序编码样式下bibitemindent与bibhang的意义与著者-出版年制下相同,但由于数字标签盒子的存在,所以页边到各行起始位置的距离bibhang=labelnumberwidth +biblabelsep -bibitemindent。
+顺序编码样式使用了两类输出环境,所以设定选项也区分两类:
-当采用某些字体导致计算的标签宽度不足时,可以设置biblabelextend尺寸,来增加labelnumberwidth的宽度避免缩进格式产生问题,使得:bibhang=labelnumberwidth +biblabelextend +biblabelsep -bibitemindent。默认情况下biblabelextend尺寸为0pt。
+\begin{itemize}
+\item 一是采用list环境的文献表,即设置gbalign=left、right、center时(即顺序编码标签是左对齐、右对齐和居中对齐的情况)。此时需要调整的尺寸包括三个:biblabelsep,bibitemindent,biblabelextend。
-二是采用正常段落环境的文献表,即设置gbalign=gb7714-2015时(即项对齐情况,就是各条文献是自身对齐的情况)。
-此时数字标签盒子默认宽度根据标签实际宽度自动设定,因此不会存在数字标签盒子宽度不足的情况,所以不用设置biblabelextend尺寸。数字标签的盒子与文献内容之间的间距通过调整biblabelsep可设置。\emph{每条参考文献第二行开始的缩进距离}通过调整bibitemindent尺寸设置,bibitemindent默认为0pt,则一条文献内所有行缩进相同,若bibitemindent>0pt则第一行相比后面各行缩进,若bibitemindent<0pt则后面各行相比第一行缩进。
+\hspace{2em}此时的文献表环境中,数字标签盒子默认宽度为labelnumberwidth,由biblatex根据文献数量自动计算后设定,因此改变缩进主要通过调整biblabelsep和bibitemindent两个尺寸来实现。biblabelsep设置数字标签盒子与文献内容之间的间距。bibitemindent设置第一行相对后面其它行的缩进,默认情况下bibitemindent为0pt,则一条文献内所有行缩进相同,若bibitemindent>0pt则第一行相比后面各行缩进,若bibitemindent<0pt则后面各行相比第一行缩进。
+\hspace{2em}顺序编码样式下bibitemindent与bibhang的意义与著者-出版年制下相同,但由于数字标签盒子的存在,所以页边到各行起始位置的距离bibhang=labelnumberwidth +biblabelsep -bibitemindent。
+当采用某些字体导致默认计算的标签宽度不足时,可以设置biblabelextend尺寸,来增加labelnumberwidth的宽度避免缩进格式产生问题,使得:bibhang=labelnumberwidth +biblabelextend +biblabelsep -bibitemindent。默认情况下biblabelextend尺寸为0pt。
-调整方法见例\ref{eg:biblist:hspace}。
+\item 二是采用正常段落环境的文献表,即设置gbalign=gb7714-2015时(即项对齐情况,每条文献严格按从左到右的顺序输出,顺序数字标签宽度等于实际宽度,文献内容与其间隔biblabelsep)。此时需要调整的尺寸包括两个:biblabelsep,bibitemindent。
+\hspace{2em}此时数字标签盒子默认宽度根据标签实际宽度自动设定,因此不存在数字标签盒子宽度不足的情况,因而无需设置biblabelextend尺寸。数字标签盒子与文献内容之间的间距可通过调整biblabelsep设置。\emph{每条参考文献第二行开始的缩进距离}通过调整bibitemindent尺寸设置,bibitemindent默认为0pt,则一条文献内所有行缩进相同,若bibitemindent>0pt则第一行相比后面各行缩进,若bibitemindent<0pt则后面各行相比第一行缩进。
+\end{itemize}
\begin{example}{文献表水平缩进控制}{eg:biblist:hspace}
@@ -1512,7 +1627,7 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\end{texlist}
\end{example}
-(c) 其它形式的文献表。
+\textbf{(c)} 其它形式的文献表
除了使用这种段落形式的文献表外,也有生成\emph{表格文献表}的需求,即把文献表放到一个表格里面,要求每一条文献占据表格的一行。这也是能实现的,具体参考我的博客文章
\href{https://blog.csdn.net/xenonhu/article/details/121696116}{latex中生成表格形式的参考文献表}。
@@ -1581,18 +1696,28 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\renewcommand*{\finentrypunct}{\iffieldequalstr{userd}{chinese}{。}{\adddot}}
%姓名格式相关的标点
-\DeclareDelimFormat{nameyeardelim}{,}%\addcomma\addspace
-%\DeclareDelimFormat[bib,biblist]{nameyeardelim}{,}%\addcomma\addspace
-\DeclareDelimFormat{multinamedelim}{,}%[bib,biblist]
-\DeclareDelimFormat{finalnamedelim}{,}
-\DeclareDelimFormat{andothersdelim}{,}
-\renewcommand*{\revsdnamepunct}{,}%
+\DeclareDelimFormat[bib,biblist]{nameyeardelim}{,}%\addcomma\addspace
+\DeclareDelimFormat[bib,biblist]{multinamedelim}{,}%[bib,biblist]
+\DeclareDelimFormat[bib,biblist]{finalnamedelim}{,}
+\DeclareDelimFormat[bib,biblist]{andothersdelim}{,}
+
+%姓名内部的相关标点,包括如下等设置
+%注意这类设置与gbnamefmt选项相关,不同的选项值对应不同的gb...localset
+%除了如下命令外还有其它设置,有需要可以查biblatex文档
+\def\gbcaselocalset{%
+\renewcommand*{\revsdnamepunct}{,}%%
+\renewrobustcmd*{\bibinitperiod}{}%将名字简写后的点去掉
+\renewrobustcmd*{\bibinithyphendelim}{}%.\mbox{-}
+\renewrobustcmd*{\bibnamedelima}{} %%\mbox{-}
+}
\end{texlist}
\end{example}
-\subsubsection{条目著录格式的选项控制}\label{sec:entry:fmt}
+\subsubsection{条目著录格式控制}\label{sec:entry:fmt}
-文献表输出的格式即参考文献著录样式,除了整体的段落格式外,还有条目内部的格式可以控制,条目内部的这些项称为著录项,这些著录项的格式通常可由选项控制。可用选项除了biblatex 提供的标准选项外,也包括样式包提供的选项。
+文献表输出的格式即参考文献著录样式,除了整体的段落格式外,还有条目内部的格式可以控制,条目内部的这些项称为著录项,这些著录项的格式通常可由选项控制。
+
+可用选项除了biblatex 提供的标准选项外,也包括样式包提供的选项。
图\ref{fig:content:fmta}、\ref{fig:content:fmtb}、\ref{fig:content:fmtc}给出了一些选项设置后的格式控制效果,
更多选项的详细说明见第\ref{sec:added:opt}、\ref{sec:old:opt}小节。
@@ -1651,9 +1776,11 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\caption{文献表条目著录格式示例三}\label{fig:content:fmtc}
\end{figure}
-\subsubsection{条目著录格式的局部调整}\label{sec:entry:fmtlocal}
-得益于biblatex利用tex宏控制著录格式的特点,加上tex语言本身编组的局部化特性,所以在利用biblatex生成参考文献的过程中可以有丰富手段来进行参考文献著录格式的局部调整。因为是局部的格式调整,所以通常是结合refsection或者refsegment来操作的。前面提到过的一个很简单的例子,当在学位论文的写作中需要正文部分的参考文献使用顺序编码制,而附录中研究成果部分使用作者年制这样的需求就是一个典型的局部化格式调整。这一问题的解决方式为:在研究成果部分使用refsection将其局部化,并结合gb7714-2015mx样式,并利用setaystylesection命令设置该refsection为作者年制样式。
+\subsubsection{参考文献表的局部调整}\label{sec:entry:fmtlocal}
+
+文档中有时需要多个文献表,而且可能具有不同的格式,因此全局的设置不一定满足要求,所以需要进行局部的调整,调整的内容也包括:文献表的标题、段落格式和著录格式。
+得益于biblatex利用tex宏控制著录格式的特点,加上tex语言本身编组的局部化特性,所以在利用biblatex生成参考文献的过程中可以有丰富手段来进行参考文献表的局部调整。因为是局部的格式调整,所以通常是结合refsection或者refsegment来操作的。前面提到过的一个很简单的例子,当在学位论文的写作中需要正文部分的参考文献使用顺序编码制,而附录中研究成果部分使用作者年制这样的需求就是一个典型的局部化格式调整。这一问题的解决方式为:在研究成果部分使用refsection将其局部化,并结合gb7714-2015mx样式,并利用setaystylesection命令设置该refsection为作者年制样式。
因为tex宏的局部化调整特性,因此几乎biblatex中所有格式设置都是可以做局部调整的,限于篇幅,这里仅介绍一些常见的简单的调整方式:
@@ -1828,7 +1955,8 @@ biber -l zh__stroke jobname
为避免这一添加拼音到key域的操作,这里提供另一种可能更为方便的方法。biber在做排序时实际上是利用 perl 的 Unicode::Collation::locale 模块,其中的Pinyin.pm提供了汉字的拼音顺序,对该文件做临时的修改,可以调整多音字的顺序。
-因为在参考文献排序中通常会使用字的姓名音,所以我们对这个文件做非正式的修改,并放到github上(\href{https://github.com/hushidong/biblatex-gb7714-2015/files/11120449/Pinyin.zip}{Pinyin.zip}),若用户需要正确的姓的多音字排序,那么只要用该文件替换biber临时工作目录中的文件即可。注意:目前该文件只修改了“曾”“沈”两个字,而“翟”“仇”等没有做修改,若用户有需求后面再增加。
+因为在参考文献排序中通常会使用字的姓名音,所以我们对这个文件做非正式的修改,并放到github上(\href{https://github.com/hushidong/biblatex-gb7714-2015/files/11147697/Pinyin-modified-zhai.zip}{Pinyin.zip}),若用户需要正确的姓的多音字排序,那么只要用该文件替换biber临时工作目录中的文件即可。
+%注意:目前该文件只修改了“曾”“沈”两个字,而“翟”“仇”等没有做修改,若用户有需求后面再增加。
通常biber在第一次运行的时候,会构建一个依赖目录,这也是biber的临时工作路径,而所有的依赖文件就在其中。
在windows下通常会在临时目录temp下构建类似\verb|par-<hex_encoded_username>/cache-|的目录(其它系统也是类似命名,可以搜索一下),所有的依赖包括Pinyin.pm都会在其内部,找到并替换即可(Pinyin.pm文件通常在\verb|cache-<hex-code-string>\inc\lib\Unicode\Collate\CJK|下)。
@@ -1934,7 +2062,8 @@ leftrule=0pt,rightrule=0pt,toprule=0.4pt,bottomrule=0.4pt]
\paragraph{\heiti 利用条目集类型满足双语文献要求}
-设置条目集类型(set)有静态和动态两种方法。其中动态方法使用更为方便,只需在写文档时利用\verb|\defbibentryset|将两条文献不同语言的文献设置成一个set条目,然后引用set的bibtex键。比如:
+设置条目集类型(set)有静态和动态两种方法。其中动态方法使用更为方便,
+只需在写文档时利用\verb|\defbibentryset|将两条文献不同语言的文献设置成一个set条目,然后引用set的bibtex键。比如:
\begin{example}{设置set条目集用于双语文献的动态方法}{eg:setforbilangentry}
\begin{texlist}
\defbibentryset{bilangyi2013}{易仕和2013--,Yi2013--}
@@ -1955,9 +2084,9 @@ biblatex v3.7及之前版本,因为 set 带有第一个子条目的信息,
\end{texlist}
\end{example}
-\bc{在biblatex3.8以上版本中,例{eg:setforbilangentry}的作者年制标注标签会是“易仕和,等,2013”,注意到其中的逗号是中文全角逗号,与其它标签的英文逗号的存在差异,正因为此,该方法并没有完美解决问题。}
+\bc{在biblatex3.8以上版本中,例\ref{eg:setforbilangentry}的作者年制标注标签会是“易仕和,等,2013”,注意到其中的逗号是中文全角逗号,与其它标签的英文逗号的存在差异,正因为此,该方法并没有完美解决问题。}
-\bc{由于顺序编码制使用的时数字标签,前述的问题对于顺序编码制并不存在。而作者年制中的标签问题,可以采用下面的静态条目集方法和关联(related)方法来解决。}
+\bc{由于顺序编码制使用的是数字标签,前述的问题对于顺序编码制并不存在。而作者年制中的标签问题,可以采用下面的静态条目集方法和关联(related)方法来解决。}
静态方法是在bib源文件中给出条目集(set)并使用biber后端进行解析,条目的域信息定义方法如下:
@@ -1965,7 +2094,7 @@ biblatex v3.7及之前版本,因为 set 带有第一个子条目的信息,
\begin{example}{设置set条目集用于双语文献的静态方法}{eg:set:static}
\begin{texlist}
@Set{set1,
-entryset = {key1,key2,key3},
+entryset = {entrykey1,entrykey2,entrykey3},
}
%如果要达到上例动态设置set一样的结果,在bib文件中静态设置set条目如下:
@Set{bilangyi2013,
@@ -1977,10 +2106,10 @@ entryset = {易仕和2013--,Yi2013--},
然而例\ref{eg:set:static}这般简单的静态条目集设置,还存在两个小的问题:
\begin{enumerate}
\item 中文排序会出现问题,条目集会出现在文献表末尾,这是因为条目集没有设置language域用于排序,而其它常规条目都会利用动态数据修改设置language域,但因为静态条目集需要在biber运行时解析,所以无法对language域进行处理。而使用动态条目集方法则没有这一问题,因为其解析过程直接会利用第一个子条目的排序信息。
- \item 著者-出版年制中的标注标签问题,对于静态条目集,v3.8以上版本的biblatex同样不复制第一个子条目信息,因此著者- 出版年制中的引用也无法生成正确的标注标签,这也就是前面动态条目集方法中提到的问题
+ \item 著者-出版年制中的标注标签问题,对于静态条目集,v3.8以上版本的biblatex同样不复制第一个子条目信息,因此著者- 出版年制中的引用也无法生成正确的标注标签,这也就是前面动态条目集方法中提到的问题。
\end{enumerate}
-但静态条目集方法有自己的解决方便,对于第一个问题,可以通过在set条目中手动设置language域来解决;第二个问题,也可以通过在set条目中手动设置label域来解决。比如:
+但静态条目集方法有自己的解决之道,对于第一个问题,可以通过在set条目中手动设置language域来解决;第二个问题,也可以通过在set条目中手动设置label域来解决。比如:
\begin{example}{在bib文件中正确设置set条目集的静态方法}{eg:set:staticright}
\begin{texlist}
@@ -2005,7 +2134,8 @@ language={chinese}
除上述给出的条目集方案外,关联条目方法则是另一种可行方案\footnote{Again about the \@ set label for authoryear style:\url{https://github.com/plk/biblatex/issues/681}}。该方案同样也有静态和动态两种方法,静态就是直接修改bib文件的内容,动态则是在tex源文档中做设置,然后通过biblatex的动态数据修改机制做临时修改。
-静态方法很简单,bib文件中条目设置如例\ref{eg:related:staticright}所示,它能解决双语同时显示的问题,也能解决排序和标注标签问题,唯一的问题在于修改了bib文件后,当不需要双语文献时还需改回来,这会带来不便,因此可以考虑下面的动态方法。但要注意动态方法需要利用多个\verb|\DeclareStyleSourcemap|,因此该方法只适用于biblatex v3.7及以上版本。
+静态方法很简单,bib文件中条目设置如例\ref{eg:related:staticright}所示,它能解决双语同时显示的问题,也能解决排序和标注标签问题,唯一的问题在于修改了bib文件后,当不需要双语文献时还需改回来,这会带来不便,因此可以考虑下面的动态方法。
+但要注意动态方法需要利用多个\verb|\DeclareStyleSourcemap|,因此该方法只适用于biblatex v3.7及以上版本。
\begin{example}{在bib文件中正确设置关联条目的静态方法}{eg:related:staticright}
\begin{texlist}
@@ -2029,7 +2159,7 @@ language={chinese}
\end{texlist}
\end{example}
-动态方法利用动态数据修改自动添加related域,避免对bib文件做直接修改。本样式中对该过程进行了封装,定义一个新的命令\verb|\defdoublelangentry|,例如:
+动态方法利用动态数据修改自动添加related域,避免对bib文件做直接修改。本样式中对该过程进行了封装,定义一个新的命令\verb|\defdblanentry|和一个等价命令\verb|\defdoublelangentry|来实现,例如:
\begin{example}{设置关联条目的动态方法}{eg:related:dynamic}
\begin{texlist}
\defdoublelangentry{易仕和2013--}{Yi2013--}
@@ -2038,7 +2168,7 @@ language={chinese}
使用该命令后,可以引用主条目“易仕和2013--”生成双语文献。
但要注意由于\verb|\DeclareStyleSourcemap|命令只能在导言区中使用,
-因此\verb|\defdoublelangentry|命令也只能出现在导言区中,这也是相比条目集动态方法的唯一遗憾。
+因此\verb|\defdblanentry|或\verb|\defdoublelangentry|命令也只能出现在导言区中,这也是相比条目集动态方法的唯一遗憾。
实现的具体细节见
\href{https://github.com/hushidong/biblatex-solution-to-latex-bibliography}%
{biblatex-solution-to-latex-bibliography}。
@@ -2303,11 +2433,16 @@ bib文件中的参考文献信息是以条目形式组织,一篇文献创建
需要注意的是,
\begin{itemize}
- \item note域在本样式中也做特殊用途,即在book类型的note域中输入standard表示标准,在aritcle类型的note域中输入news或newspaper表示报纸,当然也可以不做特殊用,而只是表示杂项信息。因为报纸和标准也可以在entrysubtype域中输入new|newspaper和standard表示,或者标准和报纸直接用standard 和newspaper 类型表示,尽管这两种类型不是biblatex 原生支持的条目类型。
+ \item note域在本样式中也做特殊用途,即在book类型的note域中输入standard表示标准,在aritcle类型的note域中输入news或newspaper表示报纸。
+ 当然也可以不做特殊用,而只是表示杂项信息,因为报纸和标准也可以在entrysubtype域中输入new或newspaper和standard表示报纸和标准类型,亦或者直接用standard 和newspaper 类型表示两者,尽管这两种类型不是biblatex 原生支持的条目类型。
- \item usera域用于表示参考文献类型和载体标识符(为兼容Lee zeping 的bst样式使用的bib文件也可以用mark和medium 表示)。一般情况下usera,mark,medium这些域不用在bib文件中输入,而由样式文件自动处理得到,既为了使bib文件更纯粹,也为了兼容不同的样式。想象一下如果在bib文件中给出usera域,但另一样式需要使用usera域且用途不同,那么就会有兼容性问题。不用手动输入更重要的目的是为用户减负,因为用户可以直接使用从网络(各种学术网站)导出参考文献信息而不用再额外添加一个参考文献类型和载体标识符。
+ \item usera域用于表示参考文献类型和载体标识符(为兼容Lee zeping 的bst样式使用的bib文件也可以用mark和medium 表示)。一般情况下usera,mark,medium这些域不用在bib文件中输入,而由样式文件自动处理得到,既为了使bib文件更纯粹,也为了兼容不同的样式。
+ %想象一下如果在bib文件中给出usera域,但另一样式需要使用usera域且用途不同,那么就会有兼容性问题。不用手动输入更重要的目的是为用户减负,因为用户可以直接使用从网络(各种学术网站)导出参考文献信息而不用再额外添加一个参考文献类型和载体标识符。
+ 因此,用户可以直接使用从网络(各种学术网站)导出参考文献本身的信息而不用再额外手动添加参考文献类型和载体标识符。
- \item 本样式自动判断语言,用户一般不需要直接给出表示文献语言的域language,因为样式在处理过程中会对各个域的字符做语言判断,这对于一篇文献存在多种语言的情况非常有用,比如一本英文著作被翻译为中文,原作者仍用英文,而译者则使用中文。那么该文献无法用一个language 标识文献的语言,简单来说,标记language域更多的目的是用在多种语言混合的文档中,可以用language 来标记英语、中文、日语、法语和俄语等用于分文种排序。当然这种标记也是由样式自动处理的,用户仅需在自动判断出现问题时手动干预。
+ \item 本样式自动判断语言,用户一般不需要直接给出表示文献语言的域language,因为样式在处理过程中会对各个域的字符做语言判断,这对于一篇文献存在多种语言的情况非常有用,比如一本英文著作被翻译为中文,原作者仍用英文,而译者则使用中文。那么该文献无法用一个language 标识文献的语言,但会对不同的域如作者和译者做额外的判断,从而使输出的格式正确。
+ 所以,使用language域更多的是用于多种语言混合文献表的排序,即用language 来标记英语、中文、日语、法语和俄语等用于分文种排序。
+ %当然这种标记也是由样式自动处理的,用户仅需在自动判断出现问题时手动干预。
\end{itemize}
@@ -2433,7 +2568,7 @@ bib文件中的参考文献信息是以条目形式组织,一篇文献创建
-\subsection{其它注意事项}\label{sec:pkg:hints}
+\subsection{其它事项}\label{sec:pkg:hints}
\begin{enumerate}
\item biblatex 的优点
@@ -3057,7 +3192,7 @@ gb7714-2015实现了GB/T 7714-2015第8.8节要求的析出文献相关格式。
%读者若查看样式文件内容可以看到作者对各目标要求所做的修改及,读者也可以根据自己的需求进行修改,作者设计样式文件的思路以及在设计过程中用到的一些biblatex宏包功能说明,详见第\ref{sec:biblatex:mech}节和LaTeX文档中文参考文献的biblatex解决方案的第2.7节。
最后要感谢如下各位师长和朋友,正是在各位的帮助建议下,本样式不断升级逐渐完善。包括: moewew (biblatex 现在的维护者之一,给予不少有益的建议和指导)、 李志奇(基于biblatex的符合GBT7714-2005的中文文献生成工具的作者,工具中的一些设计如usera域的使用/卷期范围解析等带来很多启发,本人之前一直使用该工具,之所以开发biblatex-gb7714-2015其实主要是因为该工具因biblatex升级而无法使用)、caspervector(虽然未曾真正交流,但从biblatex-caspervector样式包中学到很多,包括排序/GBK编码等问题的解决思路)、LeoLiu(刘海洋,给出的CJK字符判断函数
-\footnote{\url{http://bbs.ctex.org/forum.php?mod=viewthread&tid=152663&extra=page\%3D3}} 对本宏包非常有帮助)、chinatex(china tex版主,给了很多建议和帮助,并且一起合作)、Sheng wenbo(biblatex用户手册合作译者,LaTeX2e 插图指南第三版译者,我们一起翻译的过程相互激励相互促进)、zepinglee(gbt7714-2015 bst样式作者,给了很多建议和讨论)、Harry Chen(ctex套件维护者之一,给了不少好的建议)、liubenyuan(关于项目组织给出了很好的建议)、刘小涛(讨论了关于zotero的使用并提出了建议)、ghiclgi(讨论了GB中著者-出版年制标注标签的一些问题)、邓东升(很很多建议和讨论)、秀文工作组、leipility、qingkuan、湘厦人、秋平、任蒲军、fredericky123、qiuzhu、chaoxiaosu、Old Jack、Wu Nailong、Yibai Zhang、wayne508、 钟乙源、Xiaodong Yao、dsycircle、rpjshu、zjsdut、谢澜涛、Zutian Luo、海阔天空、zzqzyx、程晨、xmtangjun、蔡伟 等等。当然还有更多朋友提供了bug报告,提出了issue,提供了热心帮助,限于篇幅这里不再一一列举,在此一并表示感谢!
+\footnote{\url{http://bbs.ctex.org/forum.php?mod=viewthread&tid=152663&extra=page\%3D3}} 对本宏包非常有帮助)、chinatex(china tex版主,给了很多建议和帮助,并且一起合作)、Sheng wenbo(biblatex用户手册合作译者,LaTeX2e 插图指南第三版译者,我们一起翻译的过程相互激励相互促进)、zepinglee(gbt7714-2015 bst样式作者,给了很多建议和讨论)、Harry Chen(ctex套件维护者之一,给了不少好的建议)、liubenyuan(关于项目组织给出了很好的建议)、刘小涛(讨论了关于zotero的使用并提出了建议)、ghiclgi(讨论了GB中著者-出版年制标注标签的一些问题)、邓东升(很多建议和讨论)、秀文工作组、leipility、qingkuan、湘厦人、秋平、任蒲军、fredericky123、qiuzhu、chaoxiaosu、Old Jack、Wu Nailong、Yibai Zhang、wayne508、 钟乙源、Xiaodong Yao、dsycircle、rpjshu、zjsdut、谢澜涛、Zutian Luo、海阔天空、zzqzyx、程晨、xmtangjun、蔡伟 等等。当然还有更多朋友提供了bug报告,提出了issue,提供了热心帮助,限于篇幅这里不再一一列举,在此一并表示感谢!
\section{存在的问题和下一步工作}
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/chinese-jmw.bbx b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/chinese-jmw.bbx
index cba4e06459..a8031346b2 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/chinese-jmw.bbx
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/chinese-jmw.bbx
@@ -27,6 +27,11 @@
\DeclareBibliographyOption{gbpunctcn}[true]{%biblatex低版本
\ifstrequal{#1}{false}{\execgbpuncten}{}}
+\newtoggle{bbx:gbvolnum}
+\DeclareBibliographyOption{gbvolnum}[false]{%
+ \settoggle{bbx:gbvolnum}{#1}}
+ \ExecuteBibliographyOptions{gbvolnum}
+
\newbibmacro*{bbx:ifmergeddate}{\@secondoftwo}
\newbibmacro*{date+extradate}{}
@@ -41,18 +46,12 @@
{\printdateextra}
{\printlabeldateextra}}}}%
\renewbibmacro*{bbx:ifmergeddate}{\iflabeldateisdate}%
-% \renewbibmacro*{issue+date}{%
-% \ifboolexpr{test {\usebibmacro{bbx:ifmergeddate}}
-% and
-% test {\iffieldundef{issue}}}
-% {}
-% {\printtext[parens]{%
-% \printfield{issue}%
-% \setunit*{\addspace}%
-% \usebibmacro{bbx:ifmergeddate}
-% {}
-% {\printdate}}}%
-% \newunit}
+ \renewbibmacro*{issue+date}{%去掉括号
+ \iffieldundef{issue}
+ {\usebibmacro{date}}%
+ {\iftoggle{bbx:gbstrict}{}{\printfield{issue}%
+ \setunit*{\addspace}}%
+ \usebibmacro{date}}}%
}
@@ -91,6 +90,7 @@
dateabbrev=false,
maxbibnames=99,
mergedate=true,
+ gbfootbibfmt =true,
%datezeros=false,
}
@@ -122,7 +122,7 @@
\def\gbpunctttr{》}%
}
-\DefineBibliographyExtras{english}{\renewcommand*{\bibrangedash}{$\sim$}}%将页码间隔符替换会英文的短横线
+\DefineBibliographyExtras{english}{\renewcommand*{\bibrangedash}{\textasciitilde}}%将页码间隔符替换会英文的短横线
%==================================================
%为标注和文献表中标点格式,重设and本地化字符串
@@ -130,10 +130,10 @@
\DefineBibliographyStrings{english}{
and = { and},%and后面的空格在finalnamedelim已经加过了,所以这里去掉20191009
andcn = {\gbpunctmark\unspace},%\gbpunctmark
- %andotherscn={等},
mathesiscn={硕士学位论文},
phdthesiscn={博士学位论文},
bytranslator= {trans\adddot\ \lbx@sfromlang\ by},
+ in={in\space},
}
@@ -153,7 +153,10 @@
\DeclareFieldFormat[article,incollection,inbook,inproceedings,misc]{title}{%
\iffieldequalstr{userd}{chinese}{\gbpunctttl#1\gbpunctttr}{\mkbibquote{#1}\isdot}}
\DeclareFieldFormat*{journaltitle}{%
-\iffieldequalstr{userd}{chinese}{\gbpunctttl#1\gbpunctttr}{\textbf{\textit{#1}}}}%
+\iffieldequalstr{userd}{chinese}{\gbpunctttl#1\gbpunctttr}%
+{\iffieldequalstr{entrysubtype}{workpaper}{#1}%
+{\textbf{\textit{#1}}}%
+}}%
\DeclareFieldFormat{booktitle}{%
\iffieldequalstr{userd}{chinese}{\gbpunctttl#1\gbpunctttr}{\textbf{\textit{#1}}}}
\renewcommand*{\revsdnamepunct}{%
@@ -216,9 +219,10 @@
% 调整页码前的标点和去掉期刊文章等页码后面的标点
%
\renewbibmacro*{note+pages}{%源来自standard.bbx
-% \iffieldundef{postnote}{\iffieldundef{pages}{}{%
-% \setunit{\bibpagespunct}%
-% \printfield{pages}}}{}%
+\iffieldequalstr{userd}{chinese}{}%
+ {\iffieldundef{pages}{}{%
+ \setunit{\bibpagespunct}%
+ \printfield{pages}}}%
}
@@ -239,7 +243,13 @@
\printdelim{finalpunct}}
%调整标注的注释中的条目结尾标点
\DeclareDelimFormat{finalpunct}{\iffieldequalstr{userd}{chinese}{\gbpunctdot}{\adddot}}
-\DeclareDelimFormat[fullinnercite]{finalpunct}{}
+%注意由于usedriver中biblatex自动把\finenty定义为\blx@finentry@usedrv
+%而\blx@finentry@usedrv的标点默认设置为空,所以userdriver最后本来没有标点
+%这里将其恢复成文献表中的标点\blx@imc@finentry,所以会与文献表一致
+\AtUsedriver{%
+ \let\finentry\blx@imc@finentry%\blx@finentry@usedrv
+}
+
%出版项中:出版社地址后面的标点
\renewcommand{\publocpunct}{%
@@ -408,7 +418,9 @@
\renewbibmacro*{in:}{%
-\iftoggle{bbx:gbpunctin}{\gbpunctcomma}%\addthinspace
+\iftoggle{bbx:gbpunctin}{\iffieldequalstr{userd}{chinese}%
+ {\gbpunctcomma}%
+ {\newunit\printtext{\bibstring{in}}}}%\addthinspace
{\setunit{\adddot\addspace}%
\iffieldequalstr{userd}{chinese}%
{\gbpunctcomma}%
@@ -431,11 +443,12 @@
\printtext{\bibstring{serialcn}\addthinspace\arabic{numberwithoutzero} 期}}%
{\printtext{\bibstring{serialcn}\addthinspace #1 期}}%
}}%
- {\newunit\setcounter{numberwithoutzero}{#1}\printtext{\bibstring{number}}\arabic{numberwithoutzero}}%
+ {\setcounter{numberwithoutzero}{#1}\printtext{\bibstring{number}}~\arabic{numberwithoutzero}}%
}
\DeclareFieldFormat[book,inbook,incollection,misc]{number}%
-{\iffieldequalstr{userd}{chinese}{\iffieldint{number}%
+{\iffieldequalstr{userd}{chinese}
+ {\iffieldint{number}%
{%
\bibstring{serialcn}#1\bibstring{numbercn}%
}{#1}%
@@ -516,13 +529,31 @@
\iffieldequalstr{userd}{chinese}%
{\iffieldundef{volume}{}{\printfield{volume}}%
\iffieldundef{number}{}{\printfield{number}}}%区别于顺序编码制
- {\newunit\printfield{volume}%
- \printfield{number}%
- \setunit{\addcomma\space}%
+ {\newunit%
+ \iftoggle{bbx:gbvolnum}%
+ {\usebibmacro{gb+volume+number}}%
+ {\iffieldundef{volume}{}{\printfield{volume}}%
+ \newunit\iffieldundef{number}{}{\printfield{number}}}%
\printfield{eid}}%
}
+\DeclareFieldFormat{plainvolume}{#1}%
+
+
+\newbibmacro*{gb+volume+number}
+{%
+\ifboolexpr{
+ not test {\iffieldundef{volume}} and not test {\iffieldundef{number}}
+ }
+ {\printfield[plainvolume]{volume}\printfield[parens]{number}}
+ {%
+ \iffieldundef{volume}{}{\printfield{volume}}%
+ \iffieldundef{number}{}{\printfield{number}}%
+ }%
+}
+
+
%
% 期刊的标题做修改
%
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/chinese-jmw.cbx b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/chinese-jmw.cbx
index d8a89fb535..9b21ea69f4 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/chinese-jmw.cbx
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/chinese-jmw.cbx
@@ -78,6 +78,13 @@
\DeclareDelimFormat[parencite]{andothersdelim}{\iffieldequalstr{userf}{chinese}{}{\addspace}}%
+%去掉footfullcite后面的点
+%注意由于usedriver中biblatex自动把\finenty设置为空,所以userdriver最后本来没有标点
+%默认了加了period所以把它去掉
+\renewcommand{\bibfootnotewrapper}[1]{%
+ \bibsentence#1}%
+
+
%标注压缩时,直接用date+extradate代替extradate实现2006a,2006b的效果
%\DeclareDelimFormat*{compcitedelim}{\gbpunctmarkcite}%\addcomma\addspace
\newbibmacro*{cite:extradate}{%
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015.bbx b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015.bbx
index b5233fc1f9..d68a55d403 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015.bbx
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015.bbx
@@ -11,7 +11,7 @@
%
% 版本和时间信息
%
-\def\versionofgbtstyle{2023/04/24 v1.1m}
+\def\versionofgbtstyle{2023/05/24 v1.1n}
\def\versionofbiblatex{\abx@version}
\ProvidesFile{gb7714-2015.bbx}[\versionofgbtstyle biblatex bibliography style]
%\RequireBiber[3]%显式指定用biber后端,当用bibtex时会报错,但其实不会影响编译,只是采用bibtex后无法达成格式需求
@@ -215,14 +215,21 @@
%% 20220625,hzz,v1.1i
\newlength{\BracketLift}
\setlength{\BracketLift}{0.0ex}
-\renewcommand*{\bibleftparen}{\blx@postpunct\raise\BracketLift\hbox{(}}
-\renewcommand*{\bibrightparen}{\blx@postpunct\raise\BracketLift\hbox{)}\midsentence}
-\renewcommand*{\bibleftbracket}{\blx@postpunct\raise\BracketLift\hbox{[}}
-\renewcommand*{\bibrightbracket}{\blx@postpunct\raise\BracketLift\hbox{]}\midsentence}
-\newcommand*{\gbleftparen}{\raise\BracketLift\hbox{(}}
-\newcommand*{\gbrightparen}{\raise\BracketLift\hbox{)}}
-\newcommand*{\gbleftbracket}{\raise\BracketLift\hbox{[}}
-\newcommand*{\gbrightbracket}{\raise\BracketLift\hbox{]}}
+%如下4个字符可以做全局性的改变,无论是在citation还是bibliography中
+\def\CharParenLeft{(}
+\def\CharParenRight{)}
+\def\CharBracketLeft{[}
+\def\CharBracketRight{]}
+%如下4个用于改变biblatex提供的括号命令中的字符的位置抬升
+\renewcommand*{\bibleftparen}{\blx@postpunct\raise\BracketLift\hbox{\CharParenLeft}}
+\renewcommand*{\bibrightparen}{\blx@postpunct\raise\BracketLift\hbox{\CharParenRight}\midsentence}
+\renewcommand*{\bibleftbracket}{\blx@postpunct\raise\BracketLift\hbox{\CharBracketLeft}}
+\renewcommand*{\bibrightbracket}{\blx@postpunct\raise\BracketLift\hbox{\CharBracketRight}\midsentence}
+%如下4个用于改变biblatex-gb7714-2015相关的括号命令中的字符的位置抬升
+\newcommand*{\gbleftparen}{\raise\BracketLift\hbox{\CharParenLeft}}
+\newcommand*{\gbrightparen}{\raise\BracketLift\hbox{\CharParenRight}}
+\newcommand*{\gbleftbracket}{\raise\BracketLift\hbox{\CharBracketLeft}}
+\newcommand*{\gbrightbracket}{\raise\BracketLift\hbox{\CharBracketRight}}
%=====================================================================
@@ -689,7 +696,10 @@
%为数字标签格式选择增加的计数器/命令
\newcommand{\mkgbnumlabel}[1]{\mkbibbrackets{#1}}
\def\gbbiblabelopt@bracket{\renewcommand{\mkgbnumlabel}[1]{\mkbibbrackets{##1}}}
+ \def\gbbiblabelopt@bracketqj{\renewcommand{\mkgbnumlabel}[1]{【##1】}}
+ \def\gbbiblabelopt@quanjiao{\renewcommand{\mkgbnumlabel}[1]{【##1】}}
\def\gbbiblabelopt@parens{\renewcommand{\mkgbnumlabel}[1]{\mkbibparens{##1}}}
+ \def\gbbiblabelopt@parensqj{\renewcommand{\mkgbnumlabel}[1]{(##1)}}
\def\gbbiblabelopt@dot{\renewcommand{\mkgbnumlabel}[1]{##1\adddot}}
\def\gbbiblabelopt@plain{\renewcommand{\mkgbnumlabel}[1]{##1}}
\def\gbbiblabelopt@box{\renewcommand{\mkgbnumlabel}[1]{\framebox{##1}}}
@@ -801,6 +811,7 @@
\ifstrequal{#1}{right}{\setcounter{gbalignlabel}{0}}{}
\ifstrequal{#1}{left}{\setcounter{gbalignlabel}{1}}{}
\ifstrequal{#1}{center}{\setcounter{gbalignlabel}{2}}{}
+ \ifstrequal{#1}{centpos}{\setcounter{gbalignlabel}{3}}{}
\ifstrequal{#1}{gb7714-2015}{\setaligngbstyle}{}
\ifstrequal{#1}{gb7714-2015ay}{\setaligngbstyleay}{}
}
@@ -845,6 +856,7 @@
\ifstrequal{#1}{right}{\setcounter{gbalignlabel}{0}}{}
\ifstrequal{#1}{left}{\setcounter{gbalignlabel}{1}}{}
\ifstrequal{#1}{center}{\setcounter{gbalignlabel}{2}}{}
+ \ifstrequal{#1}{centpos}{\setcounter{gbalignlabel}{3}}{}
\ifstrequal{#1}{gb7714-2015}{}{}
\ifstrequal{#1}{gb7714-2015ay}{\setaligngbstyleay}{}
}
@@ -2229,6 +2241,8 @@ test {\iftoggle{iftlseven}}%biblatex<=3.7
\mkgbnumlabel{#1}\hfill%
\or%中间对齐,比如:序号数字居于[]中间
\hfil\mkgbnumlabel{\hfill#1\hfill}\hfil%
+\or%中间对齐,但是整个标签位于中间,比如:[1]位于中间
+ \hfil\mkgbnumlabel{#1}\hfil%
\fi}
%
@@ -3185,6 +3199,7 @@ test {\iftoggle{iftlseven}}%biblatex<=3.7
}
}
}
+ \let\defdblanentry=\defdoublelangentry
}
%
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015.cbx b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015.cbx
index 7c39e23385..7d9d75eefe 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015.cbx
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015.cbx
@@ -58,6 +58,18 @@
\renewrobustcmd{\mkbibleftborder}{\gbleftparen}%
\renewrobustcmd{\mkbibrightborder}{\gbrightparen}%
}
+\def\gbcitelabelopt@parensqj{%
+\renewrobustcmd{\mkbibleftborder}{\allowbreak(}%
+\renewrobustcmd{\mkbibrightborder}{)\unspace}%
+}
+\def\gbcitelabelopt@bracketqj{%
+\renewrobustcmd{\mkbibleftborder}{\allowbreak【}%
+\renewrobustcmd{\mkbibrightborder}{】\unspace}%
+}
+\def\gbcitelabelopt@quanjiao{%
+\renewrobustcmd{\mkbibleftborder}{\allowbreak(}%
+\renewrobustcmd{\mkbibrightborder}{)\unspace}%
+}
\def\gbcitelabelopt@dot{%
\renewrobustcmd{\mkbibleftborder}{}%
\renewrobustcmd{\mkbibrightborder}{.}%
@@ -100,12 +112,13 @@
% 20210121,v1.0w,hzz
%
\iftoggle{iftlatest}%
-{\renewbibmacro*{textcite}{%
+{%
+\renewbibmacro*{textcite}{%
\iffieldequals{namehash}{\cbx@lasthash}
{\usebibmacro{cite:comp}}
{\usebibmacro{cite:dump}%
\ifbool{cbx:parens}
- {\printtext{\bibclosebracket}\global\boolfalse{cbx:parens}}
+ {\printtext{\mkbibrightborder}\global\boolfalse{cbx:parens}}%\bibclosebracket
{}%
\iffirstcitekey
{}
@@ -115,14 +128,37 @@
{\printfield[citetitle]{labeltitle}}
{\iftoggle{bbx:gblabelref}{\printtext[bibhyperref]{\printnames{labelname}}}{\printnames{labelname}}}%
\setunit*{\printdelim{namelabeldelim}}%
- \printtext{\bibopenbracket}\global\booltrue{cbx:parens}%
+ \printtext{\mkbibleftborder}\global\booltrue{cbx:parens}%\bibopenbracket
\ifnumequal{\value{citecount}}{1}
{\usebibmacro{prenote}}
{}%
\usebibmacro{cite:comp}%
\stepcounter{textcitecount}%
- \savefield{namehash}{\cbx@lasthash}}}%
- }
+ \savefield{namehash}{\cbx@lasthash}}}
+%这是老版本的textcite,上面是新版本的,使用新版本后,对于老版本的biblatex的兼容性可能会受影响
+%\renewbibmacro*{textcite}{%
+% \iffieldequals{namehash}{\cbx@lasthash}
+% {\usebibmacro{cite:comp}}
+% {\usebibmacro{cite:dump}%
+% \ifbool{cbx:parens}
+% {\printtext{\mkbibrightborder}\global\boolfalse{cbx:parens}}%\bibclosebracket
+% {}%
+% \iffirstcitekey
+% {}
+% {\setunit{\textcitedelim}}%
+% \usebibmacro{cite:init}%
+% \ifnameundef{labelname}
+% {\printfield[citetitle]{labeltitle}}
+% {\iftoggle{bbx:gblabelref}{\printtext[bibhyperref]{\printnames{labelname}}}{\printnames{labelname}}}%
+% \setunit*{\printdelim{namelabeldelim}}%
+% \printtext{\mkbibleftborder}\global\booltrue{cbx:parens}%\bibopenbracket
+% \ifnumequal{\value{citecount}}{1}
+% {\usebibmacro{prenote}}
+% {}%
+% \usebibmacro{cite:comp}%
+% \stepcounter{textcitecount}%
+% \savefield{namehash}{\cbx@lasthash}}}%
+}
%
@@ -178,7 +214,7 @@
% 定义一个上标方括号wrapper
%
\newcommand*\mkbibsuperbracket[1]{%
- \mkbibsuperscript{\mkbibbrackets{#1}}%
+ \mkbibsuperscript{\mkbibleftborder{#1}\mkbibrightborder}%
}
% 修改postnote的输出格式
@@ -201,7 +237,7 @@
\begingroup%
\protected\long\def\mkbibsuperscriptusp##1{%
\blx@warning{Nested superscript}%
- \mkbibbrackets{##1}}%
+ \mkbibleftborder{##1}\mkbibrightborder}%
#1\endgroup}}
@@ -243,7 +279,7 @@
% 重定义parencite命令,以满足标签带页码的国标要求
%
\DeclareCiteCommand{\parencite}%[\mkbibbrackets]
- {\addspace\mkbibleftborder\usebibmacro{cite:init}%
+ {\mkbibleftborder\usebibmacro{cite:init}%
\usebibmacro{prenote}}%
{\usebibmacro{citeindex}%
\usebibmacro{cite:comp}}
@@ -352,7 +388,8 @@
{\usebibmacro{cite:comp}}%
{\usebibmacro{cite:dump}%
\ifbool{cbx:parens}%
- {\mkbibsuperscript{{\hspace{-0.075em}\bibclosebracket}}\global\boolfalse{cbx:parens}}%\printtext
+ {\mkbibsuperscript{{\hspace{-0.075em}\mkbibrightborder}}%\bibclosebracket
+ \global\boolfalse{cbx:parens}}%\printtext
{}%
\iffirstcitekey
{}
@@ -362,7 +399,8 @@
{\printfield[citetitle]{labeltitle}}
{\printnames{labelname}}%
%\setunit*{\printdelim{namelabeldelim}}%
- \mkbibsuperscript{\printtext{\bibopenbracket}\global\booltrue{cbx:parens}%
+ \mkbibsuperscript{\printtext{\mkbibleftborder}%\bibopenbracket
+ \global\booltrue{cbx:parens}%
\ifnumequal{\value{citecount}}{1}
{\usebibmacro{prenote}}%
{}%
@@ -378,11 +416,13 @@
{}%
{\ifbool{cbx:incitet}%
{\mkbibsuperscript{\usebibmacro{cite:dump}\usebibmacro{postnote}%
- \ifbool{cbx:parens}{\hspace{-0.075em}\bibclosebracket\global\boolfalse{cbx:parens}}{}%
+ \ifbool{cbx:parens}{\hspace{-0.075em}\mkbibrightborder%\bibclosebracket
+ \global\boolfalse{cbx:parens}}{}%
}%
}%
{\usebibmacro{cite:dump}\usebibmacro{postnote}%
- \ifbool{cbx:parens}{\bibclosebracket\global\boolfalse{cbx:parens}}{}%
+ \ifbool{cbx:parens}{\mkbibrightborder%\bibclosebracket
+ \global\boolfalse{cbx:parens}}{}%
}%
}
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ay.bbx b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ay.bbx
index a1f7a23492..3ebe52afca 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ay.bbx
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ay.bbx
@@ -10,7 +10,7 @@
%
% 版本和时间信息
%
-\def\versionofgbtstyle{2023/04/24 v1.1m}
+\def\versionofgbtstyle{2023/05/24 v1.1n}
\def\versionofbiblatex{\abx@version}
\ProvidesFile{gb7714-2015ay.bbx}[\versionofgbtstyle biblatex bibliography style]
%\RequireBiber[3]%显式指定用biber后端,当用bibtex时会报错,但其实不会影响编译,只是采用bibtex后无法达成格式需求
@@ -212,14 +212,21 @@
%% 20220625,hzz,v1.1i
\newlength{\BracketLift}
\setlength{\BracketLift}{0.0ex}
-\renewcommand*{\bibleftparen}{\blx@postpunct\raise\BracketLift\hbox{(}}
-\renewcommand*{\bibrightparen}{\blx@postpunct\raise\BracketLift\hbox{)}\midsentence}
-\renewcommand*{\bibleftbracket}{\blx@postpunct\raise\BracketLift\hbox{[}}
-\renewcommand*{\bibrightbracket}{\blx@postpunct\raise\BracketLift\hbox{]}\midsentence}
-\newcommand*{\gbleftparen}{\raise\BracketLift\hbox{(}}
-\newcommand*{\gbrightparen}{\raise\BracketLift\hbox{)}}
-\newcommand*{\gbleftbracket}{\raise\BracketLift\hbox{[}}
-\newcommand*{\gbrightbracket}{\raise\BracketLift\hbox{]}}
+%如下4个字符可以做全局性的改变,无论是在citation还是bibliography中
+\def\CharParenLeft{(}
+\def\CharParenRight{)}
+\def\CharBracketLeft{[}
+\def\CharBracketRight{]}
+%如下4个用于改变biblatex提供的括号命令中的字符的位置抬升
+\renewcommand*{\bibleftparen}{\blx@postpunct\raise\BracketLift\hbox{\CharParenLeft}}
+\renewcommand*{\bibrightparen}{\blx@postpunct\raise\BracketLift\hbox{\CharParenRight}\midsentence}
+\renewcommand*{\bibleftbracket}{\blx@postpunct\raise\BracketLift\hbox{\CharBracketLeft}}
+\renewcommand*{\bibrightbracket}{\blx@postpunct\raise\BracketLift\hbox{\CharBracketRight}\midsentence}
+%如下4个用于改变biblatex-gb7714-2015相关的括号命令中的字符的位置抬升
+\newcommand*{\gbleftparen}{\raise\BracketLift\hbox{\CharParenLeft}}
+\newcommand*{\gbrightparen}{\raise\BracketLift\hbox{\CharParenRight}}
+\newcommand*{\gbleftbracket}{\raise\BracketLift\hbox{\CharBracketLeft}}
+\newcommand*{\gbrightbracket}{\raise\BracketLift\hbox{\CharBracketRight}}
%=====================================================================
@@ -634,7 +641,10 @@
%为数字标签格式选择增加的计数器/命令
\newcommand{\mkgbnumlabel}[1]{\mkbibbrackets{#1}}
\def\gbbiblabelopt@bracket{\renewcommand{\mkgbnumlabel}[1]{\mkbibbrackets{##1}}}
+ \def\gbbiblabelopt@bracketqj{\renewcommand{\mkgbnumlabel}[1]{【##1】}}
+ \def\gbbiblabelopt@quanjiao{\renewcommand{\mkgbnumlabel}[1]{【##1】}}
\def\gbbiblabelopt@parens{\renewcommand{\mkgbnumlabel}[1]{\mkbibparens{##1}}}
+ \def\gbbiblabelopt@parensqj{\renewcommand{\mkgbnumlabel}[1]{(##1)}}
\def\gbbiblabelopt@dot{\renewcommand{\mkgbnumlabel}[1]{##1\adddot}}
\def\gbbiblabelopt@plain{\renewcommand{\mkgbnumlabel}[1]{##1}}
\def\gbbiblabelopt@box{\renewcommand{\mkgbnumlabel}[1]{\framebox{##1}}}
@@ -744,6 +754,7 @@
\ifstrequal{#1}{right}{\setcounter{gbalignlabel}{0}\setaligngbnumeric}{}
\ifstrequal{#1}{left}{\setcounter{gbalignlabel}{1}\setaligngbnumeric}{}
\ifstrequal{#1}{center}{\setcounter{gbalignlabel}{2}\setaligngbnumeric}{}
+ \ifstrequal{#1}{centpos}{\setcounter{gbalignlabel}{3}\setaligngbnumeric}{}
\ifstrequal{#1}{gb7714-2015}{\setaligngbstyle}{}
\ifstrequal{#1}{gb7714-2015ay}{}{}%默认就是ay样式的
}%
@@ -791,6 +802,7 @@
\ifstrequal{#1}{right}{\setcounter{gbalignlabel}{0}\setaligngbnumeric}{}
\ifstrequal{#1}{left}{\setcounter{gbalignlabel}{1}\setaligngbnumeric}{}
\ifstrequal{#1}{center}{\setcounter{gbalignlabel}{2}\setaligngbnumeric}{}
+ \ifstrequal{#1}{centpos}{\setcounter{gbalignlabel}{3}\setaligngbnumeric}{}
\ifstrequal{#1}{gb7714-2015}{\setaligngbstyle}{}
\ifstrequal{#1}{gb7714-2015ay}{}{}
}%
@@ -2005,6 +2017,7 @@
}
}
}
+ \let\defdblanentry=\defdoublelangentry
}
@@ -2103,6 +2116,8 @@ test {\iftoggle{iftlseven}}%biblatex<=3.7
\mkgbnumlabel{#1}\hfill%
\or%中间对齐,比如:序号数字居于[]中间
\hfil\mkgbnumlabel{\hfill#1\hfill}\hfil%
+\or%中间对齐,但是整个标签位于中间,比如:[1]位于中间
+ \hfil\mkgbnumlabel{#1}\hfil%
\fi}
%
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ay.cbx b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ay.cbx
index 454e5cc7e6..739528dc1b 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ay.cbx
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ay.cbx
@@ -28,6 +28,9 @@
% 增加标签包围符号格式处理选项
% 20211030,1.1a,hzz
%
+\def\gbpunctcommacite{\addcomma\addspace}
+\def\gbpunctmarkcite{\addcomma\addspace}%
+\def\gbpunctsemicoloncite{\addsemicolon\addspace}
\newrobustcmd{\mkbibleftborder}{\gbleftparen}
\newrobustcmd{\mkbibrightborder}{\gbrightparen}
\DeclareBibliographyOption[string]{gbcitelabel}[bracket]{%
@@ -43,6 +46,21 @@
\renewrobustcmd{\mkbibleftborder}{\gbleftparen}%
\renewrobustcmd{\mkbibrightborder}{\gbrightparen}%
}
+\def\gbcitelabelopt@parensqj{%
+\renewrobustcmd{\mkbibleftborder}{\allowbreak(}%
+\renewrobustcmd{\mkbibrightborder}{)\unspace}%
+}
+\def\gbcitelabelopt@bracketqj{%
+\renewrobustcmd{\mkbibleftborder}{\allowbreak【}%
+\renewrobustcmd{\mkbibrightborder}{】\unspace}%
+}
+\def\gbcitelabelopt@quanjiao{%
+\renewrobustcmd{\mkbibleftborder}{\allowbreak(}%
+\renewrobustcmd{\mkbibrightborder}{)\unspace}%
+\def\gbpunctcommacite{,}%
+\def\gbpunctmarkcite{、}%
+\def\gbpunctsemicoloncite{;}%
+}
\def\gbcitelabelopt@dot{%
\renewrobustcmd{\mkbibleftborder}{}%
\renewrobustcmd{\mkbibrightborder}{.}%
@@ -116,14 +134,20 @@ test {\iftoggle{iftlseven}}%3.7=biblatex
% v1.0t,20200320,hzz,修改如下
% 在cbx中增加标注中的nameyeardelim标点定义,避免bbx使用其它样式时出现问题
% 同时设置textcite的nameyeardelim为一个短空格,似乎原来直接连上去的不够美观
-\DeclareDelimFormat[cite,parencite,pagescite]{nameyeardelim}{\addcomma\space}%\addcomma\space
-\DeclareDelimFormat[textcite]{nameyeardelim}{\addthinspace}%\addcomma\space
-\DeclareDelimFormat[textcite]{andothersdelim}{\iffieldequalstr{userf}{chinese}{\addthinspace}{\addspace}}%
-\AtEveryCitekey{%
-\iffieldequalstr{userf}{chinese}{\renewcommand*{\andothersdelim}{\addthinspace}}%\addthinspace
- {\renewcommand*{\andothersdelim}{\addspace}}%
-}
-\newcommand{\compextradelim}{\addcomma\addthinspace} %标注中压缩后相同年份后附加标签a、b之间的标点
+\renewcommand*{\multicitedelim}{\gbpunctsemicoloncite}%\addsemicolon\addspace;
+\renewcommand*{\compcitedelim}{\gbpunctmarkcite}
+\newcommand{\compextradelim}{\gbpunctcommacite} %标注中压缩后相同年份后附加标签a、b之间的标点
+\DeclareDelimFormat[cite,parencite,pagescite,citep]{nameyeardelim}{\gbpunctcommacite}%\addcomma\space
+\DeclareDelimFormat[textcite,authornumcite,citet]{nameyeardelim}{\addthinspace}%\addcomma\space
+\DeclareDelimFormat[cite,parencite,pagescite,citep]{andothersdelim}
+ {\iffieldequalstr{userf}{chinese}{\addthinspace}{\addspace}}%
+\DeclareDelimFormat[textcite,authornumcite,citet]{andothersdelim}
+ {\iffieldequalstr{userf}{chinese}{\addthinspace}{\addspace}}%
+%\AtEveryCitekey{%
+%\iffieldequalstr{userf}{chinese}{\renewcommand*{\andothersdelim}{\addthinspace}}%\addthinspace
+% {\renewcommand*{\andothersdelim}{\addspace}}%
+%}
+
%
% 修订使可用选项gblabelref来控制是否将标准标签中的作者加上超链接
@@ -152,12 +176,12 @@ test {\iftoggle{iftlseven}}%3.7=biblatex
{\usebibmacro{cite:shorthand}%
\usebibmacro{cite:reinit}}%
\setunit{\multicitedelim}}
-\renewbibmacro*{textcite}{%
+\newbibmacro*{textcite}{%
\iffieldequals{namehash}{\cbx@lasthash}
{\iffieldundef{shorthand}
{\ifthenelse{\iffieldequals{labelyear}{\cbx@lastyear}\AND
\(\value{multicitecount}=0\OR\iffieldundef{postnote}\)}
- {\setunit{\compextradelim}%
+ {\setunit{\addcomma}%
\usebibmacro{cite:extradate}}
{\setunit{\compcitedelim}%
\usebibmacro{cite:labeldate+extradate}%
@@ -170,7 +194,7 @@ test {\iftoggle{iftlseven}}%3.7=biblatex
{\usebibmacro{cite:label}%
\setunit{%
\global\booltrue{cbx:parens}%
- \printdelim{nonameyeardelim}\bibopenparen}%
+ \printdelim{nonameyeardelim}\mkbibleftborder}%\bibopenparen
\ifnumequal{\value{citecount}}{1}
{\usebibmacro{prenote}}
{}%
@@ -179,7 +203,7 @@ test {\iftoggle{iftlseven}}%3.7=biblatex
{\iftoggle{bbx:gblabelref}{\printtext[bibhyperref]{\printnames{labelname}}}{\printnames{labelname}}%
\setunit{%
\global\booltrue{cbx:parens}%
- \printdelim{nameyeardelim}\bibopenparen}%
+ \printdelim{nameyeardelim}\mkbibleftborder}%\bibopenparen
\ifnumequal{\value{citecount}}{1}
{\usebibmacro{prenote}}
{}%
@@ -194,9 +218,69 @@ test {\iftoggle{iftlseven}}%3.7=biblatex
\savefield{namehash}{\cbx@lasthash}}%
\setunit{%
\ifbool{cbx:parens}
- {\bibcloseparen\global\boolfalse{cbx:parens}}
+ {\mkbibrightborder\global\boolfalse{cbx:parens}}%\bibcloseparen
{}%
- \textcitedelim}}}{}
+ \textcitedelim}}
+\newbibmacro*{textcite:postnote}{%
+ \usebibmacro{postnote}%
+ \ifthenelse{\value{multicitecount}=\value{multicitetotal}}
+ {\setunit{}%
+ \printtext{%
+ \ifbool{cbx:parens}
+ {\mkbibrightborder\global\boolfalse{cbx:parens}}%\bibcloseparen
+ {}}}
+ {\setunit{%
+ \ifbool{cbx:parens}
+ {\mkbibrightborder\global\boolfalse{cbx:parens}}%\bibcloseparen
+ {}%
+ \textcitedelim}}}
+%这是老版本的textcite,上面是新版本的,使用新版本后,对于老版本的biblatex的兼容性可能会受影响
+%\renewbibmacro*{textcite}{%
+% \iffieldequals{namehash}{\cbx@lasthash}
+% {\iffieldundef{shorthand}
+% {\ifthenelse{\iffieldequals{labelyear}{\cbx@lastyear}\AND
+% \(\value{multicitecount}=0\OR\iffieldundef{postnote}\)}
+% {\setunit{\compextradelim}%
+% \usebibmacro{cite:extradate}}
+% {\setunit{\compcitedelim}%
+% \usebibmacro{cite:labeldate+extradate}%
+% \savefield{labelyear}{\cbx@lastyear}}}
+% {\setunit{\compcitedelim}%
+% \usebibmacro{cite:shorthand}%
+% \global\undef\cbx@lastyear}}
+% {\ifnameundef{labelname}
+% {\iffieldundef{shorthand}
+% {\usebibmacro{cite:label}%
+% \setunit{%
+% \global\booltrue{cbx:parens}%
+% \printdelim{nonameyeardelim}\bibopenparen}%\bibopenparen\mkbibleftborder
+% \ifnumequal{\value{citecount}}{1}
+% {\usebibmacro{prenote}}
+% {}%
+% \usebibmacro{cite:labeldate+extradate}}
+% {\usebibmacro{cite:shorthand}}}
+% {\iftoggle{bbx:gblabelref}{\printtext[bibhyperref]{\printnames{labelname}}}{\printnames{labelname}}%
+% \setunit{%
+% \global\booltrue{cbx:parens}%
+% \printdelim{nameyeardelim}\bibopenparen}%\mkbibleftborder
+% \ifnumequal{\value{citecount}}{1}
+% {\usebibmacro{prenote}}
+% {}%
+% \iffieldundef{shorthand}
+% {\iffieldundef{labelyear}
+% {\usebibmacro{cite:label}}
+% {\usebibmacro{cite:labeldate+extradate}}%
+% \savefield{labelyear}{\cbx@lastyear}}
+% {\usebibmacro{cite:shorthand}%
+% \global\undef\cbx@lastyear}}%
+% \stepcounter{textcitecount}%
+% \savefield{namehash}{\cbx@lasthash}}%
+% \setunit{%
+% \ifbool{cbx:parens}
+% {\bibcloseparen\global\boolfalse{cbx:parens}}%\bibcloseparen\mkbibrightborder
+% {}%
+% \textcitedelim}}%
+}{}
@@ -229,6 +313,7 @@ test {\iftoggle{iftlseven}}%3.7=biblatex
{\mkbibrightborder\mkbibsuperscript{\usebibmacro{postnote}}%\usebibmacro{postnote}
}
+
%
% 定义upcite命令
% 20180604,v1.0l,hzz
@@ -332,7 +417,7 @@ test {\iftoggle{iftlseven}}%3.7=biblatex
\savefield{labelyear}{\cbx@lastyear}}}
{\iftoggle{bbx:gblabelref}{\printtext[bibhyperref]{\printnames{labelname}}}{\printnames{labelname}}%%
%\setunit{\printdelim{nameyeardelim}}%
- \gbleftparen\usebibmacro{cite:labeldate+extradate}\gbrightparen%
+ \mkbibleftborder\usebibmacro{cite:labeldate+extradate}\mkbibrightborder%
\savefield{namehash}{\cbx@lasthash}%
\savefield{labelyear}{\cbx@lastyear}}}}
{\usebibmacro{cite:shorthand}%
@@ -385,11 +470,11 @@ test {\iftoggle{iftlseven}}%3.7=biblatex
{\setunit{}%
\printtext{%
\ifbool{cbx:parens}
- {\bibcloseparen\global\boolfalse{cbx:parens}}
+ {\mkbibrightborder\global\boolfalse{cbx:parens}}%\bibcloseparen
{}}}
{\setunit{%
\ifbool{cbx:parens}
- {\bibcloseparen\global\boolfalse{cbx:parens}}
+ {\mkbibrightborder\global\boolfalse{cbx:parens}}%\bibcloseparen
{}%
\textcitedelim}}%
\renewbibmacro*{postnote}{%
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ms.bbx b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ms.bbx
index f60044ae8a..fe97e02286 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ms.bbx
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015ms.bbx
@@ -1786,6 +1786,7 @@
}
}
}
+ \let\defdblanentry=\defdoublelangentry
% 关联文献的输出格式
%
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015mx.bbx b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015mx.bbx
index 7f090e434a..e829ef3c3a 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015mx.bbx
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/gb7714-2015mx.bbx
@@ -2359,6 +2359,7 @@
}
}
}
+ \let\defdblanentry=\defdoublelangentry
%
% 关联文献间的分隔符
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/makeall.py b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/makeall.py
index b783537cb5..10b5db33dc 100644
--- a/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/makeall.py
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-gb7714-2015/makeall.py
@@ -20,7 +20,9 @@ def compileall():
pwd=os.getcwd()
filesneedcopy=['gb7714-CCNU.bbx','gb7714-CCNU.cbx','gb7714-NWAFU.bbx','gb7714-NWAFU.cbx','gb7714-SEU.bbx','gb7714-SEU.cbx',
- 'chinese-erj.bbx','chinese-erj.cbx','chinese-css.bbx','chinese-css.cbx','example.bib', 'gb7714-1987.bbx', 'gb7714-1987.cbx',
+ 'chinese-erj.bbx','chinese-erj.cbx','chinese-css.bbx','chinese-css.cbx',
+ 'chinese-jmw.bbx','chinese-jmw.cbx',
+ 'example.bib', 'gb7714-1987.bbx', 'gb7714-1987.cbx',
'gb7714-1987ay.bbx', 'gb7714-1987ay.cbx', 'gb7714-2005.bbx', 'gb7714-2005.cbx', 'gb7714-2005ay.bbx',
'gb7714-2005ay.cbx', 'gb7714-2015-gbk.def', 'gb7714-2015.bbx', 'gb7714-2015.cbx', 'gb7714-2015ay.bbx',
'gb7714-2015ay.cbx', 'gb7714-2015ms.bbx', 'gb7714-2015ms.cbx', 'gb7714-2015mx.bbx', 'gb7714-2015mx.cbx']
diff --git a/macros/latex/contrib/listlbls/Makefile b/macros/latex/contrib/listlbls/Makefile
index 20ecc6f468..64df745ce7 100644
--- a/macros/latex/contrib/listlbls/Makefile
+++ b/macros/latex/contrib/listlbls/Makefile
@@ -1,13 +1,17 @@
-NAME = listlbls
-SHELL = bash
-PWD = $(shell pwd)
-TEMP := $(shell mktemp -d)
-TDIR = $(TEMP)/$(NAME)
-VERS = $(shell ltxfileinfo -v $(NAME).dtx)
-LOCAL = $(shell kpsewhich --var-value TEXMFLOCAL)
-UTREE = $(shell kpsewhich --var-value TEXMFHOME)
-
-all: $(NAME).pdf README.md README clean
+NAME = listlbls
+SHELL = bash
+PWD = $(shell pwd)
+TEMP := $(shell mktemp -d)
+TDIR = $(TEMP)/$(NAME)
+VERS = $(shell ltxfileinfo -v $(NAME).dtx)
+LOCAL = $(shell kpsewhich --var-value TEXMFLOCAL)
+UTREE = $(shell kpsewhich --var-value TEXMFHOME)
+PREFIX ?= $(LOCAL)
+LATEX = xelatex
+SUDO = sudo
+
+all: $(NAME).pdf README.md README
+ $(MAKE) clean
README: README.txt
cp README.txt README
@@ -17,11 +21,12 @@ README.txt: $(NAME).pdf
README.md: $(NAME).pdf
$(NAME).pdf: $(NAME).dtx
- xelatex -shell-escape -recorder -interaction=batchmode $(NAME).dtx >/dev/null
+ $(LATEX) -shell-escape -recorder $(NAME).dtx
if [ -f $(NAME).glo ]; then makeindex -q -s gglo.ist -o $(NAME).gls $(NAME).glo; fi
if [ -f $(NAME).idx ]; then makeindex -q -s gind.ist -o $(NAME).ind $(NAME).idx; fi
- xelatex -shell-escape -recorder -interaction=nonstopmode $(NAME).dtx > /dev/null
- xelatex -shell-escape -recorder -interaction=nonstopmode $(NAME).dtx > /dev/null
+ $(LATEX) -shell-escape -recorder -interaction=scrollmode $(NAME).dtx
+ $(LATEX) -shell-escape -recorder -interaction=scrollmode $(NAME).dtx
+ $(LATEX) -shell-escape -recorder -interaction=scrollmode $(NAME).dtx
clean:
rm -f *.fls
@@ -31,16 +36,13 @@ distclean: clean
rm -f $(NAME).{pdf,sty} README{,.{md,txt}}
inst: all
- mkdir -p $(UTREE)/{tex,source,doc}/latex/$(NAME)
- cp $(NAME).dtx $(UTREE)/source/latex/$(NAME)
- cp $(NAME).sty $(UTREE)/tex/latex/$(NAME)
- cp $(NAME).pdf $(UTREE)/doc/latex/$(NAME)
+ $(MAKE) install PREFIX=$(UTREE) SUDO=""
install: all
- sudo mkdir -p $(LOCAL)/{tex,source,doc}/latex/$(NAME)
- sudo cp $(NAME).dtx $(LOCAL)/source/latex/$(NAME)
- sudo cp $(NAME).sty $(LOCAL)/tex/latex/$(NAME)
- sudo cp $(NAME).pdf $(LOCAL)/doc/latex/$(NAME)
+ $(SUDO) mkdir -p $(PREFIX)/{tex,source,doc}/latex/$(NAME)
+ $(SUDO) cp $(NAME).dtx $(PREFIX)/source/latex/$(NAME)
+ $(SUDO) cp $(NAME).sty $(PREFIX)/tex/latex/$(NAME)
+ $(SUDO) cp $(NAME).pdf $(PREFIX)/doc/latex/$(NAME)
zip: all
mkdir $(TDIR)
diff --git a/macros/latex/contrib/listlbls/listlbls.dtx b/macros/latex/contrib/listlbls/listlbls.dtx
index 52da33c381..a52b55a6cf 100644
--- a/macros/latex/contrib/listlbls/listlbls.dtx
+++ b/macros/latex/contrib/listlbls/listlbls.dtx
@@ -120,17 +120,17 @@ Running "make install" installs the files in the local TeX tree.
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{listlbls}
%<*package>
- [2014/08/04 v1.03 Creates a list of all labels used throughout a document]
+ [2023/05/24 v1.04 Creates a list of all labels used throughout a document]
%</package>
%<*driver>
\documentclass{ltxdoc}
\usepackage{microtype}
-\usepackage{libertine}
-\usepackage[a4paper,margin=25mm,left=50mm,nohead]{geometry}
-\usepackage{colordoc}
+\usepackage{lmodern}
+\usepackage{fontawesome5}
+\usepackage[a4paper,margin=25mm,left=45mm,nohead]{geometry}
\usepackage{multicol}
-\usepackage{dox}
-\doxitem{Option}{option}{option}
+\usepackage[reportchangedates]{doc}
+\usepackage{dtxdescribe}
\usepackage[numbered]{hypdoc}
\usepackage{xspace}
\usepackage{nameref}
@@ -140,6 +140,10 @@ Running "make install" installs the files in the local TeX tree.
\CodelineIndex
\RecordChanges
\newcommand\TSE{\href{http://tex.stackexchange.com/}{\TeX-Stackexchange}\xspace}
+
+\newcommand\link[2]{\href{#1}{#2}\footnote{\nolinkurl{#1}}}
+\newcommand\ghissue[3]{\link{https://github.com/#1/#2/issues/#3}{\faIcon{github}~#1/#2\##3}}
+\newcommand\thisissue[1]{\ghissue{nobbz}{listlbls}{#1}}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
@@ -160,9 +164,11 @@ Running "make install" installs the files in the local TeX tree.
%\changes{v1.00}{2014/07/25}{First public release}
%\changes{v1.01}{2014/07/25}{Changed maintainer email}
%\changes{v1.01}{2014/07/25}{Changed some internal stuff to make it releaseable on CTAN}
-%\changes{v1.02}{2014/07/26}{Local option wins agains global option}
+%\changes{v1.02}{2014/07/27}{Local option wins agains global option}
%\changes{v1.02}{2014/07/27}{Added languag-support for English, German and French.}
%\changes{v1.03}{2014/08/04}{Proceeding with namespacing internal macros}
+%\changes{v1.04}{2023/05/24}{Fix build problems due to bitrotten dependencies}
+%\changes{v1.04}{2023/05/24}{Switch back to lmodern for documentation}
% \begin{abstract}
% This is a package meant to help a \LaTeX-writer to keep track all the defined labels by typesetting a complete list of labels whereever the author requests it. Keep in mind, that you might need to have additional \LaTeX\ runs to get the references right.
%
@@ -183,8 +189,10 @@ Running "make install" installs the files in the local TeX tree.
% \subsection{From Github}\label{ssec:inst-gh}
%
% \begin{enumerate}
-% \item Check out the sourcecode from \href{https://github.com/}{GitHub}:\\
-% |git clone git@github.com:NobbZ/listlbls.git|
+% \item Check out the sourcecode from \link{https://github.com/}{GitHub}:\\
+% |git clone https://github.com/NobbZ/nixos-config.git| or\\
+% |git clone git@github.com:NobbZ/listlbls.git| or\\
+% |gh repo clone NobbZ/listlbls|
% \item Switch to the source-folder:\\|cd listlbls|
% \item Checkout the branch/tag you desire: |master| for latest release, |develop| for latest builds (might be broken) or the version number desired.\\
% |git checkout <branch/tag>|
@@ -240,9 +248,12 @@ Running "make install" installs the files in the local TeX tree.
%
% Then anywhere in your document, you can use the |\listoflabels|-macro to typeset a list of labels. An example can be seen on page \pageref{special:listoflabels}.
%
-% \DescribeMacro{\label} Use |\label| as you are used to it!
+% \DescribeMacro{\label} \marg{name}
+% Use |\label| as you are used to it!
%
-% \DescribeMacro{\listoflabels} This macro will typeset the list of labels when this module is in draft mode. It will itself register the label ``|special:listoflabels|''.
+% \DescribeMacro{\listoflabels} \oarg{label}
+% This macro will typeset the list of labels when this module is in draft mode.
+% It will itself register the label from the optional arg, defaulting to ``|special:listoflabels|''.
%
%\StopEventually{^^A
% \PrintChanges
@@ -254,11 +265,11 @@ Running "make install" installs the files in the local TeX tree.
%
% \section{Contribution and bugreports}\label{sec:contribute}
%
-% If you have feature-requests or bug-reports, please feel free to report them on the \href{https://github.com/NobbZ/listlbls}{project page at GitHub}.
+% If you have feature-requests or bug-reports, please feel free to report them on the \link{https://github.com/NobbZ/listlbls}{project page at GitHub}.
%
% If you want to contribute then follow these steps:
% \begin{enumerate}
-% \item Visit the \href{https://github.com/NobbZ/listlbls}{project page at GitHub},
+% \item Visit the \link{https://github.com/NobbZ/listlbls}{project page at GitHub},
% \item forkt it,
% \item clone it to your local machine,
% \item create a branch ``|feature/|\meta{feature name}'',
@@ -268,6 +279,17 @@ Running "make install" installs the files in the local TeX tree.
% \item and wait for approval.
% \end{enumerate}
% After approval your code will be merged to the |development|-branch and I will generally not accept pull-requests that edit |develop| directly.
+%
+% \section{Known issues and limitations}\label{sec:issues}
+% \changes{v1.04}{2023/05/24}{Add issues and limitations section}
+%
+% \subsection{\texttt{\textbackslash{}include}}\label{ssec:issues-include}
+%
+% Documents containing |\include| will not work.
+% Currently there is no logic to recurse through the different |.aux|-files.
+%
+% Please see \thisissue{4} for more information.
+%
% \section{Implementation}\label{sec:implementation}
%
% \begin{macrocode}
@@ -280,7 +302,7 @@ Running "make install" installs the files in the local TeX tree.
% \subsection{Options}\label{ssec:impl-options}
% \begin{option}{draft}
% \changes{v1.01}{2014/07/25}{Added option}
-% \changes{v1.02}{2014/07/26}{Introduced @ifdraft}
+% \changes{v1.02}{2014/07/27}{Introduced @ifdraft}
% Check for |draft|-option:
% \begin{macrocode}
\DeclareOption{draft}{\llbls@drafttrue}
@@ -288,21 +310,21 @@ Running "make install" installs the files in the local TeX tree.
% \end{option}
% \begin{option}{final}
% \changes{v1.01}{2014/07/25}{Added option}
-% \changes{v1.02}{2014/07/26}{Introduced @ifdraft}
+% \changes{v1.02}{2014/07/27}{Introduced @ifdraft}
% Check for |final|-option:
% \begin{macrocode}
\DeclareOption{final}{\llbls@draftfalse}
% \end{macrocode}
% \end{option}
% \begin{option}{totoc}
-% \changes{v1.02}{2014/07/26}{Added option}
+% \changes{v1.02}{2014/07/27}{Added option}
% Check for |totoc|-option:
% \begin{macrocode}
\DeclareOption{totoc}{\llbls@totoctrue}
% \end{macrocode}
% \end{option}
% \begin{option}{notoc}
-% \changes{v1.02}{2014/07/26}{Added option}
+% \changes{v1.02}{2014/07/27}{Added option}
% Check for |notoc|-option:
% \begin{macrocode}
\DeclareOption{notoc}{\llbls@totocfalse}
@@ -368,14 +390,27 @@ Running "make install" installs the files in the local TeX tree.
{llbls-onpage}%
{\`a la page}
% \end{macrocode}
+% \subsubsection{Portuguese}\label{sssec:impl-i18n-pt}
+% \changes{v1.04}{2023/05/24}{Add Portuguese translation}
+% \begin{macrocode}
+\DeclareTranslation{Portuguese}%
+ {llbls-listoflabels}%
+ {Lista de R\'{o}tulos}
+\DeclareTranslation{Portuguese}%
+ {llbls-onpage}%
+ {na p\'{a}gina}
+% \end{macrocode}
% \subsection{Internal stuff}\label{ssec:impl-internal}
% \begin{macro}{\llbls@headline}\begin{macro}{\llbls@toccommand}\begin{macro}{\llbls@tocgroup}
% Determine if we have |\chapter|s or not and create a command that maps to |\chapter| or |\section| as needed.
% \begin{macrocode}
-\ifdefined\chapter*
+\ifdefined\chapter
\ifllbls@numtoc
\def\llbls@headline{%
- \chapter{List of Labels}\label{special:listoflabels}}
+% \end{macrocode}
+% We are using |\llbls@labelname| here and in the other possible definitions of |\llbls@headline| to be able to set the label name in the |\listoflabels| macro.
+% \begin{macrocode}
+ \chapter{List of Labels}\label{\llbls@labelname}}
\else
\def\llbls@toccommand{\chapter*}
\def\llbls@tocgroup{chapter}
@@ -383,7 +418,7 @@ Running "make install" installs the files in the local TeX tree.
\else
\ifllbls@numtoc
\def\llbls@headline{%
- \section{List of Labels}\label{special:listoflabels}}
+ \section{List of Labels}\label{\llbls@labelname}}
\else
\def\llbls@toccommand{\section*}
\def\llbls@tocgroup{section}
@@ -392,7 +427,7 @@ Running "make install" installs the files in the local TeX tree.
\ifdefined\llbls@headline\else
\def\llbls@headline{%
\llbls@toccommand{\GetTranslation{llbls-listoflabels}}%
- \label{special:listoflabels}%
+ \label{\llbls@labelname}%
\ifllbls@totoc%
\addcontentsline{toc}%
{\llbls@tocgroup}%
@@ -428,7 +463,7 @@ Running "make install" installs the files in the local TeX tree.
% \end{macro}
%
% \begin{macro}{\llbls@showlabel}
-% \changes{v1.03}{2014/07/27}{Add support for nameref-package}
+% \changes{v1.02}{2014/08/04}{Add support for nameref-package}
% Displays a single entry in the |\listoflabels|
% \begin{macrocode}
\def\llbls@showlabel#1#2{%
@@ -454,13 +489,16 @@ Running "make install" installs the files in the local TeX tree.
\ifllbls@draft
% \end{macrocode}
% \begin{macro}{\listoflabels}
+% \changes{v1.04}{2023/05/24}{add optional argument to change the name of the label used.}
+% \begin{macro}{\llbls@labelname}
% Print a list of all available lables that are defined throughout the document.
% \begin{macrocode}
- \newcommand\listoflabels{%
+ \newcommand{\listoflabels}[1][special:listoflabels]{%
+ \def\llbls@labelname{#1}%
\llbls@headline%
\the\llbls@lablist}
% \end{macrocode}
-% \end{macro}
+% \end{macro}\end{macro}
% \begin{macrocode}
\else
\let\listoflabels=\relax
diff --git a/macros/latex/contrib/listlbls/listlbls.pdf b/macros/latex/contrib/listlbls/listlbls.pdf
index 15a732d799..537f54e51a 100644
--- a/macros/latex/contrib/listlbls/listlbls.pdf
+++ b/macros/latex/contrib/listlbls/listlbls.pdf
Binary files differ
diff --git a/macros/latex/contrib/nicematrix/nicematrix-code.dtx b/macros/latex/contrib/nicematrix/nicematrix-code.dtx
index 4c28160949..93555aa1e5 100644
--- a/macros/latex/contrib/nicematrix/nicematrix-code.dtx
+++ b/macros/latex/contrib/nicematrix/nicematrix-code.dtx
@@ -17,8 +17,8 @@
%
% \fi
% \iffalse
-\def\myfileversion{6.19}
-\def\myfiledate{2023/05/15}
+\def\myfileversion{6.19a}
+\def\myfiledate{2023/05/25}
%
%
%<*batchfile>
@@ -1743,7 +1743,10 @@ version 2005/12/01 or later.
\seq_map_indexed_inline:Nn \g_@@_notes_seq
{
\tl_if_eq:nnT { { #1 } { #2 } } { ##2 }
- { \int_set:Nn \l_tmpa_int { ##1 } \seq_map_break: }
+ {
+ \int_set:Nn \l_tmpa_int { ##1 }
+ \seq_map_break:
+ }
}
\int_compare:nNnF \l_tmpa_int = \c_zero_int
{ \int_add:Nn \l_tmpa_int \g_@@_notes_caption_int }
@@ -1829,31 +1832,20 @@ version 2005/12/01 or later.
{ \int_gzero:N \c@tabularnote }
% \end{macrocode}
% Now, we try to detect duplicate notes in the caption.
+% Be careful! We must put |\tl_if_in:NnF| and not |\tl_if_in:NnT|!
% \begin{macrocode}
- \bool_set_false:N \l_tmpa_bool
- \seq_map_inline:Nn \g_@@_notes_in_caption_seq
- { \@@_if_eq_two_three:nnn ##1 { #2 } }
-% \end{macrocode}
-% Be careful! We must put |\bool_if:NF| and not |\bool_if:NT|!
-% \begin{macrocode}
- \bool_if:NF \l_tmpa_bool
+ \seq_if_in:NnF \g_@@_notes_in_caption_seq { { #1 } { #2 } }
{ \@@_error:n { Identical~notes~in~caption } }
}
{
% \end{macrocode}
% In the following code, we are in the first composition of the caption or at
-% the first |\tabularnote| of the second composition. We have
-% to see whether the text of our tabular note is among the texts of the
-% tabularnotes stored in |\g_@@_notes_in_caption_seq|. For that, we will loop on
-% |\g_@@_notes_in_caption_seq| and we will raise |\l_tmpa_bool| if the text is found.
+% the first |\tabularnote| of the second composition.
% \begin{macrocode}
- \bool_set_false:N \l_tmpa_bool
- \seq_map_inline:Nn \g_@@_notes_in_caption_seq
- { \@@_if_eq_two_three:nnn ##1 { #2 } }
- \bool_if:NTF \l_tmpa_bool
+ \seq_if_in:NnTF \g_@@_notes_in_caption_seq { { #1 } { #2 } }
{
% \end{macrocode}
-% Now, we known that are in the second composition of the caption since we are
+% Now, we know that are in the second composition of the caption since we are
% reading a tabular note which has yet been read. Now, the value of
% |\g_@@_notes_caption_int| won't change anymore: it's the number of uses
% \emph{without optional argument} of the command |\tabularnote| in the caption.
@@ -1884,16 +1876,6 @@ version 2005/12/01 or later.
}
% \end{macrocode}
%
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_if_eq_two_three:nnn #1 #2 #3
- {
- \tl_if_eq:nnT { #2 } { #3 }
- {
- \bool_set_true:N \l_tmpa_bool
- \seq_map_break:
- }
- }
-% \end{macrocode}
%
% \begin{macrocode}
\cs_new_protected:Npn \@@_count_novalue_first:nn #1 #2
@@ -9218,7 +9200,8 @@ version 2005/12/01 or later.
%
% In the |\CodeAfter|, the command |\@@_line:nn| will be linked to |\line|. This
% command takes two arguments which are the specifications of two cells in the
-% array (in the format $i$-$j$) and draws a dotted line between these cells.
+% array (in the format $i$-$j$) and draws a dotted line between these cells. In
+% fact, if also works with names of blocks.
%
% \medskip
% First, we write a command with the following behaviour:
@@ -9284,7 +9267,10 @@ version 2005/12/01 or later.
{
\@@_error:nnn { unknown~cell~for~line~in~CodeAfter } { #1 } { #2 }
}
- { \@@_draw_line_ii:nn { #1 } { #2 } }
+% \end{macrocode}
+% The test of |measuring@| is a security (cf. question 686649 on TeX StackExchange).
+% \begin{macrocode}
+ { \legacy_if:nF { measuring@ } { \@@_draw_line_ii:nn { #1 } { #2 } } }
}
% \end{macrocode}
%
diff --git a/macros/latex/contrib/nicematrix/nicematrix-code.pdf b/macros/latex/contrib/nicematrix/nicematrix-code.pdf
index 6cc99d6835..923fd4f553 100644
--- a/macros/latex/contrib/nicematrix/nicematrix-code.pdf
+++ b/macros/latex/contrib/nicematrix/nicematrix-code.pdf
Binary files differ
diff --git a/macros/latex/contrib/nicematrix/nicematrix-french.pdf b/macros/latex/contrib/nicematrix/nicematrix-french.pdf
index fcc05694fd..d7c7d18c98 100644
--- a/macros/latex/contrib/nicematrix/nicematrix-french.pdf
+++ b/macros/latex/contrib/nicematrix/nicematrix-french.pdf
Binary files differ
diff --git a/macros/latex/contrib/nicematrix/nicematrix-french.tex b/macros/latex/contrib/nicematrix/nicematrix-french.tex
index 1b5bf2b9df..b27ce64a4e 100644
--- a/macros/latex/contrib/nicematrix/nicematrix-french.tex
+++ b/macros/latex/contrib/nicematrix/nicematrix-french.tex
@@ -1808,7 +1808,10 @@ l'extension \pkg{xcolor} ;
rowcolor}, etc.)}
\colorbox{yellow!50}{\textbf{Nouveau 6.18}}
-une spécification d'opacité selon la forme \texttt{opacity = \textsl{valeur}}.
+une spécification d'opacité selon la forme \texttt{opacity =
+ \textsl{valeur}}.\footnote{Attention : cette fonctionnalité génère des instructions de
+ transparence dans le \textsc{pdf} résultant et certains lecteurs de
+ \textsc{pdf} n'acceptent pas la transparence.}
\end{itemize}
diff --git a/macros/latex/contrib/nicematrix/nicematrix.pdf b/macros/latex/contrib/nicematrix/nicematrix.pdf
index 474dac2ee0..9f3a9dfb70 100644
--- a/macros/latex/contrib/nicematrix/nicematrix.pdf
+++ b/macros/latex/contrib/nicematrix/nicematrix.pdf
Binary files differ
diff --git a/macros/latex/contrib/nicematrix/nicematrix.tex b/macros/latex/contrib/nicematrix/nicematrix.tex
index 6cf322afa9..f09d282e10 100644
--- a/macros/latex/contrib/nicematrix/nicematrix.tex
+++ b/macros/latex/contrib/nicematrix/nicematrix.tex
@@ -1755,7 +1755,9 @@ by a comma)
the extension \pkg{xcolor};
\item \index{opacity (key of commands such as\newline \texttt{\textbackslash rowcolor}, etc.)}
\colorbox{yellow!50}{\textbf{New 6.18}}\par\nobreak
-a specification of opacity f the form \texttt{opacity = \textsl{value}}.
+a specification of opacity of the form \texttt{opacity =
+ \textsl{value}}.\footnote{Caution : that feature creates instructions of
+ transparency in the \textsc{pdf} and some \textsc{pdr} don't support such instructions.}
\end{itemize}
\bigskip
diff --git a/macros/latex/contrib/oststud/hsrstud-classes.pdf b/macros/latex/contrib/oststud/hsrstud-classes.pdf
index 29590a39a7..8fc79d86d6 100644
--- a/macros/latex/contrib/oststud/hsrstud-classes.pdf
+++ b/macros/latex/contrib/oststud/hsrstud-classes.pdf
Binary files differ
diff --git a/macros/latex/contrib/oststud/hsrstud.pdf b/macros/latex/contrib/oststud/hsrstud.pdf
index cf1ad1e27f..0f3a59381e 100644
--- a/macros/latex/contrib/oststud/hsrstud.pdf
+++ b/macros/latex/contrib/oststud/hsrstud.pdf
Binary files differ
diff --git a/macros/latex/contrib/oststud/oststud.dtx b/macros/latex/contrib/oststud/oststud.dtx
index 35539e7b19..c9aadcfbb8 100644
--- a/macros/latex/contrib/oststud/oststud.dtx
+++ b/macros/latex/contrib/oststud/oststud.dtx
@@ -19,7 +19,7 @@
%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<package>\ProvidesPackage{oststud}
%<*package>
- [2023/04/18 v0.3 OST Student's package]
+ [2023/05/20 v0.4 OST Student's package]
%</package>
%
%<*driver>
@@ -27,6 +27,7 @@
\usepackage{oststud}
\usepackage{enumitem}
+\usepackage{esint}
\usepackage{tikz}
\usepackage{framed}
\usepackage[
@@ -50,6 +51,7 @@
% \changes{v0.1}{2022/11/18}{Initial version}
% \changes{v0.2}{2022/11/22}{Port features of \texttt{hsrstud}}
% \changes{v0.3}{2023/04/18}{Cleanup for CTAN upload}
+% \changes{v0.4}{2023/05/20}{Fix probability operators and improve documentation}
%
% \GetFileInfo{oststud.dtx}
%
@@ -87,8 +89,12 @@
% derivatives. Instead the symbols \(\vec{\nabla}, \vec{\nabla}\dotp,
% \vec{\nabla}\crossp, \nabla^2, \vec{\nabla}^2\) are be replaced with
% grad, div, curl and div grad.
-% \item[|bfemph|] \textit{Work in progress.}
-% \item[|bbprobability|] \textit{Work in progress.}
+% \item[|bfemph|] Change the behaviour of |\emph| to use a bold font for
+% emphasis (instead of italics). This option cannot be used together
+% with the |dontrenew| option.
+% \item[|bbprobability|] Use blackboard symbols $\mathbb{P}$, $\mathbb{E}$
+% and $\mathbb{V}$ instead of Pr, E and Var for the probability,
+% expectation and variance respectively.
% \item[|scrtransforms|] \textit{Work in progress.}
% \end{description}
%
@@ -106,6 +112,9 @@
% arrow ($\oldvec{u}$) is replaced by bold and the arrow notation saved in
% |\oldvec|. In vector calculus it is common to denote unit vectors by putting
% a hat, so there is a macro |\uvec| that does just that:
+% ^^A \begin{leftbar}
+% ^^A |\uvec{u} = \vec{u}/u|
+% ^^A \end{leftbar}
% \[
% \uvec{u} = \vec{u}/u.
% \]
@@ -115,6 +124,9 @@
% To differentiate the dot and cross products (between vectors) from normal
% product between scalars ($a \cdot b$ and $a \times b$), the macros |\dotp|
% and |\crossp| provide a bold variant:
+% \begin{leftbar}
+% |\vec{u} \dotp \vec{v}, \vec{u} \crossp \vec{v}|
+% \end{leftbar}
% \[
% \vec{u} \dotp \vec{v}, \qquad
% \vec{u} \crossp \vec{v}.
@@ -133,6 +145,9 @@
% divergence and the symbol $\divsymb$ is saved in |\divsymb|. For a scalar
% field $\phi$ or a vector field $\vec{F}$ the notation (in order) of the
% gradient, divergence and curl appear as follows:
+% \begin{leftbar}
+% |\grad \phi, \div \vec{F}, \curl \vec{F}|
+% \end{leftbar}
% \[
% \grad \phi, \quad
% \div \vec{F}, \quad
@@ -143,6 +158,9 @@
% \DescribeMacro{\vlaplacian}
% Continuing with the (ab)use of the ``Nabla'' or ``Del'' notation, the
% there is a macro |\laplacian| for the Laplacian operator
+% \begin{leftbar}
+% |\laplacian \equiv \div \grad \equiv \sum_i \partial^2_i|
+% \end{leftbar}
% \[
% \laplacian \equiv \div \grad \equiv \sum_i \partial^2_i.
% \]
@@ -191,9 +209,15 @@
% \DescribeMacro{\tr}
% This package also provides a macro for the trace of a matrix.
%
-% \subsection{Complex Numbers}
+% \subsection{Mathematical Programming}
%
+% \DescribeMacro{\argmin}
+% \DescribeMacro{\argmax}
% ^^A TODO: write section
+% \textit{Work in progress.}
+%
+% \subsection{Complex Numbers}
+%
% \DescribeMacro{\Re}
% \DescribeMacro{\Im}
% AMS maths's default notation for the real and imaginary parts of a complex
@@ -206,17 +230,76 @@
%
% \subsection{Probability Operators}
%
-% ^^A TODO: write section
-% \textit{Work in progress.}
+% \DescribeMacro{\Pr}
+% \DescribeMacro{\E}
+% \DescribeMacro{\Var}
+% Since according to quantum mechanics it seems that ultimately the universe
+% can only be described using probabilities there are the operators |\Pr|, |\E|
+% and |\Var| for the probability, expectation and variance respectively. If the
+% |dontrenew| option is set, the probability is defined in the csname |\P|.
+%
+% All three operators take an argument \marg{expression} which is automatically
+% surrounded using curly braces. If the expression contains multiple random
+% variables, to disambiguate with respect to which variable the operation is
+% being taken it is possible to specify an optional argument \oarg{rv}. An
+% example:
+% \begin{leftbar}
+% |\E[x]{g(x)} = \int_\mathcal{X} g(\bar{x}) p_x(\bar{x}) \, d\bar{x}|
+% \end{leftbar}
+% \[
+% \E[x]{g(x)} = \int_\mathcal{X} g(\bar{x}) p_x(\bar{x}) \, d\bar{x}.
+% \]
+%
+% Because some people like to use the blackboard font for the probability
+% operators (such as in the machine learning community), there is an option
+% |bbprobability| that changes the look of the three operators to $\mathbb{P}$,
+% $\mathbb{E}$ and $\mathbb{V}$.
%
% \subsection{Transformation Operators}
%
-% ^^A TODO: write section
-% \textit{Work in progress.}
+% \DescribeMacro{\corresponds}
+% \DescribeMacro{\rcorresponds}
+% When working with transformations it is common to use the ``correspondence
+% symbol'' show below for example with the Laplace transformation:
+% \begin{leftbar}
+% |\laplace\{f(t)\} = F(s) \corresponds f(t) \rcorresponds F(s)|
+% \end{leftbar}
% \[
% \laplace\{f(t)\} = F(s) \corresponds f(t) \rcorresponds F(s)
% \]
%
+% \DescribeMacro{\fourier}
+% \DescribeMacro{\ifourier}
+% \DescribeMacro{\laplace}
+% \DescribeMacro{\ilaplace}
+% \DescribeMacro{\ztransf}
+% \DescribeMacro{\iztransf}
+% \DescribeMacro{\hilbert}
+% As shown in the example above the for the Laplace transform operator symbol
+% there is a macro |\laplace|. Similar operators are also defined for other
+% transformations and their inverses. Here is their usual definition:
+% \begin{align*}
+% \fourier\left\{f(t)\right\}(\omega)
+% &= \frac{1}{\sqrt{2\pi}} \int_\mathbb{R} f(t) e^{-i\omega t} \, dt, &
+% \ifourier\left\{F(\omega)\right\}(t)
+% &= \frac{1}{\sqrt{2\pi}} \int_\mathbb{R} F(\omega) e^{i\omega t} \, d\omega, \\
+% \laplace\left\{f(t)\right\}(s)
+% &= \int_\mathbb{R^+} f(t) e^{-st} \, dt, &
+% \ilaplace\left\{F(s)\right\}(t)
+% &= \frac{1}{2\pi i}\int_{\gamma + i\mathbb{R}} F(s) e^{st} \, ds, \\
+% \ztransf \left\{f_k\right\}(z)
+% &= \sum_{k \in \mathbb{Z}^+} f_k z^{-k}, &
+% \iztransf \left\{F(z)\right\}(k)
+% &= \frac{1}{2\pi i} \ointctrclockwise_C F(z) z^{k-1} \, dz, \\
+% \hilbert \left\{ f(t) \right\}(\tau)
+% &= \mathrm{P.V.} \frac{1}{\pi} \int_\mathbb{R} \frac{f(t)}{\tau - t} \, dt,
+% \end{align*}
+% in order they are the Fourier transform (|\fourier|, |\ifourier|), the
+% Laplace transform (|\laplace|, |\ilaplace|), the Z-transform (|\ztransf|,
+% |\iztransf|), and the Hilbert transform (|\hilbert|). The Hilbert has no
+% inverse since $-\hilbert \hilbert f(t) = f(t)$, tough of course one could
+% write |\hilbert^{-1}| to get $\hilbert^{-1}$.
+%
% \subsection{References}
%
% ^^A TODO: write section
@@ -460,11 +543,11 @@
% Expectation of a random variable.
% \begin{macrocode}
\ifost@bbprobability
- \DeclareMathOperator{\ost@expectation}{\mathbb{E}}
+ \DeclareMathOperator*{\ost@expectation}{\mathbb{E}}
\else
- \DeclareMathOperator{\ost@expectation}{E}
+ \DeclareMathOperator*{\ost@expectation}{E}
\fi
-\newcommand{\E}[1]{\ost@expectation\left\{#1\right\}}
+\newcommand*{\E}[2][]{\ost@expectation_{#1}\left\{#2\right\}}
% \end{macrocode}
% \end{macro}
%
@@ -472,11 +555,11 @@
% Variance of a random variable.
% \begin{macrocode}
\ifost@bbprobability
- \DeclareMathOperator{\ost@variance}{\mathbb{V}}
+ \DeclareMathOperator*{\ost@variance}{\mathbb{V}}
\else
- \DeclareMathOperator{\ost@variance}{Var}
+ \DeclareMathOperator*{\ost@variance}{Var}
\fi
-\newcommand{\Var}[1]{\ost@variance\left\{#1\right\}}
+\newcommand*{\Var}[2][]{\ost@variance_{#1}\left\{#2\right\}}
% \end{macrocode}
% \end{macro}
%
@@ -484,14 +567,14 @@
% Probability operator.
% \begin{macrocode}
\ifost@bbprobability
- \DeclareMathOperator{\ost@probability}{\mathbb{P}}
+ \DeclareMathOperator*{\ost@probability}{\mathbb{P}}
\else
- \DeclareMathOperator{\ost@probability}{Pr}
+ \DeclareMathOperator*{\ost@probability}{Pr}
\fi
\ifost@dontrenew
- \newcommand{\P}[1]{\ost@probability\left\{#1\right\}}
+ \newcommand*{\P}[2][]{\ost@probabiliy_{#1}\left\{#2\right\}}
\else
- \renewcommand{\Pr}[1]{\ost@probability\left\{#1\right\}}
+ \renewcommand*{\P}[2][]{\ost@probabiliy_{#1}\left\{#2\right\}}
\fi
% \end{macrocode}
% \end{macro}
diff --git a/macros/latex/contrib/oststud/oststud.pdf b/macros/latex/contrib/oststud/oststud.pdf
index 74abd99be0..1e0148e24b 100644
--- a/macros/latex/contrib/oststud/oststud.pdf
+++ b/macros/latex/contrib/oststud/oststud.pdf
Binary files differ