Debian Codegraph @

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

raw
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