% language=us runpath=texruns:manuals/tagging

% todo: use concrete

\usemodule
% [abbreviations-logos,scite,math-verbatim] % math verbatim messes up text
  [abbreviations-logos,scite] % math verbatim messes up text

% \showframe

\setupbackend[format=pdf/ua-2]
\setuptagging[state=start]
% \nopdfcompression

\setupbodyfont
  [pagella,12pt]

\setuplayout
  [header=0pt,
   width=middle]

\setupheadertexts
  []

\setupfootertexts
  [chapter]
  [pagenumber]

\setupwhitespace
  [big]

\setuphead
  [chapter]
  [style=\bfc,
   interaction=all]

\setuphead
  [section]
  [style=\bfb]

\setuphead
  [subsection]
  [style=\bfa]

\setuphead
  [subsubsection]
  [style=\bf,
   after=]

\setuplist
  [interaction=all]

\setupdocument
  [before=\directsetup{document:titlepage}]

% The tag shape will be improved.

\startuseMPgraphic{titlepage}
    numeric n ;

    path p ; p :=
            (1,0)
        --- (5,0)
        ... (6,3)
        ... (4,4)
        --- (4,6)
        ... (3,7)
        ... (2,6)
        --- (2,4)
        ... (0,3)
        ... cycle
    ;

    for i=1 upto 21 :
        for j=1 upto 30 :
            draw image (
                fill
                    p
                    withcolor .7yellow ;
                fill
                    fullcircle shifted (3,6)
                    withcolor white ;
                n := -1 randomized 2 ;
                draw textext (
                    if n > 0.5 :
                        "\ttbf no\hskip.2em tag"
                    elseif n > 0 :
                        "\ttbf retag"
                    elseif n > -0.5 :
                        "\ttbf untag"
                    else :
                        "\ttbf tag"
                    fi
                ) ysized 3/2 shifted (3,3/2)
                    withcolor white ;
            ) rotated (-15 randomized 30)
                shifted (10i,10j) ;
        endfor ;
    endfor ;

    setbounds currentpicture to boundingbox currentpicture enlarged 3 ;

    addbackground withcolor .8blue ;

    currentpicture := currentpicture xysized(PaperWidth,PaperHeight) ;

    picture q[] ;

    q[1] := image (
        draw image (
            for i=1 upto 15 :
                for j=1 upto 14 :
                    fill
                        (fullsquare xyscaled (2,3))
                        shifted (3*i,4*j)
                    ;
                endfor ;
            endfor ;
        ) withcolor .7red ;
        draw image (
            for i=1 upto 15 :
                for j=1 upto 14 :
                    draw
                        textext("\ttbf MCID") rotated 90 xsized .8
                        shifted (3*i,4*j)
                    ;
                endfor ;
            endfor ;
        ) withcolor white ;
    )
      xsized .9PaperWidth
    ;

    q[2] := image (
        fill
            p
            withcolor .7green ;
        fill
            fullcircle shifted (3,6)
            withcolor white ;
        n := -1 randomized 2 ;
        draw textext ("\ttbf PDF")
            ysized 3/2 shifted (3,3/2)
            withcolor white ;
    )
      rotated -5
      xsized .25PaperWidth
    ;

    q[3] := image (
        fill
            p
            withcolor .7green ;
        fill
            fullcircle shifted (3,6)
            withcolor white ;
        n := -1 randomized 2 ;
        draw textext ("\ttbf tagged")
            ysized 3/2 shifted (3,3/2)
            withcolor white ;
    )
      rotated 5
      xsized .25PaperWidth
    ;

    q[1] := q[1]
        shifted -center topboundary q[1]
        shifted center topboundary currentpicture
        shifted (0,-PaperHeight/20)
    ;

    q[2] := q[2]
        shifted -center topboundary q[2]
        shifted center bottomboundary q[1]
        shifted (6.5PaperWidth/20,1.5PaperHeight/20)
    ;

    q[3] := q[3]
        shifted -center topboundary q[3]
        shifted center bottomboundary q[1]
        shifted (PaperWidth/20,1PaperHeight/20)
    ;

    draw q[1] withtransparency (1,.70) ;
    draw q[2] withtransparency (1,.85) ;
    draw q[3] withtransparency (1,.85) ;

\stopuseMPgraphic

\startsetups document:titlepage
    \startTEXpage
        \useMPgraphic{titlepage}
    \stopTEXpage
\stopsetups

\setuptyping[option=TEX]

\startdocument[title=foo]

\startchapter[title=Why do we tag]

Around 2010 tagged \PDF\ showed up in \CONTEXT. Apart from demonstrating that it
could be done it served little purpose because only full Acrobat could show a
structure tree and in the more than a decade afterwards no other viewer did
something with it. However for some users it was a necessity.

In 2024 we picked up on tagging because due to regulations (especially in higher
education) demands for tagged \PDF\ in the perspective of accessibility popped
up. We will not go into details here but just mention that we want to make sure
that users can meet these demands.

As of now (2024) we have little expectations when it comes to tagging. The
ongoing discussions about how to tag, how to interpret the specification, what to
validate, and what to expect from applications are likely to go on for a while,
so the best we can do is keep an eye on it and adapt when needed. If we have
opinions, these will be exposed in other documents (and articles).

We can also notice that the standard is less standard as things change, part as
side effect of clarification (which tells us something) but also because it looks
like some applications have problems with it. Working on this is disappointing
and dissatisfying, but often we have a good laugh about this mess, so we try to
keep up (adapt) anyway.

\startlines
Hans Hagen
Mikael Sundqvist
\stoplines

\stopchapter

\startchapter[title=Tagging text]

As mentioned in the introduction, we need to satisfy validators that are imposed
on those working in education (often via web interfaces with little information
on what actually gets checked, it's business after all). It is not that hard to
fool them and make documents compliant, so that is what we can do anyway. It is
also possible to let these tools do some auto tagging but our experiments showed
that this is a disaster. So, we end up with a mix of relatively rich tagging that
we feel good with. When we're a decade down the road we expect that with a little
help from large language models a decent verbose tagging is better than a crappy
suboptimal one.

One reason for tagging is that it could permit extraction but there are better
solutions to that: if there is something shown in a table or graphic, why not add
the dataset. We currently add \MATHML\ and \BIBTEX\ blobs but more can become
possible in the future (this also depends on user demand).

Another application is reflow but when that is needed, why not go \HTML\ or
distribute different output. When accessibility is the target one has to wait
till more is clear how that is actually supposed to work. Often the
recommendations are to use Arial, little color, simple sectioning etc, so that
gives little reason to use \PDF\ at all.

All that said, we assume that \PDF\ level 2 is used, if only because it looks
like validators aim for that. Also, if you find pre level 2 documents produced
elsewhere, often tagging is so bad or weird that one can as well ignore it.

You should realize that tagging is actually rather old, it was already available
in the early version. You can enable tagging with:

\starttyping
\setuptagging[state=start]
\stoptyping

This will give you basic tagging: directives in the page stream combined with
a structure tree. You can also decide to add mapping to \PDF\ specific tags. This
is done with:

\starttyping
\setupbackend[format=pdf/ua-2]
\setuptagging[state=start]
\stoptyping

The first command ensures that the right data ends up in the \PDF\ file, and the
second one enables tagging. As long as you're working on a document you can
comment these commands which saves you some runtime and give way smaller files.

We don't want to cripple proper structure \CONTEXT\ support by the limitations
introduced in \PDF\ version 2, but we do offer users some control, as long as it
does not backfire. Due to the fluid situation (around 2024) we delegate some
choices to the user. By default we use robust mapping (read: not sensitive for
limitations in nesting \PDF\ specific tags cf.\ checkers) but you can say this:

\starttyping
\setuptagging[preset=basic]
\stoptyping

The basic mapping is defined in \typ {lpdf-tag-imp-basic*} files and get and of
course define your own. The basic set works for a few complex documents we tried
but has to work around limitations. We have no clue how that works out in the
long term because (as mentioned) validation, standardization and whatever relates
are fluid. We still provide:

\starttyping
\setuptagging [preset=mkiv]
\stoptyping

you get the mapping used in \MKIV\ but that one fails level 2 validation. In due
time we might explain (re)mapping here in more detail. There are various features
controlled by directives but these mostly serve(d) testing.

\stopchapter

\startchapter[title=Interactivity]

By default we ignore references and links in the mapping. This because we found
it to be confusing, unreliable, limited and (some searching indicated) open to
interpretations and changes. It doesn't bring anything to the table anyway. In
\CONTEXT\ users can make advanced interactive documents; it was always a strong
point and for for some users a reason to use this system. If you really want
it to be taken into account, you can do this:

\starttyping
\setuptagging [option=interactivity]
\stoptyping

You might need to change your document if validation fails, for instance because
you add buttons and such in constructs that no one could envisage.

\stopchapter

\startchapter[title=Tagging math]

Tagging math at level 2 is still experimental but works as follows. Instead of
tagging the atoms and structures, as we do in level 1, we generate a \MATHML\
attachment and put a so called actual text on the math structure node. This text
can be spoken by reading machinery. The \MATHML\ is not that rich but we can enable
more detail when needed. However, given the way (presentational) \MATHML\ evolved
we are somewhat pessimistic. Instead of adding a few more elements that would
help to provide structure, some features are dropped. Also, support in browsers
comes and goes, either native or depending on \JAVASCRIPT.

Because there is much freedom in how mathematical symbols and constructs are
used, you might need to help math tagging bit. The process is driven by group
sets that refer to domains. An example of a domain is chemistry. For now we just
mention that this features is there and as time flies by we can expect more
granular usage.

\starttyping
\definemathgroupset
  [mydomain]
  [every] % a list of dictionaries

\setmathgroupset
  [mydomain]
\stoptyping

For now you can ignore these commands because we default to \type {every}.

{Todo: list all possible dictionaries.}

You can control the tagger by specifying what symbols and characters actually
mean, for instance:

\starttyping
\registermathfunction[𝑓]
\registermathfunction[𝑔]

% \registermathsymbol[default][en][𝐮][the vector]
% \registermathsymbol[default][en][𝐯][the vector]
% \registermathsymbol[default][en][𝖠][the matrix]

\registermathsymbol[default][en][lowercasebold]           [the vector] % [of]
\registermathsymbol[default][en][uppercasesansserifnormal][the matrix]
\stoptyping

From the language tag being used here you can deduce that this can be done per
language.

You can trace math translations with:

\starttyping
\setupnote[mathnote][location=page]
\enabletrackers[math.textblobs]
\stoptyping

which is what we used when developing these features. In a few hundred page math
book one easily gets thousands of notes.

In \type {examples-mathmeanings} you can find a lot of examples. In due time we
expect to offer more translations. The English and Swedish are for now the
benchmark. \footnote {As a proof of concept, at Bacho\TeX\ 2024, the Ukrain
translations were provided by Team Odessa, but they need some tuning.} Likely
other languages will be served by Tomáš Hala as result of courses on typesetting.
Feel free to contact all those involved in this.

\stopchapter

% time stamp next sections: Rendezvous Point - Presence, mid 2024 (a whow video too)

\startchapter[title=Structure]

Although today all goes to \PDF, that is not what \TEX\ macro packages started
with. Basically they just use the \TEX\ engine to render something in the
tradition of printing but using a target format that can be converted to
something that a printer understands. Nowadays that just happens to be \PDF.

So, although the target is \PDF, that doesn't mean that \PDF\ drives (or should
drive) the process. If we want what is called tagged \PDF\ where tagging
represents structure, one could argue that this is then a follow up on whatever
structure users used in the process. In \CONTEXT\ we start from the \TEX\ input
end, not from some tagging related \PDF\ wish list which could handicap us. So
called tagged \PDF\ is not the objective, it is just a possible byproduct.

Keep in mind that tagging related to structure serves a few purposes: reflow,
conversion, and accessibility. We're not at all interested in reflow of \PDF,
because is that a which one should just produce \HTML. We're also not interested
in conversion because, again, one could just use a different workflow, maybe one
that starts from \XML\ and can target different media. When it comes to
accessibility this mixed bag contains options like generating different versions,
each tuned to a specific target audience. Typesetting is about generating some
visual representation and just like people have different food preferences, one
can imagine different representations: there is no reason to only produce \PDF.
And even if there are ways to help something rendered for printing, or reading on
screen, for instance by providing audio, there is no need to do that for very
complex documents. Given the often poor quality of simple \TEX\ documents one can
even wonder if that tool should be used at al then. It's not like \TEX\ is the
only system that can do math nowadays.

When we look at structure, this is how \CONTEXT\ sees a section:

\starttyping[option=TEX]
\startchapter[title={This is a chapter.}
  \startsection[title={This is a section.}
    Some text here.
  \stopsection
\stopchapter
\stoptyping

In \XML\ that could be something like this with the number being optional as it
can be generated:

\starttyping[option=XML]
<section detail="chapter">
  <sectioncaption>
    <sectionnumber>1</sectionnumber>
    <sectiontitle>This is a chapter.</sectiontitle>
  </sectioncaption>
  <sectioncontent>
    <section detail="section">
      <sectioncaption>
        <sectionnumber>1.2</sectionnumber>
        <sectiontitle>This is a section.</sectiontitle>
      </sectioncaption>
      <sectioncontent>
        Some text here.
      </sectioncontent>
    </section>
  </sectioncontent>
</section>
\stoptyping

In a \PDF\ there can also be additional rendered material, like headers and
footers and maybe the section title is rendered in a special way but we ignore
that for now.

When I comes to the content blob, we have to look at the \TEX\ end. User input
normally will give this:

\starttyping[option=XML]
<sectioncontent>
  A first paragraph.

  A second paragraph.
</sectioncontent>
\stoptyping

An empty line starts a paragraph but it can also be explicitly forced (think
\type {\par}).

\starttyping[option=XML]
<sectioncontent>
  A first paragraph.
  <break/>
  A second paragraph.
</sectioncontent>
\stoptyping

But one can also explicit encode paragraphs and then get:

\starttyping[option=XML]
<sectioncontent>
  <paragraph>A first paragraph.</paragraph>
  <paragraph>A second paragraph.</paragraph>
</sectioncontent>
\stoptyping

which in \TEX\ speak is:

\starttyping[option=TEX]
\startchapter[title={This is a chapter.}
  \startsection[title={This is a section.}
    \startparagraph A first paragraph.  \stopparagraph
    \startparagraph A second paragraph. \stopparagraph
  \stopsection
\stopchapter
\stoptyping

But it will be clear that not all users want to do that, which means that we end
up with the \type {<break/>} variant. Now you can ask, why not infer this extra
level of structure and the answer is: it's not how \TEX\ works. The content can
be anything and the fact that there is no real clear solution is actually
reflected in how \PDF\ tagging maps onto pseudo \HTML\ elements: not all can
nest, so for instance a paragraph cannot contain a paragraph. That means that we
cannot reliable add that level of structure automatically as it limits the
degrees of freedom that users have. As mentioned: tagging in \PDF\ is not the
starting point, just a possible byproduct.

Let's look at another structure element:

\starttyping[option=TEX]
\startitemize
  \startitem A first item. \stopitem
  \startitem
    A second item.
    \startitemize
      \startitem Again first item. \stopitem
      \startitem And a last one. \stopitem
    \stopitemize
  \stopitem
  \startitem A third item. \stopitem
\stopitemize
\stoptyping

If we start from input, we can use this kind of \XML:

\starttyping[option=XML]
<itemize>
  <item>A first item.</item>
  <item>
    A second item.
    <itemize>
      <item>Again a first item.</item>
      <item>And a last one.</item>
    </itemize>
  </item>
  <item>A third item.</item>
</itemize>
\stoptyping

But once we're done, we actually have something typeset, so we end up with more detail:

\starttyping[option=XML]
<itemgroup>
  <item>
    <itemtag>1.</itemtag>
    <itemcontent>
      <itemhead/>
      <itembody>A first item.</itembody>
    </itemcontent>
  </item>
  <item>
    <itemtag>2.</itemtag>
    <itemcontent>
      <itemhead/>
      <itembody>
        A second item.
        <itemgroup>
          <item>
            <itemtag>a.</itemtag>
            <itemcontent>
               <itemhead/>
               <itembody>Again a first item.</itembody>
            </itemcontent>
          </item>
          <item>
            <itemtag>b.</itemtag>
            <itemcontent>
              <itemhead/>
              <itembody>And a last one.</itembody>
            </itemcontent>
          </item>
        </itemgroup>
      </itembody>
    </itemcontent>
  </item>
  <itemtag>3.</itemtag>
  <itemcontent>
    <itemhead/>
    <itembody>
      A third item.
    </itembody>
  </itemcontent>
</itemgroup>
\stoptyping

This represents what gets rendered but one can leave out the tag and let whatever
interprets this deal with that.

So, we have input that can be either explicit (given numbers and tags) or
implicit (the system generates them) but output can also be explicit or implicit.
And when output carries structure the question is: do we want to preserve
abstraction or do we want the rendered results. It only makes sense to invest in
this when it pays off, also because the resulting \PDF\ file get bloated a lot.

\stopchapter

\startchapter[title=PDF]

The specification (say the second edition of 2020) has a section about tagged
\PDF\ in the perspective of reflow, conversion and accessibility. As we mentioned
already the lack of tools using any of this didn't help much in clarifying all
this. At some point it became possible to verify a \PDF\ file and some
rudimentary converters popped up but it looks like everyone had to interpret the
rules laid out in the specification. Mid 2024 we also had numerous errata
and|/|or clarifications of the specification (not only tagging) but (at least for
us) it is not clear what criteria for changes (more restrictions) were.

For instance, the ISO 32000-2 specification explicitly mentions the usefulness of
the \type {H} mapping for classes of documents. But in ISO 14289-2:2024 we can
read \quotation {The \type {H} structure type requires processors to track
section depth, which adds an unnecessary burden on processors and can cause
ambiguity.} This is a quite baffling remark given the complexity of \PDF\ and web
technologies in general. So in the end it was dropped in order to make some
developers lives easier, while complicating that of others.

It is this, and other vague (and changing) descriptions, take for instance \type
{Part} and \type {Sect}, that made us decide to draw a line. We tried some in our
opinion reasonable variants but could never satisfy the validators completely.
Keep in mind that we started from tagging everything, not just the easy bits and
pieces and then wrapping whatever left in artifacts or a wildcard paragraph. When
we looked at tagging with 2024 glasses on we were willing to adapt but in the end
it makes little sense. We can add a few mappings but in general it is too
conflicting with our approach to structure, one that goes back decades. So, as
long as a (audio) reader can do a reasonable job, we're okay. There are more
interesting challenges on our plates anyway.

\stopchapter

\startchapter[title=Tracing]

There are a few trackers that relate to tagging but these are more for ourselves
so we just mention them:

\starttyping
\enabletrackers[structures.tags]
\enabletrackers[structures.tags.info]
\enabletrackers[structures.tags.math]
\enabletrackers[structures.tags.blobs]
\enabletrackers[structures.tags.internals]
\enabletrackers[structures.tags.suspects]
\enabletrackers[structures.tags.attribute]
\enabletrackers[structures.tags.paragraphs]
\enabletrackers[structures.tags.objects]
\stoptyping

The first few are probably the most useful as it shows how \CONTEXT\ sees the
structure of your document. Others are there because they help figuring out
issues.

We also have a script that can help checking:

\starttyping
mtxrun --script pdf --validate yourfile
\stoptyping

This will use (currently only) verapdf to check the file and show a summary.
Another feature is:

\starttyping
mtxrun --script pdf --structure yourfile  [--details --save]
\stoptyping

and both can be done in one step with:

\starttyping
mtxrun --script pdf --check yourfile
\stoptyping

When you tag a document, best do that as late as possible because it adds runtime
and checking doesn't really help much when writing something. You might want to
put the setup in a mode so that you can enable it from the command line. The
documents also become way bigger. And, if you really care about accessibility,
consider making two versions: one that suits your typographic needs, and one that
targets the audience that needs accessibility. And, for printed documents, you
can just ignore it.

\stopchapter

\stopdocument
