[pdftex] pdftex manual LaTeX conversion for 2024

[Ulrike Fischer]

Am Mon, 8 Jan 2024 16:53:00 -0700 schrieb Karl Berry:

> Hi Ulrike,
> 
>     I couldn't test everything as I'm missing some input files 
> 
> I made an error in the Makefile 

I didn't get so far to try a Makefile ;-).

I have no idea how to checkout the sources (I tried with tortoise
svn on https://tug.org/svn/pdftex/branches/stable/ but it errored
"Redirect cycle detected for URL") and was to lazy to download all
files one by one, so picked up only the tex and a few includes and
tried manually. 

 >     but it looks basically "taggable". 
> 
> I had tried it too, by adding:
> \DocumentMetadata{testphase={phase-III,firstaid}}
> before the \documentclass. Should I use a different command?

firstaid should not be needed, but I would add table as you have a
tabular.

\DocumentMetadata{testphase={phase-III,table}}

> 
> I got many warnings about
> Package tagpdf Warning: The structure Sect can not be closed.
> and other things, ending with a fatal error. I gave up. (My log attached.)

Well yes they are few errors that must be corrected but not many. I
could take a look if you want to do it (but due to the "testphase"
it is a bit experimental, so I don't know if it is good idea for the
general manual, perhaps a variant "pdftex-tagged"?).

> 
> By the way, the first warning is
>   Package hyperref Warning: Option 'ocgcolorlinks' is unknown or deprecated...
> but I don't specify that option; I suppose it's a hyperref default.
> Seems like some sort of hyperref/tagging clash. Maybe a candidate for
> firstaid?

I saw that too, it is small (harmless) bug in the generic driver. It
only appears because you are using a very old PDF version (1.3?).
Does that really make sense nowadays? Why not 1.7 or even 2.0?

> 
>     In both cases a \par is missing before the group is closed:
> 
> It's just a {verbatim} block. Is inserting such a
> unnecessary-for-normal-output \par going to be a requirement forever?
> That would be painful. Anyway, ok, I went ahead and inserted it.

LaTeX block environments (center, quote, verbatim, lists etc) test
if the following text is separated by a \par. So 

\end{verbatim}
following text

will *not* indent the following text, but this will:

\end{verbatim}

following text

This works with some \everypar-magic called "\@doendpe".

If you are using low-level grouping you are destroying this
mechanism. So this here will *not* suppress the indentation anymore:

\documentclass{article}
\begin{document}
text before
{\small
\begin{verbatim}
abc
\end{verbatim}
}
text after
\end{document}

Now without tagging you are only destroying the indentation test,
but tagging makes use of this mechanism too and gets more confused
and errors. This means that with tagging you should do such grouping
through LaTeX-environments, as their code take care to keep
\@doendpe alive:

text before
\begin{small}
\begin{verbatim}
abc
\end{verbatim}
\end{small}
text after

Or you should add a \par before closing the group (which will always
lead to indentation in the following text). 

As alternative you could use a hook to change the font:

\AddToHookNext{env/verbatim/begin}{\small} 

> \myverbatim just uses the standard command \verbatiminput. Why isn't
> that taggable as is? Being in a group seems immaterial in that case.
> Not that I know anything.

For the same reason as above: you are destroying the \@doendpe-magic
by the low-level grouping:

\def\myverbatiminput#1{\begingroup
\small
\openin0 = #1
\ifeof0 \errmessage{No verbatiminput file #1}\else\closein0 \fi
\verbatiminput{#1}%
\vspace{-\baselineskip}%
\endgroup}

 
>     The primitive \moveright /\hbox construction gives a faulty
>     structure. 
> 
> Yeah, not surprising. What do you suggest? I want the output to look
> right.  I just did the simplest thing that came to mind.  

Well I couldn't test what should came out. But it looks as if you
want

\hspace*{5pt}\includegraphics{...}

(There should never be a need to put a graphic inside a \hbox).

> 
> P.S. Is there a document/web page/q&a somewhere about "here are the
> errors you're likely to get when tagging, and here's what to do about
> them"?  

Not yet. But this is certainly we should do at some time (e.g. I
should write down the \@doendpe case, as that is quite frequent).

> I get errors with pretty much every real document, and I don't
> know what to do about them. I'm not going to research every error from
> scratch, nor do I want to bother you with every error, nor are the
> answers at all apparent.

You can always add a question at the github as issue or discussion
(https://github.com/latex3/tagging-project) or sent me a question.
Such feedback is important! We need to learn the typical problems so
that we can write the documents about "likely errors" ;-)

Ulrike