summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/minim-pdf/minim-pdf.doc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2024-03-02 03:04:21 +0000
committerNorbert Preining <norbert@preining.info>2024-03-02 03:04:21 +0000
commitb7323fe884f378851ee661babaa5bd644271f348 (patch)
tree8891732393826e5c5893d00fa39cf9a5eb0a3a90 /macros/luatex/generic/minim-pdf/minim-pdf.doc
parent19a826b6e3a0d2ea6bbd1bf733a8e590463275ed (diff)
CTAN sync 202403020304
Diffstat (limited to 'macros/luatex/generic/minim-pdf/minim-pdf.doc')
-rw-r--r--macros/luatex/generic/minim-pdf/minim-pdf.doc165
1 files changed, 138 insertions, 27 deletions
diff --git a/macros/luatex/generic/minim-pdf/minim-pdf.doc b/macros/luatex/generic/minim-pdf/minim-pdf.doc
index 111d8c1423..3dc0349aca 100644
--- a/macros/luatex/generic/minim-pdf/minim-pdf.doc
+++ b/macros/luatex/generic/minim-pdf/minim-pdf.doc
@@ -14,8 +14,8 @@ all other features of the package are described here.
\else \startmetadata
author {Esger Renkema}
title {minim-pdf}
- date {2024-01-05}
- version {2024/1.4}
+ date {2024-02-25}
+ version {2024/1.5}
keywords {LuaTeX; Plain TeX; PDF/A; Tagged PDF; accessibility; a11y;
hypertext; bookmarks; document outline; associated files}
stopmetadata
@@ -40,9 +40,16 @@ Hyperlinks can be made with
With the ⟦name⟧ action, a named destination must be used (see below), while the
⟦user⟧ action will be passed directly to the back-end (as with the pdftex
primitive).
+After the ⟦url⟧ action, the characters \Uchar`\~, \# and \% need not be escaped.
+(Of course, this does nothing for already-tokenised text; be aware of this when
+you wrap ⟦\hyperlink⟧ into another macro.)
+Any spaces after the ⟦<action>⟧ will be ignored.
+
The ⟦*\hyperlinkstyle⟧ token list can be used so set common (pdf) link
attributes; it defaults to ⟦/Border [0 0 0]⟧. The contents of the optional
⟦attr⟧ parameter will be appended to these.
+The ⟦alt⟧ options sets the ⟦/Contents⟧ key that is required by PDF/UA (where it
+has the purpose of an alt text).
A named destination can be created with ⟦*\nameddestination {...}⟧ (also in
horizontal mode, unlike the backend primitive) and if you cannot think of
@@ -53,18 +60,24 @@ generated name.
\section Bookmarks % 1
-Bookmarks (also known as outlines) can be added with ⟦*\outline [open|closed]
-[dest {name}] {title}⟧.
+Bookmarks (also known as outlines) can be added with
+⟦*\outline [level n] [open|closed] [dest {name}] {title}⟧.
Add ⟦open⟧ or ⟦closed⟧ to have the bookmark appear initially open or closed
-(default), and
+(the default), and
say ⟦dest {name}⟧ for having it refer to a specific named destination
(otherwise, a new one will be created where the ⟦\outline⟧ command appears).
-A bookmark is automatically associated with the current structure element and
-the hierarchy of structure elements determines the nesting of bookmarks.
-Therefore, if you want nested bookmarks, you \emph{must} precede the ⟦\outline⟧
-command with a declaration of the current structure element, even if you have
-otherwise disabled tagging. See the next chapter on how to do this.
+In the absence of the ⟦level⟧ option, the bookmark is automatically associated
+with the current structure element and the hierarchy of structure elements
+determines the nesting of bookmarks. This works even if you have otherwise
+disabled tagging and is the recommended way of generating outlines.
+(You can find all relevant macros in next chapter under ‘Document structure’
+and ‘Structure element aliases’.)
+
+As a fallback, outlines specified with the ⟦level n⟧ option will be inserted at
+the end of the current outline list at the specified level (${\tt n}≥1$ and
+need not be contiguous). Both methods can be intertwined, but please use the
+document structure if you can.
\section Page labels % 1
@@ -201,6 +214,46 @@ For a more general introduction to and discussion of tagged pdf, please read
the (excellent) manual of latex’s tagpdf package.
+\section Quick-start guide % 1
+
+The minimal setup for producing tagged pdf from plain tex documents is
+something like the following:
+
+⟦% first update all fonts to TrueType (ttf) or OpenType (otf)
+\input luaotfload.sty
+% ... font redefinitions omitted ...
+\input minim-mp
+\pdfalevel 2a % declare pdf/a conformance, enable tagging
+\autotagplainoutput % update the output routine
+% create section markers and counters
+\sectionstructure { subsection, section, chapter }⟧
+
+You can then update your sectioning macros to look like this:
+
+⟦\def\section#1\par{%
+ % space above
+ \bigskip \goodbreak
+ % structure and outline (this is the new part)
+ \marksection \outline open {#1}
+ % section header
+ \noindent {\bf \the\chapternr.\the\sectionnr. #1}
+ % space below
+ \smallskip \noindent}⟧
+
+Other macros you might have for laying out structural elements, such as tables
+or lists, should of course also be updated. The rest of this chapter describes
+the tools you can use.
+
+Please be advised that producing tagged pdf will likely forever remain
+a fragile and error-prone process.
+You should always validate the resulting pdf.
+An easy-to-use and free validator is \hyperlink alt {The veraPDF website.}
+url {https://verapdf.org/home}veraPDF\endlink.
+For inspecting the document structure, you can use the ⟦pdfinfo⟧ utility that
+comes with the \hyperlink alt {The Poppler website.}
+url {https://poppler.freedesktop.org/}Poppler\endlink\ pdf library.
+
+
\section Purpose, limitations and pitfalls % 1
The main purpose of this package is semi-automatically marking up the
@@ -213,7 +266,7 @@ Furthermore, while the macros in this package are sophisticated enough that
tagging can be done without any manual intervantion, it is quite possible and
rather easy to generate the wrong document structure, or even cause syntax
errors in the resulting pdf code.
-You should always check the result in an external application.
+You should always inspect and validate the result.
This is the full list of limitations, pitfalls and shortcomings:
\startlist
@@ -223,15 +276,13 @@ can mark out-of-order content explicitly if you know what you are doing; see
below).
\item2. The contents of ⟦\localleftbox⟧ and ⟦\localrightbox⟧ must be marked
manually, probably as artifact.
-\item3. You must mark page header, page footer and footnote rule yourself; no
-default is set.
-\item4. There currently is no way of marking xforms or other pdf objects as
+\item3. There currently is no way of marking xforms or other pdf objects as
content items of themselves.
-\item5. The content of xforms (i.e. pdf objects created by ⟦\useboxresource⟧)
+\item4. The content of xforms (i.e. pdf objects created by ⟦\useboxresource⟧)
should not contain tagging commands.
-\item6. Likewise, you should be careful with box reuse: it might work, but you
+\item5. Likewise, you should be careful with box reuse: it might work, but you
should check.
-\item7. This package currently only supports pdf~1.7 tagging and is not yet
+\item6. This package currently only supports pdf~1.7 tagging and is not yet
ready for use with pdf~2.0.
\stoplist
@@ -279,7 +330,7 @@ Use of ⟦ActualText⟧, ⟦Alt⟧ or ⟦Lang⟧ attribute on MCIs, while allowe
pdf standard, is not supported by this package. You should set these on the
structure element instead.
-The begining and ending of a content item can be forced with
+The beginning and ending of a content item can be forced with
⟦*\startcontentitem⟧ and ⟦*\stopcontentitem⟧, while ⟦*\ensurecontentitem⟧ will
only open a new content item if you are currently outside any.
If you need some part to be a single content item, you can use
@@ -336,17 +387,10 @@ All these helpful features can be disabled by setting
will have to be closed by an explicit closing tag, as in xml.
In this case, ⟦\stopelement⟧ and ⟦\ensurestopelement⟧ will be equivalent.
-By default, ⟦P⟧ structure elements are inserted automatically at the start of
-every paragraph. The tag can be changed with ⟦*\nextpartag {Tag}⟧; leaving the
-argument empty will prevent marking the next paragraph.
-Keep in mind that the reassignment is local: if a paragraph marked with
-⟦\nextpartag⟧ starts inside a group, it will not reset.
-Auto-marking paragraphs can be (locally) disabled or enabled by saying
-⟦*\markparagraphsfalse⟧ or ⟦*\markparagraphstrue⟧.
-
You can query the place in the document structure of any point with
⟦*\showdocumentstructure⟧.
+
\section Structure element aliases % 1
New structure element tags can be created with
@@ -360,6 +404,33 @@ Any aliases you declare will be written to the pdf’s ⟦RoleMap⟧ only if the
have actually been used.
+\section Automatic tagging of paragraphs % 1
+
+By default, ⟦P⟧ structure elements are inserted automatically at the start of
+every paragraph. The tag can be changed with ⟦*\nextpartag {Tag}⟧; leaving the
+argument empty will prevent marking the next paragraph.
+Keep in mind that the (internal) reassignment is local: if a paragraph marked
+with ⟦\nextpartag⟧ starts inside a group, it will not reset.
+Hence, to avoid surprises, you should have ⟦\nextpartag⟧ and the start of your
+paragraph at the same grouping level.
+
+Useful structure elements for ⟦\nextpartag⟧ include ⟦H⟧ for headings and ⟦LI⟧
+for list items. Since minim-pdf produces strongly-structured documents, the
+tags ⟦H1⟧, ⟦H2⟧, ⟦H3⟧ etc. should not be used.
+
+Please also note that if you add ⟦\hbox⟧es directly to a vertical list
+(this includes ⟦\line⟧, ⟦\centerline⟧ and the like),
+the ⟦\everypar⟧ token list is not inserted and no new paragraph structure element
+will be opened.
+The contents of the ⟦\hbox⟧ will be added to the current structure element, and
+this may result in an invalid structure hierarchy (and an error messsage
+reading ‘Structure type mismatch’).
+You can make your intentions clear by inserting ⟦\startelement{P}⟧ at the
+appropriate place (see above).
+
+Auto-marking paragraphs can be (locally) disabled or enabled by saying
+⟦*\markparagraphsfalse⟧ or ⟦*\markparagraphstrue⟧.
+
\section Manipulating the logical order % 1
With the process outlined above, the logical order of structure elements has to
@@ -504,7 +575,7 @@ list item. Of course, this only works with two-column tables.
Cells spanning multiple cells or rows can be marked with
⟦*\markcolumnspan {width}⟧ and ⟦*\markrowspan {height}⟧; these statements may not
occur before ⟦\marktablecell⟧. Note that while ⟦\markcolumnspan⟧ properly
-increases the (internal) column number, ⟦\markcolumnrow⟧ does nothing of the
+increases the (internal) column number, ⟦\markrowspan⟧ does nothing of the
sort (and indeed, no general logic can be given in the latter case). Always proceed
with caution when using cells spanning multiple rows, and inspect the resulting
structure carefully.
@@ -529,6 +600,46 @@ For tagging (foot)notes, ⟦*\marknoteref{*}⟧ and ⟦*\marknotelbl{*}⟧, when
around the footnote markers, will insert the proper ⟦Ref⟧, ⟦Note⟧ and ⟦Lbl⟧
tags.
+Helper macros for tagging sections can be setup quickly with
+⟦*\sectionstructure { <section list> }⟧. The ⟦<section list>⟧ should be an
+increasing comma-separated list of section types, e.g.
+⟦{subsection, section, chapter}⟧. This will first reserve the ⟦\count⟧
+registers ⟦\subsectionnr⟧ etc, then create the structure aliases ⟦/Subsection⟧
+etc. and finally define the helper macros ⟦\marksubsection⟧ etc, which will do
+the following:
+\startlist
+\item 1. Call ⟦\ensurestopelement⟧ on all lower section types.
+\item 2. Set all lower section number counts to zero.
+\item 3. Increase the current section type number by one.
+\item 4. Call ⟦\startelement⟧ for the current section type.
+\item 5. Set the ⟦\nextpartag⟧ to ⟦H⟧.
+\stoplist
+The proper place for these helper macros is just before the section heading;
+inbetween those two may come an ⟦\outline⟧ statement (see the previous
+chapter). You can set the ⟦title⟧ option to the internal ⟦\startelement⟧
+statement with an optional argument (e.g.
+⟦\marksection [Section \the\sectionnr]⟧).
+
+\section Tagging the output routine % 1
+
+The command ⟦*\autotagplainoutput⟧ will try and update plain tex’s output routine
+to produce tagged page artifacts and footnotes.
+It redefines ⟦\makeheadline⟧, ⟦\makefootline⟧,
+⟦\footnoterule⟧, ⟦\footnote⟧ and ⟦\vfootnote⟧.
+Headline and footline will not be marked as artifacts if their contents equal
+⟦\hfil⟧; the footnote macros are edited to include the ⟦\marknoteref⟧ and
+⟦\marknotelbl⟧ macros described above.
+Note that the ⟦\topinsert⟧, ⟦\midinsert⟧ and ⟦\pageinsert⟧ macros are left
+untouched; you will have to mark those explicitly.
+
+You can make some changes to the affected macros before calling
+⟦\autotagplainoutput⟧, as it tries to be smart about it.
+Though the redefinitions involve a full expansion,
+most conditionals and common typesetting instructions (⟦\line⟧, ⟦\quad⟧,
+⟦\strut⟧ etc.) are safe-to-use and will not be expanded.
+If you include custom macros of your own, however, it is wise to have those
+⟦\protected⟧.
+
% 
\endmanual