diff options
Diffstat (limited to 'macros/luatex/generic/minim-xmp/minim-xmp.doc')
-rw-r--r-- | macros/luatex/generic/minim-xmp/minim-xmp.doc | 196 |
1 files changed, 196 insertions, 0 deletions
diff --git a/macros/luatex/generic/minim-xmp/minim-xmp.doc b/macros/luatex/generic/minim-xmp/minim-xmp.doc new file mode 100644 index 0000000000..01d2084f6c --- /dev/null +++ b/macros/luatex/generic/minim-xmp/minim-xmp.doc @@ -0,0 +1,196 @@ + +\input minim-doc.sty + +\manual{minim-xmp} + +\ifchapter \chapter Metadata + +\else \startmetadata + author {Esger Renkema} + title {minim-xmp} + date {2021-06-01} + version {2021/1.0} + 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⟧, ⟦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 + +⟦ <rdf:Description rdf:about="" + xmlns:colours="http://example.com/minim/colours/" + xmlns:c="http://example.com/minim/colours/"> + <colours:Favourite rdf:parseType="Resource"> + <c:B>255</c:B> + <c:G>0</c:G> + <c:R>0</c:R> + </colours:Favourite> + </rdf:Description>⟧ + +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. + +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 + |