correct documentation, issue #90

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}
 %

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)}

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}