diff --git a/base/changes.txt b/base/changes.txt index f84abfa95..5bca41bce 100644 --- a/base/changes.txt +++ b/base/changes.txt @@ -6,6 +6,11 @@ to completeness or accuracy and it contains some references to files that are not part of the distribution. ================================================================================ +2023-12-02 Frank Mittelbach + * doc.dtx (subsection{API creation}): + Provide \ProvideDocElement for use cases where files are processed + individually as well as together, e.g., the LaTeX kernel documentation. + 2023-12-01 Joseph Wright * ltcmd.dtx (subsection{Declaring commands and environments}): Optimize creation of simple document commands (gh/1189) diff --git a/base/doc.dtx b/base/doc.dtx index 961ccdb18..ee53875da 100644 --- a/base/doc.dtx +++ b/base/doc.dtx @@ -45,7 +45,7 @@ %<+package> %<+package>\ProvidesPackage{doc} %<+shortvrb>\ProvidesPackage{shortvrb} -%<+package|shortvrb> [2022/11/13 v3.0m +%<+package|shortvrb> [2023/12/02 v3.0n %<+package|shortvrb> Standard LaTeX documentation package V3 (FMi)] %\catcode`\<=12 % @@ -695,6 +695,12 @@ % |\NewDocElement{Env}{environment}| % though that's not quite what has been done, as we will see later. % +% \DescribeInterfaceMacro{\ProvideDocElement} +% This declaration does nothing when the doc element is already +% declared, otherwise it works like \cs{NewDocElement}. It can be +% useful if you have many documentation files that you may want to +% process individually as well as together. +% % \DescribeOption[noprint]{macrolike} % \DescribeOption[noprint]{envlike} % \DescribeOption[noprint]{toplevel} @@ -5940,6 +5946,16 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\doc@ignoredinfo} +% +% \begin{macrocode} +\def\doc@ignoredinfo#1#2{% + \PackageInfo{doc}{Doc element '#1/#2' declaration + ignored}% +} +% \end{macrocode} +% \end{macro} +% % % \begin{imacro}{\NewDocElement} % \oarg{options}\marg{name}\marg{envname} @@ -5963,6 +5979,30 @@ % \end{macrocode} % \end{imacro} % +% \begin{imacro}{\ProvideDocElement} +% \oarg{options}\marg{name}\marg{envname} +% This does nothing unless the doc element could be declared with +% \cs{NewDocElement}. +% \begin{macrocode} +\newcommand\ProvideDocElement[3][]{% +% \end{macrocode} +% +% \begin{macrocode} + \@ifundefined{Print#2Name}% + {\@ifundefined{PrintDescribe#2}% + {\@ifundefined{#3}% + {\@ifundefined{end#3}% + {\@NewDocElement{#1}}% + \doc@ignoredinfo + }\doc@ignoredinfo + }\doc@ignoredinfo + }\doc@ignoredinfo + {#2}{#3}% +} +% \end{macrocode} +% \end{imacro} +% +% % \begin{imacro}{\RenewDocElement} % \oarg{options}\marg{name}\marg{envname} % diff --git a/base/doc/ltnews39.tex b/base/doc/ltnews39.tex index ebcb3eb0a..52bc4c5a2 100644 --- a/base/doc/ltnews39.tex +++ b/base/doc/ltnews39.tex @@ -148,6 +148,14 @@ \section{Introduction} \section{New or improved commands} +\subsection{pkg{doc}: provide \cs{ProvideDocElement}} + +Beside \cs{NewDocElement} and \cs{RenewDocElement} we now also offer a +\cs{ProvideDocElement} declaration that does nothing unless the doc +element could be declared with \cs{NewDocElement}. This can be useful +if documentation files are processed both individually as well as +combined. + \section{Code improvements} diff --git a/base/testfiles-doc/tlb-dox006.luatex.tlg b/base/testfiles-doc/tlb-dox006.luatex.tlg index 942b300db..4a4c8ea7c 100644 --- a/base/testfiles-doc/tlb-dox006.luatex.tlg +++ b/base/testfiles-doc/tlb-dox006.luatex.tlg @@ -9,6 +9,16 @@ There is already a definition for '\PrintOptionName', '\PrintDescribeOption' or the environment 'option'. Maybe you are overwriting something by mistake! Otherwise use '\RenewDocElement' instead. +! Package doc Error: Doc element 'Option/option' unknown. +See the doc package documentation for explanation. +Type H for immediate help. + ... +l. ...\RenewDocElement {Option}{option} + % doesn't work either in this case! +I expected an existing definition for '\PrintOptionName', +'\PrintDescribeOption' and the environment 'option' but +not all of them are defined. +Maybe you wanted to use '\NewDocElement'? ! Package doc Error: Doc element 'Length/length' unknown. See the doc package documentation for explanation. Type H for immediate help. @@ -47,3 +57,5 @@ I expected an existing definition for '\PrintDimenName', '\PrintDescribeDimen' and the environment 'dimen' but not all of them are defined. Maybe you wanted to use '\NewDocElement'? +Package doc Info: Doc element 'Provide/provide' declaration ignored on input line .... +Package doc Info: Doc element 'Option/provideoption' declaration ignored on input line .... diff --git a/base/testfiles-doc/tlb-dox006.lvt b/base/testfiles-doc/tlb-dox006.lvt index 51f20a04b..a196e7ce8 100644 --- a/base/testfiles-doc/tlb-dox006.lvt +++ b/base/testfiles-doc/tlb-dox006.lvt @@ -24,6 +24,7 @@ \def\PrintOptionName{defined} \NewDocElement {Option}{option} +\RenewDocElement {Option}{option} % doesn't work either in this case! \RenewDocElement[macrolike] {Length}{length} @@ -34,4 +35,10 @@ \RenewDocElement{Dimen}{dimen} % but \PrintDimenName undefined +\ProvideDocElement {Provide}{provide} +\ProvideDocElement {Provide}{provide} +\RenewDocElement {Provide}{provide} + +\ProvideDocElement {Option}{provideoption} + \END diff --git a/base/testfiles-doc/tlb-dox006.tlg b/base/testfiles-doc/tlb-dox006.tlg index 4e835df6f..f13b427a5 100644 --- a/base/testfiles-doc/tlb-dox006.tlg +++ b/base/testfiles-doc/tlb-dox006.tlg @@ -9,6 +9,16 @@ There is already a definition for '\PrintOptionName', '\PrintDescribeOption' or the environment 'option'. Maybe you are overwriting something by mistake! Otherwise use '\RenewDocElement' instead. +! Package doc Error: Doc element 'Option/option' unknown. +See the doc package documentation for explanation. +Type H for immediate help. + ... +l. ...\RenewDocElement {Option}{option} + % doesn't work either in this case! +I expected an existing definition for '\PrintOptionName', +'\PrintDescribeOption' and the environment 'option' but +not all of them are defined. +Maybe you wanted to use '\NewDocElement'? ! Package doc Error: Doc element 'Length/length' unknown. See the doc package documentation for explanation. Type H for immediate help. @@ -47,3 +57,5 @@ I expected an existing definition for '\PrintDimenName', '\PrintDescribeDimen' and the environment 'dimen' but not all of them are defined. Maybe you wanted to use '\NewDocElement'? +Package doc Info: Doc element 'Provide/provide' declaration ignored on input line .... +Package doc Info: Doc element 'Option/provideoption' declaration ignored on input line .... diff --git a/base/update-doc.sh b/base/update-doc.sh index 4af0bc1ba..dbea5c0c5 100644 --- a/base/update-doc.sh +++ b/base/update-doc.sh @@ -1,4 +1,4 @@ -l3build save -cconfig-doc -eetex \ +l3build save -cconfig-doc -epdftex \ github-0023 \ github-0750 \ tlb-dox009 \ @@ -8,15 +8,15 @@ l3build save -cconfig-doc -eetex \ tlb-dox013 \ tlb-dox014 -l3build save -cconfig-doc -eetex,xetex,luatex \ +l3build save -cconfig-doc -epdftex,xetex,luatex \ github-0205 \ tlb-dox004 \ tlb-dox005 -# l3build save -cconfig-doc -eetex,xetex +# l3build save -cconfig-doc -epdftex,xetex -l3build save -cconfig-doc -eetex,luatex \ +l3build save -cconfig-doc -epdftex,luatex \ github-0075 \ tlb-doc009 \ tlb-dox001 \ @@ -34,5 +34,5 @@ l3build save -cconfig-doc -eetex,luatex \ -#l3build save -eetex \ +#l3build save -epdftex \