From d14ac3f3158120bf1e6a67a6ef6526d5c5c33cf6 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Wed, 9 Jun 2021 20:42:49 +0000 Subject: minim-pdf (9jun21) git-svn-id: svn://tug.org/texlive/trunk@59539 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/luatex/minim-pdf/EUPL-1.2-EN.txt | 287 ++++++++++++++ Master/texmf-dist/doc/luatex/minim-pdf/README | 36 ++ .../texmf-dist/doc/luatex/minim-pdf/minim-pdf.doc | 425 +++++++++++++++++++++ .../texmf-dist/doc/luatex/minim-pdf/minim-pdf.pdf | Bin 0 -> 108362 bytes 4 files changed, 748 insertions(+) create mode 100644 Master/texmf-dist/doc/luatex/minim-pdf/EUPL-1.2-EN.txt create mode 100644 Master/texmf-dist/doc/luatex/minim-pdf/README create mode 100644 Master/texmf-dist/doc/luatex/minim-pdf/minim-pdf.doc create mode 100644 Master/texmf-dist/doc/luatex/minim-pdf/minim-pdf.pdf (limited to 'Master/texmf-dist/doc/luatex') diff --git a/Master/texmf-dist/doc/luatex/minim-pdf/EUPL-1.2-EN.txt b/Master/texmf-dist/doc/luatex/minim-pdf/EUPL-1.2-EN.txt new file mode 100644 index 00000000000..4153cd37753 --- /dev/null +++ b/Master/texmf-dist/doc/luatex/minim-pdf/EUPL-1.2-EN.txt @@ -0,0 +1,287 @@ + EUROPEAN UNION PUBLIC LICENCE v. 1.2 + EUPL © the European Union 2007, 2016 + +This European Union Public Licence (the ‘EUPL’) applies to the Work (as defined +below) which is provided under the terms of this Licence. Any use of the Work, +other than as authorised under this Licence is prohibited (to the extent such +use is covered by a right of the copyright holder of the Work). + +The Work is provided under the terms of this Licence when the Licensor (as +defined below) has placed the following notice immediately following the +copyright notice for the Work: + + Licensed under the EUPL + +or has expressed by any other means his willingness to license under the EUPL. + +1. Definitions + +In this Licence, the following terms have the following meaning: + +- ‘The Licence’: this Licence. + +- ‘The Original Work’: the work or software distributed or communicated by the + Licensor under this Licence, available as Source Code and also as Executable + Code as the case may be. + +- ‘Derivative Works’: the works or software that could be created by the + Licensee, based upon the Original Work or modifications thereof. This Licence + does not define the extent of modification or dependence on the Original Work + required in order to classify a work as a Derivative Work; this extent is + determined by copyright law applicable in the country mentioned in Article 15. + +- ‘The Work’: the Original Work or its Derivative Works. + +- ‘The Source Code’: the human-readable form of the Work which is the most + convenient for people to study and modify. + +- ‘The Executable Code’: any code which has generally been compiled and which is + meant to be interpreted by a computer as a program. + +- ‘The Licensor’: the natural or legal person that distributes or communicates + the Work under the Licence. + +- ‘Contributor(s)’: any natural or legal person who modifies the Work under the + Licence, or otherwise contributes to the creation of a Derivative Work. + +- ‘The Licensee’ or ‘You’: any natural or legal person who makes any usage of + the Work under the terms of the Licence. + +- ‘Distribution’ or ‘Communication’: any act of selling, giving, lending, + renting, distributing, communicating, transmitting, or otherwise making + available, online or offline, copies of the Work or providing access to its + essential functionalities at the disposal of any other natural or legal + person. + +2. Scope of the rights granted by the Licence + +The Licensor hereby grants You a worldwide, royalty-free, non-exclusive, +sublicensable licence to do the following, for the duration of copyright vested +in the Original Work: + +- use the Work in any circumstance and for all usage, +- reproduce the Work, +- modify the Work, and make Derivative Works based upon the Work, +- communicate to the public, including the right to make available or display + the Work or copies thereof to the public and perform publicly, as the case may + be, the Work, +- distribute the Work or copies thereof, +- lend and rent the Work or copies thereof, +- sublicense rights in the Work or copies thereof. + +Those rights can be exercised on any media, supports and formats, whether now +known or later invented, as far as the applicable law permits so. + +In the countries where moral rights apply, the Licensor waives his right to +exercise his moral right to the extent allowed by law in order to make effective +the licence of the economic rights here above listed. + +The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to +any patents held by the Licensor, to the extent necessary to make use of the +rights granted on the Work under this Licence. + +3. Communication of the Source Code + +The Licensor may provide the Work either in its Source Code form, or as +Executable Code. If the Work is provided as Executable Code, the Licensor +provides in addition a machine-readable copy of the Source Code of the Work +along with each copy of the Work that the Licensor distributes or indicates, in +a notice following the copyright notice attached to the Work, a repository where +the Source Code is easily and freely accessible for as long as the Licensor +continues to distribute or communicate the Work. + +4. Limitations on copyright + +Nothing in this Licence is intended to deprive the Licensee of the benefits from +any exception or limitation to the exclusive rights of the rights owners in the +Work, of the exhaustion of those rights or of other applicable limitations +thereto. + +5. Obligations of the Licensee + +The grant of the rights mentioned above is subject to some restrictions and +obligations imposed on the Licensee. Those obligations are the following: + +Attribution right: The Licensee shall keep intact all copyright, patent or +trademarks notices and all notices that refer to the Licence and to the +disclaimer of warranties. The Licensee must include a copy of such notices and a +copy of the Licence with every copy of the Work he/she distributes or +communicates. The Licensee must cause any Derivative Work to carry prominent +notices stating that the Work has been modified and the date of modification. + +Copyleft clause: If the Licensee distributes or communicates copies of the +Original Works or Derivative Works, this Distribution or Communication will be +done under the terms of this Licence or of a later version of this Licence +unless the Original Work is expressly distributed only under this version of the +Licence — for example by communicating ‘EUPL v. 1.2 only’. The Licensee +(becoming Licensor) cannot offer or impose any additional terms or conditions on +the Work or Derivative Work that alter or restrict the terms of the Licence. + +Compatibility clause: If the Licensee Distributes or Communicates Derivative +Works or copies thereof based upon both the Work and another work licensed under +a Compatible Licence, this Distribution or Communication can be done under the +terms of this Compatible Licence. For the sake of this clause, ‘Compatible +Licence’ refers to the licences listed in the appendix attached to this Licence. +Should the Licensee's obligations under the Compatible Licence conflict with +his/her obligations under this Licence, the obligations of the Compatible +Licence shall prevail. + +Provision of Source Code: When distributing or communicating copies of the Work, +the Licensee will provide a machine-readable copy of the Source Code or indicate +a repository where this Source will be easily and freely available for as long +as the Licensee continues to distribute or communicate the Work. + +Legal Protection: This Licence does not grant permission to use the trade names, +trademarks, service marks, or names of the Licensor, except as required for +reasonable and customary use in describing the origin of the Work and +reproducing the content of the copyright notice. + +6. Chain of Authorship + +The original Licensor warrants that the copyright in the Original Work granted +hereunder is owned by him/her or licensed to him/her and that he/she has the +power and authority to grant the Licence. + +Each Contributor warrants that the copyright in the modifications he/she brings +to the Work are owned by him/her or licensed to him/her and that he/she has the +power and authority to grant the Licence. + +Each time You accept the Licence, the original Licensor and subsequent +Contributors grant You a licence to their contributions to the Work, under the +terms of this Licence. + +7. Disclaimer of Warranty + +The Work is a work in progress, which is continuously improved by numerous +Contributors. It is not a finished work and may therefore contain defects or +‘bugs’ inherent to this type of development. + +For the above reason, the Work is provided under the Licence on an ‘as is’ basis +and without warranties of any kind concerning the Work, including without +limitation merchantability, fitness for a particular purpose, absence of defects +or errors, accuracy, non-infringement of intellectual property rights other than +copyright as stated in Article 6 of this Licence. + +This disclaimer of warranty is an essential part of the Licence and a condition +for the grant of any rights to the Work. + +8. Disclaimer of Liability + +Except in the cases of wilful misconduct or damages directly caused to natural +persons, the Licensor will in no event be liable for any direct or indirect, +material or moral, damages of any kind, arising out of the Licence or of the use +of the Work, including without limitation, damages for loss of goodwill, work +stoppage, computer failure or malfunction, loss of data or any commercial +damage, even if the Licensor has been advised of the possibility of such damage. +However, the Licensor will be liable under statutory product liability laws as +far such laws apply to the Work. + +9. Additional agreements + +While distributing the Work, You may choose to conclude an additional agreement, +defining obligations or services consistent with this Licence. However, if +accepting obligations, You may act only on your own behalf and on your sole +responsibility, not on behalf of the original Licensor or any other Contributor, +and only if You agree to indemnify, defend, and hold each Contributor harmless +for any liability incurred by, or claims asserted against such Contributor by +the fact You have accepted any warranty or additional liability. + +10. Acceptance of the Licence + +The provisions of this Licence can be accepted by clicking on an icon ‘I agree’ +placed under the bottom of a window displaying the text of this Licence or by +affirming consent in any other similar way, in accordance with the rules of +applicable law. Clicking on that icon indicates your clear and irrevocable +acceptance of this Licence and all of its terms and conditions. + +Similarly, you irrevocably accept this Licence and all of its terms and +conditions by exercising any rights granted to You by Article 2 of this Licence, +such as the use of the Work, the creation by You of a Derivative Work or the +Distribution or Communication by You of the Work or copies thereof. + +11. Information to the public + +In case of any Distribution or Communication of the Work by means of electronic +communication by You (for example, by offering to download the Work from a +remote location) the distribution channel or media (for example, a website) must +at least provide to the public the information requested by the applicable law +regarding the Licensor, the Licence and the way it may be accessible, concluded, +stored and reproduced by the Licensee. + +12. Termination of the Licence + +The Licence and the rights granted hereunder will terminate automatically upon +any breach by the Licensee of the terms of the Licence. + +Such a termination will not terminate the licences of any person who has +received the Work from the Licensee under the Licence, provided such persons +remain in full compliance with the Licence. + +13. Miscellaneous + +Without prejudice of Article 9 above, the Licence represents the complete +agreement between the Parties as to the Work. + +If any provision of the Licence is invalid or unenforceable under applicable +law, this will not affect the validity or enforceability of the Licence as a +whole. Such provision will be construed or reformed so as necessary to make it +valid and enforceable. + +The European Commission may publish other linguistic versions or new versions of +this Licence or updated versions of the Appendix, so far this is required and +reasonable, without reducing the scope of the rights granted by the Licence. New +versions of the Licence will be published with a unique version number. + +All linguistic versions of this Licence, approved by the European Commission, +have identical value. Parties can take advantage of the linguistic version of +their choice. + +14. Jurisdiction + +Without prejudice to specific agreement between parties, + +- any litigation resulting from the interpretation of this License, arising + between the European Union institutions, bodies, offices or agencies, as a + Licensor, and any Licensee, will be subject to the jurisdiction of the Court + of Justice of the European Union, as laid down in article 272 of the Treaty on + the Functioning of the European Union, + +- any litigation arising between other parties and resulting from the + interpretation of this License, will be subject to the exclusive jurisdiction + of the competent court where the Licensor resides or conducts its primary + business. + +15. Applicable Law + +Without prejudice to specific agreement between parties, + +- this Licence shall be governed by the law of the European Union Member State + where the Licensor has his seat, resides or has his registered office, + +- this licence shall be governed by Belgian law if the Licensor has no seat, + residence or registered office inside a European Union Member State. + +Appendix + +‘Compatible Licences’ according to Article 5 EUPL are: + +- GNU General Public License (GPL) v. 2, v. 3 +- GNU Affero General Public License (AGPL) v. 3 +- Open Software License (OSL) v. 2.1, v. 3.0 +- Eclipse Public License (EPL) v. 1.0 +- CeCILL v. 2.0, v. 2.1 +- Mozilla Public Licence (MPL) v. 2 +- GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3 +- Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for + works other than software +- European Union Public Licence (EUPL) v. 1.1, v. 1.2 +- Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong + Reciprocity (LiLiQ-R+). + +The European Commission may update this Appendix to later versions of the above +licences without producing a new version of the EUPL, as long as they provide +the rights granted in Article 2 of this Licence and protect the covered Source +Code from exclusive appropriation. + +All other changes or additions to this Appendix require the production of a new +EUPL version. diff --git a/Master/texmf-dist/doc/luatex/minim-pdf/README b/Master/texmf-dist/doc/luatex/minim-pdf/README new file mode 100644 index 00000000000..1d1f02a9135 --- /dev/null +++ b/Master/texmf-dist/doc/luatex/minim-pdf/README @@ -0,0 +1,36 @@ +Version: 2021/1.0 + +SUMMARY + +This package adds low-level support to plain LuaTeX for marking up the +structure of a PDF document. The implementation is rather basic, but should +allow you to make your PDFs fully PDF/A-compliant. + +This encompasses the following features: + + - Creating Tagged PDF + - Marking hyperlinks, bookmarks and page labels + - Marking spaces and (implicit) hyphens + - Embedding associated files + - Declaring PDF/A conformance + +Support for XMP data inclusion (another requirement of PDF/A) is provided by +a separate package, minim-xmp. + + +DOCUMENTATION + +In order to obtain the typeset manual of this package, simply say: + + luatex minim-pdf.doc + + +COPYING + +(c) 2021 Esger Renkema + +These files may be distributed under the terms of the European Union Public +Licence (EUPL) version 1.2 or later. A copy can be obtained at: + +https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + diff --git a/Master/texmf-dist/doc/luatex/minim-pdf/minim-pdf.doc b/Master/texmf-dist/doc/luatex/minim-pdf/minim-pdf.doc new file mode 100644 index 00000000000..2c06dd25b0e --- /dev/null +++ b/Master/texmf-dist/doc/luatex/minim-pdf/minim-pdf.doc @@ -0,0 +1,425 @@ + +\input minim-doc.sty + +\manual{minim-pdf} + +\ifchapter \chapter Hypertext + +This chapter and the next document the support of the modern pdf features +provided by the minim-pdf package. +Load it by saying ⟦\input minim-pdf⟧. +The next chapter concerns the creation of tagged pdf; +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} + keywords {LuaTeX; Plain TeX; PDF/A; Tagged PDF; accessibility; a11y; + hypertext; bookmarks; document outline; associated files} + stopmetadata +\maketitle + +This package adds low-level support to plain luatex for marking up the +structure of a pdf document. The implementation is rather basic, but should +allow you to make your pdfs fully pdf/a-compliant. +Load the package by saying ⟦\input minim-pdf⟧. + +The creation of tagged pdf will be described in the second half of this manual; +all other features will be covered first. + +\fi + +\section Hyperlinks % 1 + +For most simple cases, you can use +⟦*\hyperlink [name {...} | url {...}] ... \endlink⟧ for linking to a named +destination in your own document or to an external hyperlink respectively. +There is no support for nonsimple cases. + +A named destination can be created with ⟦*\nameddestination {...}⟧ (also in +horizontal mode, unlike the backend primitive) and if you cannot think of +a name, ⟦*\newdestinationname⟧ should generate a unique one. +If you need the latter twice, ⟦*\lastdestinationname⟧ gives the last +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 +say ⟦dest {name}⟧ for having it refer to a specific named destination +(otherwise, a new one will be created where the ⟦\outline⟧ command appears). + +A bookmark is automatically associated with the current structure element and +the hierarchy of structure elements determines the nesting of bookmarks. +Therefore, if you want nested bookmarks, you \emph{must} precede the ⟦\outline⟧ +command with a declaration of the current structure element, even if you have +otherwise disabled tagging. See the next chapter on how to do this. + + +\section Page labels % 1 + +If the page numbers of your document are not a simple sequence starting with~1, +you can use ⟦*\setpagelabels [pre {prefix}] style nr⟧ for communicating +this to the pdf viewer. +This command affects the page labels from the next page on: ⟦nr⟧ should be the +numerical page number of that page. +The ⟦prefix⟧ is prepended to each number and the +⟦style⟧ must be one of ⟦decimal⟧, ⟦roman⟧, ⟦Roman⟧, ⟦alphabetic⟧, ⟦Alphabetic⟧ +or ⟦none⟧. In the last case, only the prefix is used. + + +\section PDF/A % 1 + +You can declare pdf/a conformance with ⟦*\pdfalevel xy⟧, with version $\tt +x ∈ \{1,2,3\}$ and conformance level $\tt y ∈ \{a,b,u\}$. This will set the +correct pdf version and ⟦pdfaid⟧ metadata. If the conformance level is ‘⟦a⟧’, +tagging will be enabled (see the next chapter). Finally, a default RGB colour +profile will be included. +The conformance level can be queried from the ⟦*\pdfaconformancelevel⟧ register. + +Note that merely declaring conformance will not make your document pdf/a +compliant, and that minim will not warn you if it is not. +However, the features described in this chapter and the next should be enough +to make pdf/a compliance possible. + +Also note that there currently is no documented way of choosing a different +colour profile from the default (i.e. the default rgb profile provided by the +colorprofiles package). +Should you need do that, you will have to do so manually, after +disabling the automatic inclusion by saying +⟦\expandafter\let \csname minim:default:rgb:profile\endcsname = \relax⟧. + +Finally, note that pdf/a requires that spaces are represented by actual space +characters and that discretionary hyphens are marked as soft hyphens +(⟦U+00AD⟧). +Since both features benefit accessibility and text extraction in general, they +are enabled by default. +You can disable them by setting ⟦*\writehyphensandspaces⟧ to a nonpositive value. + + +\section Embedded files % 1 + +You can attach (associate) files with ⟦*\embedfile ⟧. +The file will be attached to the current structure element (see the next +chapter) unless the ⟦global⟧ option is given: then it will be added to the +document catalog. +Arguments consisting of a single word can be given without braces and +exactly one of the options ⟦file⟧ or ⟦string⟧ must be present. + +\smallskip\marktableaslist \halign{#\quad\hfil&#\hfil\cr +⟦file ⟧\hfill⟦{...}⟧ & The file to embed.\cr +⟦string ⟧\hfill⟦{...}⟧ & The string to embed.\cr +⟦global⟧ & Attach to the document catalog.\cr +⟦uncompressed⟧ & Do not compress the file stream.\cr +⟦mimetype ⟧\hfill⟦{...}⟧ & The file’s mime type.\cr +⟦moddate ⟧\hfill⟦{...}⟧\rlap{*} & The modification date (see * below).\cr +⟦desc ⟧\hfill⟦{...}⟧ & A description (the ⟦/Desc⟧ key).\cr +⟦relation ⟧\hfill⟦{...}⟧ & The ⟦/AFRelationship⟧ value as defined in pdf/a-3.\cr +⟦name ⟧\hfill⟦{...}⟧ & The file name (only required when writing a ⟦string⟧).\cr } + +* The modification date must be of the form ⟦yyyy[-m[m][-d[d]]]⟧. A default +moddate can be set with ⟦*\setembeddedfilesmoddate {default}⟧. +The ⟦default⟧ date will be expanded fully at the time of embedding. +With the minim-xmp package, a useful setting is +⟦\setembeddedfilesmoddate {\getmetadata date}⟧. + +\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. + + +%  + +\chapter Tagged PDF + +This chapter is a continuation of the previous and describes the parts of +minim-pdf that concern the creation of tagged pdf. All features in this chapter +must be explicitly enabled by setting ⟦*\writedocumentstructure⟧ to a positive +value. This will be done automatically if you declare pdf/a conformance (see +above). + +This part of the package is rather low-level and this chapter rather technical. +For a more general introduction to and discussion of tagged pdf, please read +the (excellent) manual of latex’s tagpdf package. + + +\section Purpose, limitations and pitfalls % 1 + +The main purpose of this package is semi-automatically marking up the +(hierarchical) structure of your document, thereby creating so-called tagged pdf. +The mechanism presented here is not quite as versatile as the pdf format +allows. The most important restriction is that all content of the document must +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 +errors in the resulting pdf code. +You should always check the result in an external application. + +This is the full list of limitations, pitfalls and shortcomings: +\startlist +\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 +manually, probably as artifact. +\item4. 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 +content items of themselves. +\item6. 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 +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 +ready for use with pdf~2.0. +\stoplist + +In order to help you debugging, some errors will refer you to the resulting pdf +file. If you get such errors, decompress the pdf and search for the string +‘Warning:’. It will appear in the pdf stream at the exact spot the problem +occurs. + + +\section General overview % 1 + +When speaking about tagging, we have to do with two (or perhaps three) separate +and orthogonal tagging processes. +The first is the creation of a hierarchical \emph{document structure}, made up +of \emph{structure elements} (SEs). The document structure describes the +logical structure of a document, made up of chapters, paragraphs, references +etc. +The second tagging process is the tagging of \emph{marked content items} +(MCIs): this is the partition of the actual page contents into (disjoint) +blocks that can be assigned to the proper structure element. +Finally, as a separate process, some parts of the page can be marked as +\emph{artifacts}, excluding their content from both content and structure +tagging. + +When using this package, artifacts and structure elements (excluding +paragraphs; see below) must be marked explicitly, while marked content items +will be created, marked and assigned automatically. +There is some (partial and optional) logic for automatically arranging +structure elements in their correct hierarchical relation. + +The mechanism through which this is achieved uses attributes and whatsits for +marking the contents and borders of SEs, MCIs and artifacts. At the end of the +output routine, just before the pdf page is assembled, this information will be +converted into markers inserted in the pdf stream. + + +\section Marked content items % 1 + +Content items are automatically delineated at page, artifact and structure +element boundaries and terminated at paragraph or display skips. +This should relieve you from any manual intervention. However, if you run into +problems, the commands below might be helpful. + +Use of ⟦ActualText⟧, ⟦Alt⟧ or ⟦Lang⟧ attribute on MCIs, while allowed by the +pdf standard, is not supported by this package. You should set these on the +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 +⟦*\startsinglecontentitem ... \stopsinglecontentitem⟧. +This will disable all SE and MCI tagging inside. + +Tagging (both of MCIs and SEs) can be disabled and re-enabled locally with +⟦*\stoptagging⟧ and ⟦*\starttagging⟧. + + +\section Artifacts % 1 + +Artifacts can be marked in two ways: with ⟦*\markartifact {type} {...}⟧ or with +⟦*\startartifact {type} ... \stopartifact⟧. +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, +automatically closing and re-opening content items before and after the +artifact. +While the pdf standard does not require the latter, not enforcing this seems to +confuse some pdf software. + + +\section Document structure % 1 + +Like artifacts, structure elements can be given as ⟦*\markelement {Tag} {...}⟧ +or ⟦*\startelement {Tag} ... \stopelement {Tag}⟧. +Here, in many cases the ⟦\stopelement⟧ is optional: whenever opening an element +would cause a nesting of incompatible ⟦Tag⟧s, the current element will be +closed until such a nesting is possible. +Thus, opening a ⟦TR⟧ will close the previous ⟦TR⟧, opening an ⟦H1⟧ will +automatically close any open inline or block structure elements, opening +a ⟦TOCI⟧ will close all elements up until the current ⟦TOC⟧ etc. etc. + +As a special case, the tags ⟦Document⟧, ⟦Part⟧, ⟦Art⟧, ⟦Sect⟧ and ⟦Div⟧ (and +their aliases) will try and close all open structure elements up to and +including the last structure element with the same tag. +(An alias will of course only match the same alias.) + +While the above can greatly reduce the effort of tagging, the logic is neither +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 +⟦*\ensurestopelement {Tag}⟧ instead of ⟦\stopelement⟧ +to prevent an error being raised. + +All these helpful features can also 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. + +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. +Auto-marking paragraphs can be (locally) disabled or enabled by saying +⟦*\markparagraphsfalse⟧ or ⟦*\markparagraphstrue⟧. + + +\section Structure element aliases % 1 + +New structure element tags can be created with +⟦*\addstructuretype [options] Existing Alias⟧. +This will create a new structure tag named ⟦Alias⟧ with the same properties as +⟦Existing⟧. +The properties can be modified by specifying ⟦options⟧: these will set values +of the corresponding entry in the ⟦structure_types⟧ table (see the lua source +file for this package). +Any aliases you declare will be written to the pdf’s ⟦RoleMap⟧ only if they +have actually been used. + + +\section Manipulating the logical order % 1 + +With the process outlined above, the logical order of structure elements has to +coincide with the order in which the SEs are ‘digested’ by tex. +This, together with the marked content items being assigned to structure +elements in their order of appearance, lies behind the restriction that logical +and processing orders should match. + +With manual intervention, this restriction can be relaxed somewhat. +Issuing the pair ⟦*\savecurrentelement ... \continueelement⟧ will append the +MCIs following ⟦\continueelement⟧ to the SE containing ⟦\savecurrentelement⟧. +Since the assignments made here are global, this process cannot be nested; +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 {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 +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. + + +\section Languages % 1 + +If you do not specify a language code for a structure element, its language +will be determined automatically. +In order for this to work, you must associate a language code to every used +language; you can do so with ⟦*\setlanguagecode name code⟧, where ⟦name⟧ must +be an identifier used with ⟦\uselanguage {name}⟧ and ⟦code⟧ must be a two or +three-letter language code, optionally followed by a dialect specification, +a country code, and/or some other tag. +Note that the language code is associated to a language \emph{name}, not to the +numerical value of the ⟦\language⟧ parameter. This allows you to assign +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. + +An actual language change introduced by ⟦\uselanguage⟧ will not otherwise be +acted upon by this package. Therefore, you will probably want to add +⟦\startelement{Span}⟧ after every in-line invocation of ⟦\uselanguage⟧. + +You can set the document language with ⟦*\setdocumentlanguage language-code⟧. +If unset, the language code associated with the first ⟦\uselanguage⟧ statement +will be used, or else ⟦und⟧ (undetermined). The only function of the document +language is that it is mentioned in the pdf catalog: it has no other influence. + +New languages can be declared with ⟦*\newnamedlanguage {name} {lhm} {rhm}⟧ and +new dialects with ⟦*\newnameddialect {language name} {dialect name}⟧. +Dialects will use the same hyphenation patterns (and will indeed have the same +⟦\language⟧ value) as their parent languages; newly declared languages will +start with no hyphenation patterns. +Do note that you will probably also have to specify language codes for new +languages or dialects. + +This package ensures the existence of the ⟦nohyph⟧, ⟦nolang⟧, ⟦uncoded⟧ and +⟦undetermined⟧ dummy languages, all without hyphenation. + + +\section Helper macros + +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 +tags in the correct way. (The ⟦dest⟧ is a link destination and can be empty; +the ⟦lbl⟧ is a section number and can also be empty.) + +For marking up tables, a whole array of helper macros is available. First, +⟦*\marktable⟧ should be given \emph{before} the ⟦\halign⟧. +Then, in the template, the first cell should start with ⟦*\marktablerow⟧ and +each subsequent cell with ⟦*\marktablecell⟧. +If your table starts with a header, insert ⟦*\marktableheader⟧ before it and +⟦*\marktablebody⟧ after. +Before a table footer, insert ⟦*\marktablefooter⟧. + +For greater convenience, insert just ⟦*\automarktable⟧ before the ⟦\halign⟧. +Then you can leave out all the above commands (unless you ⟦\omit⟧ a template of +course). +This assumes the table has a single header row and more than one column. +If you use a table for typesetting a list, you can use ⟦*\marktableaslist⟧ +instead, which marks the first column as list label and the second column as +list item. Of course, this only works with two-column tables. + +Finally, you can auto-tag equations as formulas by specifing +⟦*\autotagformulas⟧. This is especially dangerous, because sometimes equations +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 name of this file can be changed by redefining ⟦*\formulafilename⟧ inside +the equation. + + +%  + +\endmanual + diff --git a/Master/texmf-dist/doc/luatex/minim-pdf/minim-pdf.pdf b/Master/texmf-dist/doc/luatex/minim-pdf/minim-pdf.pdf new file mode 100644 index 00000000000..b460bdf4ed8 Binary files /dev/null and b/Master/texmf-dist/doc/luatex/minim-pdf/minim-pdf.pdf differ -- cgit v1.2.3