Debian Codegraph @

texmf-dist/doc/luatex/minim-pdf/minim-pdf.doc

raw
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