[latex3-commits] [latex3/latex2e] docelement: provide \ProvideDocElement (e4d3f8dc)
github at latex-project.org
github at latex-project.org
Sat Dec 2 10:29:14 CET 2023
Repository : https://github.com/latex3/latex2e
On branch : docelement
Link : https://github.com/latex3/latex2e/commit/e4d3f8dc1fa6cdfeed6a32908e984a2dcc29dd33
>---------------------------------------------------------------
commit e4d3f8dc1fa6cdfeed6a32908e984a2dcc29dd33
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Sat Dec 2 10:29:14 2023 +0100
provide \ProvideDocElement
>---------------------------------------------------------------
e4d3f8dc1fa6cdfeed6a32908e984a2dcc29dd33
base/changes.txt | 5 ++++
base/doc.dtx | 42 +++++++++++++++++++++++++++++++-
base/doc/ltnews39.tex | 8 ++++++
base/testfiles-doc/tlb-dox006.luatex.tlg | 12 +++++++++
base/testfiles-doc/tlb-dox006.lvt | 7 ++++++
base/testfiles-doc/tlb-dox006.tlg | 12 +++++++++
base/update-doc.sh | 10 ++++----
7 files changed, 90 insertions(+), 6 deletions(-)
diff --git a/base/changes.txt b/base/changes.txt
index f84abfa9..5bca41bc 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 <Frank.Mittelbach at latex-project.org>
+ * 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 <Joseph.Wright at latex-project.org>
* 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 75e04cc2..1956bf07 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 at ignoredinfo}
+%
+% \begin{macrocode}
+\def\doc at 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 at ignoredinfo
+ }\doc at ignoredinfo
+ }\doc at ignoredinfo
+ }\doc at 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 ebcb3eb0..52bc4c5a 100644
--- a/base/doc/ltnews39.tex
+++ b/base/doc/ltnews39.tex
@@ -148,6 +148,14 @@
\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 942b300d..4a4c8ea7 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 <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
index 51f20a04..a196e7ce 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 4e835df6..f13b427a 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 <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
index 4af0bc1b..dbea5c0c 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 \
More information about the latex3-commits
mailing list.