[latex3-commits] [latex3/latex2e] latex-lab/uf-review-05: first draft marginpar tagging (ce3c3d65)
github at latex-project.org
github at latex-project.org
Sat Feb 3 01:40:31 CET 2024
Repository : https://github.com/latex3/latex2e
On branch : latex-lab/uf-review-05
Link : https://github.com/latex3/latex2e/commit/ce3c3d6513b8ea0a9920be4d2a6ec1d519b7d5d7
>---------------------------------------------------------------
commit ce3c3d6513b8ea0a9920be4d2a6ec1d519b7d5d7
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date: Sat Feb 3 01:40:31 2024 +0100
first draft marginpar tagging
>---------------------------------------------------------------
ce3c3d6513b8ea0a9920be4d2a6ec1d519b7d5d7
required/latex-lab/latex-lab-marginpar.dtx | 249 +++++++++++++++++++++++++++++
required/latex-lab/latex-lab.ins | 4 +
2 files changed, 253 insertions(+)
diff --git a/required/latex-lab/latex-lab-marginpar.dtx b/required/latex-lab/latex-lab-marginpar.dtx
new file mode 100644
index 00000000..65e08d28
--- /dev/null
+++ b/required/latex-lab/latex-lab-marginpar.dtx
@@ -0,0 +1,249 @@
+% \iffalse meta-comment
+%
+%% File: latex-lab-marginpar.dtx (C) Copyright 2023 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
+%
+%
+% The development version of the bundle can be found below
+%
+% https://github.com/latex3/latex2e/required/latex-lab
+%
+% for those people who are interested or want to report an issue.
+%
+\def\ltlabmarginpardate{2024-02-03}
+\def\ltlabmarginparversion{0.85b}
+
+%<*driver>
+\documentclass{l3doc}
+\EnableCrossrefs
+\CodelineIndex
+\begin{document}
+ \DocInput{latex-lab-marginpar.dtx}
+\end{document}
+%</driver>
+%
+% \fi
+%
+% \title{The \textsf{latex-lab-marginpar} package\\
+% Changes related to the tagging of margin notes}
+% \author{\LaTeX{} Project\thanks{Initial implementation done by Ulrike Fischer}}
+% \date{v\ltlabmarginparversion\ \ltlabmarginpardate}
+%
+% \maketitle
+%
+% \newcommand{\xt}[1]{\textsl{\textsf{#1}}}
+% \newcommand{\TODO}[1]{\textbf{[TODO:} #1\textbf{]}}
+% \newcommand{\docclass}{document class \marginpar{\raggedright document class
+% customizations}}
+%
+% \providecommand\hook[1]{\texttt{#1\DescribeHook[noprint]{#1}}}
+% \providecommand\socket[1]{\texttt{#1\DescribeSocket[noprint]{#1}}}
+% \providecommand\plug[1]{\texttt{#1\DescribePlug[noprint]{#1}}}
+%
+% \NewDocElement[printtype=\textit{socket},idxtype=socket,idxgroup=Sockets]{Socket}{socketdecl}
+% \NewDocElement[printtype=\textit{hook},idxtype=hook,idxgroup=Hooks]{Hook}{hookdecl}
+% \NewDocElement[printtype=\textit{plug},idxtype=plug,idxgroup=Plugs]{Plug}{plugdecl}
+%
+% \begin{abstract}
+% \end{abstract}
+%
+% \section{Introduction}
+%
+% This module contains changes to improve the tagging (in the standard classes) of
+% margin notes created with the \cs{marginpar} command.
+%
+% Such margin notes are rather small but nevertheless tagging is not trivial and poses
+% a number of interesting problems both regarding the structure and the implementation.
+%
+% \subsection{Structure}
+% \cs{marginpar} creates small boxes in the margin of a page.
+% While they are technically floats they also typically
+% relates to the paragraph beside them, so their structure element should be placed near
+% such a paragraph.
+%
+% They can be tagged either as artifacts (if they are merely distracting decoration),
+% as small headings before the paragraph, or as |Aside|. Unlike the PDF 1.7 fallback |Note|
+% the structure |Aside| is not allowed inside |P|,
+% so if |Aside| is used, it must be placed before or after the current |P| in the surounding |text-unit|,
+% or it must split the |P|. Splitting is probably not so good as
+% |\marginpar| is often used somewhere in the middle of sentence.
+% The best default is probably to use |Aside|, find the parent |text-unit| and add it there.
+%
+% \subsection{Implementation}
+%
+% |marginpar` has an optional argument which allows to define a different content
+% on left/right margins for odd/even pages (depending on twoside and \cs{reversemarginpar}).
+%
+% The current implementation stores *both* arguments in boxes and
+% decides in the output routine which
+% one to use. This is quite problematic for tagging, as the unused box produces
+% structure objects, literals, labels, MCID numbers,
+% and perhaps OBJR-objects from links
+% which must be later thrown away again (or are thrown away by the engine).
+% While it is theoretically not impossible to create
+% both boxes while taging is active but to keep everything on hold and insert
+% the real structure only when the box is used it is in practice quite difficult,
+% slow and error prone.
+%
+% There are a number of options to avoid this hassle.
+%
+% \begin{description}
+% \item[Minimal tagging] One option is to disable tagging when the boxes
+% are built and when the box is used to surround them with a simple Aside.
+%
+% \begin{description}
+% \item[Pro:] easy to implement
+% \item[Contra:]
+% Content that perhaps needed tagging (|\LaTeX| logo with /ActualText, images, links) is not tagged.
+% \end{description}
+%
+% \item[Remaking the box]
+% Tagging is deactivated when the boxes are created.
+% The arguments are stored and when the box should be used in the output routine
+% (and when it is known which one will be used) the box is (re)created, now with proper tagging.
+%
+% Contra: The content can change e.g. if it uses counters or macros that are redefine later before the
+% output routine is called. As tagging is done later, it is not trivial to insert the
+% |Aside| in the right place in the paragraph structure.
+%
+% \item[Two pass compilation]
+% A label is used to detect which argument/boxed is used and
+% tagging is activated only for this one.
+%
+% Contra: costs a |label| and requires a two pass compilation (which is needed anyway).
+% This should be ok. |\marginnote| uses a label too, and the same
+% label could also be used to resolve problems if a margin note
+% moves to a new page (and so replace the mparhack package).
+% \end{description}
+%
+% The last options seems the best and is therefore implemented.
+%
+%
+% \section{Implementation}
+% \begin{macrocode}
+%<*package>
+%<@@=tag>
+% \end{macrocode}
+% \begin{macrocode}
+\ProvidesExplPackage {latex-lab-testphase-marginpar} {\ltlabmarginpardate} {\ltlabmarginparversion}
+ {Changes related to the tagging of the margin notes}
+% \end{macrocode}
+% \subsection{Variables}
+% We need a variable to make the label unique.
+% Todo: Not sure about the name.
+% \begin{macro}{\g__kernel_marginpar_int}
+% \begin{macrocode}
+\int_new:N \g__kernel_marginpar_int
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Tagging sockets}
+%
+% \begin{socketdecl}{tagsupport/marginpar/begin,tagsupport/marginpar/end}
+% \begin{macrocode}
+\socket_new:nn {tagsupport/marginpar/begin}{0}
+\socket_new:nn {tagsupport/marginpar/end}{0}
+% \end{macrocode}
+% \end{socketdecl}
+% \begin{plugdecl}{tagsupport/marginpar/begin,tagsupport/marginpar/end}
+% \begin{macrocode}
+\socket_new_plug:nnn {tagsupport/marginpar/begin}{default}
+ {
+ \if_mode_horizontal:
+ \tag_mc_end:
+ \tag_struct_begin:n{tag=Aside,parent=\g__tag_para_main_struct_tl}%
+ \else:
+ \tag_struct_begin:n{tag=Aside}%
+ \fi:
+ }
+\socket_new_plug:nnn {tagsupport/marginpar/end}{default}
+ {
+ \tag_struct_end:
+ \if_mode_horizontal: \tag_mc_begin:n{} \fi:
+ }
+\socket_assign_plug:nn {tagsupport/marginpar/begin}{default}
+\socket_assign_plug:nn {tagsupport/marginpar/end}{default}
+% \end{macrocode}
+% \end{socketdecl}
+
+% \subsection{Kernel command changes}
+% \begin{macro}{\@savemarbox }
+% We add sockets that add a tagging structure Aside:
+% \begin{macrocode}
+\long\def \@savemarbox #1#2{%
+ \UseTaggingSocket{marginpar/begin}
+ \global\setbox #1%
+ \color at vbox
+ \vtop{%
+ \hsize\marginparwidth
+ \@parboxrestore
+ \@marginparreset
+ #2\par
+ \@minipagefalse
+ \outer at nobreak
+ }%
+ \color at endbox
+ \UseTaggingSocket{marginpar/end}
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@ympar}
+% We must avoid that \cs{@xympar} creates tagging structure:
+% \begin{macrocode}
+\long\def\@ympar#1{%
+ \@savemarbox\@marbox{#1}%
+ \global\setbox\@currbox\copy\@marbox
+ \tag_stop:
+ \@xympar
+ \tag_start:}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@xmpar}
+% \cs{@xmpar} is the command used if an optional argument is present.
+% In this case we must stop tagging for \cs{@xympar} as above
+% but also decide which of the two @savemarbox should have tagging active.
+% We add a label to \cs{@marbox}. If that exist tagging is activated for this
+% box else for the other one.
+% \begin{macrocode}
+\long\def\@xmpar[#1]#2{%
+ \int_gincr:N\g__kernel_marginpar_int
+ \property_if_recorded:eTF { tag_marginpar-opt-\int_use:N\g__kernel_marginpar_int }
+ {
+ \@savemarbox\@marbox {#1\property_record:ee { tag_marginpar-opt-\int_use:N\g_tmpa_int }{page} }%
+ \tag_stop:
+ \@savemarbox\@currbox{#2}%
+ \tag_start:
+ }
+ {
+ \tag_stop:
+ \@savemarbox\@marbox{#1\property_record:ee { marginpar-opt-\int_use:N\g_tmpa_int }{page}}%
+ \tag_start:
+ \@savemarbox\@currbox{#2}%
+ }
+ \tag_stop:
+ \@xympar
+ \tag_start:
+ }
+% \end{macrocode}
+% \end{macro}
+%</package>
+% \end{macrocode}
+
+% \begin{macrocode}
+%<*latex-lab>
+\ProvidesFile{marginpar-latex-lab-testphase.ltx}
+ [\ltlabmarginpardate\space v\ltlabmarginparversion\space
+ Changes related to the tagging of the margin notes]
+
+\RequirePackage{latex-lab-testphase-marginpar}
+
+%</latex-lab>
+% \end{macrocode}
diff --git a/required/latex-lab/latex-lab.ins b/required/latex-lab/latex-lab.ins
index c7b55147..7071ed6e 100644
--- a/required/latex-lab/latex-lab.ins
+++ b/required/latex-lab/latex-lab.ins
@@ -161,6 +161,10 @@ where one can also log issues in case there are any.
\generate{\file{title-latex-lab-testphase.ltx}{\from{latex-lab-title.dtx}{latex-lab}}}
\generate{\file{latex-lab-testphase-title.sty}{\from{latex-lab-title.dtx}{package}}}
+%marginpar
+\generate{\file{marginpar-latex-lab-testphase.ltx}{\from{latex-lab-marginpar.dtx}{latex-lab}}}
+\generate{\file{latex-lab-testphase-marginpar.sty}{\from{latex-lab-marginpar.dtx}{package}}}
+
% stop docstrip adding \endinput
\preamble
\endpreamble
More information about the latex3-commits
mailing list.