provide \ProvideDocElement (latex3#1193)

muzimuzhi · Dec 5, 2023 · 8d23e0e · 8d23e0e
1 parent b472022
commit 8d23e0e
Show file tree

Hide file tree

Showing 7 changed files with 90 additions and 6 deletions.
diff --git 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  <[email protected]>
+	* 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  <[email protected]>
 	* 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
@@ -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
@@ -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
@@ -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 <return>  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 <return>  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
@@ -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
@@ -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 <return>  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 <return>  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
@@ -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 \