| 1 |
|
| 2 |
\input minim-doc.sty |
| 3 |
|
| 4 |
\manual{minim-pdf} |
| 5 |
|
| 6 |
\ifchapter \chapter Hypertext |
| 7 |
|
| 8 |
This chapter and the next document the support of the modern pdf features |
| 9 |
provided by the minim-pdf package. |
| 10 |
Load it by saying ⟦\input minim-pdf⟧. |
| 11 |
The next chapter concerns the creation of tagged pdf; |
| 12 |
all other features of the package are described here. |
| 13 |
|
| 14 |
\else \startmetadata |
| 15 |
author {Esger Renkema} |
| 16 |
title {minim-pdf} |
| 17 |
date {2025-02-22} |
| 18 |
version {2025/1.7} |
| 19 |
keywords {LuaTeX; Plain TeX; PDF/A; Tagged PDF; accessibility; a11y; |
| 20 |
hypertext; bookmarks; document outline; associated files} |
| 21 |
stopmetadata |
| 22 |
\maketitle |
| 23 |
|
| 24 |
This package adds low-level support to plain luatex for marking up the |
| 25 |
structure of a pdf document. The implementation is rather basic, but should |
| 26 |
allow you to make your pdfs fully pdf/a-compliant. |
| 27 |
Load the package by saying ⟦\input minim-pdf⟧. |
| 28 |
|
| 29 |
The creation of tagged pdf will be described in the second half of this manual; |
| 30 |
all other features will be covered first. |
| 31 |
|
| 32 |
\fi |
| 33 |
|
| 34 |
\section Hyperlinks %1 |
| 35 |
|
| 36 |
Hyperlinks can be made with |
| 37 |
⟦*\hyperlink [alt {...}] [attr {...}] <action> ... \endlink⟧, where the |
| 38 |
⟦<action>⟧ must be one of |
| 39 |
⟦name {...} | url {...} | name {...} | next | prev | first | last⟧ |
| 40 |
With the ⟦name⟧ action, a named destination must be used (see below), while the |
| 41 |
⟦user⟧ action will be passed directly to the back-end (as with the pdftex |
| 42 |
primitive). |
| 43 |
After the ⟦url⟧ action, the characters \Uchar`\~, \# and \% need not be escaped. |
| 44 |
(Of course, this does nothing for already-tokenised text; be aware of this when |
| 45 |
you wrap ⟦\hyperlink⟧ into another macro.) |
| 46 |
Any spaces after the ⟦<action>⟧ will be ignored. |
| 47 |
|
| 48 |
The ⟦*\hyperlinkstyle⟧ token list can be used so set common (pdf) link |
| 49 |
attributes; it defaults to ⟦/Border [0 0 0]⟧. The contents of the optional |
| 50 |
⟦attr⟧ parameter will be appended to these. |
| 51 |
The ⟦alt⟧ options sets the ⟦/Contents⟧ key that is required by PDF/UA (where it |
| 52 |
has the purpose of an alt text). |
| 53 |
|
| 54 |
A named destination can be created with ⟦*\nameddestination {...}⟧ (also in |
| 55 |
horizontal mode, unlike the backend primitive) and if you cannot think of |
| 56 |
a name, ⟦*\newdestinationname⟧ should generate a unique one. |
| 57 |
If you need the latter twice, ⟦*\lastdestinationname⟧ gives the last |
| 58 |
generated name. |
| 59 |
|
| 60 |
|
| 61 |
\section Bookmarks %1 |
| 62 |
|
| 63 |
Bookmarks (also known as outlines) can be added with |
| 64 |
⟦*\outline [level n] [open|closed] [dest {name}] {title}⟧. |
| 65 |
Add ⟦open⟧ or ⟦closed⟧ to have the bookmark appear initially open or closed |
| 66 |
(the default), and |
| 67 |
say ⟦dest {name}⟧ for having it refer to a specific named destination |
| 68 |
(otherwise, a new one will be created where the ⟦\outline⟧ command appears). |
| 69 |
|
| 70 |
In the absence of the ⟦level⟧ option, the bookmark is automatically associated |
| 71 |
with the current structure element and the hierarchy of structure elements |
| 72 |
determines the nesting of bookmarks. This works even if you have otherwise |
| 73 |
disabled tagging and is the recommended way of generating outlines. |
| 74 |
(You can find all relevant macros in next chapter under ‘Document structure’ |
| 75 |
and ‘Structure element aliases’.) |
| 76 |
|
| 77 |
As a fallback, outlines specified with the ⟦level n⟧ option will be inserted at |
| 78 |
the end of the current outline list at the specified level (${\tt n}≥1$ and |
| 79 |
need not be contiguous). Both methods can be intertwined, but please use the |
| 80 |
document structure if you can. |
| 81 |
|
| 82 |
|
| 83 |
\section Page labels %1 |
| 84 |
|
| 85 |
If the page numbers of your document are not a simple sequence starting with~1, |
| 86 |
you can use ⟦*\setpagelabels [pre {prefix}] style nr⟧ for communicating |
| 87 |
this to the pdf viewer. |
| 88 |
This command affects the page labels from the next page on: ⟦nr⟧ should be the |
| 89 |
numerical page number of that page. |
| 90 |
The ⟦prefix⟧ is prepended to each number and the |
| 91 |
⟦style⟧ must be one of ⟦decimal⟧, ⟦roman⟧, ⟦Roman⟧, ⟦alphabetic⟧, ⟦Alphabetic⟧ |
| 92 |
or ⟦none⟧. In the last case, only the prefix is used. |
| 93 |
|
| 94 |
|
| 95 |
\section PDF/A %1 |
| 96 |
|
| 97 |
You can declare pdf/a conformance with ⟦*\pdfalevel xy⟧, with version $\tt |
| 98 |
x ∈ \{1,2,3\}$ and conformance level $\tt y ∈ \{a,b,u\}$. This will set the |
| 99 |
correct pdf version and ⟦pdfaid⟧ metadata. If the conformance level is ‘⟦a⟧’, |
| 100 |
tagging will be enabled (see the next chapter). Finally, a default RGB colour |
| 101 |
profile will be included. |
| 102 |
The conformance level can be queried from the ⟦*\pdfaconformancelevel⟧ register. |
| 103 |
|
| 104 |
Note that merely declaring conformance will not make your document pdf/a |
| 105 |
compliant, and that minim will not warn you if it is not. |
| 106 |
However, the features described in this chapter and the next should be enough |
| 107 |
to make pdf/a compliance possible. |
| 108 |
|
| 109 |
Also note that there currently is no documented way of choosing a different |
| 110 |
colour profile from the default (i.e. the default rgb profile provided by the |
| 111 |
colorprofiles package). |
| 112 |
Should you need do that, you will have to do so manually, after |
| 113 |
disabling the automatic inclusion by saying |
| 114 |
⟦\expandafter\let \csname minim:default:rgb:profile\endcsname = \relax⟧. |
| 115 |
|
| 116 |
Finally, note that pdf/a requires that spaces are represented by actual space |
| 117 |
characters and that discretionary hyphens are marked as soft hyphens |
| 118 |
(⟦U+00AD⟧). |
| 119 |
Since both features benefit accessibility and text extraction in general, they |
| 120 |
are enabled by default. |
| 121 |
You can disable them by setting ⟦*\writehyphensandspaces⟧ to a nonpositive value. |
| 122 |
|
| 123 |
|
| 124 |
\section PDF/UA %1 |
| 125 |
|
| 126 |
You can claim pdf/ua conformance with ⟦*\pdfualevel 1⟧. |
| 127 |
By itself, this will do very little: |
| 128 |
|
| 129 |
\startlist |
| 130 |
\tagattribute List ListNumbering /Decimal |
| 131 |
\item 1. The ⟦pdfuaid:part⟧ metadata key will be set. |
| 132 |
\item 2. A conforming ⟦ViewerPreferences⟧ dictionary will be added to the document catalog. |
| 133 |
\item 3. The ⟦/Suspects⟧ key of the ⟦MarkInfo⟧ dictionary will be set to ⟦false⟧. |
| 134 |
\item 4. ⟦/Tab /S⟧ will be added to the page attributes. |
| 135 |
\stoplist |
| 136 |
|
| 137 |
Also making your document pdf/a-compliant, however, will relieve you of a few |
| 138 |
additional worries: |
| 139 |
|
| 140 |
\startlist |
| 141 |
\tagattribute List ListNumbering /Decimal |
| 142 |
\tagattribute List ContinuedList true |
| 143 |
\item 5. Fonts will be included properly. |
| 144 |
\item 6. The (natural) language of every element will be known. |
| 145 |
\item 7. Headings will be strongly-structured. |
| 146 |
\item 8. Table headers will have their ⟦Scope⟧ set properly. |
| 147 |
\item 9. A document outline will be generated automatically. |
| 148 |
\stoplist |
| 149 |
|
| 150 |
This leaves the following for you to provide before your document can be |
| 151 |
pdf/ua-compliant: |
| 152 |
|
| 153 |
\startlist |
| 154 |
\tagattribute List ListNumbering /Decimal |
| 155 |
\tagattribute List ContinuedList true |
| 156 |
\item 10. Figure and Formula structure elements must have alt texts. |
| 157 |
\item 11. Hyperlinks must have alternate descriptions. |
| 158 |
\item 12. Lists must have the ⟦ListNumbering⟧ attribute set. |
| 159 |
\item 13. Tables must have headers that are tagged as such. |
| 160 |
\item 14. Page headers and footers must be marked as header or footer artifacts. |
| 161 |
\item 15. Document section structure elements should have their ⟦title⟧ set. |
| 162 |
\item 16. All embedded files must have a description. |
| 163 |
\stoplist |
| 164 |
|
| 165 |
|
| 166 |
\section Embedded files %1 |
| 167 |
|
| 168 |
You can attach (associate) files with ⟦*\embedfile <options>⟧. |
| 169 |
The file will be attached to the current structure element (see the next |
| 170 |
chapter) unless the ⟦global⟧ option is given: then it will be added to the |
| 171 |
document catalog. |
| 172 |
Arguments consisting of a single word can be given without braces and |
| 173 |
exactly one of the options ⟦file⟧ or ⟦string⟧ must be present. |
| 174 |
|
| 175 |
\smallskip\marktableaslist |
| 176 |
\tagattribute List ListNumbering /Description |
| 177 |
\halign{#\quad\hfil&#\hfil\cr |
| 178 |
⟦file ⟧\hfill⟦{...}⟧ & The file to embed.\cr |
| 179 |
⟦string ⟧\hfill⟦{...}⟧ & The string to embed.\cr |
| 180 |
⟦global⟧ & Attach to the document catalog.\cr |
| 181 |
⟦uncompressed⟧ & Do not compress the file stream.\cr |
| 182 |
⟦mimetype ⟧\hfill⟦{...}⟧ & The file’s mime type.\cr |
| 183 |
⟦moddate ⟧\hfill⟦{...}⟧\rlap{*} & The modification date (see * below).\cr |
| 184 |
⟦desc ⟧\hfill⟦{...}⟧ & A description (the ⟦/Desc⟧ key).\cr |
| 185 |
⟦relation ⟧\hfill⟦{...}⟧ & The ⟦/AFRelationship⟧ value as defined in pdf/a-3.\cr |
| 186 |
⟦name ⟧\hfill⟦{...}⟧ & The file name (only required when writing a ⟦string⟧).\cr } |
| 187 |
|
| 188 |
* The modification date must be of the form ⟦yyyy[-m[m][-d[d]]]⟧. A default |
| 189 |
moddate can be set with ⟦*\setembeddedfilesmoddate {default}⟧. |
| 190 |
The ⟦default⟧ date will be expanded fully at the time of embedding. |
| 191 |
With the minim-xmp package, a useful setting is |
| 192 |
⟦\setembeddedfilesmoddate {\getmetadata date}⟧. |
| 193 |
|
| 194 |
\section Lua module %1 |
| 195 |
|
| 196 |
The interface of the lua module (available via |
| 197 |
⟦local M = require('minim-pdf')⟧) should be stable by now. |
| 198 |
Though it contains lua equivalents for most tex commands described here, using |
| 199 |
them directly is not very ergonomical and not recommended. |
| 200 |
Please consult the source if you do want to use them anyway. |
| 201 |
|
| 202 |
% |
| 203 |
|
| 204 |
\chapter Tagged PDF |
| 205 |
|
| 206 |
This chapter is a continuation of the previous and describes the parts of |
| 207 |
minim-pdf that concern the creation of tagged pdf. All features in this chapter |
| 208 |
must be explicitly enabled by setting ⟦*\writedocumentstructure⟧ to a positive |
| 209 |
value. This will be done automatically if you declare pdf/a conformance (see |
| 210 |
above). |
| 211 |
|
| 212 |
This part of the package is rather low-level and this chapter rather technical. |
| 213 |
For a more general introduction to and discussion of tagged pdf, please read |
| 214 |
the (excellent) manual of latex’s tagpdf package. |
| 215 |
|
| 216 |
|
| 217 |
\section Quick-start guide % 1 |
| 218 |
|
| 219 |
The minimal setup for producing tagged pdf from plain tex documents is |
| 220 |
something like the following: |
| 221 |
|
| 222 |
⟦% first update all fonts to TrueType (ttf) or OpenType (otf) |
| 223 |
\input luaotfload.sty |
| 224 |
% ... font redefinitions omitted ... |
| 225 |
\input minim-mp |
| 226 |
\pdfalevel 2a % declare pdf/a conformance, enable tagging |
| 227 |
\autotagplainoutput % update the output routine |
| 228 |
% create section markers and counters |
| 229 |
\sectionstructure { subsection, section, chapter }⟧ |
| 230 |
|
| 231 |
You can then update your sectioning macros to look like this: |
| 232 |
|
| 233 |
⟦\def\section#1\par{% |
| 234 |
% space above |
| 235 |
\bigskip \goodbreak |
| 236 |
% structure and outline (this is the new part) |
| 237 |
\marksection \outline open {#1} |
| 238 |
% section header |
| 239 |
\noindent {\bf \the\chapternr.\the\sectionnr. #1} |
| 240 |
% space below |
| 241 |
\smallskip \noindent}⟧ |
| 242 |
|
| 243 |
Other macros you might have for laying out structural elements, such as tables |
| 244 |
or lists, should of course also be updated. The rest of this chapter describes |
| 245 |
the tools you can use. |
| 246 |
|
| 247 |
Please be advised that producing tagged pdf will likely forever remain |
| 248 |
a fragile and error-prone process. |
| 249 |
You should always validate the resulting pdf. |
| 250 |
An easy-to-use and free validator is \hyperlink alt {The veraPDF website.} |
| 251 |
url {https://verapdf.org/home}veraPDF\endlink. |
| 252 |
For inspecting the document structure, you can use the ⟦pdfinfo⟧ utility that |
| 253 |
comes with the \hyperlink alt {The Poppler website.} |
| 254 |
url {https://poppler.freedesktop.org/}Poppler\endlink\ pdf library. |
| 255 |
|
| 256 |
|
| 257 |
\section Purpose, limitations and pitfalls %1 |
| 258 |
|
| 259 |
The main purpose of this package is semi-automatically marking up the |
| 260 |
(hierarchical) structure of your document, thereby creating so-called tagged pdf. |
| 261 |
The mechanism presented here is not quite as versatile as the pdf format |
| 262 |
allows. The most important restriction is that all content of the document must |
| 263 |
be seen by tex’s stomach in the \emph{logical} order. |
| 264 |
|
| 265 |
Furthermore, while the macros in this package are sophisticated enough that |
| 266 |
tagging can be done without any manual intervantion, it is quite possible and |
| 267 |
rather easy to generate the wrong document structure, or even cause syntax |
| 268 |
errors in the resulting pdf code. |
| 269 |
You should always inspect and validate the result. |
| 270 |
|
| 271 |
This is the full list of limitations, pitfalls and shortcomings: |
| 272 |
\startlist |
| 273 |
\tagattribute List ListNumbering /Decimal |
| 274 |
\item1. Document content must be seen by tex in its logical order (although you |
| 275 |
can mark out-of-order content explicitly if you know what you are doing; see |
| 276 |
below). |
| 277 |
\item2. The contents of ⟦\localleftbox⟧ and ⟦\localrightbox⟧ must be marked |
| 278 |
manually, probably as artifact. |
| 279 |
\item3. There currently is no way of marking xforms or other pdf objects as |
| 280 |
content items of themselves. |
| 281 |
\item4. The content of xforms (i.e. pdf objects created by ⟦\useboxresource⟧) |
| 282 |
should not contain tagging commands. |
| 283 |
\item5. Likewise, you should be careful with box reuse: it might work, but you |
| 284 |
should check. |
| 285 |
\item6. This package currently only supports pdf~1.7 tagging and is not yet |
| 286 |
ready for use with pdf~2.0. |
| 287 |
\stoplist |
| 288 |
|
| 289 |
In order to help you debugging, some errors will refer you to the resulting pdf |
| 290 |
file. If you get such errors, decompress the pdf and search for the string |
| 291 |
‘Warning:’. It will appear in the pdf stream at the exact spot the problem |
| 292 |
occurs. |
| 293 |
|
| 294 |
|
| 295 |
\section General overview %1 |
| 296 |
|
| 297 |
When speaking about tagging, we have to do with two (or perhaps three) separate |
| 298 |
and orthogonal tagging processes. |
| 299 |
The first is the creation of a hierarchical \emph{document structure}, made up |
| 300 |
of \emph{structure elements} (SEs). The document structure describes the |
| 301 |
logical structure of a document, made up of chapters, paragraphs, references |
| 302 |
etc. |
| 303 |
The second tagging process is the tagging of \emph{marked content items} |
| 304 |
(MCIs): this is the partition of the actual page contents into (disjoint) |
| 305 |
blocks that can be assigned to the proper structure element. |
| 306 |
Finally, as a separate process, some parts of the page can be marked as |
| 307 |
\emph{artifacts}, excluding their content from both content and structure |
| 308 |
tagging. |
| 309 |
|
| 310 |
When using this package, artifacts and structure elements (excluding |
| 311 |
paragraphs; see below) must be marked explicitly, while marked content items |
| 312 |
will be created, marked and assigned automatically. |
| 313 |
There is some (partial and optional) logic for automatically arranging |
| 314 |
structure elements in their correct hierarchical relation. |
| 315 |
|
| 316 |
The mechanism through which this is achieved uses attributes and whatsits for |
| 317 |
marking the contents and borders of SEs, MCIs and artifacts. At the end of the |
| 318 |
output routine, just before the pdf page is assembled, this information will be |
| 319 |
converted into markers inserted in the pdf stream. |
| 320 |
|
| 321 |
|
| 322 |
\section Marked content items %1 |
| 323 |
|
| 324 |
Content items are automatically delineated at page, artifact and structure |
| 325 |
element boundaries and terminated at paragraph or display skips. |
| 326 |
This should relieve you from any manual intervention. However, if you run into |
| 327 |
problems, the commands below might be helpful. |
| 328 |
|
| 329 |
Use of ⟦ActualText⟧, ⟦Alt⟧ or ⟦Lang⟧ attribute on MCIs, while allowed by the |
| 330 |
pdf standard, is not supported by this package. You should set these on the |
| 331 |
structure element instead. |
| 332 |
|
| 333 |
The beginning and ending of a content item can be forced with |
| 334 |
⟦*\startcontentitem⟧ and ⟦*\stopcontentitem⟧, while ⟦*\ensurecontentitem⟧ will |
| 335 |
only open a new content item if you are currently outside any. |
| 336 |
If you need some part to be a single content item, you can use |
| 337 |
⟦*\startsinglecontentitem ... \stopsinglecontentitem⟧. |
| 338 |
This will disable all SE and MCI tagging inside. |
| 339 |
|
| 340 |
Tagging (both of MCIs and SEs) can be disabled and re-enabled locally with |
| 341 |
⟦*\stoptagging⟧ and ⟦*\starttagging⟧. |
| 342 |
|
| 343 |
|
| 344 |
\section Artifacts %1 |
| 345 |
|
| 346 |
Artifacts can be marked in two ways: with ⟦*\markartifact {type} {...}⟧ or with |
| 347 |
⟦*\startartifact {type} ... \stopartifact⟧. |
| 348 |
The ⟦type⟧ is written to the pdf attribute dictionary directly, so that if you |
| 349 |
need a subtype, you can write e.g. |
| 350 |
⟦\startartifact {Pagination /Subtype/Header} etc⟧. |
| 351 |
|
| 352 |
Inside artifacts, other structure content markers will be ignored. Furthermore, |
| 353 |
this package makes sure artifacts are never part of marked content items, |
| 354 |
automatically closing and re-opening content items before and after the |
| 355 |
artifact. |
| 356 |
While the pdf standard does not require the latter, not enforcing this seems to |
| 357 |
confuse some pdf software. |
| 358 |
|
| 359 |
|
| 360 |
\section Document structure %1 |
| 361 |
|
| 362 |
Like artifacts, structure elements can be given as ⟦*\markelement {Tag} {...}⟧ |
| 363 |
or ⟦*\startelement {Tag} ... \stopelement {Tag}⟧. |
| 364 |
Here, in many cases the ⟦\stopelement⟧ is optional: whenever opening an element |
| 365 |
would cause a nesting of incompatible ⟦Tag⟧s, the current element will be |
| 366 |
closed until such a nesting is possible. |
| 367 |
Thus, opening a ⟦TR⟧ will close the previous ⟦TR⟧, opening an ⟦H1⟧ will |
| 368 |
automatically close any open inline or block structure elements, opening |
| 369 |
a ⟦TOCI⟧ will close all elements up until the current ⟦TOC⟧ etc. etc. |
| 370 |
|
| 371 |
As a special case, the tags ⟦Document⟧, ⟦Part⟧, ⟦Art⟧, ⟦Sect⟧ and ⟦Div⟧ (and |
| 372 |
their aliases) will try and close all open structure elements up to and |
| 373 |
including the last structure element with the same tag. |
| 374 |
(An alias will of course only match the same alias.) |
| 375 |
|
| 376 |
While the above can greatly reduce the effort of tagging, the logic is neither |
| 377 |
perfect nor complete. You should always check the results in an external |
| 378 |
application. |
| 379 |
Particular care should be taken when ‘skipping’ structure levels: the sequence |
| 380 |
chapter – subsection – section will result in the section beneath the subsection. |
| 381 |
If you are in doubt whether an element has been closed already, you can use |
| 382 |
⟦*\ensurestopelement {Tag}⟧ instead of ⟦\stopelement⟧ |
| 383 |
to prevent an error being raised. |
| 384 |
|
| 385 |
All these helpful features can be disabled by setting |
| 386 |
⟦*\strictstructuretagging⟧ to a positive value. Then, every structure element |
| 387 |
will have to be closed by an explicit closing tag, as in xml. |
| 388 |
In this case, ⟦\stopelement⟧ and ⟦\ensurestopelement⟧ will be equivalent. |
| 389 |
|
| 390 |
You can query the place in the document structure of any point with |
| 391 |
⟦*\showdocumentstructure⟧. |
| 392 |
|
| 393 |
|
| 394 |
\section Structure element aliases %1 |
| 395 |
|
| 396 |
New structure element tags can be created with |
| 397 |
⟦*\addstructuretype [options] Existing Alias⟧. |
| 398 |
This will create a new structure tag named ⟦Alias⟧ with the same properties as |
| 399 |
⟦Existing⟧. |
| 400 |
The properties can be modified by specifying ⟦options⟧: these will set values |
| 401 |
of the corresponding entry in the ⟦structure_types⟧ table (see the lua source |
| 402 |
file for this package). |
| 403 |
Any aliases you declare will be written to the pdf’s ⟦RoleMap⟧ only if they |
| 404 |
have actually been used. |
| 405 |
|
| 406 |
|
| 407 |
\section Automatic tagging of paragraphs %1 |
| 408 |
|
| 409 |
By default, ⟦P⟧ structure elements are inserted automatically at the start of |
| 410 |
every paragraph. The tag can be changed with ⟦*\nextpartag {Tag}⟧; leaving the |
| 411 |
argument empty will prevent marking the next paragraph. |
| 412 |
Keep in mind that the (internal) reassignment is local: if a paragraph marked |
| 413 |
with ⟦\nextpartag⟧ starts inside a group, it will not reset. |
| 414 |
Hence, to avoid surprises, you should have ⟦\nextpartag⟧ and the start of your |
| 415 |
paragraph at the same grouping level. |
| 416 |
|
| 417 |
Useful structure elements for ⟦\nextpartag⟧ include ⟦H⟧ for headings and ⟦LI⟧ |
| 418 |
for list items. Since minim-pdf produces strongly-structured documents, the |
| 419 |
tags ⟦H1⟧, ⟦H2⟧, ⟦H3⟧ etc. should not be used. |
| 420 |
|
| 421 |
Please also note that if you add ⟦\hbox⟧es directly to a vertical list |
| 422 |
(this includes ⟦\line⟧, ⟦\centerline⟧ and the like), |
| 423 |
the ⟦\everypar⟧ token list is not inserted and no new paragraph structure element |
| 424 |
will be opened. |
| 425 |
The contents of the ⟦\hbox⟧ will be added to the current structure element, and |
| 426 |
this may result in an invalid structure hierarchy (and an error messsage |
| 427 |
reading ‘Structure type mismatch’). |
| 428 |
You can make your intentions clear by inserting ⟦\startelement{P}⟧ at the |
| 429 |
appropriate place (see above). |
| 430 |
|
| 431 |
Auto-marking paragraphs can be (locally) disabled or enabled by saying |
| 432 |
⟦*\markparagraphsfalse⟧ or ⟦*\markparagraphstrue⟧. |
| 433 |
|
| 434 |
\section Manipulating the logical order %1 |
| 435 |
|
| 436 |
With the process outlined above, the logical order of structure elements has to |
| 437 |
coincide with the order in which the SEs are ‘digested’ by tex. |
| 438 |
This, together with the marked content items being assigned to structure |
| 439 |
elements in their order of appearance, lies behind the restriction that logical |
| 440 |
and processing orders should match. |
| 441 |
|
| 442 |
With manual intervention, this restriction can be relaxed somewhat. |
| 443 |
Issuing the pair ⟦*\savecurrentelement ... \continueelement⟧ will append the |
| 444 |
MCIs following ⟦\continueelement⟧ to the SE containing ⟦\savecurrentelement⟧. |
| 445 |
Since the assignments made here are global, this process cannot be nested; |
| 446 |
in more complicated situations you should therefore use |
| 447 |
⟦*\savecurrentelementto\name ... \continueelementfrom\name⟧ which restores the |
| 448 |
current SE from a named identifier ⟦\name⟧. |
| 449 |
|
| 450 |
\section Structure element options %1 |
| 451 |
|
| 452 |
The ⟦\startelement⟧ command allows a few options that are not mentioned above: |
| 453 |
its full syntax is ⟦*\startelement <options> {Tag}⟧. |
| 454 |
The three most useful options are ⟦alt⟧ for setting an alt-text (the ⟦/Alt⟧ |
| 455 |
entry in the structure element dicionary), ⟦actual⟧ for a text replacement |
| 456 |
(⟦/ActualText⟧) and ⟦lang⟧ for the language (⟦/Lang⟧; see the next section). |
| 457 |
The alternative and actual texts can also be given after the fact with |
| 458 |
⟦*\setalttext {...}⟧ and ⟦*\setactualtext {...}⟧; these apply to the current |
| 459 |
structure element. |
| 460 |
|
| 461 |
Structure element attributes can be given with |
| 462 |
⟦attr <owner> <key> <value>⟧, e.g. ⟦attr Layout Placement /Inline⟧ or added |
| 463 |
later with ⟦*\tagattribute⟧. |
| 464 |
Note that for the ⟦owner⟧ and ⟦key⟧ the initial slash must be omitted; the |
| 465 |
⟦value⟧ on the other hand will be written to the pdf verbatim. |
| 466 |
Any number of attributes can be added. |
| 467 |
|
| 468 |
An identifier can be set with the ⟦id {...}⟧ option, or after the fact with |
| 469 |
⟦*\settagid {...}⟧. This identifier will be added to the ⟦IDTree⟧ and is |
| 470 |
entirely optional; you will probably already know when you need it. |
| 471 |
The ⟦ref {...}⟧ option lets a structure element refer to another (the ⟦/Ref⟧ |
| 472 |
option in the structure element dictionary). Its argument should be the ⟦id⟧ of |
| 473 |
the other structure element. |
| 474 |
|
| 475 |
The title of the structure element (corresponding to the ⟦/T⟧ entry in the |
| 476 |
structure element dictionary) can be set with the ⟦title {...}⟧ option. The |
| 477 |
pdf/ua standard requires this key for all document sections. |
| 478 |
|
| 479 |
Finally, structure element classes can be given with the |
| 480 |
⟦class <classname>⟧ keyword, which can be repeated. |
| 481 |
Classes can be defined with |
| 482 |
⟦*\newattributeclass classname <attributes>⟧ where ⟦<attributes>⟧ can be any |
| 483 |
number of ⟦attr⟧ statements as above. |
| 484 |
|
| 485 |
|
| 486 |
\section Languages %1 |
| 487 |
|
| 488 |
If you do not specify a language code for a structure element, its language |
| 489 |
will be determined automatically. |
| 490 |
In order for this to work, you must associate a language code to every used |
| 491 |
language; you can do so with ⟦*\setlanguagecode name code⟧, where ⟦name⟧ must |
| 492 |
be an identifier used with ⟦\uselanguage {name}⟧ and ⟦code⟧ must be a two or |
| 493 |
three-letter language code, optionally followed by a dialect specification, |
| 494 |
a country code, and/or some other tag. |
| 495 |
Note that the language code is associated to a language \emph{name}, not to the |
| 496 |
numerical value of the ⟦\language⟧ parameter. This allows you to assign |
| 497 |
separate codes to dialects. |
| 498 |
|
| 499 |
There is a small set of default language code associations, which can be found |
| 500 |
in the file ⟦minim-languagecodes.lua⟧. |
| 501 |
It covers most languages defined by the hyph-utf8 package, as well as (due to |
| 502 |
their ubiquitous use) some ancient languages. |
| 503 |
|
| 504 |
An actual language change introduced by ⟦\uselanguage⟧ will not otherwise be |
| 505 |
acted upon by this package. Therefore, you will probably want to add |
| 506 |
⟦\startelement{Span}⟧ after every in-line invocation of ⟦\uselanguage⟧. |
| 507 |
|
| 508 |
You can set the document language with ⟦*\setdocumentlanguage language-code⟧. |
| 509 |
If unset, the language code associated with the first ⟦\uselanguage⟧ statement |
| 510 |
will be used, or else ⟦und⟧ (undetermined). The only function of the document |
| 511 |
language is that it is mentioned in the pdf catalog: it has no other influence. |
| 512 |
|
| 513 |
New languages can be declared with ⟦*\newnamedlanguage {name} {lhm} {rhm}⟧ and |
| 514 |
new dialects with ⟦*\newnameddialect {language name} {dialect name}⟧. |
| 515 |
Dialects will use the same hyphenation patterns (and will indeed have the same |
| 516 |
⟦\language⟧ value) as their parent languages; newly declared languages will |
| 517 |
start with no hyphenation patterns. |
| 518 |
Do note that you will probably also have to specify language codes for new |
| 519 |
languages or dialects. |
| 520 |
|
| 521 |
This package ensures the existence of the ⟦nohyph⟧, ⟦nolang⟧, ⟦uncoded⟧ and |
| 522 |
⟦undetermined⟧ dummy languages, all without hyphenation. |
| 523 |
|
| 524 |
|
| 525 |
\section Mathematics %1 |
| 526 |
|
| 527 |
You can auto-tag equations as formulas by specifing ⟦*\autotagformulas⟧. |
| 528 |
After this command, auto-tagging can be switched off and on with |
| 529 |
⟦*\stopformulatagging⟧ and ⟦*\startformulatagging⟧. |
| 530 |
Auto-tagging formulas is dangerous, because sometimes equations are used for |
| 531 |
lay-out and should not be marked as such. |
| 532 |
It is also somewhat fragile, as it requires equations to end with dollar |
| 533 |
signs (and not with ⟦\Ustopmath⟧ or ⟦\Ustopdisplaymath⟧). |
| 534 |
|
| 535 |
The tex source of an equation can be associated with the ⟦Formula⟧ structure |
| 536 |
element in various ways, which can be configured with ⟦*\includeformulasources |
| 537 |
{options}⟧, where the ⟦options⟧ must be a comma-separated list of |
| 538 |
⟦alttext⟧, ⟦actualtext⟧ or ⟦attachment⟧. |
| 539 |
The ⟦alttext⟧ and ⟦actualtext⟧ option will set the ⟦/Alt⟧ or ⟦/ActualText⟧ |
| 540 |
attributes to the unexpanded source code of the equation, surrounded by the |
| 541 |
appropriate number of dollar signs. |
| 542 |
The ⟦attachment⟧ option attaches the source of the formula as an embedded file |
| 543 |
with its ⟦/AFRelation⟧ set to ⟦Source⟧; |
| 544 |
this will only work if ⟦\pdfaconformancelevel⟧ equals three. |
| 545 |
The name of this file can be changed by redefining ⟦*\formulafilename⟧ inside |
| 546 |
the equation. |
| 547 |
The default value is ⟦{actualtext,attachment}⟧. |
| 548 |
|
| 549 |
Note that the contents of the equation will be expanded fully (as in ⟦\xdef⟧) |
| 550 |
before their inclusion as the equation source. This may place restrictions on |
| 551 |
the macros you want to use (those in minim-math should be safe). |
| 552 |
Any occurrence of ⟦\alttext⟧ or ⟦\actualtext⟧ overrides the |
| 553 |
automatically-assigned value and will be stripped from the equation source. |
| 554 |
|
| 555 |
|
| 556 |
\section Tables %1 |
| 557 |
|
| 558 |
For marking up tables, a whole array of helper macros is available. First, |
| 559 |
⟦*\marktable⟧ should be given \emph{before} the ⟦\halign⟧. |
| 560 |
Then, in the template, the first cell should start with ⟦*\marktablerow⟧ |
| 561 |
⟦*\marktablecell⟧ and |
| 562 |
each subsequent cell with ⟦\marktablecell⟧. |
| 563 |
If your table starts with a header, insert ⟦*\marktableheader⟧ before it and |
| 564 |
⟦*\marktablebody⟧ after. |
| 565 |
Before a table footer, insert ⟦*\marktablefooter⟧. |
| 566 |
|
| 567 |
For greater convenience, insert just ⟦*\automarktable⟧ before the ⟦\halign⟧. |
| 568 |
Then you can leave out all the above commands (unless you ⟦\omit⟧ a template of |
| 569 |
course). |
| 570 |
This assumes the table has a single header row and more than one column. |
| 571 |
If you use a table for typesetting a list, you can use ⟦*\marktableaslist⟧ |
| 572 |
instead, which marks the first column as list label and the second column as |
| 573 |
list item. Of course, this only works with two-column tables. |
| 574 |
|
| 575 |
Cells spanning multiple cells or rows can be marked with |
| 576 |
⟦*\markcolumnspan {width}⟧ and ⟦*\markrowspan {height}⟧; these statements may not |
| 577 |
occur before ⟦\marktablecell⟧. Note that while ⟦\markcolumnspan⟧ properly |
| 578 |
increases the (internal) column number, ⟦\markrowspan⟧ does nothing of the |
| 579 |
sort (and indeed, no general logic can be given in the latter case). Always proceed |
| 580 |
with caution when using cells spanning multiple rows, and inspect the resulting |
| 581 |
structure carefully. |
| 582 |
|
| 583 |
Marking up a table header (except if done through ⟦\automarktable⟧) |
| 584 |
will not connect normal table cells with their headers; you will have to |
| 585 |
connect these manually by including ⟦*\markcolumnhead⟧ or ⟦*\markrowhead⟧ in |
| 586 |
the appropriate header cells. This must be done \emph{after} ⟦\markcolumnspan⟧ |
| 587 |
if the latter appplies. If properly setup like this, other cells of the table |
| 588 |
(including header cells) will be assigned to matching row or column headers |
| 589 |
automatically. |
| 590 |
|
| 591 |
|
| 592 |
\section Other helper macros %1 |
| 593 |
|
| 594 |
For marking up an entry in a table of contents, you can use the macro |
| 595 |
⟦*\marktocentry {dest} {lbl} {title} {filler} {pageno}⟧, which should insert all |
| 596 |
tags in the correct way. (The ⟦dest⟧ is a link destination and can be empty; |
| 597 |
the ⟦lbl⟧ is a section number and can also be empty.) |
| 598 |
|
| 599 |
For tagging (foot)notes, ⟦*\marknoteref{*}⟧ and ⟦*\marknotelbl{*}⟧, when placed |
| 600 |
around the footnote markers, will insert the proper ⟦Ref⟧, ⟦Note⟧ and ⟦Lbl⟧ |
| 601 |
tags. |
| 602 |
|
| 603 |
Helper macros for tagging sections can be setup quickly with |
| 604 |
⟦*\sectionstructure { <section list> }⟧. The ⟦<section list>⟧ should be an |
| 605 |
increasing comma-separated list of section types, e.g. |
| 606 |
⟦{subsection, section, chapter}⟧. This will first reserve the ⟦\count⟧ |
| 607 |
registers ⟦\subsectionnr⟧ etc, then create the structure aliases ⟦/Subsection⟧ |
| 608 |
etc. and finally define the helper macros ⟦\marksubsection⟧ etc, which will do |
| 609 |
the following: |
| 610 |
\startlist |
| 611 |
\item 1. Call ⟦\ensurestopelement⟧ on all lower section types. |
| 612 |
\item 2. Set all lower section number counts to zero. |
| 613 |
\item 3. Increase the current section type number by one. |
| 614 |
\item 4. Call ⟦\startelement⟧ for the current section type. |
| 615 |
\item 5. Set the ⟦\nextpartag⟧ to ⟦H⟧. |
| 616 |
\stoplist |
| 617 |
The proper place for these helper macros is just before the section heading; |
| 618 |
inbetween those two may come an ⟦\outline⟧ statement (see the previous |
| 619 |
chapter). You can set the ⟦title⟧ option to the internal ⟦\startelement⟧ |
| 620 |
statement with an optional argument (e.g. |
| 621 |
⟦\marksection [Section \the\sectionnr]⟧). |
| 622 |
|
| 623 |
\section Tagging the output routine %1 |
| 624 |
|
| 625 |
The command ⟦*\autotagplainoutput⟧ will try and update plain tex’s output routine |
| 626 |
to produce tagged page artifacts and footnotes. |
| 627 |
It redefines ⟦\makeheadline⟧, ⟦\makefootline⟧, |
| 628 |
⟦\footnoterule⟧, ⟦\footnote⟧ and ⟦\vfootnote⟧. |
| 629 |
Headline and footline will not be marked as artifacts if their contents equal |
| 630 |
⟦\hfil⟧; the footnote macros are edited to include the ⟦\marknoteref⟧ and |
| 631 |
⟦\marknotelbl⟧ macros described above. |
| 632 |
Note that the ⟦\topinsert⟧, ⟦\midinsert⟧ and ⟦\pageinsert⟧ macros are left |
| 633 |
untouched; you will have to mark those explicitly. |
| 634 |
|
| 635 |
You can make some changes to the affected macros before calling |
| 636 |
⟦\autotagplainoutput⟧, as it tries to be smart about it. |
| 637 |
Though the redefinitions involve a full expansion, |
| 638 |
most conditionals and common typesetting instructions (⟦\line⟧, ⟦\quad⟧, |
| 639 |
⟦\strut⟧ etc.) are safe-to-use and will not be expanded. |
| 640 |
If you include custom macros of your own, however, it is wise to have those |
| 641 |
⟦\protected⟧. |
| 642 |
|
| 643 |
% |
| 644 |
|
| 645 |
\endmanual |
| 646 |
|