\input minim-doc.sty \manual{minim-xmp} \ifchapter \chapter Metadata \else \startmetadata author {Esger Renkema} title {minim-xmp} date {2024-01-05} version {2024/1.3} keywords {LuaTeX; Plain TeX; XMP; metadata; PDF/A;} stopmetadata \maketitle \fi This package enables simple XMP (eXtensible Metadata Platform) packet inclusion and will automatically generate pdf/a extension schemas. Use it by saying ⟦\input minim-xmp.tex⟧. Thereafter, you can use ⟦*\setmetadata key {value}⟧ and ⟦*\getmetadata key⟧ for setting and retrieving document-level metadata values. You do not need this package if you have your metadata ready-made in a separate file, for then you can simply say \startelement{Code} \startsinglecontentitem$$\halign{#\hfil\cr ⟦\immediate\pdfextension obj uncompressed⟧ \cr \qquad⟦stream attr {/Type/Metadata /Subtype/XML}⟧ \cr \qquad⟦file {your-file.xmp}⟧ \cr ⟦\pdfextension catalog⟧ \cr \qquad⟦{/Metadata \pdffeedback lastobj 0 R}⟧\cr }$$\stopsinglecontentitem \vskip-\belowdisplayskip \section Setting metadata Metadata fields that contain (ordered or unordered) lists will be split on the ⟦*\metadataseparator⟧ character; this is a semicolon by default. Alternatively, you can just make multiple assignments: these will be concatenated. Where applicable, language alternatives can be given like ⟦\setmetadata /de⟧ ⟦dc:title {...}⟧ or ⟦\setmetadata /{de_DE} dc:title {...}⟧. Braces are necessary in the second case because the catcode of the underscore is not 11~or~12. When no alternative is given, the value ⟦*x-default⟧ will be used. Instead of using ⟦*\setmetadata⟧, multiple fields can be set in one go with ⟦*\startmetadata⟧. This way is particularly useful when assigning structured data to a key (see later on). In this example, ⟦key1⟧ contains a normal value, ⟦key2⟧ language alternatives and ⟦key3⟧ structured data: ⟦\startmetadata key1 {...} key2 {... (default) ...} /alt1 {...} /alt2 {...} key3 /field1 {...} /field2 {...} stopmetadata⟧ Since metadata values are read by lua as text, linebreaks and paragraphs are not preserved. You can work around this by saying ⟦{\def\par{\Uchar"A\Uchar"A} \setmetadata abstract {...}}⟧. \section Getting metadata Metadata values can be retrieved again with ⟦*\getmetadata key⟧. This command is fully expandible. If the data is a list, it will be returned according to the current value of ⟦\metadataseparator⟧. If the data has language alternatives, the ⟦x-default⟧ value will be returned: the alternatives are accessible by ⟦*\getmetadata /lang key⟧. For structured types (discussed below), ⟦\getmetadata /field key⟧ will return the value of a single field and ⟦\getmetadata key⟧ will return all fields as ⟦/{field1} {value1} /{field2} {value2} ...⟧ (this can be used again as input to ⟦\startmetadata⟧). \section Supported metadata keys Initially, the ⟦\setmetadata⟧ and ⟦\getmetadata⟧ recognise all pdf/a compatible fields in the ⟦pdf⟧, ⟦pdfaid⟧, ⟦pdfuaid⟧, ⟦dc⟧, ⟦xmp⟧, ⟦xmpMM⟧ and ⟦xmpRights⟧ namespaces. Keys should be prefixed with their namespace, e.g. ⟦dc:creator⟧ or ⟦xmp:CreatorTool⟧. Note that the ⟦dc⟧ namespace has lower-case fields; field names are case-sensitive. Because the precise details of the above metadata namespaces can be confusing, you might want use one of the aliases ⟦author⟧ (dc:creator), ⟦title⟧ (dc:title), ⟦date⟧ (dc:date and xmp:CreateDate), ⟦language⟧ (dc:language), ⟦keywords⟧ (dc:subject and pdf:Keywords), ⟦publisher⟧ (dc:publisher), ⟦abstract⟧ (dc:description), ⟦copyright⟧ (dc:rights), ⟦version⟧ (xmpMM:VersionID) and ⟦identifier⟧ (dc:identifier). New aliases can be defined in the ⟦aliases⟧ table of the lua module. \section Adding new keys and schemas \directlua{require('minim-xmp').add_namespace( 'Example namespace', 'colours', 'http://example.com/minim/colours/', { Favourite = { 'Colour', 'The author’s favourite colour' }, }, { Colour = { 'RGB Colour', { R = { 'Integer', 'Red component' }, G = { 'Integer', 'Green component' }, B = { 'Integer', 'Blue component' } }, prefix = 'c' }, })} \startmetadata colours:Favourite /R 0 /G 0 /B 255 stopmetadata New metadata namespaces can be added in the following way: ⟦require('minim-xmp').add_namespace( 'Example namespace', 'colours', 'http://example.com/minim/colours/', { -- metadata keys Favourite = { 'Colour', 'The author’s favourite colour' }, }, { -- value types Colour = { 'RGB Colour', { R = { 'Integer', 'Red component' }, G = { 'Integer', 'Green component' }, B = { 'Integer', 'Blue component' } }, prefix = 'c' }, })⟧ This will setup a namespace with prefix ⟦colours⟧ and one key: ⟦Favourite⟧, of type ⟦Colour⟧. That value type happens to be a structured type with three fields, which are also described. You can now use this namespace as ⟦\startmetadata colours:Favourite /R 0 /G 0 /B 255 stopmetadata⟧ or the equivalent but more verbose ⟦\setmetadata/R colours:Favourite 0 \setmetadata/G colours:Favourite 0 \setmetadata/B colours:Favourite 255⟧ after which the generated XMP code will be ⟦ 255 0 0 ⟧ If use of the pdf/a format is detected (i.e. a ⟦pdfaid⟧ entry is present in the metadata), the following pdf/a extension schema will also be generated: \font\seventt {Latin Modern Mono:script=latn;+smcp;} at 7pt \begingroup\rightskip=-6cm\baselineskip=9pt ⟦∥let∥tentt∥seventt∥seventt Example namespace http://example.com/minim/colours/ colours Favourite Colour external The author’s favourite colour Colour http://example.com/minim/colours/ c RGB Colour B Integer Blue component G Integer Green component R Integer Red component ⟧ \par\endgroup You probably will not need defining your own value types, so in most cases you should omit the fifth argument to ⟦add_namespace⟧. If you do define a new value type, you can specify its prefix if it differs from the namespace prefix (as is done above) and likewise its ⟦uri⟧ identifier if it differs from the namespace URI. List types can be given as ⟦'Bag TypeName'⟧ or ⟦'Seq TypeName'⟧; language alternatives as ⟦'Lang Alt'⟧. All other types will be treated as ⟦'Text'⟧, though for ⟦'Boolean'⟧, ⟦'Integer'⟧ and ⟦'Date'⟧ some validation is performed when setting values. Additional metadata value type handling can be defined in the ⟦getters⟧ and ⟦setters⟧ tables of the lua module. Appropriate entries to those tables will be generated automatically for new structured types (which is why you could set the colour like we did above). Value types without fields, however, will be stored and retrieved as if they were ⟦Text⟧ until you provide another way. \section Generated XMP All metadata will be written to the PDF file uncompressed. The ⟦*\metadatamodification⟧ setting controls whether XMP packets will be marked as read-only (value~0; default) or writeable (value~1). Writeable XMP packets will be padded with about 2\thinspace kB of whitespace. You can prohibit writing metadata altogether by specifying ⟦*\writedocumentmetadata = 0⟧. If the document-level metadata contains values in the ⟦pdfaid⟧ namespace, metadata extension schemas will be appended to the document-level metadata packet automatically. These extension schema’s will only include keys that have been set somewhere, though they need not have been set in the document-level metadata. No extension schemas are generated for the built-in namespaces, as they are already included in the pdf/a standards. \endmanual