% \iffalse meta-comment % %% File: latex-lab-namespace.dtx %% % Copyright (C) 2023-2026 LaTeX Project % % It may be distributed and/or modified under the conditions of the % LaTeX Project Public License (LPPL), either version 1.3c of this % license or (at your option) any later version. The latest version % of this license is in the file % % https://www.latex-project.org/lppl.txt % %<*package> \def\ltlabnamesdate{2026-04-28} \def\ltlabnamesversion{0.8k} % %<*driver> \DocumentMetadata{tagging=on,pdfstandard=ua-2} \documentclass[kernel]{l3in2edoc} \usepackage{amstext} \EnableCrossrefs \CodelineIndex \usepackage{todonotes} \begin{document} \DocInput{latex-lab-namespace.dtx} \end{document} % % \fi % \title{Prototype reimplementation of \LaTeXe{}'s role mapping} % \author{\LaTeX{} Project, initial implementation Ulrike Fischer} % \date{v\ltlabnamesversion\ \ltlabnamesdate} % % \maketitle % % \NewDocumentCommand\fmi{sO{}m} % {\IfBooleanTF{#1}{\todo[inline,#2]{#3}}^^A % {\todo[#2]{#3}}} % % % \NewDocumentCommand\ufi{sO{}m} % {\IfBooleanTF{#1}{\todo[inline,#2]{UFi:#3}}^^A % {\todo[#2]{UFi:#3}}} % \begin{documentation} % % % % \section{Introduction} % % This file provides support for tag names and symbolic structure names. % % At first, it creates tagpdf-ns-latex-lab.def which collects tag names % from the \LaTeX{} namespace and their role mapping. % The names and the roles are not necessarily the final ones! % % Later settings of the same tag overwrite previous settings. % The syntax of a line is a list of three strings ending with commas: % \begin{verbatim} % latex-tag, PDF-tag, name space, % \end{verbatim} % % The name space is normally pdf2 with the exception of the following PDF-tags % which are only in pdf namespace: % Art, BlockQuote, TOC, TOCI, Index, Private, Quote, Note, % Reference, BibEntry, Code. % % At second it provides an interface to use symbolic structure names % which can be used in the \texttt{tag} key of \cs{tagstructbegin}. % The symbolic names are strings % structured with slashes similar to the names of (tagging) sockets. % The list of such names used by \LaTeX{} is below in the implementation section. % % In PDF 2.0 there are namespaces, so theoretically it is possible to use the % same tag name for different purposes and with different role mapping. % But practically this is not an option as we build also a global RoleMap % dictionary for compatibility with applications that are not PDF 2.0 aware, % and this dictionary can only contain unique tag names. So we assume that tag % names are used only once across all namespaces. Documents that want to use % their own specialized tag names must take care not to clash with existing names, % e.g., by using a specific prefix on all their tag names. % % \begin{function}{\NewStructureName} % \begin{syntax} % \cs{NewStructureName}\Arg{symbolic name} % \end{syntax} % This declares a new symbolic % structure name \meta{symbolic name} which is initially % defined as \texttt{NonStruct}. To assign it another role use % \cs{AssignStructureRole} described below. % \end{function} % % \begin{function}[EXP]{\UseStructureName} % \begin{syntax} % \cs{UseStructureName}\Arg{symbolic name} % \end{syntax} % This uses the new symbolic structure name \meta{symbolic name}, e.g.\\ % \verb+tagstructbegin{tag=\UseStructureName{sec/section}}+ is the same as % \verb+tagstructbegin{tag=Sect}+ assuming that % \verb+\NewStructureName{sec/section}+ and \verb+\AssignStructureRole{sec/section}{Sect}+ % has been used before. % \end{function} % % \begin{function}{\AssignStructureRole} % \begin{syntax} % \cs{AssignStructureRole}\Arg{symbolic name}\Arg{role} % \end{syntax} % This assigns to the symbolic structure name \meta{symbolic name} the role \meta{role}. % \meta{symbolic name} must have been declared first with \verb+\NewStructureName+. % If \meta{role} is a known role it is simply used. If it is unknown, it is declared % first and rolemapped to the tag currently stored for \meta{name}. So % \begin{verbatim} % \NewStructureName{sec/section} % % structure with tag 'NonStruct' % \tagstructbegin{tag=\UseStructureName{sec/section}} % % \AssignStructureRole{sec/section}{Sect} % % structure with tag 'Sect' % \tagstructbegin{tag=\UseStructureName{sec/section}} % % \AssignStructureRole{sec/section}{Abschnitt} % % structure with tag 'Abschnitt' rolemapped to 'Sect' % \tagstructbegin{tag=\UseStructureName{sec/section}} % % \AssignStructureRole{sec/section}{Figure} % % structure with tag 'Figure' % \tagstructbegin{tag=\UseStructureName{sec/section}} % \end{verbatim} % % Assigning a symbolic structure name a role that is not suitable for the % structure element can lead to invalid tagging and parent-child warnings! % \end{function} % \end{documentation} % % \begin{implementation} % \changes{v0.8c}{2025/01/12}{changed mapping of verbatim to Code as Sub is now allowed inside Code} % \begin{macrocode} %<*ns-latex-lab> %% \ProvidesExplFile {tagpdf-ns-latex-lab.def} {2023-09-04} {0.8} %% {latex} {https://www.latex-project.org/ns/lab/2022}{} % \end{macrocode} % \subsection{Role from tagpdf} % The following tags are already set by tagpdf, so deleting here will not remove them. % \begin{macrocode} title, Title, pdf2, part, Title, pdf2, % \end{macrocode} % Headings differ in article and book class. This here is for article: % \begin{macrocode} section, H1, pdf2, subsection, H2, pdf2, subsubsection,H3, pdf2, paragraph, H4, pdf2, subparagraph, H5, pdf2, % \end{macrocode} % And this here is used in book: % \begin{macrocode} %chapter, H1, pdf2, %section, H2, pdf2, %subsection, H3, pdf2, %subsubsection, H4, pdf2, %paragraph, H5, pdf2, %subparagraph, H6, pdf2, % \end{macrocode} % % \begin{macrocode} list, L, pdf2, itemize, L, pdf2, enumerate, L, pdf2, description, L, pdf2, quote, BlockQuote,pdf, quotation, BlockQuote,pdf, verbatim, Code, pdf, % overwritten by block item, LI, pdf2, itemlabel, Lbl, pdf2, itembody, LBody, pdf2, footnote, FENote, pdf2, footnotemark, Lbl, pdf2, footnotelabel,Lbl, pdf2, text-unit, Part, pdf2, text, P, pdf2, % \end{macrocode} % \subsection{From sec code} % \begin{macrocode} section-number, Span, pdf2, % \end{macrocode} % \subsection{From block code} % \begin{macrocode} theorem-like, Sect, pdf2, verbatim, Code, pdf, codeline, Sub, pdf2, % \end{macrocode} % \subsection{From float code} % \begin{macrocode} float, Aside, pdf2, figures, Sect, pdf2, tables, Sect, pdf2, % \end{macrocode} % \begin{macrocode} % % \end{macrocode} % % \begin{macrocode} %<*package> \ProvidesExplPackage {latex-lab-testphase-names} {\ltlabnamesdate} {\ltlabnamesversion} {Code related to the names of tags} % \end{macrocode} % \begin{macrocode} %<@@=tag> % \end{macrocode} % % % \begin{macro}{\AssignStructureRole} % We redefine \cs{AssignStructureRole} to set up roles for tagging. % The second argument needs expansion so that we do % not store things like % \verb=\UseStructureName{block/verbatim/codeline}}= but its final % value. Otherwise \ldots\fmi{fix implementation and docu} % \changes{v0.8h}{2025/12/23}{Expand second argument before storing} % \begin{macrocode} \cs_set_protected:Npn\AssignStructureRole#1#2 { \exp_args:Nne \@@_AssignStructureRole {#1}{#2} } \cs_set_protected:Npn\@@_AssignStructureRole#1#2 { \prop_get:NnNF\g_@@_role_tags_NS_prop{#2}\l_@@_tmp_unused_tl {\exp_args:Ne\tagpdfsetup{role/new-tag=#2/\UseStructureName{#1}}} \tl_set:cn { l_@@_name_#1_tl }{#2} } % \end{macrocode} % \end{macro} % % % \begin{macrocode} % % \end{macrocode} % % \subsection{Symbolic names} % These are the planned symbolic structure names. % Every commented name is not decided and not used yet and can change in future. % % \subsubsection{Generic} % In various places we have to use a \texttt{Span} structure % to add attributes. % \begin{macrocode} %<*package> \NewStructureName{span} \AssignStructureRole{span}{Span} % % \end{macrocode} % % \subsubsection{Paragraphs} % % \begin{macrocode} %<*package> \NewStructureName{para/textblock} \AssignStructureRole{para/textblock}{text} \NewStructureName{para/semantic} \AssignStructureRole{para/semantic}{text-unit} % % \end{macrocode} % % \subsubsection{Sectioning commands} % \begin{macrocode} %<*package> %-1=part, 0=chapter, 1=section etc \NewStructureName{sec/-1} \AssignStructureRole{sec/-1}{Part} \NewStructureName{sec/-1/title} \AssignStructureRole{sec/-1/title}{part} \NewStructureName{sec/-1/titleline} % \end{macrocode} % Sub does not work as part is rolemapped to Title so we use Span % \begin{macrocode} \AssignStructureRole{sec/-1/titleline}{Span} \NewStructureName{sec/-1/number} \AssignStructureRole{sec/-1/number}{section-number} \NewStructureName{sec/0} \AssignStructureRole{sec/0}{Sect} \NewStructureName{sec/0/title} \AssignStructureRole{sec/0/title}{chapter} \NewStructureName{sec/0/titleline} \AssignStructureRole{sec/0/titleline}{Span} \NewStructureName{sec/0/number} \AssignStructureRole{sec/0/number}{section-number} \NewStructureName{sec/1} \AssignStructureRole{sec/1}{Sect} \NewStructureName{sec/1/title} \AssignStructureRole{sec/1/title}{section} \NewStructureName{sec/1/number} \AssignStructureRole{sec/1/number}{section-number} \NewStructureName{sec/2} \AssignStructureRole{sec/2}{Sect} \NewStructureName{sec/2/title} \AssignStructureRole{sec/2/title}{subsection} \NewStructureName{sec/2/number} \AssignStructureRole{sec/2/number}{section-number} \NewStructureName{sec/3} \AssignStructureRole{sec/3}{Sect} \NewStructureName{sec/3/title} \AssignStructureRole{sec/3/title}{subsubsection} \NewStructureName{sec/3/number} \AssignStructureRole{sec/3/number}{section-number} \NewStructureName{sec/4} \AssignStructureRole{sec/4}{Sect} \NewStructureName{sec/4/title} \AssignStructureRole{sec/4/title}{paragraph} \NewStructureName{sec/4/number} \AssignStructureRole{sec/4/number}{section-number} \NewStructureName{sec/5} \AssignStructureRole{sec/5}{Sect} \NewStructureName{sec/5/title} \AssignStructureRole{sec/5/title}{subparagraph} \NewStructureName{sec/5/number} \AssignStructureRole{sec/5/number}{section-number} % \end{macrocode} % % \subsubsection{Table of contents and similar} % \begin{macrocode} \NewStructureName{toc} \AssignStructureRole{toc}{TOC} \NewStructureName{toc/item} \AssignStructureRole{toc/item}{TOCI} \NewStructureName{toc/item/label} \AssignStructureRole{toc/item/label}{Lbl} \NewStructureName{toc/item/text} \AssignStructureRole{toc/item/text}{Reference} \NewStructureName{toc/item/page} \AssignStructureRole{toc/item/page}{Reference} % \end{macrocode} % % \subsubsection{Title} % \enquote{title} in this context can be a structure that surrounds the \emph{title block} (or a part from it) % with author, title, subtitle, date and perhaps more. Or it can mean only the \emph{title text} (plus perhaps % the subtitle). % In PDF 2.0 the tag \texttt{Title} is described as grouping and block type and it can not be used % in a \texttt{P} tag, so it is better used for the \emph{title block}. % With PDF 1.7 \texttt{Title} is currently rolemapped to \texttt{P} and % the code in latex-lab-title uses it for the \emph{title text}. % \ufi{This should be discussed.} % We provide therefore two symbolic names for the two concepts, which both map to \texttt{Title}. % \begin{macrocode} \NewStructureName{title/block} \AssignStructureRole{title/block}{Title} \NewStructureName{title/text} \AssignStructureRole{title/text}{Title} % \end{macrocode} % % \subsubsection{Lists and blocks} % \texttt{block/inner} is the generic named used for inner blocks % in, e.g., the recipe \texttt{standard}. % \begin{macrocode} \NewStructureName{block/inner} \AssignStructureRole{block/inner}{Div} \NewStructureName{block/itemize} \AssignStructureRole{block/itemize}{itemize} \NewStructureName{block/description} \AssignStructureRole{block/description}{description} \NewStructureName{block/enumerate} \AssignStructureRole{block/enumerate}{enumerate} \NewStructureName{block/list} \AssignStructureRole{block/list}{list} \NewStructureName{block/list/item} \AssignStructureRole{block/list/item}{item} \NewStructureName{block/list/label} \AssignStructureRole{block/list/label}{itemlabel} \NewStructureName{block/list/body} \AssignStructureRole{block/list/body}{itembody} % \end{macrocode} % % \begin{macrocode} \NewStructureName{block/quote} \AssignStructureRole{block/quote}{quote} % \end{macrocode} % % For now we map \texttt{verse} to \texttt{quote} which means % it will become BlockQuote in tagging.\fmi{decide on tagging % for verse} % \begin{macrocode} \NewStructureName{block/verse} \AssignStructureRole{block/verse}{quote} % \end{macrocode} % % \begin{macrocode} \NewStructureName{block/quotation} \AssignStructureRole{block/quotation}{quotation} % \NewStructureName{block/verbatim} \AssignStructureRole{block/verbatim}{verbatim} \NewStructureName{block/verbatim/codeline} \AssignStructureRole{block/verbatim/codeline}{codeline} \NewStructureName{block/verbatim/linenumber} \AssignStructureRole{block/verbatim/linenumber}{Lbl} % \NewStructureName{block/theorem-like} \AssignStructureRole{block/theorem-like}{theorem-like} \NewStructureName{block/theorem-like/caption} \AssignStructureRole{block/theorem-like/caption}{Caption} \NewStructureName{block/theorem-like/label} \AssignStructureRole{block/theorem-like/label}{Lbl} % \end{macrocode} % For now we map proof to theorem-like: % \begin{macrocode} \NewStructureName{block/proof} \AssignStructureRole{block/proof}{theorem-like} % \end{macrocode} % % Bibliographies normally use internally lists and tag names should be adapted % by changing the symbolic names of lists locally, so dedicated symbolic names % are probably not needed. % \begin{macrocode} %\NewStructureName{block/bib} %\AssignStructureRole{block/bib}{L} %\NewStructureName{block/bib/label} %\AssignStructureRole{block/bib/label}{Lbl} %\NewStructureName{block/bib/item} %\AssignStructureRole{block/bib/item}{LI} %\NewStructureName{block/bib/body} %\AssignStructureRole{block/bib/body}{LBody} % \end{macrocode} % %\subsubsection{\LaTeX{} Code documentation} % The class l3doc defines a number of structures for the document of \LaTeX\ code. % The exact tagging is currently experimental and it is unclear if % symbolic names and tag names for this case should be setup here by default. % Their setup is therefore done in latex-lab-l3doc-tagging. % % %\subsubsection{References and Links} % % \begin{macrocode} \NewStructureName{ref} \AssignStructureRole{ref}{Reference} \NewStructureName{link} \AssignStructureRole{link}{Link} \NewStructureName{cite} \AssignStructureRole{cite}{Reference} % \end{macrocode} % % \subsubsection{Tables} % % \begin{macrocode} \NewStructureName{table} \AssignStructureRole{table}{Table} \NewStructureName{table/row} \AssignStructureRole{table/row}{TR} \NewStructureName{table/cell} \AssignStructureRole{table/cell}{TD} \NewStructureName{table/headercell} \AssignStructureRole{table/headercell}{TH} % \end{macrocode} % THead and TFoot are currently not used but are perhaps needed later % \begin{macrocode} %\NewStructureName{tbl/table/head} %\AssignStructureRole{tbl/table/head}{} %\NewStructureName{tbl/table/foot} %\AssignStructureRole{tbl/table/foot}{} % \end{macrocode} % Inside p-cells we have to set the para/semantic structure to Div as Part is not % allowed as child of TD and as we can not flatten the paragraphs. % \begin{macrocode} \NewStructureName{table/para/semantic} \AssignStructureRole{table/para/semantic}{Div} % \end{macrocode} % We need also names for layout tables % \begin{macrocode} \NewStructureName{layouttable} \AssignStructureRole{layouttable}{Div} \NewStructureName{layouttable/row} \AssignStructureRole{layouttable/row}{NonStruct} \NewStructureName{layouttable/cell} \AssignStructureRole{layouttable/cell}{\UseStructureName{para/textblock}} \NewStructureName{layouttable/pcell} \AssignStructureRole{layouttable/pcell}{NonStruct} % \end{macrocode} % % % % \subsubsection{Floats} % % \begin{macrocode} \NewStructureName{float/generic} \AssignStructureRole{float/generic}{float} \NewStructureName{float/figures} \AssignStructureRole{float/figures}{figures} \NewStructureName{float/tables} \AssignStructureRole{float/tables}{tables} \NewStructureName{float/figure} \AssignStructureRole{float/figure}{float} \NewStructureName{float/table} \AssignStructureRole{float/table}{float} \NewStructureName{float/figure/caption} \AssignStructureRole{float/figure/caption}{Caption} \NewStructureName{float/table/caption} \AssignStructureRole{float/table/caption}{Caption} \NewStructureName{float/figure/label} \AssignStructureRole{float/figure/label}{Lbl} \NewStructureName{float/table/label} \AssignStructureRole{float/table/label}{Lbl} % \end{macrocode} % % \subsubsection{Footnotes} % % \begin{macrocode} \NewStructureName{fnote/mark} \AssignStructureRole{fnote/mark}{footnotemark} \NewStructureName{fnote/note} \AssignStructureRole{fnote/note}{footnote} \NewStructureName{fnote/note/label} \AssignStructureRole{fnote/note/label}{footnotelabel} % \end{macrocode} % % \subsubsection{Graphics} % \begin{macrocode} \NewStructureName{graphic} \AssignStructureRole{graphic}{Figure} \NewStructureName{graphic/symbol} \AssignStructureRole{graphic/symbol}{Span} % \end{macrocode} % % \subsubsection{Marginnotes} % \begin{macrocode} \NewStructureName{marginnote} \AssignStructureRole{marginnote}{Aside} % \end{macrocode} % % \subsubsection{Minipages and parboxes} % \begin{macrocode} \NewStructureName{minipage} \AssignStructureRole{minipage}{Div} \NewStructureName{parbox} \AssignStructureRole{parbox}{Div} % \end{macrocode} % % \subsubsection{Text} % \begin{macrocode} \NewStructureName{text/emph} \AssignStructureRole{text/emph}{Em} \NewStructureName{text/verb} \AssignStructureRole{text/verb}{Code} % \end{macrocode} % % \subsubsection{Math} % Math uses internally MathML and this should not be remapped so we need only % names for the outer \texttt{Formula} tag and perhaps for a label: % \begin{macrocode} \NewStructureName{math/inline} \AssignStructureRole{math/inline}{Formula} \NewStructureName{math/display} \AssignStructureRole{math/display}{Formula} \NewStructureName{math/label} \AssignStructureRole{math/label}{Lbl} % \end{macrocode} % % \subsubsection{Index and glossaries} % Tagging not decided yet. % % \subsection{Attributes} % \changes{v0.8j}{2026-04-27}{Add kernel attributes} % \changes{v0.8k}{2026-04-28}{Add more kernel attributes} % The latex-lab code sets up a number of kernel attributes. These are collected here: % \begin{macrocode} \tagpdfsetup { % \end{macrocode} % \subsection{Text attributes} % These attributes are for super- and subscripts and are used in latex-lab-text: % \begin{macrocode} role/new-attribute = {sub} {/O /Layout /TextPosition/Sub}, role/new-attribute = {sup} {/O /Layout /TextPosition/Sup}, % \end{macrocode} % These are for text alignment and they are used in latex-lab-block: role/new-attribute = {justify} {/O /Layout /TextAlign/Justify}, role/new-attribute = {center} {/O /Layout /TextAlign/Center}, role/new-attribute = {raggedright}{/O /Layout /TextAlign/Start}, role/new-attribute = {raggedleft} {/O /Layout /TextAlign/End}, % \subsection{Math attributes} % \begin{macrocode} role/new-attribute = {inline} {/O /Layout /Placement/Inline}, role/new-attribute = {display} {/O /Layout /Placement/Block}, % \end{macrocode} % \subsection{List attributes} % \begin{macrocode} role/new-attribute = {itemize} {/O /List /ListNumbering/Unordered}, role/new-attribute = {enumerate} {/O /List /ListNumbering/Ordered}, role/new-attribute = {description} {/O /List /ListNumbering/Description}, % \end{macrocode} % Initially, we had \texttt{/None} for the basic \env{list} % environment, but that is not allowed in PDF/UA-2 if the list % contains any Lbl tags. So the \texttt{list} attribute uses % \texttt{Unordered} too. % \begin{macrocode} role/new-attribute = {list}{/O /List /ListNumbering/Unordered}, % \end{macrocode} % \subsection{Table attributes} % The code predeclares three attribute names for the scope of header, % \texttt{TH-col}, \texttt{TH-row}, \texttt{TH-both}. % The latex-lab-table code declares on the fly additional attributes % \texttt{colspan-\meta{number}} and \texttt{rowspan-\meta{number}} % with the content \texttt{/O /Table /ColSpan \meta{number}} and % \texttt{/O /Table /RowSpan \meta{number}} % \begin{macrocode} role/new-attribute = {TH-col} {/O /Table /Scope /Column}, role/new-attribute = {TH-row} {/O /Table /Scope /Row}, role/new-attribute = {TH-both} {/O /Table /Scope /Both}, role/new-attribute = {ARIA-role-presentation} {/O /ARIA-1.1/role (presentation)} % \end{macrocode} % \begin{macrocode} } %end tagpdfsetup % \end{macrocode} % The three main table attributes are put directly into the class map % TODO: either tagpdf should do that directly all roles or offer an interface: % \begin{macrocode} \ExplSyntaxOn \seq_gput_left:Ne\g__tag_attr_class_used_seq {\pdf_name_from_unicode_e:n{TH-col}} \seq_gput_left:Ne\g__tag_attr_class_used_seq {\pdf_name_from_unicode_e:n{TH-row}} \seq_gput_left:Ne\g__tag_attr_class_used_seq {\pdf_name_from_unicode_e:n{TH-both}} \ExplSyntaxOff % \end{macrocode} % \begin{macrocode} % % \end{macrocode} % \end{implementation} \endinput