xerif

h1. Accessibiliy Features

{{>toc}}

h2. Activate Accessibility Features

Add @a11y@ to the @\documentclass@ options:

<pre><code>\documentclass[…,a11y]{cocotex}

</code></pre>

For PDF 2.0 use @a11y20@, instead.

Make sure that the "env.sh":https://github.com/transpect/xerif-latex/blob/main/env.sh (part of the "xerif-latex":https://github.com/transpect/xerif-latex/tree/main repo) is sourced or that the Makefile includes the parameters defined this script. This is necessary so TeX finds the lua files from the @ltpdfa@ package.

h2. Set main language

Add @lang-id=XXX@ to the documentclass options following "ISO 639-2":https://de.wikipedia.org/wiki/Liste_der_ISO-639-2-Codes, e.g. for German:

<pre><code>\documentclass[…,lang-id=deu]{cocotex}

</code></pre>

h2. Artifact tagging

Images and other contents that fulfill decorational purposes only must be tagged as artifacts to be ignored by reading software. This can be achieved as follows:

<pre><code class="tex">

\ccaStructStart{Artifact}Linie\ccaStructEnd{Artifact}

</code></pre>

* there exists also an environment that is not yet thoroughly tested:

<pre><code class="tex">

\begin{ccaArtifact}…\end{ccaArtifact}

</code></pre>

* consider tagging *decorational images*

* *writing lines* (if not tagged as forms)

* tbc

h2. Paragraph tagging

Until further notice, text paragraphs need to be tagged by the converter by adding @\ccaVstructStart{P}@ at the beginning of each paragraph (no whitespaces between the macro and subsequent text or other macros!) and @\ccaVstructEnd{P}@ at the end of each paragraph (no whitespaces before @\ccaVstructEnd@!):

<pre>

\ccaVstructStart{P}Ipsum Lorem … finis.\ccaVstructEnd{P}

</pre>

This must also be done in broader contexts that may(!) contain multiple paragraphs of plain text, like 

* footnotes, 

* captions, 

* bibliographic references, 

* list items, 

* quotations, 

* table cells or 

* abstracts. Which ones exactly varies from publisher style to publisher style, so if in doubt, ask your friendly neighborhood TeX developer.

h2. Alternative Texts

Figures and Math both need alternative texts.

h4. Figures

For figures, there are two ways to encode alt-text: the @alt@ Parameter in the optional argument of @\includegraphics@ (needs texlive > 2021), e.g.

<pre>\incudegraphics[...,alt={This is what the image file shows}]{image.png}</pre>

or as @\tpAltText@ inside the @tpFigure@ or @tpSubFloat@ environments:

<pre>\begin{tpFigure}

  \tpCaption{This is the caption}

  \tpAltText{This is the alt text. It MUST NOT be the same as the caption!}

  \tpFig{\includegraphics{image.png}}

\end{tpFigure}</pre>If both exist, the @alt@ in @\includegraphics@ takes precedence over the @\tpAltText@.

h4. Math

both inline and display style math needs alternative texts. This is done with the @\ccaAddAltText@ macro:

<pre><code class="tex">

\ccaStructStart{P}\begin{equation*}\ccaAddAltText{Z equals x minus mu divided by sigma}%

  \mathbf{Z}=\,\frac{\boldsymbol{x}-\mathbf{\mu }}{\mathbf{\sigma }}

\end{equation*}

\ccaStructStart{P}

</code></pre>

or, for inline math:

<pre><code class="tex">The Variable  \ccaStructStart{Formula}$x\addAltText{x}$\ccaStructEnd{Formula} means...</code></pre>

or

<pre><code class="tex">The Variable\(x\ccaAddAltText{alternative text}\).</code></pre>

(in @\(...)\@ the tagging is already included).

h2. XMP Meta Data

_(see [[XMP Meta Data]])_

h2. Colours and Embedded Images

h3. Output Intent and Embedded ICC Colour Profiles

By default, CoCoTeX puts **CMYK** as output intent, but this can be overridden with the @color-env@ class option:

<pre><code class="latex">\documentclass[…,color-env=<space>,…]{cocotex}</code></pre>The Value @<space>@ should be one of the values in the left column of the following table:

|_. @<space>@ |_. icc profile|

| @srgb@, @rgb@ |  IEC 61966-2.1 Default RGB colour space - sRGB |

| @cmy@, @cmyk@ | Coated FOGRA39 |

| @grey@, @gray@ | ISO Coated v2 - GREY 1c - (basICColor) |

| @natural@, @none@ | (gray) |

Publisher-wide colour profile can be set with the @profile@ Property of the @titlepage@ Container:<pre><code class="latex">\ccAddToType{Properties}{titlepage}{%

    \ccSetProperty{output-intent}{%

      profile=<path to .icc file>;%

      components=<number of colour components>;%

      identifier=<name of colour profile>%

  }}</code></pre>with the following values:

* @<path to .icc file>@ is the path to the icc colour profile relative to the .tex file, including the file extension.

* @<number of colour components>@ is the number of colour components, e.g., @3@ for RGB, @4@ for CMYK, etc.

* @<name of colour profile>@ is the name of the colour profile (default values correspond to the right column in above's table)

A custom .icc profile valid only for the current document can be embedded with the following Components inside the @tpMeta@ environment:<pre><code class="latex">\begin{tpMeta}

  …

  \tpIccProfileFile{<path to .icc file>}

  \tpIccComponents{<number of colour components>}

  \tpIccIdentifier{<name of colour profile>}

  …

\end{tpMeta}</code></pre>

h3. Image files

The colour spaces of embedded images **must match the Output Indent of the PDF file** for the latter to be PDF/A2-a compatible. 

A quick-and-dirty conversion can be done with imagemagick:<pre><code class="bash">magick <input>  -colorspace <color_space> -profile <path_to_icc> <output></code></pre>with

* @<input>@ the path to the input image

* @<color_space>@ the color space the image should be converted to (cmyk, rgb, etc)

* @<path_to_icc>@ the path to the icc profile that gets embedded into the image

* @<output>@ the name of the output image

h3. Custom Text Colours

Custom document colours get automatically converted to the Output Intent color space by LaTeX, so they may be defined with any color model. The following colour definitions are roughly equivalent:<pre><code class="latex">\definecolor{myblue}{HTML}{3527FF}

\definecolor{myblue}{RGB}{53,39,255}

\definecolor{myblue}{rgb}{0.21,0.15,1}

\definecolor{myblue}{cmyk}{0.79,0.85,0,0}</code></pre>

h2. Checking PDF/UA compliance on Linux

The main tool for validating the PDF/UA compliance of documents is the "PDF Accessibility Checker (PAC)":https://support.axes4.com/hc/de/articles/7371921627794-PDF-Accessibility-Checker-PAC-2024. Using it on Windows is rather straightforward but requires a few more steps to make it run on Linux. The following procedure has been tested successfully with Wine 7.0 and should work with later versions quite as well.

# Install <code>wine</code> and <code>winetricks</code> via your package manager. Ensure that it is at least Wine version 7.0.

# It is recommended to use a separate Wine prefix (i.e. a separate environment with its own configuration and installed Windows components/packages). To do so, issue <code>WINEPREFIX=~/.wine-pac wineboot --init</code>. The path <code>~/.wine_pac</code> is an example and may be replaced with a path to your liking.

# Install all fonts available for Wine (<code>corefonts</code> package won’t suffice) as well as .NET 4.8 by issuing <code>WINEPREFIX=~/.wine-pac winetricks --force dotnet48 allfonts</code>. The <code>--force</code> option is required, because <code>winetricks</code> will otherwise quit the installation with a warning, stating that the .NET 4.8 package may be broken since Wine release 5.0.

# After the installation routines of the aforementioned Windows software via Wine, you should now be able to run PAC via <code>WINEPREFIX=~/.wine-pac wine "/Path/to/your/PAC_directory/PAC.exe".