summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/minim-pdf/minim-pdf.doc
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/generic/minim-pdf/minim-pdf.doc')
-rw-r--r--macros/luatex/generic/minim-pdf/minim-pdf.doc86
1 files changed, 47 insertions, 39 deletions
diff --git a/macros/luatex/generic/minim-pdf/minim-pdf.doc b/macros/luatex/generic/minim-pdf/minim-pdf.doc
index 2c06dd25b0..71e8cea89c 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 {2021-06-01}
- version {2021/1.0}
+ date {2022-03-03}
+ version {2022/1.1}
keywords {LuaTeX; Plain TeX; PDF/A; Tagged PDF; accessibility; a11y;
hypertext; bookmarks; document outline; associated files}
stopmetadata
@@ -47,8 +47,9 @@ generated name.
\section Bookmarks % 1
-Bookmarks can be added with ⟦*\outline [open] [dest {name}] {title}⟧.
-Add ⟦open⟧ to have the bookmark appear initially open and
+Bookmarks can be added with ⟦*\outline [open|closed] [dest {name}] {title}⟧.
+Add ⟦open⟧ or ⟦closed⟧ to have the bookmark appear initially open or
+closed (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).
@@ -129,11 +130,10 @@ With the minim-xmp package, a useful setting is
\section Lua module % 1
The interface of the lua module (available via
-⟦local M = require('minim-pdf')⟧) is not stable yet, and may change.
-One function of interest, however, is
-⟦M.pdf_string(...)⟧, wich converts a lua string to a pdf string. The
-surrounding ⟦<>⟧ or ⟦()⟧ characters are included in the return value.
-
+⟦local M = require('minim-pdf')⟧) should be stable by now.
+Though it contains lua equivalents for most tex commands described here, using
+them directly is not very ergonomical and not recommended.
+Please consult the source if you do want to use them anyway.
% 
@@ -160,7 +160,7 @@ be seen by tex’s stomach in the \emph{logical} order.
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 structore, or even cause syntax
+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.
@@ -169,21 +169,17 @@ This is the full list of limitations, pitfalls and shortcomings:
\item1. Document content must be seen by tex in its logical order (although you
can mark out-of-order content explicitly if you know what you are doing; see
below).
-\item2. Artifacts cannot be split across pages. A pagebreak inmidst an artifact
-will cause incorrect pdf without error or warning.
-\item3. The contents of ⟦\localleftbox⟧ and ⟦\localrightbox⟧ must be marked
+\item2. The contents of ⟦\localleftbox⟧ and ⟦\localrightbox⟧ must be marked
manually, probably as artifact.
-\item4. You must mark page header, page footer and footnote rule yourself; no
+\item3. You must mark page header, page footer and footnote rule yourself; no
default is set.
-\item5. There currently is no way of marking xforms or other pdf objects as
+\item4. There currently is no way of marking xforms or other pdf objects as
content items of themselves.
-\item6. The content of xforms (i.e. pdf objects created by ⟦\useboxresource⟧)
+\item5. The content of xforms (i.e. pdf objects created by ⟦\useboxresource⟧)
should not contain tagging commands.
-\item7. Likewise, you should be careful with box reuse: it might work, but you
+\item6. Likewise, you should be careful with box reuse: it might work, but you
should check.
-\item8. The use of structure element attributes is currently not supported
-except in a limited number of cases.
-\item9. This package currently only supports pdf~1.7 tagging and is not yet
+\item7. This package currently only supports pdf~1.7 tagging and is not yet
ready for use with pdf~2.0.
\stoplist
@@ -234,7 +230,7 @@ structure element instead.
The begining 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, that can use
+If you need some part to be a single content item, you can use
⟦*\startsinglecontentitem ... \stopsinglecontentitem⟧.
This will disable all SE and MCI tagging inside.
@@ -249,8 +245,6 @@ Artifacts can be marked in two ways: with ⟦*\markartifact {type} {...}⟧ or w
The ⟦type⟧ is written to the pdf attribute dictionary directly, so that if you
need a subtype, you can write e.g.
⟦\startartifact {Pagination /Subtype/Header} etc⟧.
-Do make sure your artifact does not contain a page break, as this will result
-in invalid output.
Inside artifacts, other structure content markers will be ignored. Furthermore,
this package makes sure artifacts are never part of marked content items,
@@ -281,11 +275,11 @@ perfect nor complete. You should always check the results in an external
application.
Particular care should be taken when ‘skipping’ structure levels: the sequence
chapter – subsection – section will result in the section beneath the subsection.
-If you are in doubt about an element being closed already, you can use
+If you are in doubt whether an element has been closed already, you can use
⟦*\ensurestopelement {Tag}⟧ instead of ⟦\stopelement⟧
to prevent an error being raised.
-All these helpful features can also be disabled by setting
+All these helpful features can be disabled by setting
⟦*\strictstructuretagging⟧ to a positive value. Then, every structure element
will have to be closed by an explicit closing tag, as in xml.
In this case, ⟦\stopelement⟧ and ⟦\ensurestopelement⟧ will be equivalent.
@@ -293,6 +287,8 @@ 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⟧.
@@ -326,20 +322,28 @@ in more complicated situations you should therefore use
⟦*\savecurrentelementto\name ... \continueelementfrom\name⟧ which restores the
current SE from a named identifier ⟦\name⟧.
-
\section Structure element options % 1
-The ⟦\startcontentitem⟧ command allows a few options that are not mentioned
-above: its full syntax is ⟦*\startcontentitem <options> {Tag}⟧.
+The ⟦\startelement⟧ command allows a few options that are not mentioned
+above: its full syntax is ⟦*\startelement <options> {Tag}⟧.
The three most useful options are ⟦alt⟧ for setting an alt-text (the ⟦/Alt⟧
entry in the structure element dicionary), ⟦actual⟧ for a text replacement
(⟦/ActualText⟧) and ⟦lang⟧ for the language (⟦/Lang⟧; see the next section).
The alternative and actual texts can also be given after the fact with
-⟦*\setalttext{...}⟧ and ⟦*\setactualtext{...}⟧. These apply to the current
+⟦*\setalttext{...}⟧ and ⟦*\setactualtext{...}⟧; these apply to the current
structure element.
-Setting structure element attributes is not supported at this moment, except
-the placement attributes ⟦block⟧ and ⟦inline⟧, which can be given as options.
+Structure element attributes can be given with
+⟦attr <owner> <key> <value>⟧, e.g. ⟦attr Layout Placement /Inline⟧.
+Note that for the ⟦owner⟧ and ⟦key⟧ the initial slash must be omitted; the
+⟦value⟧ on the other hand will be written to the pdf verbatim.
+Any number of attributes can be added.
+
+Finally, structure element classes can be given with the
+⟦class <classname>⟧ keyword, which can be repeated.
+Classes can be defined with
+⟦*\newattributeclass classname <attributes>⟧ where ⟦<attributes>⟧ can be any
+number of ⟦attr⟧ statements as above.
\section Languages % 1
@@ -358,7 +362,7 @@ separate codes to dialects.
There is a small set of default language code associations, which can be found
in the file ⟦minim-languagecodes.lua⟧.
It covers most languages defined by the hyph-utf8 package, as well as (due to
-their ubiquitous use) many ancient languages.
+their ubiquitous use) some ancient languages.
An actual language change introduced by ⟦\uselanguage⟧ will not otherwise be
acted upon by this package. Therefore, you will probably want to add
@@ -381,7 +385,7 @@ This package ensures the existence of the ⟦nohyph⟧, ⟦nolang⟧, ⟦uncoded
⟦undetermined⟧ dummy languages, all without hyphenation.
-\section Helper macros
+\section Helper macros % 1
For marking up an entry in a table of contents, you can use the macro
⟦*\marktocentry {dest} {lbl} {title} {filler} {pageno}⟧, which should insert all
@@ -410,14 +414,18 @@ are used for lay-out and should not be marked as such.
After the latter command, auto-tagging can be switched off and on with
⟦*\stopformulatagging⟧ and ⟦*\startformulatagging⟧.
-Both alt and actualtext of the ⟦Formula⟧ structure element will be set to the
-(unexpanded) source code of the equation, surrounded by the appropriate number
-of dollar signs.
-Furthermore, if ⟦\pdfaconformancelevel⟧ equals three, the source of the formula
-will be attached in an embedded file with the ⟦/AFRelation⟧ set to ⟦Source⟧.
+The source of the equation can be associated with the ⟦Formula⟧ structure
+element in various ways, which can be configured with ⟦*\includeformulasources
+{option}⟧, where the ⟦option⟧ must be one of ⟦none⟧, ⟦actualtext⟧, ⟦attachment⟧
+or ⟦both⟧.
+The ⟦actualtext⟧ option will use the unexpanded source code of the equation,
+surrounded by the appropriate number of dollar signs.
+The ⟦attachment⟧ option will only work if ⟦\pdfaconformancelevel⟧ equals three:
+then the source of the formula will be attached in an embedded file with the
+⟦/AFRelation⟧ set to ⟦Source⟧.
The name of this file can be changed by redefining ⟦*\formulafilename⟧ inside
the equation.
-
+The default value is ⟦both⟧.
%