[latex3-commits] [latex3/tagpdf] develop: correct documentation, issue #90 (5f88240)
github at latex-project.org
github at latex-project.org
Wed Dec 20 22:23:19 CET 2023
Repository : https://github.com/latex3/tagpdf
On branch : develop
Link : https://github.com/latex3/tagpdf/commit/5f88240c342a39e487593029bf24d8295801eb28
>---------------------------------------------------------------
commit 5f88240c342a39e487593029bf24d8295801eb28
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date: Wed Dec 20 22:23:19 2023 +0100
correct documentation, issue #90
>---------------------------------------------------------------
5f88240c342a39e487593029bf24d8295801eb28
doc/tagpdf-code.pdf | Bin 1646817 -> 1653258 bytes
tagpdf-checks.dtx | 20 ++++++++++--
tagpdf-struct.dtx | 20 ++++++++++--
tagpdf-user.dtx | 88 ++++++++++++++++++++++++++++++++--------------------
4 files changed, 89 insertions(+), 39 deletions(-)
diff --git a/doc/tagpdf-code.pdf b/doc/tagpdf-code.pdf
index f222571..0b08ea0 100644
Binary files a/doc/tagpdf-code.pdf and b/doc/tagpdf-code.pdf differ
diff --git a/tagpdf-checks.dtx b/tagpdf-checks.dtx
index 80d8654..1f5d29b 100644
--- a/tagpdf-checks.dtx
+++ b/tagpdf-checks.dtx
@@ -284,16 +284,30 @@
% mc-current}
% Various messages related to mc-chunks. TODO document their meaning.
% \end{function}
-% \begin{function}{struct-no-objnum,struct-faulty-nesting,
+% \begin{function}{struct-unknown,struct-no-objnum,struct-orphan,struct-faulty-nesting,
% struct-missing-tag,struct-used-twice,struct-label-unknown,struct-show-closing}
-% Various messages related to structure. TODO document their meaning.
+% Various messages related to structure. Check the definition in the code for their
+% meaning and the arguments they take.
% \end{function}
%
+% \begin{function}{tree-struct-still-open}
+% Message issued at the end of the compilation
+% if there are (beside Root) other open structures on the stack.
+% \end{function}
+%
+
+% \begin{function}{show-struct,show-kids}
+% These two messages are used in debug mode
+% to show the current structures in the log and terminal.
+% \end{function}
+%
+
% \begin{function}{attr-unknown}
% Message if an attribute i sunknown.
% \end{function}
%
-% \begin{function}{role-missing,role-unknown,role-unknown-tag,role-tag,new-tag}
+% \begin{function}{role-missing,role-unknown,role-unknown-tag,role-tag,new-tag,
+% role-parent-child,role-remapping}
% Messages related to role mapping.
% \end{function}
%
diff --git a/tagpdf-struct.dtx b/tagpdf-struct.dtx
index 4808ccc..dd92598 100644
--- a/tagpdf-struct.dtx
+++ b/tagpdf-struct.dtx
@@ -63,9 +63,10 @@
% it will check if the \Arg{tag} (after expansion)
% is identical to the current structure on the stack. The tag is not role mapped!
% \end{function}
-% \begin{function}{\tag_struct_use:n}
+% \begin{function}{\tag_struct_use:n,\tag_struct_use_num:n}
% \begin{syntax}
-% \cs{tag_struct_use:n}\Arg{label}
+% \cs{tag_struct_use:n}\Arg{label}\\
+% \cs{tag_struct_use_num:n}\Arg{structure number}
% \end{syntax}
% These commands insert a structure previously stashed away as kid
% into the currently active structure.
@@ -105,6 +106,21 @@
% This gives back the next free /StructParent number (assuming that it is
% together with \cs{tag_struct_insert_annot:nn} which will increase the number.
% \end{function}
+%
+% \begin{function}{\tag_struct_gput:nnn}
+% \begin{syntax}
+% \cs{tag_struct_gput:nnn}\Arg{structure number}\Arg{keyword}\Arg{value}
+% \end{syntax}
+% This is a command that allows to update the data of a structure.
+% This often can't done simply by replacing the value, as we have to
+% preserve and extend existing content. We use therefore dedicated functions
+% adjusted to the key in question.
+% The first argument is the number of the structure,
+% the second a keyword referring to a function,
+% the third the value. Currently the only keyword is \texttt{ref} which updates
+% the Ref key (an array)
+% \end{function}
+%
% \section{Public keys}
% \subsection{Keys for the structure commands}
% \begin{function}{tag (struct-key)}
diff --git a/tagpdf-user.dtx b/tagpdf-user.dtx
index 5f1a72a..1998df3 100644
--- a/tagpdf-user.dtx
+++ b/tagpdf-user.dtx
@@ -120,7 +120,7 @@
% \cs{ShowTagging} \Arg{key-val}
% \end{syntax}
% This is a generic function to output various debugging helps. It not
-% necessarly stops the compilation. The keys and their function are described below.
+% necessarily stops the compilation. The keys and their function are described below.
% \end{function}
%
% \begin{function}{mc-data (show-key)}
@@ -158,6 +158,15 @@
% If no value is used, then the default is |show|.
% \end{function}
%
+% \begin{function}{debug/structures (show-key)}
+% \begin{syntax}
+% |debug/structures| = \meta{structure number}
+% \end{syntax}
+% This key is available only if the tagpdf-debug package is loaded
+% and shows all structures starting with the one with the number
+% given by the key.
+% \end{function}
+
% \section{Extension commands}
% The following commands and code parts are not core commands of tagpdf.
% They either provide work-arounds for missing functionality elsewhere,
@@ -243,6 +252,50 @@
% { Contents }
% { (ref) }
% \end{verbatim}
+%
+% \section{Socket support}
+%
+% \begin{function}{\tag_socket_use:n,\tag_socket_use:nn,\UseTaggingSocket}
+% \begin{syntax}
+% \cs{tag_socket_use:n} \Arg{socket name}\\
+% \cs{tag_socket_use:nn} \Arg{socket name} \Arg{socket argument}\\
+% \cs{UseTaggingSocket} \Arg{socket name} \\
+% \cs{UseTaggingSocket} \Arg{socket name} \Arg{socket argument}\\
+% \end{syntax}
+% \end{function}
+
+% The next \LaTeX{} will use special sockets for the tagging.
+%
+% These sockets will use names starting
+% with \texttt{tagsupport/}. Usually, these sockets have exactly two
+% plugs defined: \texttt{noop} (when no tagging is requested or
+% tagging is not wanted for some reason) and
+% a second plug that enables the tagging. There
+% may be more, e.g., tagging with special debugging, etc., but right
+% now it is usually just on or off.
+%
+% Given that we sometimes have to suspend tagging, it would be fairly
+% inefficient to put different plugs into these sockets whenever that
+% happens. We therefore offer \cs{UseTaggingSocket} which is like
+% \cs{UseSocket} except that the socket name is specified without
+% \texttt{tagsupport/}, i.e.,
+% \begin{quote}
+% \verb=\UseTaggingSocket{foo}= $\to$
+% \verb=\UseSocket{tagsupport/foo}=
+% \end{quote}
+% Beside being slightly shorter, the big advantage is that this way
+% we can change \cs{UseTaggingSocket} to do nothing by switching a boolean
+% instead of changing the plugs of the tagging support sockets back and forth.
+%
+% It is possible to use the tagging support sockets with
+% \cs{UseSocket} directly, but in this case the socket remains active
+% if e.g. \cs{SuspendTagging} is in force. There may be reasons for doing
+% that but in general we expect to always use \cs{UseTaggingSocket}.
+%
+% The L3 programming layer versions \cs{tag_socket_use:n} and
+% \cs{tag_socket_use:nn} are slightly more efficient than
+% \cs{UseTaggingSocket} because they do not have to determine how
+% many arguments the socket takes when disabling it.
% \end{documentation}
%
% \begin{implementation}
@@ -347,39 +400,6 @@
% \end{macro}
%
% \section{Socket support}
-% The next \LaTeX{} will use special sockets for the tagging.
-%
-% These sockets will use names starting
-% with \texttt{tagsupport/}. Usually, these sockets have exactly two
-% plugs defined: \texttt{noop} (when no tagging is requested or
-% tagging is not wanted for some reason) and
-% a second plug that enables the tagging. There
-% may be more, e.g., tagging with special debugging, etc., but right
-% now it is usually just on or off.
-%
-% Given that we sometimes have to suspend tagging, it would be fairly
-% inefficient to put different plugs into these sockets whenever that
-% happens. We therefore offer \cs{UseTaggingSocket} which is like
-% \cs{UseSocket} except that the socket name is specified without
-% \texttt{tagsupport/}, i.e.,
-% \begin{quote}
-% \verb=\UseTaggingSocket{foo}= $\to$
-% \verb=\UseSocket{tagsupport/foo}=
-% \end{quote}
-% Beside being slightly shorter, the big advantage is that this way
-% we can change \cs{UseTaggingSocket} to do nothing by switching a boolean
-% instead of changing the plugs of the tagging support sockets back and forth.
-%
-% It is possible to use the tagging support sockets with
-% \cs{UseSocket} directly, but in this case the socket remains active
-% if e.g. \cs{SuspendTagging} is in force. There may be reasons for doing
-% that but in general we expect to always use \cs{UseTaggingSocket}.
-%
-% The L3 programming layer versions \cs{tag_socket_use:n} and
-% \cs{tag_socket_use:nn} are slightly more efficient than
-% \cs{UseTaggingSocket} because they do not have to determine how
-% many arguments the socket takes when disabling it.
-%
% Until we can be sure that the kernel defines the commands we provide them before
% redefining them:
% \begin{macrocode}
More information about the latex3-commits
mailing list.