summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tagpdf/tagpdf.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/tagpdf/tagpdf.tex')
-rw-r--r--macros/latex/contrib/tagpdf/tagpdf.tex277
1 files changed, 180 insertions, 97 deletions
diff --git a/macros/latex/contrib/tagpdf/tagpdf.tex b/macros/latex/contrib/tagpdf/tagpdf.tex
index 510ed6b0a2..4e9d37cbc0 100644
--- a/macros/latex/contrib/tagpdf/tagpdf.tex
+++ b/macros/latex/contrib/tagpdf/tagpdf.tex
@@ -4,8 +4,8 @@
\makeatletter
-\def\UlrikeFischer@package@version{0.82}
-\def\UlrikeFischer@package@date{2021-06-14}
+\def\UlrikeFischer@package@version{0.9}
+\def\UlrikeFischer@package@date{2021-06-29}
\makeatother
\documentclass[DIV=12,parskip=half-,bibliography=totoc]{scrartcl}
@@ -53,7 +53,6 @@
interwordspace=true,
%log=v
%show-spaces
- global-mc
}
\usepackage{hyperxmp}
@@ -79,13 +78,9 @@
\usepackage{tagpdfdocu-patches}
+\cfoot*{\pagemark}
-%header and footer. This still needs some sorting, the first page does't work correctly
-\cfoot*{\leavevmode\tagmcbegin{artifact=pagination}\pagemark\tagmcend}
-\makeatletter
-\patchcmd\@oddfoot{\begingroup}{\begingroup\tagpdfparaOff}{}{}
-\patchcmd\@oddhead{\begingroup}{\begingroup\tagpdfparaOff}{}{}
-\makeatother
+%
\newcommand\PDF{PDF}
@@ -154,10 +149,20 @@ Issues, comments, suggestions should be added as issues to the github tracker:
\tableofcontents
+\section{Preface to version 0.9}
+
+In this version lots of things have changed, but most of them are internal: the code has been reviewed and cleaned up,
+a number of errors corrected, the code has been properly documented (and the code documentation can now be compiled and
+printed).
+
+There are nevertheless also a number of changes for the public interface, including some breaking changes. Check the change section below for
+details.
+
+
\section{Preface to version 0.8 and newer}
-Starting with version 0.8 one major step towards integration of the code into the \LaTeX{} has been done:
+Starting with version 0.8 one major step towards integration of the code into the \LaTeX{} kernel has been done:
The code now relies on the new \LaTeX{} PDF management. This management, which is for a testphase provided
as an external package, \texttt{pdfmanagement-testphase},
prepares the ground for better support for tagged PDF in \LaTeX{}.
@@ -204,6 +209,8 @@ I implemented the generic mode first. Mostly because my tex skills are much bett
While the generic mode is not bad and I spent quite some time to get it working I nevertheless think that the lua mode is the future and the only one that will be usable for larger documents. \PDF{} is a page orientated format and so the ability of luatex to manipulate pages and nodes after the \TeX-processing is really useful here. Also with luatex characters are normally already given as unicode.
+The package uses quite a lot labels (in generic mode more than with luamode). At the begin it relied on the \pkg{zref} package, but switched now to a new experimental implementation for labels. The drawback of the new method is that they don't give yet good rerun messages if they have changed. I advise to use the \pkg{rerunfilecheck} package as a intermediate work-around.
+
\subsection{References and target PDF version}
@@ -214,7 +221,7 @@ In 2018 \PDF{} 2.0. has been released, and since 2020 all engines can set the ve
now target \PDF{} 2.0. This doesn't mean that 2.0 will be required, but that the code and the options will be extended to
support \PDF{} 2.0. One example is the support for associated files, another the support for name spaces in version 0.82.
-The packages doesn't try to suppress all 2.0 features if an older \PDF{} version is produced. It normally doesn't harm if a \PDF{} contains keys unknown in its version and it makes the code faster and easier to maintain if there aren't too many tests and code pathes; so for example associated files will always be added. But tests could be added in case this leads to incompabilities.
+The package doesn't try to suppress all 2.0 features if an older \PDF{} version is produced. It normally doesn't harm if a \PDF{} contains keys unknown in its version and it makes the code faster and easier to maintain if there aren't too many tests and code pathes; so for example associated files will always be added. But tests could be added in case this leads to incompabilities.
It should be noted that some tools don't like \PDF{}~2.0. PAC3 for example simply crashes, and pdftk will create a \PDF{}~1.0 from it. This makes testing \PDF{}~2.0 files a bit of a challenge.
@@ -239,7 +246,7 @@ One must check how good the accessibility is \emph{practically}.
Syntax validation and formal standard validation can be done with preflight of the (non-free) adobe acrobat.
It can also be done also with the free \PDF{} Accessibility Checker (PAC~3) \parencite{pac3}.
There is also the validator veraPDF \parencite{verapdf}.
-A rather new tool is \enquote{Next Generation PDF} \parencite{ngpdf}, a browser application which converts a tagged PDF to html, allows to inspect its structure and also to edit the structure.
+A rather new and quite useful tool is \enquote{Next Generation PDF} \parencite{ngpdf}, a browser application which converts a tagged PDF to html, allows to inspect its structure and also to edit the structure.
Practical validation is naturally the more complicated part. It needs screen reader, users which actually knows how to handle them, can test documents and can report where a \PDF{} has real accessibility problems.
@@ -338,6 +345,48 @@ New commands to store and reset mc-tags.
PDF 2.0 namespace are now supported.
+\subsection{Changes in version 0.82}
+
+A command |\tag_if_active:TF| to test if tagging is active has been added. This allow external packages to write conditional code.
+
+The commands |\tag_struct_parent_int:| and |\tag_struct_insert_annot:nn| have been added. They allow to
+add annotations to the structure.
+
+
+\subsection{Changes in version 0.83}
+
+|\tag_finish_structure:| has been removed, it is no longer a public command.
+
+\subsection{Changes in version 0.9}
+
+\begin{itemize}
+\item Code has been cleaned up and better documented.
+
+\item \textbf{More engines supported} The generic mode of \pkg{tagpdf} now works
+(theoretically, it is not much tested) with all engines supported
+by the pdfmanagement. So compilations with Xe\LaTeX{} or with dvips should work. But it should be noted that
+these engines and backends don't support the |interspaceword| option. With Xe\LaTeX{} it is perhaps possible
+implement something with |\XeTeXinterchartoks|, but for the dvips route I don't see an option (apart from lots
+of manual macros everywhere).
+\item \textbf{MC-attributes are global again} In\sidenote{Breaking change!} version 0.6 the attributes used in
+luamode to mark the MC-chunks were no longer set globally. This avoided a number of problems with header and footer
+and background material, but further tests showed that it makes it difficult to correctly mark things like
+links which have to interrupt the current marking code---the attributes couldn't easily escape groups added by
+users. See section~\ref{sec:global-local} for more details.
+\item \textbf{key global-mc removed:} Due to the changes in the attribute keys this key is not longer needed.
+\item \textbf{key check-tags removed:} It doesn't fit. Checks are handled over the logging level.
+\item |\tagpdfget| has been removed, use the expl3 version if needed.
+\item The show commands |\showtagpdfmcdata|, |\showtagpdfattributes|, |\showtagstack| have been removed and replaced
+by a more flexible command |\ShowTagging|.
+\item The commands |\tagmcbegin| and |\tagmcend| no longer ignore following spaces or remove earlier one. While this
+is nice in some places, it also ate spaces in places where this wanted expected. From now on both commands behave exactly
+like the expl3 versions.
+\item The lua-code to add real space glyphs has been separated from the tagging code. This means that |interwordspace| now
+works also if tagging is not active.
+\item The key |activate| has been added, it open the first structure, see below.
+\end{itemize}
+
+
\subsection{Proof of concept: the tagging of the documentation itself}
Starting with version 0.6 the documentation itself has been tagged. The tagging wasn't (and isn't) in no way perfect. The validator from Adobe didn't complain, but PAX3 wanted alternative text for all links (no idea why) and so I put everywhere simple text like \enquote{link} and \enquote{ref}. The links to footnotes gave warnings, so I disabled them. I used types from the \PDF{} version 1.7, mostly as I have no idea what should be used for code in 2.0. Margin notes were simply wrong \ldots
@@ -370,6 +419,8 @@ Most commands do nothing if tagging is not activated, but in case a test is need
\begin{docCommand}{tag_if_active:TF}{}\end{docCommand}
+The check is true only if \emph{everything} is activated. In all other cases (also if tagging has been stopped locally) it will be false.
+
\subsection{Modes and package options}
@@ -401,6 +452,9 @@ The key-val list understands the following keys:
\begin{description}
\item[\PrintKeyName{activate-all}]
Boolean, initially false. Activates everything, that's normally the sensible thing to do.
+\item [\PrintKeyName{activate}] Like |activate-all|, \emph{additionally} is opens at begin document
+a structure with |\tagstructbegin| and closes it at end document. The key accepts as value a tag name which is used as the tag of the structure.
+The default value is |Document|.
\item[\PrintKeyName{activate-mc}]
Boolean, initially false. Activates the code related to marked content.
\item[\PrintKeyName{activate-struct}]
@@ -409,8 +463,6 @@ The key-val list understands the following keys:
Boolean, initially false. Activates the code related to trees. Should be used only if the two other keys has been used too.
\item[\PrintKeyName{add-new-tag}]
Allows to define new tag names, see section \ref{sec:new-tag} for a description.
-\item[\PrintKeyName{check-tags}]
- Boolean, initially true. Activates some safety checks (but doesn't do very much currently. It will perhaps be merged with the log-level key).
\item[\PrintKeyName{interwordspace}]
Choice key, possible values are \PrintKeyName{true}/""\PrintKeyName{on} and \PrintKeyName{false}/\PrintKeyName{off}. The key activates/deactivates the insertion of space glyphs, see section~\ref{sec:spacechars}. In the luamode it only works if at least \PrintKeyName{activate-mc} has been used.
@@ -438,9 +490,6 @@ That's a debug option, it helps in lua mode to see where space glyph will be ins
\item[\PrintKeyName{uncompress}]
Sets both the \PDF{} compresslevel and the \PDF{} objcompresslevel to 0 and so allows to inspect the \PDF{}.
-\item[\PrintKeyName{global-mc}]
- Only relevant for luatex and luamode and can only be used in the preamble. If used the attributes used for the mc-tags are set globally. This key is temporary! It is there to allow to test if global or local setting is more sensible. See section~\ref{sec:global-local} for more info.
-
\end{description}
@@ -653,7 +702,16 @@ This sounds easy. But there are quite a number of traps, mostly with pdfLaTeX:
Often text in a document is created automatically or moved around: entries in the table of contents, index, bibliography and more. To mark these text chunks correctly one has to analyze the code creating such content to find suitable places to inject the literals.
\item
- The literals are inserted directly and not at shipout. This means that due to the asynchronous page breaking of \TeX\ the MCID-number can be wrong even if the counter is reset at every page (this package uses in generic mode a label-ref-system to get around this problem. This sadly means that three compilations are needed until everything has settled down).
+ The literals are inserted directly and not at shipout. This means that due to the asynchronous page breaking of \TeX\ the MCID-number can be wrong even if the counter is reset at every page. This package uses in generic mode a label-ref-system to get around this problem. This sadly means that often at least three compilations are needed until everything has settled down.
+
+ It can actually be worse: If the text is changed after the MCID-numbers have been assigned, and
+ a new mc-chunk is inserted in the middle of the page, then all the numbers have to be recalculated
+ and that requires again a number of compilations until it really settles down again.
+ Internal references are especially problematic here, as the first compilation
+ typically creates a non-link |??|, and only the second inserts the structure and the new mc.
+ When the reference system in LaTeX will be extended, care will be taken to ensure that already the dummy text builds a chunk.
+ Until then the advice is to first compile the document and resolve all cross-reference and to activate tagging only at the end.
+
\item
There exist environments which process their content more than once -- examples are \texttt{align} and \texttt{tabularx}.
@@ -680,6 +738,7 @@ This means that quite a number of problems mentioned above are not relevant for
+
\subsubsection{Commands to mark content and chunks}
@@ -690,7 +749,7 @@ For strategies how to handle paragraphs that split over pages see subsection~\re
\begin{docCommand}{tag_mc_begin:n}{\marg{key-val-list}}\end{docCommand}
-These commands insert the begin of the marked content code in the \PDF{}. They don't start a paragraph. \emph{They don't start a group}. The user command additionally issues an \verb+\ignorespaces+ to suppress spaces after itself.
+These commands insert the begin of the marked content code in the \PDF{}. They don't start a paragraph. \emph{They don't start a group}.
Such markers should not be nested. The command will warn you if this happens.
The key-val list understands the following keys:
@@ -751,26 +810,26 @@ The key-val list understands the following keys:
\begin{docCommand}{tagmcend}{}\end{docCommand}
\begin{docCommand}{tag_mc:end}{}\end{docCommand}
-These commands insert the end code of the marked content. They don't end a group and in generic mode it doesn't matter if they are in another group as the starting commands. The user command also issues in hmode at first an \verb+\unskip+. In generic mode both commands check if there has been a begin marker and issue a warning if not. In luamode it is often possible to omit the command, as the effect of the begin command ends with the current group or with a new \verb+\tagmcbegin+ anyway.
-
-
-
-\begin{tcolorbox}[before upper=\tagpdfparaOn]
-\minisec{About nesting mc-commands}\label{mc-nesting}
+These commands insert the end code of the marked content. They don't end a group and it doesn't matter if they are in another group as the starting commands. In generic mode both commands check if there has been a begin marker and issue a warning if not. In luamode it is often possible to omit the command, as the effect of the begin command ends with a new \verb+\tagmcbegin+ anyway.
-\textbf{Attention!}\sidenote{luamode} As mentioned above in luamode it is often possible to omit the \verb+\tagmcend+ command. This basically means that mc-chunks can be nested. But be aware that this can have surprising side effects on the order in the structure.
-Consider a code like this:
-
-
-\begin{lstlisting}
-\tagmcbegin{tag=P} Block 1 {\tagmcbegin{tag=P} Block 2} Block 3 \tagmcend
-\end{lstlisting}
-
-
-Block 3 will here get the same id number as Block 1 and be stored in the structure \emph{before} Block 2. The \PDF{} will record the chunks in the order \texttt{Block 1 -- Block 3 -- Block 2}. See also section~\ref{sec:global-local}.
-
-\end{tcolorbox}
+% no longer relevant
+%\begin{tcolorbox}[before upper=\tagpdfparaOn]
+%\minisec{About nesting mc-commands}\label{mc-nesting}
+%
+%\textbf{Attention!}\sidenote{luamode} As mentioned above in luamode it is often possible to omit the \verb+\tagmcend+ command. This basically means that mc-chunks can be nested. But be aware that this can have surprising side effects on the order in the structure.
+%
+%Consider a code like this:
+%
+%
+%\begin{lstlisting}
+%\tagmcbegin{tag=P} Block 1 {\tagmcbegin{tag=P} Block 2} Block 3 \tagmcend
+%\end{lstlisting}
+%
+%
+%Block 3 will here get the same id number as Block 1 and be stored in the structure \emph{before} Block 2. The \PDF{} will record the chunks in the order \texttt{Block 1 -- Block 3 -- Block 2}. See also section~\ref{sec:global-local}.
+%
+%\end{tcolorbox}
\begin{docCommand}{tagmcuse}{}\end{docCommand}
@@ -803,24 +862,24 @@ In \emph{generic mode}, where marked content command shouldn't be nested, it wor
In \emph{lua mode} it tests if the mc-attribute is currently unset. You can't test the nesting level with it!
-\begin{docCommand}{tagpdfget}{\marg{key word}}\end{docCommand}
\begin{docCommand}{tag_get:n}{\marg{key word}}\end{docCommand}
-
-These commands give back some variables. Currently the only working key words are \verb+mc\_tag+ and \verb+struct\_tag+.
+This command give back some variables. Currently the only working key words are \verb+mc\_tag+ and \verb+struct\_tag+.
\subsubsection{Luamode: global or not global -- that is the question}\label{sec:global-local}
-In\sidenote{Luamode mode only} luamode the mc-commands set and unset an attribute to mark the nodes. One can view such an attribute like a font change or a color: they affect all following chars and glue node until stopped.
+In\sidenote{Luamode mode only} luamode the mc-commands set and unset an attribute to mark the nodes. One can view such an attribute like a font change or a color: they affect all following chars and glue nodes until stopped.
-Currently the attributes are set locally. This has the advantage that the attributes don't spill over in area where they are not wanted like the header and footer or the background pictures.
-But it has the disadvantage that is difficult for an inner structure to correctly interrupt the outer
-mc-chunk if it can't control the group level. For example this would work fine:
+From version 0.6 to 0.82 the attributes were set locally.
+This had the advantage that the attributes didn't spill over in area where they are not wanted like the header and footer or the background pictures.
+But it had the disadvantage that it was difficult for an inner structure to correctly interrupt the outer
+mc-chunk if it can't control the group level. For example this didn't work due to the grouping inserted by the user:
\begin{lstlisting}
\tagstructbegin{tag=P}
\tagmcbegin{tag=P}
Start paragraph
+ {% user grouping
\tag_mc_end_push:
\tagstructbegin{tag=Em}
\tagmcbegin{tag=Em}
@@ -828,35 +887,50 @@ mc-chunk if it can't control the group level. For example this would work fine:
\tagmcend
\tagstructend
\tag_mc_begin_pop:n{}
+ }% user grouping
Continuation of paragraph
\tagmcend
\tagstructend
\end{lstlisting}
-But if the user adds a group like in the following listing, then the reading order will be wrong and the \emph{emphasized text} will move in the structure at the end as described in the box about nesting
-mc-chunks on page~\pageref{mc-nesting}.
+The reading order was then wrong, and the \emph{emphasized text} moved in the structure at the end.
+
+So starting with version 0.9 this has been reverted. The attribute is now global again.
+This solves the \enquote{interruption} problem, but has its price: Material inserted by the output routine
+must be properly guarded. For example
\begin{lstlisting}
-\tagstructbegin{tag=P}
-\tagmcbegin{tag=P}
- Start paragraph
- { %group
- \tag_mc_end_push:
- \tagstructbegin{tag=Em}
- \tagmcbegin{tag=Em}
- \emph{with emphasized text}
- \tagmcend
- \tagstructend
- \tag_mc_begin_pop:n{}
- } %group
- Continuation of paragraph
-\tagmcend
+\RequirePackage{pdfmanagement-testphase}
+\DeclareDocumentMetadata{uncompress}
+\documentclass{article}
+\usepackage{tagpdf}
+\tagpdfsetup{activate,interwordspace=true}
+
+\pagestyle{headings}
+\begin{document}
+\tagstructbegin{tag=Document}
+\sectionmark{HEADER}
+\AddToHook{shipout/background}{\put(5cm,-5cm){BACKGROUND}}
+\tagmcbegin{tag=P}Page 1\newpage Page 2\tagmcend
\tagstructend
+\end{document}
\end{lstlisting}
-If the attribute is set globally this wouldn't be a problem. Currently the question is undecided.
-To allow to test with both versions it is possible to switch for a document with \texttt{global-mc} to global attributes.
+Here the header and the background code on the \emph{first} page will be marked up as paragraph
+and added as chunk to the document structure. The header and the background code on
+the \emph{second} page will be marked as artifact. The following figure shows how the tags looks
+like.
+
+\tagpdfparaOff
+\tagstructbegin{tag=Figure,alttext=Show tags of examples,attribute=bbox}\tagmcbegin{tag=Figure}
+\includegraphics{global-ex}
+\tagmcend\tagstructend
+\tagpdfparaOn
+It is therefore from now on important to correctly markup such code. Header and footer typically should be
+artifacts. The LaTeX kernel hasn't yet suitable hooks around header and footer to allow to automate
+this, but they will be added. With packages like \pkg{fancyhdr} or \pkg{scrlayer-scrpage} it is quite easy to add
+the needed code too.
\subsubsection{Tips}
@@ -892,7 +966,7 @@ To allow to test with both versions it is possible to switch for a document with
\end{figure}
-\subsubsection{Links and other annotations}
+\subsubsection{Links and other annotations}\label{sec:link+annot}
Annotations (like links or form field annotations) are objects associated with a geometric region of the page rather than with a particular object in its content stream. Any connection between a link or a form field and the text is based solely on visual appearance (the link text is in the same region, or there is empty space for the form field annotation) rather than on an explicitly specified association.
@@ -904,14 +978,14 @@ To support this, \pkg{tagpdf} offers currently two commands
\begin{docCommand}{tag_struct_parent_int:}{}\end{docCommand}
-This insert the current value of a global counter used to track such object. It can be used to add the \texttt{/StructParent} value to
+This insert the current value of a global counter used to track such objects. It can be used to add the \texttt{/StructParent} value to
the annotation dictionary.
\begin{docCommand}{tag_struct_insert_annot:nn}{\marg{object reference}\marg{struct parent number}}\end{docCommand}
This will insert the annotation described by the object reference into the current structure by creating the OBJR object. It will
also add the necessary entry to the parent tree and increase the global counter referred to by |\tag_struct_parent_int:|.
-It does nothing if (structure) tagging is not activated.
+It does nothing if (structure) tagging is not activated.
Attention! As the second command increases the global counter at the end it changes the value given back by the first.
That means that if nesting is involved care must be taken that the correct numbers is used. This should be easy to fulfil for most annotations, as there are boxes.
@@ -949,8 +1023,6 @@ The following listing shows low-level to create link where the two commands are
\end{lstlisting}
-With luatex and local attributes (see section~\ref{sec:global-local}) commands like \cs{url} should not be grouped to allow them to reset the mc-attributes, or if groups are involved the mc-chunks should be closed and reopened manually to get the right reading order.
-
\subsubsection{Math}
@@ -998,14 +1070,19 @@ Pellentesque scelerisque
sit amet, lacus.\tagmcend
\end{lstlisting}
-\subsubsection{Automatic tagging of paragraphs}
+\subsubsection{Automatic tagging of paragraphs}\label{sec:paratagging}
\begin{docCommand}{tagpdfparaOn}{}\end{docCommand}
\begin{docCommand}{tagpdfparaOff}{}\end{docCommand}
Another feature that emerged from the \LaTeX{} tagged PDF project are hooks at the begin and end of paragraphs.
\pkg{tagpdf} makes use of these hooks to tag paragraphs. This can be activated/deactivated (also locally) with
-options of \cs{tagpdfsetup} or with the two commands above. \emph{This is very experimental and it requires a new latex-dev!}
+options of \cs{tagpdfsetup} or with the two commands above. \emph{This is very experimental and it requires a new \LaTeX!}
+
+The automatic tagging require that for every begin of a paragraph with the begin hook code
+there a corresponding end with the closing hook code. This can fail, e.g if a |vbox| doesn't correctly issue a |\par| at the end.
+If this happens the tagging structure can get every confused. It is therefore needed to check the structure carefully as currently
+no checks are implemented to check this automatically.
\subsection{Task 2: Marking the structure}
@@ -1136,7 +1213,7 @@ The key-val list understands the following keys:
See also section~\ref{sec:attributes}.
\item[\PrintKeyName{attribute-class}]
- This key takes as argument a comma list of attribute names (use braces to protect the commas from the external key-val parser) and allows to add one or more attribute classes to the structure object. As an example
+ This key takes as argument a comma list of attribute names (use braces to protect the commas from the external key-val parser) and allows to add them as attribute classes to the structure object. As an example
\begin{lstlisting}
@@ -1271,19 +1348,12 @@ Attributes can then be used with the key \PrintKeyName{attribute} or \PrintKeyNa
\subsection{Task 3: tree Management}
+When all the document content has been correctly marked and the data for the trees has been collected they must be flushed to the \PDF{}. This is done automatically (if the package has been activated) with an internal command in an end document hook.
-
-When all the document content has been correctly marked and the data for the trees has been collected they must be flushed to the \PDF{}. This is done automatically (if the package has been activated) with the following command in \verb+\AfterEndDocument+:
-
-\begin{docCommand}{tag_finish_structure:}{}\end{docCommand}
+\begin{docCommand}{__tag_finish_structure:}{}\end{docCommand}
This will hopefully write all the needed objects and values to the \PDF{}. (Beside the already mentioned \texttt{StructTreeRoot} and \texttt{StructElem} objects, additionally a so-called \texttt{ParentTree} is needed which records the parents of all the marked contents bits, a \texttt{Rolemap}, perhaps a \texttt{ClassMap} and object for the attributes, and a few more values and dictionaries).
-I'm not quite sure if this shouldn't be a really internal command.
-
-
-
-
\subsection{A fully marked up document body}
@@ -1476,7 +1546,8 @@ With the key \PrintKeyName{interwordspace} you can activate such space glyphs.
With pdftex this will simply call the primitive \verb+\pdfinterwordspaceon+. pdftex will then insert at various places a char from a font called dummy-space. Attention! This means that at every space there are additional font switches in the \PDF{}: from the current font to the dummy-space font and back again. This will make the \PDF{} larger. As \verb+\pdfinterwordspaceon+ is a primitive function it can't be fine tuned or adapted. You can only turn it on and off and insert manually such a space glyph with \verb+\pdffakespace+.
-With luatex (in luamode) interwordspace is implemented with a lua-function which is inserted in two callbacks and marks up the places where it seems sensible to inter a space glyph. Later in the process (when also the mc-markers are inserted) the space glyphs are injected -- the code will take the glyph from the current font if this has a space glyph or switch to the default latin modern font. The current code works reasonable well in normal text.
+With luatex (in luamode) |interwordspace| is implemented with a lua-function which is inserted in two callbacks and marks up the places where it seems sensible to inter a space glyph. Later in the process the space glyphs are injected -- the code will take the glyph from the current font if this has a space glyph or switch to the default latin modern font. The current code works reasonable well in normal text.
+|interwordspace| can be used without actually tagging a document.
The key \PrintKeyName{show-spaces} will show lines at the places where in lua mode spaces are inserted and so can help you to find problematic places. For listings -- which have a quite specific handling of spaces -- you can find a suggestion in the example \texttt{ex-space-glyph-listings}.
@@ -1516,22 +1587,32 @@ If suitable I will add code for this tasks to this packages. But some of them ca
\section{Debugging}
While developing commands and tagging a document, it can be useful to get some info about the current structure. For this
-a number of commands are provided
+a show command is provided
-\begin{docCommand}{showtagstack}{}\end{docCommand}
+\begin{docCommand}{ShowTagging}{\marg{key-val}}\end{docCommand}
-This shows the tag names of the currently open structures. Typically it will contain at
-least |root| and |Document|.
+This command takes as argument a key-val list which implements a number of show options.
-\begin{docCommand}{showtagpdfmcdata}{\oarg{mc number}}\end{docCommand}
-
-This\sidenote{luaonly} can only be used with lualatex and shows some info about the
-current mc-chunk. The optional argument allows to select a number.
-
-\begin{docCommand}{showtagpdfattributes}{}\end{docCommand}
+\begin{description}
+ \item[\PrintKeyName{mc-data}] This key is relevant for luamode only.
+ It shows the data of all mc-chunks created so far.
+ It is accurate only after shipout, so typically should be issued after a
+ newpage. The value is a positive integer and sets the first mc-shown. If no value
+ is given, 1 is used and so all mc-chunks created so far are shown.
+
+ \item[\PrintKeyName{mc-current}] This key shows the number and the tag of
+ the currently open mc-chunk. If no chunk is open it shows only the
+ state of the absolute counter. It works in all mode,
+ but the output in luamode looks different.
+
+ \item[\PrintKeyName{struct-stack}] This key shows the current
+ structure stack. Typically it will contain at
+ least |root| and |Document|.
+ With the value |log| the info is only
+ written to the log-file, |show| stops the compilation and shows on the terminal.
+ If no value is used, then the default is |show|.
+\end{description}
-This\sidenote{luaonly} can only be used with lualatex and shows some info about the
-current attributes.
\section{To-do}
@@ -1541,9 +1622,11 @@ current attributes.
\begin{itemize}
\item Add commands and keys to enable/disable the checks.
\item Check/extend the code for language tags.
-\item Think about math.
+\item Think about math (progress: examples using luamml, associated files exists).
\item Think about Links/Annotations
+ (progress: mostly done, see section~\ref{sec:link+annot} and the code in \pkg{l3pdffield})
\item Keys for alternative and actualtext. How to define the input encoding? Like in Accsupp?
+ (progress: keys are there, but encoding interface needs perhaps improving)
\item Check twocolumn documents
\item Examples
\item Write more Tests
@@ -1551,14 +1634,14 @@ current attributes.
\item Unicode
\item Hyphenation char
\item Think about included (tagged) \PDF{}. Can one handle them?
-\item Improve the documentation
+\item Improve the documentation (progress: it gets better)
\item Tag as proof of concept the documentation (nearly done)
-\item Document the code better
-\item Create dtx
+\item Document the code better (progress: mostly done)
+\item Create dtx (progress: done)
\item Find someone to check and improve the lua code
\item Move more things to lua in the luamode
\item Find someone to check and improve the rest of the code
-\item Check differences between \PDF{} versions 1.7 and 2.0.
+\item Check differences between \PDF{} versions 1.7 and 2.0. (progress: WIP, namespaces done)
\item bidi?
\end{itemize}