add new tutorial how to create PDF/A files with fpdf2 (#1383)

* chore: new tutorial for PDF/A creation

* chore: just to please black with tuto7

* chore: just to please black

* chore: black ignore import

* chore: test noqa: E0401 with black

* Update tuto7.py

disable Pylonen message

* Update tuto7.py

disable Import error with # pylint: disable=import-error

* Update tutorial/tuto7.py

Co-authored-by: Lucas Cimon <925560+Lucas-C@users.noreply.github.com>

* Update tutorial/tuto7.py

Co-authored-by: Lucas Cimon <925560+Lucas-C@users.noreply.github.com>

* Update tutorial/tuto7.py

Co-authored-by: Lucas Cimon <925560+Lucas-C@users.noreply.github.com>

* Update CHANGELOG.md

Co-authored-by: Lucas Cimon <925560+Lucas-C@users.noreply.github.com>

* Update tutorial/tuto7.py

Co-authored-by: Lucas Cimon <925560+Lucas-C@users.noreply.github.com>

* chore: removed assets directory, moved sRGB2014.icc to tutorial directory; enhanced tutorials with language and subject comment

---------

Co-authored-by: Lka <herbert@lischka-berlin.de>
Co-authored-by: Lucas Cimon <925560+Lucas-C@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -18,6 +18,7 @@ This can also be enabled programmatically with `warnings.simplefilter('default',
 
 ## [2.8.3] - Not released yet
 ### Added
+* added tutorial "tuto7" (in [English](https://py-pdf.github.io/fpdf2/Tutorial.html#tuto-7-creating-pdfa-documents) and [German](https://py-pdf.github.io/fpdf2/Tutorial-de.html#tuto-7-ein-pdfa-dokument-erstellen)) with documentation to create PDF/A files with fpdf2
 * support for [Output Intents](https://py-pdf.github.io/fpdf2/Images.html#output-intents) on document level
 * support for [shading patterns (gradients)](https://py-pdf.github.io/fpdf2/Patterns.html) - thanks to @andersonhc - [PR #1334](https://github.com/py-pdf/fpdf2/pull/1334)
 * support for [setting a minimal row height in tables](https://py-pdf.github.io/fpdf2/Tables.html#setting-row-height)

docs/Tutorial-de.md

@@ -188,3 +188,60 @@ Um einen internen Link hinzuzufügen, der auf die zweite Seite verweist, nutzen
 Um einen externen Link mit Hilfe eines Bildes zu erstellen, verwenden wir [`image()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.image). Es besteht die Möglichkeit, der Methode ein Linkziel als eines ihrer Argumente zu übergeben. Der Link kann sowohl einer interner als auch ein externer sein.
 
 Eine weitere Möglichkeit, den Schriftstil zu ändern und Links hinzuzufügen, stellt die Verwendung der Methode `write_html()` dar. Sie ist ein HTML-Parser, der das Hinzufügen von Text, Änderung des Schriftstils und Erstellen von Links mittels HTML ermöglicht.
+
+## Tuto 7 - Ein PDF/A Dokument erstellen ##
+
+### PDF/A Standards ###
+
+<b>PDF/A-1</b> basiert auf der PDF-Version 1.4. Alle Ressourcen (Bilder, Grafiken, Fonts) müssen im Document eingebettet werden. Erforderlich sind präzise und Plattform unabhängig kodierte Farbangaben mittels ICC-Profilen sowie die Verwendung von XMP für die Dokument-Metadata.
+
+<b>PDF/A-2</b> basiert auf PDF-Version 1.7. Es erlaubt die Kompression mit JPEG2000, transparente Elemente, OpenType Fonts and digitale Signaturen.
+
+Die einzige Erweiterung für <b>PDF/A-3</b> besteht aus der Möglichkeit, beliebige Dateien einzubetten.
+
+### Conformance Classes ###
+
+Stufe A (Zugänglichkeit) umfasst sämtliche Anforderungen des Standards inklusive Abbildung der inhaltlichen Struktur und korrekter Lesereihenfolge des Dokumentinhalts. Textinhalte müssen extrahierbar sein und die Struktur muss die natürliche Leseabfolge abbilden.
+
+Stufe B (Basic) garantiert eine eindeutige visuelle Reproduzierbarkeit der Inhalte. Stufe B lässt sich meist einfacher generieren als Stufe A, gewährleistet aber nicht zu 100 Prozent Textextraktion oder -durchsuchbarkeit. Eine problemlose Wiederverwendung des Inhalts ist nicht unbedingt gegeben.
+
+Hier ein kleines Beispiel um das zu erreichen:
+
+```python
+{% include "../tutorial/tuto7.py" %}
+```
+
+[Resulting PDF](https://github.com/py-pdf/fpdf2/raw/master/tutorial/tuto7.pdf) -
+[fpdf2-logo](https://raw.githubusercontent.com/py-pdf/fpdf2/master/docs/fpdf2-logo.png)
+
+
+```python
+pdf = PDF()
+```
+
+Die Klasse PDF fügt die benötigten Fonts mit Hilfe der Funktion
+[add_font()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.add_font)
+in das Dokument ein.
+
+Dann fügt es ein ICC Profil ein und erstellt mit Hilfe der Funktion
+[add_output_intent()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.output_intent)
+das Output Intents Verzeichnis.
+
+Nachdem wir eine erste Seite einegfüllt, den eingebetteten Font ausgewählt, und etwas Text erzeugt haben, erstellen wir das PDF mit der Funktion:
+```python
+pdf.create_pdf_with_metadata(
+    filename="tuto7.pdf",
+    language="en-US",
+    title="Tutorial7",
+    subject="Example for PDFA",
+    creator=["John Dow", "Jane Dow"],
+    description="this is my description of this file",
+    keywords="Example Tutorial7"
+    )
+```
+
+Dabei benutzen wir pikepdf um die nötigen Metadata zu erzeugen und den Typen auf PDF/A-3B zu setzen.
+
+In der Funktion `create_pdf_with_metadata` setzen wir 'language' und 'subject' ausserhalb der Metadata bevor wir pikepdf aufrufen um, die Konformität zu erreichen.
+
+Bitte benutzen Sie ein Programm, wie z.B. verapdf, um die Konformität des erstellten PDF zu sicherzustellen.

docs/Tutorial.md

@@ -233,3 +233,60 @@ To create the external link using an image, we used
 As an alternative, another option to change the font style and add links is to
  use the `write_html()` method. It is an html parser, which allows adding text,
  changing font style and adding links using html.
+
+## Tuto 7 - Creating PDF/A Documents ##
+
+### PDF/A Standards ###
+
+<b>PDF/A-1</b> uses PDF-Version 1.4. All resources (pictures, graphics, fonts) must be embedded in the document. The color management must be precise and platform independently specified with ICC-Profiles and the document metadata must be given with XMP-Metadata.
+
+<b>PDF/A-2</b> uses PDF-Version 1.7. It allows compression with JPEG2000, transparent elements, open type fonts and digital signatures.
+
+The only extension for <b>PDF/A-3</b> is the possibility to embed any possible file.
+
+### Conformance Classes ###
+
+Level A (accessible) encompasses all the requirements of the standard, including mapping the content structure and the correct reading order of the document content. Text content must be extractable, and the structure must reflect the natural reading sequence.
+
+Level B (Basic) guarantees a clear visual reproducibility of the content. Level B is generally easier to generate than Level A, but it does not ensure 100 percent text extraction or searchability. The hassle-free reuse of the content is not necessarily given.
+
+To achieve this, here a little example:
+
+```python
+{% include "../tutorial/tuto7.py" %}
+```
+
+[Resulting PDF](https://github.com/py-pdf/fpdf2/raw/master/tutorial/tuto7.pdf) -
+[fpdf2-logo](https://raw.githubusercontent.com/py-pdf/fpdf2/master/docs/fpdf2-logo.png)
+
+
+```python
+pdf = PDF()
+```
+
+The class PDF adds the needed embedded fonts using the
+[add_font()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.add_font)
+method for each style.
+
+Then it adds the ICC profile object to the output intents array using the
+[add_output_intent()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.output_intent)
+method.
+
+After adding first page, using the embedded font, writing some text, we create the pdf:
+```python
+pdf.create_pdf_with_metadata(
+    filename="tuto7.pdf",
+    language="en-US",
+    title="Tutorial7",
+    subject="Example for PDFA",
+    creator=["John Dow", "Jane Dow"],
+    description="this is my description of this file",
+    keywords="Example Tutorial7"
+    )
+```
+
+Here we use pikepdf to create the needed metadata and set the type to PDF/A-3B.
+
+In the function `create_pdf_with_metadata` we need to set 'language' and 'subject' outside the metadata before we use pikepdf to achieve conformance.
+
+Please use something like verapdf to check conformance of resulting PDF.

tutorial/sRGB2014.icc

@@ -0,0 +1,112 @@
+from pathlib import Path
+from fpdf import FPDF
+from fpdf.enums import OutputIntentSubType
+from fpdf.output import PDFICCProfileObject
+from fpdf import FPDF_VERSION
+from datetime import datetime, timezone
+import pikepdf  # pylint: disable=import-error
+
+
+DIR = Path(__file__).parent
+FONT_DIR = DIR / ".." / "test" / "fonts"
+
+
+class PDF(FPDF):
+
+    def create_pdf_with_metadata(
+        self,
+        filename: str,
+        language: str = None,
+        title: str = None,
+        subject: str = None,
+        creator: list = None,
+        description: str = None,
+        keywords: str = None,
+    ):
+        if language:
+            self.set_lang(language)
+        if subject:
+            self.set_subject(subject)
+
+        # create pdf
+        self.output(filename)
+
+        with pikepdf.open(filename, allow_overwriting_input=True) as inner_pdf:
+            with inner_pdf.open_metadata(set_pikepdf_as_editor=False) as meta:
+                if title:
+                    meta["dc:title"] = title
+                if creator:
+                    meta["dc:creator"] = creator
+                if description:
+                    meta["dc:description"] = description
+                if keywords:
+                    meta["pdf:Keywords"] = keywords
+                meta["pdf:Producer"] = f"py-pdf/fpdf{FPDF_VERSION}"
+                meta["xmp:CreatorTool"] = __file__
+                meta["xmp:CreateDate"] = datetime.now(timezone.utc).isoformat()
+                meta["pdfaid:part"] = "3"
+                meta["pdfaid:conformance"] = "B"
+            inner_pdf.save()
+
+
+pdf = PDF()
+
+# import and embed TTF Font to use in text
+pdf.add_font("dejavu-sans", style="", fname=FONT_DIR / "DejaVuSans.ttf")
+pdf.add_font(
+    "dejavu-sans",
+    style="b",
+    fname=FONT_DIR / "DejaVuSans-Bold.ttf",
+)
+pdf.add_font(
+    "dejavu-sans",
+    style="i",
+    fname=FONT_DIR / "DejaVuSans-Oblique.ttf",
+)
+pdf.add_font(
+    "dejavu-sans",
+    style="bi",
+    fname=FONT_DIR / "DejaVuSans-BoldOblique.ttf",
+)
+# set Output Intents
+with open(DIR / "sRGB2014.icc", "rb") as iccp_file:
+    icc_profile = PDFICCProfileObject(
+        contents=iccp_file.read(), n=3, alternate="DeviceRGB"
+    )
+pdf.add_output_intent(
+    OutputIntentSubType.PDFA,
+    "sRGB",
+    "IEC 61966-2-1:1999",
+    "http://www.color.org",
+    icc_profile,
+    "sRGB2014 (v2)",
+)
+# First page:
+pdf.add_page()
+# use the font imported
+# and set style and size for H1
+pdf.set_font("dejavu-sans", "B", size=20)
+pdf.write(text="Header 1")
+# print empty lines
+pdf.ln()
+pdf.ln()
+# reset style and set size for normal Text
+pdf.set_font(None, "", size=12)
+pdf.write(text="this is an example")
+# print empty lines
+pdf.ln()
+pdf.ln()
+# set style for Text 2 to italic
+pdf.set_font(None, "I")
+pdf.write(text="this is the second example")
+
+# create pdf with metadata
+pdf.create_pdf_with_metadata(
+    filename="tuto7.pdf",
+    language="en-US",
+    title="Tutorial7",
+    subject="Example for PDFA",
+    creator=["John Dow", "Jane Dow"],
+    description="this is my description of this file",
+    keywords="Example Tutorial7",
+)