summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tagpdf/tagpdf-roles.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/tagpdf/tagpdf-roles.dtx')
-rw-r--r--macros/latex/contrib/tagpdf/tagpdf-roles.dtx165
1 files changed, 113 insertions, 52 deletions
diff --git a/macros/latex/contrib/tagpdf/tagpdf-roles.dtx b/macros/latex/contrib/tagpdf/tagpdf-roles.dtx
index 7955226573..f8a11bc464 100644
--- a/macros/latex/contrib/tagpdf/tagpdf-roles.dtx
+++ b/macros/latex/contrib/tagpdf/tagpdf-roles.dtx
@@ -21,28 +21,60 @@
% https://github.com/u-fischer/tagpdf
%
% for those people who are interested.
-%
+%<*driver>
+\RequirePackage{pdfmanagement-testphase}
+\DeclareDocumentMetadata{}
+\makeatletter
+\declare@file@substitution{doc.sty}{doc-v3beta.sty}
+\makeatother
+\documentclass{l3doc}
+\usepackage{array,booktabs,caption}
+\hypersetup{pdfauthor=Ulrike Fischer,
+ pdftitle=tagpdf-checks module (tagpdf)}
+\begin{document}
+ \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
% \fi
+% \title{^^A
+% The \pkg{tagpdf-roles} module\\ Tags, roles and namesspace code ^^A
+% \\ Part of the tagpdf package
+% }
+%
+% \author{^^A
+% Ulrike Fischer\thanks
+% {^^A
+% E-mail:
+% \href{mailto:fischer@troubleshooting-tex.de}
+% {fischer@troubleshooting-tex.de}^^A
+% }^^A
+% }
%
+% \date{Version 0.9, released 2021-06-29}
+% \maketitle
+% \begin{implementation}
% \begin{macrocode}
%<@@=tag>
-%<*roles>
-\ProvidesExplPackage {tagpdf-roles-code} {2021-06-14} {0.82}
+%<*header>
+\ProvidesExplPackage {tagpdf-roles-code} {2021-06-29} {0.9}
{part of tagpdf - code related to roles and structure names}
+%</header>
% \end{macrocode}
-% \section{Variables}
+% \section{Code related to roles and structure names}
+% \subsection{Variables}
% Tags have both a name (a string) and a number (for the lua attribute).
% Testing a name is easier with a prop, while accessing with a number is
% better done with a seq. So both are used and must be kept in sync if a new
% tag is added. The number is only relevant for the MC type, tags with the same
% name from different names spaces can have the same number.
-% \begin{macro}{\g_@@_role_tags_seq,\g_@@_role_tags_prop}
+% \begin{variable}{\g_@@_role_tags_seq,\g_@@_role_tags_prop}
% \begin{macrocode}
+%<*package>
\@@_seq_new:N \g_@@_role_tags_seq %to get names (type/NS) from numbers
\@@_prop_new:N \g_@@_role_tags_prop %to get numbers from names (type/NS)
% \end{macrocode}
-% \end{macro}
-% \begin{macro}{\g_@@_role_tags_NS_prop}
+% \end{variable}
+% \begin{variable}{\g_@@_role_tags_NS_prop}
% in pdf 2.0 tags belong to a name space. For every tag we store a default
% name space.
% The keys are the tags, the value shorthands like pdf2, or mathml.
@@ -50,8 +82,8 @@
% \begin{macrocode}
\prop_new:N \g_@@_role_tags_NS_prop %to namespace info
% \end{macrocode}
-% \end{macro}
-% \begin{macro}{\g_@@_role_NS_prop}
+% \end{variable}
+% \begin{variable}{\g_@@_role_NS_prop}
% The standard names spaces are the following. The keys are the name
% tagpdf will use, the urls are the identifier in the namespace object.
% \begin{description}
@@ -68,13 +100,28 @@
% \begin{macrocode}
\prop_new:N \g_@@_role_NS_prop % collect namespaces
% \end{macrocode}
-% \end{macro}
-% \section{Namesspaces}
+% \end{variable}
+%
+% We need also a bunch of temporary variables:
+% \begin{variable}
+% {
+% \l_@@_role_tag_tmpa_tl
+% ,\l_@@_role_tag_namespace_tmpa_tl
+% ,\l_@@_role_role_tmpa_tl
+% ,\l_@@_role_role_namespace_tmpa_tl
+% }
+% \begin{macrocode}
+\tl_new:N \l_@@_role_tag_tmpa_tl
+\tl_new:N \l_@@_role_tag_namespace_tmpa_tl
+\tl_new:N \l_@@_role_role_tmpa_tl
+\tl_new:N \l_@@_role_role_namespace_tmpa_tl
+% \end{macrocode}
+% \end{variable}
+% \subsection{Namesspaces}
% The following commands setups a names space. Namespace dictionaries can
% contain an optional |/Schema| and |/RoleMapNS| entry. We only reserve the
% objects but delay the writing to the finish code, where we can test if the
% keys and the name spaces are actually needed
-% \begin{macro}{\@@_role_NS_new:nn}
% This commands setups objects for the name space and its rolemap. It also
% initialize a prop to collect the rolemaps if needed.
% \begin{function}{\@@_role_NS_new:nnn}
@@ -85,7 +132,7 @@
% \begin{macro}{\@@_role_NS_new:nnn}
% \begin{macrocode}
\cs_new_protected:Npn \@@_role_NS_new:nnn #1 #2 #3
- { \msg_redirect_name:nnn { pdfdict } { empty-value } { none }
+ {
\pdf_object_new:nn {tag/NS/#1}{dict}
\pdfdict_new:n {g_@@_role/Namespace_#1_dict}
\pdf_object_new:nn {@@/RoleMapNS/#1}{dict}
@@ -95,15 +142,20 @@
{Type}
{/Namespace}
\pdf_string_from_unicode:nnN{utf8/string}{#2}\l_tmpa_str
- \pdfdict_gput:nnx
- {g_@@_role/Namespace_#1_dict}
- {NS}
- {\l_tmpa_str}
+ \tl_if_empty:NF \l_tmpa_str
+ {
+ \pdfdict_gput:nnx
+ {g_@@_role/Namespace_#1_dict}
+ {NS}
+ {\l_tmpa_str}
+ }
%RoleMapNS is added in tree
- \pdfdict_gput:nnx{g_@@_role/Namespace_#1_dict}
- {Schema}{#3}
+ \tl_if_empty:nF {#3}
+ {
+ \pdfdict_gput:nnx{g_@@_role/Namespace_#1_dict}
+ {Schema}{#3}
+ }
\prop_gput:Nnx \g_@@_role_NS_prop {#1}{\pdf_object_ref:n{tag/NS/#1}~}
- \msg_redirect_name:nnn { pdfdict } { empty-value } { warning }
}
% \end{macrocode}
% \end{macro}
@@ -112,6 +164,7 @@
% be fixed by setting a seed. We fake a sort of
% GUID but not try to be really exact as it doesn't matter ...
%
+% \begin{variable}{\c_@@_role_userNS_id_str}
% \begin{macrocode}
\str_const:Nx \c_@@_role_userNS_id_str
{ data:,
@@ -128,6 +181,7 @@
\int_to_Hex:n{\int_rand:n {16777215}}
}
% \end{macrocode}
+% \end{variable}
% Now we setup the standard names spaces. Currently only if we detect pdf2.0 but
% this will perhaps have to change if the structure code gets to messy.
% \begin{macrocode}
@@ -141,14 +195,14 @@
}
% \end{macrocode}
%
-% \section{Data}
+% \subsection{Data}
% In this section we setup the standard data.
% At first the list of structure types. We split them in three lists,
% the tags with which are both in the pdf and pdf2 namespace,
% the one only in pdf and the one with the tags only in pdf2.
% We also define a rolemap for the pdfII only type to pdf so that
% they can always be used.
-% \begin{macro}
+% \begin{variable}
% {
% \c_@@_role_sttags_pdf_pdfII_clist,
% \c_@@_role_sttags_only_pdf_clist,
@@ -160,7 +214,8 @@
%
\clist_const:Nn \c_@@_role_sttags_pdf_pdfII_clist
{
- Document, %A complete document. This is the root element of any structure tree containing
+ Document, %A complete document. This is the root element
+ %of any structure tree containing
%multiple parts or multiple articles.
Part, %A large-scale division of a document.
Sect, %A container for grouping related content elements.
@@ -205,13 +260,16 @@
\clist_const:Nn \c_@@_role_sttags_only_pdf_clist
{
- Art,%A relatively self-contained body of text constituting a single narrative or exposition
- BlockQuote, %A portion of text consisting of one or more paragraphs attributed to someone other
- %than the author of the surrounding text.
- TOC, %A list made up of table of contents item entries (structure tag TOCI; see below)
- %and/or other nested table of contents entries
- TOCI, %An individual member of a table of contents. This entry's children can be any of
- %the following structure tags:
+ Art, %A relatively self-contained body of text
+ %constituting a single narrative or exposition
+ BlockQuote, %A portion of text consisting of one or more paragraphs
+ %attributed to someone other than the author of the
+ %surrounding text.
+ TOC, %A list made up of table of contents item entries
+ %(structure tag TOCI; see below) and/or other
+ %nested table of contents entries
+ TOCI, %An individual member of a table of contents.
+ %This entry's children can be any of the following structure tags:
%Lbl,Reference,NonStruct,P,TOC
Index,
Private,
@@ -448,7 +506,7 @@
Strong= Span,
}
% \end{macrocode}
-% \end{macro}
+% \end{variable}
% We fill the structure tags in to the seq. We allow all pdf1.7 and pdf2.0,
% and role map if needed the 2.0 tags.
% \begin{macrocode}
@@ -482,7 +540,6 @@
% For luatex and the MC we need a name/number relation.
% The name space is not relevant.
% \begin{macrocode}
-
\int_step_inline:nnnn { 1 }{ 1 }{ \seq_count:N \g_@@_role_tags_seq }
{
\@@_prop_gput:Nxn \g_@@_role_tags_prop
@@ -493,24 +550,29 @@
}
% \end{macrocode}
%
-% \section{Adding new tags and rolemapping}
+% \subsection{Adding new tags and rolemapping}
%
-% \subsection{pdf 1.7 and earlier}
+% \subsubsection{pdf 1.7 and earlier}
% With this versions only RoleMap is filled.
% At first the dictionary:
+% \begin{variable}{g_@@_role/RoleMap_dict}
% \begin{macrocode}
\pdfdict_new:n {g_@@_role/RoleMap_dict}
% \end{macrocode}
+% \end{variable}
% \begin{macro}{\@@_role_add_tag:nn}
% The pdf 1.7 version has only two arguments: new and rolemap name.
% To make pdf 2.0 types usable we directly define a rolemapping for them.
-% TODO: add checks
+%
% \begin{macrocode}
\cs_new_protected:Nn \@@_role_add_tag:nn %(new) name, reference to old
{
\prop_if_in:NnF \g_@@_role_tags_prop {#1}
{
- \msg_info:nnn { tag }{new-tag}{#1}
+ \int_compare:nNnT {\l_@@_loglevel_int} > { 0 }
+ {
+ \msg_info:nnn { tag }{new-tag}{#1}
+ }
\@@_seq_gput_right:Nn \g_@@_role_tags_seq { #1 }
\@@_prop_gput:Nnx \g_@@_role_tags_prop { #1 }
{
@@ -518,7 +580,7 @@
}
\prop_gput:Nnn \g_@@_role_tags_NS_prop { #1 }{ user }
}
- %\@@_check_add_tag_role:nn {#1}{#2} %%!TODO
+ \@@_check_add_tag_role:nn {#1}{#2}
\tl_if_empty:nF { #2 }
{
\pdfdict_gput:nnx {g_@@_role/RoleMap_dict}
@@ -538,22 +600,24 @@
% \end{macrocode}
% \end{macro}
-%
+% \subsubsection{The pdf 2.0 version}
% \begin{macro}{\@@_role_add_tag:nnnn}
-% The pdf 2.0 version takes for arguments:
+% The pdf 2.0 version takes four arguments:
% tag/namespace/role/namespace
-% TODO: add checks
% \begin{macrocode}
\cs_new_protected:Nn \@@_role_add_tag:nnnn %tag/namespace/role/namespace
{
- \msg_info:nnn { tag }{new-tag}{#1}
+ \int_compare:nNnT {\l_@@_loglevel_int} > { 0 }
+ {
+ \msg_info:nnn { tag }{new-tag}{#1}
+ }
\@@_seq_gput_right:Nn \g_@@_role_tags_seq { #1 }
\@@_prop_gput:Nnx \g_@@_role_tags_prop { #1 }
{
\seq_count:N \g_@@_role_tags_seq
}
\prop_gput:Nnn \g_@@_role_tags_NS_prop { #1 }{ #2 }
- %\@@_check_add_tag_role:nn {#1}{#3} %TODO
+ \@@_check_add_tag_role:nn {#1}{#3}
\pdfdict_gput:nnx {g_@@_role/RoleMapNS_#2_dict}{#1}
{
[
@@ -566,15 +630,11 @@
\cs_generate_variant:Nn \@@_role_add_tag:nnnn {VVVV}
% \end{macrocode}
% \end{macro}
-% The user interface use the key add-new-tag, which takes either a
+% \subsection{Key-val user interface}
+% The user interface use the key |add-new-tag|, which takes either a
% keyval list as argument, or a tag/role.
+% \begin{macro}{tag,tag-namespace,role,role-namespace,add-new-tag}
% \begin{macrocode}
-
-\tl_new:N \l_@@_role_tag_tmpa_tl
-\tl_new:N \l_@@_role_tag_namespace_tmpa_tl
-\tl_new:N \l_@@_role_role_tmpa_tl
-\tl_new:N \l_@@_role_role_namespace_tmpa_tl
-
\keys_define:nn { @@ / tag-role }
{
,tag .tl_set:N = \l_@@_role_tag_tmpa_tl
@@ -632,7 +692,8 @@
}
}
}
-
-
-%</roles>
+%</package>
% \end{macrocode}
+% \end{macro}
+% \end{implementation}
+% \PrintIndex