diff --git a/doc/tagpdf-code.pdf b/doc/tagpdf-code.pdf index f2225710..0b08ea09 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 80d86540..1f5d29b9 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 4808ccce..dd92598d 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 5f1a72a3..1998df34 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}