[latex3-commits] [latex3/latex2e] develop: some doc updates while reviewing the code (b8c845c7)
github at latex-project.org
github at latex-project.org
Tue Oct 31 11:21:27 CET 2023
Repository : https://github.com/latex3/latex2e
On branch : develop
Link : https://github.com/latex3/latex2e/commit/b8c845c79b7b3540f089d00e82aacddba0b033ae
>---------------------------------------------------------------
commit b8c845c79b7b3540f089d00e82aacddba0b033ae
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Mon Oct 30 19:31:15 2023 +0100
some doc updates while reviewing the code
>---------------------------------------------------------------
b8c845c79b7b3540f089d00e82aacddba0b033ae
required/latex-lab/latex-lab-minipage.dtx | 27 ++++---
required/latex-lab/latex-lab-table.dtx | 119 +++++++++++++++++++-----------
2 files changed, 89 insertions(+), 57 deletions(-)
diff --git a/required/latex-lab/latex-lab-minipage.dtx b/required/latex-lab/latex-lab-minipage.dtx
index 9cd7256a..1d3ee828 100644
--- a/required/latex-lab/latex-lab-minipage.dtx
+++ b/required/latex-lab/latex-lab-minipage.dtx
@@ -16,7 +16,7 @@
%
% for those people who are interested or want to report an issue.
%
-\def\ltlabminipagedate{2023-10-21}
+\def\ltlabminipagedate{2023-10-30}
\def\ltlabminipageversion{0.81c}
%<*driver>
\documentclass{l3doc}
@@ -49,18 +49,21 @@
%
% \section{Introduction}
%
-% How to tag minipages and parboxes is still under discussion.
+% How to best tag minipages and parboxes is still under discussion.
% But as they start and contain paragraphs it is clear that
-% hooks are needed to interrupt and restart the tagging.
+% some sockets are needed to interrupt and restart the tagging.
%
-% The tagging added is currently quite simple minded. See the todo-testfiles and the
-% code comments for some open points.
+% The tagging added is currently quite simple-minded. See the
+% todo-testfiles and the code comments for some open points.
%
-% One of the main problem is how to properly embed them in the surrounding.
-% When used in normal text (in a paragraph) they typically should close the \texttt{text}
-% structure and reopen one at the end. But when used inside low-level \cs{vbox} or \cs{hbox}
-% this is often wrong. The code uses now there two sockets \texttt{tagsupport/parbox/before}
-% and \texttt{tagsupport/parbox/after} which can be set to noop if needed.
+% One of the main problems is how to properly embed them in the
+% surrounding. When used in normal text (in a paragraph) they
+% typically should close the \texttt{text} structure and reopen one
+% at the end. But when used inside low-level \cs{vbox} or \cs{hbox}
+% this is often wrong. The code uses now there two sockets
+% \texttt{tagsupport/parbox/before} and
+% \texttt{tagsupport/parbox/after} which can be set to noop, if
+% necessary.
%
% \begin{macrocode}
%<*package>
@@ -142,8 +145,8 @@
\color at endgroup
\egroup
% \end{macrocode}
-% as the parbox command is called, we must prevent that it adds its additional
-% tagging commands:
+% As the parbox command is called, we must prevent that it adds its
+% additional tagging commands:
% \begin{macrocode}
\tag_stop:n{minipage}
\expandafter\@iiiparbox\@mpargs{\unvbox\@tempboxa}%
diff --git a/required/latex-lab/latex-lab-table.dtx b/required/latex-lab/latex-lab-table.dtx
index caa598c2..6c891402 100644
--- a/required/latex-lab/latex-lab-table.dtx
+++ b/required/latex-lab/latex-lab-table.dtx
@@ -55,41 +55,56 @@
%
% \begin{abstract}
% The following code implements a first draft for the tagging of
-% tables. It has a large number of restrictions!
+% tables. It still has a large number of limitations and restrictions!
% \end{abstract}
%
% \tableofcontents
%
% \section{Documentation}
%
-% In \LaTeX{} \texttt{table} is the name of the float environment which can contain
-% a data table along with a caption and additional text. The environments for
+% In \LaTeX{} the word \texttt{table} is used as the name of the float environment that can contain
+% a data table\footnote{But it does not really have to, you can put
+% other material into such environments.} along with a caption and some additional text. The environments for
% actual data tables have various names like \texttt{tabular}, \texttt{tabular*},
% \texttt{tabularx} and \texttt{longtable}---the last should not be used inside a float
% and supports its own caption command.
%
-% In this documentation \enquote{table} always means such a data table and not the float
+% In this documentation \enquote{table} always means such data tables and not the float
% environment.
%
% Tagging of tables is on one side doesn't look very difficult: one only has to
% surround rows and cells by TR and TH or TD structures.
% But there are difficulties:
-% One is that over the years various packages related to tables have been written
-% which all change some of the internals. Inserting the tagging commands and testing
-% all the variants and various nestings is not trivial.
-% The other difficulty is that most of the existing environments to create table
-% do not know the concept of headers as a semantic structures.
-% Headers are only produced through visual formatting, e.g. by making them bold
-% or by underlying some color. But accessible table need headers (and the PDF/UA standards
-% requires them) and this means that additional syntax to declare headers (when
-% they can't be guessed) must be developed. This is still an area for research.
-%
-% This module therefore does implement only some basic support for the tagging of
-% tables. A list of the known limitations is shown below.
-%
-% The module is not loaded automatically and in itself it doesn't activate
-% tagging. For proper tagging be loaded at best in combination
-% with phase-III in \cs{DocumentMetadata}:
+% \begin{itemize}
+% \item
+% One is that over the years various packages related to tables have
+% been written that all change some of the internals. Inserting the
+% tagging commands and testing all the variants and various nestings
+% is not trivial.
+%
+% \item
+% The other difficulty is that most of the existing environments to
+% create tables do not know the concept of headers as a semantic
+% structures.
+%
+% \item
+% Headers are only produced through visual formatting, e.g., by
+% making them bold or by underlying some color. But accessible
+% tables need headers (and the PDF/UA standards requires them) and
+% this means that additional syntax to declare headers (when they
+% can't be guessed) must be developed. This is still an area for
+% research.
+% \end{itemize}
+%
+% Right now, this module therefore does implement only some basic
+% support for the tagging of tables. A list of the known limitations
+% is shown below.
+%
+% The module is not loaded automatically (i.e., not yet integrated
+% into any \texttt{phase-XX}) and by itself it doesn't activate
+% tagging. For experimenting with table tagging it is therefore best
+% to load it in combination
+% with phase-III in \cs{DocumentMetadata}, i.e.:
%
% \begin{verbatim}
% \DocumentMetadata{testphase={phase-III,table}}
@@ -100,7 +115,7 @@
% Such tables can be nested.
%
% If a table should not be tagged as table, for example because it is merely used
-% to produce a layout or because it is a not yet (fully) supported table structure
+% to produce a layout or because it is a not yet (fully) supported table structure,
% the tagging can be disabled with
% \verb|\tagpdfsetup{table-tagging=false}|.
%
@@ -108,28 +123,41 @@
% p/m/b-type cells.
%
% Rows do not need to contain a full number of \&, missing cells are automatically
-% filled up with a an empty TD-structure.
-%
-% There is some basic support for headers: with
-% \verb|\tagpdfsetup{table-header-rows={|\meta{list of row numbers}\verb|}| you can
-% declare which (absolute) row numbers should be tagged as header. The row number can be
-% negative, then the counting starts at the end of the table. There is no support
-% for header columns yet. In a longtable the code will currently use the \cs{endhead} or
-% \cs{endfirsthead} rows as header if one of these commands has been used and
-% then ignore the \texttt{table-header-rows} setting.
+% added with an empty TD-structure.
+%
+% There is some basic support\footnote{This is not meant to be the
+% final interface, though.} for headers. With
+% \begin{quote}
+% \verb|\tagpdfsetup{table-header-rows={|\meta{list of row numbers}\verb|}|
+% \end{quote}
+% you can
+% declare which (absolute) row numbers should be tagged as header rows.
+% It applies to all tables until it is changed to a different list of row numbers or undone by setting
+% the key to \meta{empty}.
+% A row number can be
+% negative, then the counting starts from the end of the table. There is no support
+% for header columns yet. In a \env{longtable} the code will currently use the \cs{endhead} or
+% \cs{endfirsthead} rows as header if one of these commands has been
+% used and in that case the code
+% ignores a \texttt{table-header-rows} setting.
%
% You should not insert meaningful text with \verb+!{...}+ or \verb+@{...}+ or \cs{noalign}
% between the rows or columns of the table.
% With pdflatex such text will be unmarked, with lualatex it will be marked as artifact.
-% Both means that it will be currently ignored in the structure.\footnote{While it is theoretically possible
+% Either case means that it will be currently ignored in the
+% structure.\footnote{While it is theoretically possible
% to collect such text and move it into a structure it would require manual markup
% from the author to clarify where this text belongs too.}
%
-% As mentioned below the \pkg{colortbl} doesn't work yet properly with the tagging,
-% but once it does colors will probably be at first simply ignored. If such a color
+% As mentioned below the \pkg{colortbl} doesn't yet work properly with the tagging,
+% but once it does, then colors inside the table will probably be
+% simply ignored (at least initially). If such a color
% has a semantic meaning (like \enquote{important value}) this meaning will be lost.
%
-% Feedback and problems with the code can be reported at \url{https://github.com/latex3/tagging-project}.
+% Feedback and problems with the code can be reported at
+% \url{https://github.com/latex3/tagging-project} either in form of
+% explicit issues or as a \enquote{discussion topic}, whatever works best.
+%
%
% \section{Limitations}
%
@@ -138,9 +166,9 @@
% not really a limitation, but can affect existing tables).
%
% \item It supports only a restricted number of tables types. Currently
-% \texttt{tabular}, \texttt{tabular*}, \texttt{tabularx} and \texttt{longtable}.
+% \env{tabular}, \env{tabular*}, \env{tabularx}, and \env{longtable}.
%
-% \item \texttt{array} is assumed to be part of math and tagging as a table is disabled for
+% \item the \env{array} environment is assumed to be part of math and tagging as a table is disabled for
% it.
%
% \item Row spans are not yet supported (and the \pkg{multirow} package is untested).
@@ -157,7 +185,7 @@
% that includes packages that change rules like \pkg{booktabs}, \pkg{hhline},
% \pkg{arydshln}, \pkg{hvdashln}.
%
-% \item \texttt{longtable} currently only works with lualatex.
+% \item \env{longtable} currently only works with lualatex.
% With other engines it breaks as its output
% routine clashes with the code which closes open MC-chunks at pagebreaks and
% if this is resolved there will probably be problems with the head and foot boxes
@@ -165,25 +193,26 @@
%
% \item Not every table should be tagged as a Table structure, often they are
% only used as layout help, e.g. to align authors in a title pages. In such uses
-% the tagging of the table must be deactivated with \verb|\tagpdfsetup{table-tagging=false}|
+% the tagging of the table must be deactivated with \verb|\tagpdfsetup{table-tagging=false}|.
%
% \item Only simple header rows are currently supported. Columns and complex headers with
% subheaders will be handled later as that needs some syntax changes. Tables
% with more than one header row are probably not pdf/UA as the headers array in
% the cells is missing.
%
-% \item A longtable \cs{caption} is currently simply formatted as a multicolumn and
-% not tagged as \texttt{Caption}.
+% \item A \pkg{longtable} \cs{caption} is currently simply formatted as a multicolumn and
+% not tagged as a \texttt{Caption} structure.
%
-% \item The caption package will quite probably break the longtable caption.
+% \item The \pkg{caption} package will quite probably break the \pkg{longtable} caption.
%
-% \item The setup for longtable requires lots of patches to internal longtable
-% commands and so can easily break if other packages try to patch longtable too.
+% \item The setup for \pkg{longtable} requires lots of patches to internal \pkg{longtable}
+% commands and so can easily break if other packages try to patch \pkg{longtable} too.
%
-% \item Longtable supports footnotes in p-type columns, but it hasn't been
+% \item The \env{longtable} environment supports footnotes in p-type columns, but it hasn't been
% tested yet if this works also with the tagging code.
%
-% \item The code is quite noisy and fills the log with lots of messages.
+% \item The code is quite noisy and fills the log with lots of
+% messages.\footnote{Helpful for us at this stage.}
% \end{itemize}
%
%
More information about the latex3-commits
mailing list.