| 1 |
|
| 2 |
\input minim-doc.sty |
| 3 |
|
| 4 |
\manual{minim-xmp} |
| 5 |
|
| 6 |
\ifchapter \chapter Metadata |
| 7 |
|
| 8 |
\else \startmetadata |
| 9 |
author {Esger Renkema} |
| 10 |
title {minim-xmp} |
| 11 |
date {2025-02-12} |
| 12 |
version {2025/1.4} |
| 13 |
keywords {LuaTeX; Plain TeX; XMP; metadata; PDF/A;} |
| 14 |
stopmetadata |
| 15 |
\maketitle \fi |
| 16 |
|
| 17 |
This package enables simple XMP (eXtensible Metadata Platform) packet inclusion |
| 18 |
and will automatically generate pdf/a extension schemas. Use it by saying |
| 19 |
⟦\input minim-xmp.tex⟧. |
| 20 |
Thereafter, you can use ⟦*\setmetadata key {value}⟧ and ⟦*\getmetadata key⟧ for |
| 21 |
setting and retrieving document-level metadata values. |
| 22 |
|
| 23 |
You do not need this package if you have your metadata ready-made in a separate |
| 24 |
file, for then you can simply say |
| 25 |
\startelement{Code} |
| 26 |
\startsinglecontentitem$$\halign{#\hfil\cr |
| 27 |
⟦\immediate\pdfextension obj uncompressed⟧ \cr |
| 28 |
\qquad⟦stream attr {/Type/Metadata /Subtype/XML}⟧ \cr |
| 29 |
\qquad⟦file {your-file.xmp}⟧ \cr |
| 30 |
⟦\pdfextension catalog⟧ \cr |
| 31 |
\qquad⟦{/Metadata \pdffeedback lastobj 0 R}⟧\cr |
| 32 |
}$$\stopsinglecontentitem |
| 33 |
\vskip-\belowdisplayskip |
| 34 |
|
| 35 |
\section Setting metadata |
| 36 |
|
| 37 |
Metadata fields that contain (ordered or unordered) lists will be split on the |
| 38 |
⟦*\metadataseparator⟧ character; this is a semicolon by default. |
| 39 |
Alternatively, you can just make multiple assignments: these will be |
| 40 |
concatenated. |
| 41 |
|
| 42 |
Where applicable, language alternatives can be given like |
| 43 |
⟦\setmetadata /de⟧ ⟦dc:title {...}⟧ or |
| 44 |
⟦\setmetadata /{de_DE} dc:title {...}⟧. |
| 45 |
Braces are necessary in the second case because the catcode of the underscore |
| 46 |
is not 11~or~12. |
| 47 |
When no alternative is given, the value ⟦*x-default⟧ will be used. |
| 48 |
|
| 49 |
Instead of using ⟦*\setmetadata⟧, multiple fields can be set in one go with |
| 50 |
⟦*\startmetadata⟧. |
| 51 |
This way is particularly useful when assigning structured data to a key (see |
| 52 |
later on). |
| 53 |
In this example, ⟦key1⟧ contains a normal value, ⟦key2⟧ language alternatives |
| 54 |
and ⟦key3⟧ structured data: |
| 55 |
|
| 56 |
⟦\startmetadata |
| 57 |
key1 {...} |
| 58 |
key2 {... (default) ...} |
| 59 |
/alt1 {...} |
| 60 |
/alt2 {...} |
| 61 |
key3 |
| 62 |
/field1 {...} |
| 63 |
/field2 {...} |
| 64 |
stopmetadata⟧ |
| 65 |
|
| 66 |
Since metadata values are read by lua as text, linebreaks and paragraphs are |
| 67 |
not preserved. You can work around this by saying |
| 68 |
⟦{\def\par{\Uchar"A\Uchar"A} \setmetadata abstract {...}}⟧. |
| 69 |
|
| 70 |
\section Getting metadata |
| 71 |
|
| 72 |
Metadata values can be retrieved again with ⟦*\getmetadata key⟧. This command |
| 73 |
is fully expandible. |
| 74 |
|
| 75 |
If the data is a list, it will be returned according to the current value of |
| 76 |
⟦\metadataseparator⟧. |
| 77 |
If the data has language alternatives, the ⟦x-default⟧ value will be returned: |
| 78 |
the alternatives are accessible by ⟦*\getmetadata /lang key⟧. |
| 79 |
|
| 80 |
For structured types (discussed below), ⟦\getmetadata /field key⟧ will return |
| 81 |
the value of a single field and ⟦\getmetadata key⟧ will return all fields as |
| 82 |
⟦/{field1} {value1} /{field2} {value2} ...⟧ (this can be used again as input to |
| 83 |
⟦\startmetadata⟧). |
| 84 |
|
| 85 |
\section Supported metadata keys |
| 86 |
|
| 87 |
Initially, the ⟦\setmetadata⟧ and ⟦\getmetadata⟧ recognise all pdf/a compatible |
| 88 |
fields in the ⟦pdf⟧, ⟦pdfaid⟧, ⟦pdfuaid⟧, ⟦dc⟧, ⟦xmp⟧, ⟦xmpMM⟧ and ⟦xmpRights⟧ |
| 89 |
namespaces. |
| 90 |
Keys should be prefixed with their namespace, e.g. ⟦dc:creator⟧ or |
| 91 |
⟦xmp:CreatorTool⟧. |
| 92 |
Note that the ⟦dc⟧ namespace has lower-case fields; field names are |
| 93 |
case-sensitive. |
| 94 |
|
| 95 |
Because the precise details of the above metadata namespaces can be confusing, |
| 96 |
you might want use one of the aliases |
| 97 |
⟦author⟧ (dc:creator), ⟦title⟧ (dc:title), ⟦date⟧ (dc:date and xmp:CreateDate), |
| 98 |
⟦language⟧ (dc:language), ⟦keywords⟧ (dc:subject and pdf:Keywords), ⟦publisher⟧ |
| 99 |
(dc:publisher), ⟦abstract⟧ (dc:description), ⟦copyright⟧ (dc:rights), ⟦version⟧ |
| 100 |
(xmpMM:VersionID) and ⟦identifier⟧ (dc:identifier). |
| 101 |
New aliases can be defined in the ⟦aliases⟧ table of the lua module. |
| 102 |
|
| 103 |
|
| 104 |
\section Adding new keys and schemas |
| 105 |
|
| 106 |
\directlua{require('minim-xmp').add_namespace( |
| 107 |
'Example namespace', 'colours', |
| 108 |
'http://example.com/minim/colours/', { |
| 109 |
Favourite = { 'Colour', 'The author’s favourite colour' }, |
| 110 |
}, { |
| 111 |
Colour = { 'RGB Colour', { |
| 112 |
R = { 'Integer', 'Red component' }, |
| 113 |
G = { 'Integer', 'Green component' }, |
| 114 |
B = { 'Integer', 'Blue component' } |
| 115 |
}, prefix = 'c' }, |
| 116 |
})} |
| 117 |
\startmetadata colours:Favourite /R 0 /G 0 /B 255 stopmetadata |
| 118 |
|
| 119 |
New metadata namespaces can be added in the following way: |
| 120 |
|
| 121 |
⟦require('minim-xmp').add_namespace( |
| 122 |
'Example namespace', 'colours', |
| 123 |
'http://example.com/minim/colours/', { |
| 124 |
-- metadata keys |
| 125 |
Favourite = { 'Colour', 'The author’s favourite colour' }, |
| 126 |
}, { |
| 127 |
-- value types |
| 128 |
Colour = { 'RGB Colour', { |
| 129 |
R = { 'Integer', 'Red component' }, |
| 130 |
G = { 'Integer', 'Green component' }, |
| 131 |
B = { 'Integer', 'Blue component' } |
| 132 |
}, prefix = 'c' }, |
| 133 |
})⟧ |
| 134 |
|
| 135 |
This will setup a namespace with prefix ⟦colours⟧ and one key: ⟦Favourite⟧, of |
| 136 |
type ⟦Colour⟧. That value type happens to be a structured type with three |
| 137 |
fields, which are also described. |
| 138 |
You can now use this namespace as |
| 139 |
|
| 140 |
⟦\startmetadata colours:Favourite /R 0 /G 0 /B 255 stopmetadata⟧ |
| 141 |
|
| 142 |
or the equivalent but more verbose |
| 143 |
|
| 144 |
⟦\setmetadata/R colours:Favourite 0 |
| 145 |
\setmetadata/G colours:Favourite 0 |
| 146 |
\setmetadata/B colours:Favourite 255⟧ |
| 147 |
|
| 148 |
after which the generated XMP code will be |
| 149 |
|
| 150 |
⟦ <rdf:Description rdf:about="" |
| 151 |
xmlns:colours="http://example.com/minim/colours/" |
| 152 |
xmlns:c="http://example.com/minim/colours/"> |
| 153 |
<colours:Favourite rdf:parseType="Resource"> |
| 154 |
<c:B>255</c:B> |
| 155 |
<c:G>0</c:G> |
| 156 |
<c:R>0</c:R> |
| 157 |
</colours:Favourite> |
| 158 |
</rdf:Description>⟧ |
| 159 |
|
| 160 |
If use of the pdf/a format is detected (i.e. a ⟦pdfaid⟧ entry is present in the |
| 161 |
metadata), the following pdf/a extension schema will also be generated: |
| 162 |
|
| 163 |
\font\seventt {Latin Modern Mono:script=latn;+smcp;} at 7pt |
| 164 |
\begingroup\rightskip=-6cm\baselineskip=9pt |
| 165 |
⟦∥let∥tentt∥seventt∥seventt<rdf:Description rdf:about="" |
| 166 |
xmlns:pdfaExtension="http://www.aiim.org/pdfa/ns/extension/" |
| 167 |
xmlns:pdfaSchema="http://www.aiim.org/pdfa/ns/schema#" |
| 168 |
xmlns:pdfaProperty="http://www.aiim.org/pdfa/ns/property#" |
| 169 |
xmlns:pdfaType="http://www.aiim.org/pdfa/ns/type#" |
| 170 |
xmlns:pdfaField="http://www.aiim.org/pdfa/ns/field#" > |
| 171 |
<pdfaExtension:schemas> |
| 172 |
<rdf:Bag> |
| 173 |
<rdf:li rdf:parseType="Resource"> |
| 174 |
<pdfaSchema:schema>Example namespace</pdfaSchema:schema> |
| 175 |
<pdfaSchema:namespaceURI>http://example.com/minim/colours/</pdfaSchema:namespaceURI> |
| 176 |
<pdfaSchema:prefix>colours</pdfaSchema:prefix> |
| 177 |
<pdfaSchema:property> |
| 178 |
<rdf:Seq> |
| 179 |
<rdf:li rdf:parseType="Resource"> |
| 180 |
<pdfaProperty:name>Favourite</pdfaProperty:name> |
| 181 |
<pdfaProperty:valueType>Colour</pdfaProperty:valueType> |
| 182 |
<pdfaProperty:category>external</pdfaProperty:category> |
| 183 |
<pdfaProperty:description>The author’s favourite colour</pdfaProperty:description> |
| 184 |
</rdf:li> |
| 185 |
</rdf:Seq> |
| 186 |
</pdfaSchema:property> |
| 187 |
<pdfaSchema:valueType> |
| 188 |
<rdf:Seq> |
| 189 |
<rdf:li rdf:parseType="Resource"> |
| 190 |
<pdfaType:type>Colour</pdfaType:type> |
| 191 |
<pdfaType:namespaceURI>http://example.com/minim/colours/</pdfaType:namespaceURI> |
| 192 |
<pdfaType:prefix>c</pdfaType:prefix> |
| 193 |
<pdfaType:description>RGB Colour</pdfaType:description> |
| 194 |
<pdfaType:field> |
| 195 |
<rdf:Seq> |
| 196 |
<rdf:li rdf:parseType="Resource"> |
| 197 |
<pdfaField:name>B</pdfaField:name> |
| 198 |
<pdfaField:valueType>Integer</pdfaField:valueType> |
| 199 |
<pdfaField:description>Blue component</pdfaField:description> |
| 200 |
</rdf:li> |
| 201 |
<rdf:li rdf:parseType="Resource"> |
| 202 |
<pdfaField:name>G</pdfaField:name> |
| 203 |
<pdfaField:valueType>Integer</pdfaField:valueType> |
| 204 |
<pdfaField:description>Green component</pdfaField:description> |
| 205 |
</rdf:li> |
| 206 |
<rdf:li rdf:parseType="Resource"> |
| 207 |
<pdfaField:name>R</pdfaField:name> |
| 208 |
<pdfaField:valueType>Integer</pdfaField:valueType> |
| 209 |
<pdfaField:description>Red component</pdfaField:description> |
| 210 |
</rdf:li> |
| 211 |
</rdf:Seq> |
| 212 |
</pdfaType:field> |
| 213 |
</rdf:li> |
| 214 |
</rdf:Seq> |
| 215 |
</pdfaSchema:valueType> |
| 216 |
</rdf:li> |
| 217 |
</rdf:Bag> |
| 218 |
</pdfaExtension:schemas> |
| 219 |
</rdf:Description>⟧ |
| 220 |
\par\endgroup |
| 221 |
|
| 222 |
You probably will not need defining your own value types, |
| 223 |
so in most cases you should omit the fifth argument to ⟦add_namespace⟧. |
| 224 |
If you do define a new value type, you can specify its prefix if it differs |
| 225 |
from the namespace prefix (as is done above) and likewise its ⟦uri⟧ identifier |
| 226 |
if it differs from the namespace URI. |
| 227 |
|
| 228 |
List types can be given as ⟦'Bag TypeName'⟧ or ⟦'Seq TypeName'⟧; language |
| 229 |
alternatives as ⟦'Lang Alt'⟧. All other types will be treated as ⟦'Text'⟧, |
| 230 |
though for ⟦'Boolean'⟧, ⟦'Integer'⟧ and ⟦'Date'⟧ some validation is performed |
| 231 |
when setting values. |
| 232 |
|
| 233 |
Additional metadata value type handling can be defined in the ⟦getters⟧ and |
| 234 |
⟦setters⟧ tables of the lua module. |
| 235 |
Appropriate entries to those tables will be generated automatically for new |
| 236 |
structured types (which is why you could set the colour like we did above). |
| 237 |
Value types without fields, however, will be stored and retrieved as if they |
| 238 |
were ⟦Text⟧ until you provide another way. |
| 239 |
|
| 240 |
|
| 241 |
\section Generated XMP |
| 242 |
|
| 243 |
All metadata will be written to the PDF file uncompressed. |
| 244 |
|
| 245 |
The ⟦*\metadatamodification⟧ setting controls whether XMP packets will be |
| 246 |
marked as read-only (value~0; default) or writeable (value~1). |
| 247 |
Writeable XMP packets will be padded with about 2\thinspace kB of whitespace. |
| 248 |
You can prohibit writing metadata altogether |
| 249 |
by specifying ⟦*\writedocumentmetadata = 0⟧. |
| 250 |
|
| 251 |
If the document-level metadata contains values in the ⟦pdfaid⟧ namespace, |
| 252 |
metadata extension schemas will be appended to the document-level metadata |
| 253 |
packet automatically. |
| 254 |
These extension schema’s will only include keys that have been set somewhere, |
| 255 |
though they need not have been set in the document-level metadata. |
| 256 |
No extension schemas are generated for the built-in namespaces, as they are |
| 257 |
already included in the pdf/a standards. |
| 258 |
|
| 259 |
|
| 260 |
\endmanual |
| 261 |
|