@laminapdf/sdk 0.2.0-alpha.2 → 0.2.0-alpha.4

package/docs/pages/recipes/multilingual.md

@@ -0,0 +1,196 @@
+---
+title: "Multilingual text"
+description: "Latin, Arabic, Devanagari, Hebrew and Chinese on one page, each in its own embedded font, as a shaped line and a wrapped paragraph."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/recipes/multilingual/"
+---
+
+# Multilingual text
+
+Latin, Arabic, Devanagari, Hebrew and Chinese on one page, each in its own embedded font, as a shaped line and a wrapped paragraph.
+
+You'll put five scripts on one page: Latin, Arabic, Devanagari, Hebrew and Chinese, each as a single line and as a paragraph wrapped in a box. Start from it whenever your text goes beyond Latin, or mixes left-to-right and right-to-left writing.
+
+The function takes one font file per script, draws each script's line and paragraph, and returns the PDF's bytes. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+**TypeScript**
+
+`packages/sdk/examples/multilingual.ts`:
+
+```ts
+// Five scripts on one page, each as a single line and as a wrapped paragraph. The scripts are
+// Latin, Arabic and Hebrew (right to left), Devanagari and simplified Chinese; each is shaped and
+// bidi-resolved, and each paragraph wraps in a text box. Each script needs a font that covers it,
+// such as the Noto fonts (OFL).
+import { Builder, type BuilderOptions, type Direction, Font } from "@laminapdf/sdk";
+
+/** Each script's line, its paragraph and the paragraph's direction, in the order of the fonts. */
+export const SCRIPTS: readonly (readonly [line: string, paragraph: string, direction: Direction])[] = [
+  [
+    "Latin: the office staff fill the affine waffle flask",
+    "A paragraph breaks at spaces and fits the width of its box, line by line.",
+    "ltr",
+  ],
+  ["مرحبا بالعالم السلام عليكم", "مرحبا بالعالم السلام عليكم مرحبا بالعالم السلام عليكم", "rtl"],
+  ["नमस्ते दुनिया। हिन्दी पाठ का परीक्षण", "नमस्ते दुनिया। हिन्दी पाठ का परीक्षण नमस्ते दुनिया।", "ltr"],
+  ["שלום עולם וברוכים הבאים", "שלום עולם וברוכים הבאים שלום עולם וברוכים הבאים", "rtl"],
+  ["你好世界，这是中文字体子集测试。", "你好世界，这是中文字体子集测试。你好世界，这是中文。", "ltr"],
+];
+const MARGIN = 56;
+const FIRST_BASELINE = 80;
+/** The distance from one script's line to the next one's. */
+const SCRIPT_HEIGHT = 140;
+/** The paragraph's box: this far below the line, this wide and this tall. */
+const PARAGRAPH_DROP = 14;
+const PARAGRAPH_WIDTH = 220;
+const PARAGRAPH_HEIGHT = 100;
+
+/**
+ * The document's bytes. Needs `init({ text: true })`.
+ *
+ * @param fonts - one font file per script, in the order of {@link SCRIPTS}.
+ * @param options - can fix the file ID, the producer and the creation date.
+ */
+export function multilingual(fonts: readonly Uint8Array[], options: BuilderOptions = {}): Uint8Array<ArrayBuffer> {
+  if (fonts.length !== SCRIPTS.length) throw new Error(`${SCRIPTS.length} fonts, one per script, are needed`);
+  using b = new Builder(options);
+  const loaded = fonts.map((bytes) => Font.fromBytes(bytes));
+  for (const font of loaded) b.font(font);
+  const page = b.page("A4");
+  const s = page.surface();
+  SCRIPTS.forEach(([line, paragraph, direction], row) => {
+    const font = loaded[row];
+    if (font === undefined) return;
+    const y = FIRST_BASELINE + SCRIPT_HEIGHT * row;
+    s.text(line, { font, size: 16, at: [MARGIN, y] });
+    // A narrow box breaks the paragraph into lines; right-to-left paragraphs start at the right.
+    const box = [MARGIN, y + PARAGRAPH_DROP, PARAGRAPH_WIDTH, PARAGRAPH_HEIGHT] as const;
+    s.textBox(paragraph, { font, size: 12, box, direction, align: "start" });
+  });
+  page.finish();
+  using doc = b.finish();
+  return doc.save();
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/multilingual.rs`:
+
+````rust
+//! Five scripts on one page, each as a single line and as a wrapped paragraph.
+//!
+//! The scripts are Latin, Arabic and Hebrew (right to left), Devanagari and simplified Chinese;
+//! each is shaped and bidi-resolved, and each paragraph wraps in a text box. Each script needs a
+//! font that covers it, such as the Noto fonts (OFL).
+//!
+//! ```sh
+//! cargo run -p laminapdf --example multilingual -- latin.ttf arabic.ttf devanagari.ttf hebrew.ttf chinese.otf
+//! ```
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    Alignment, BuildOptions, Builder, Direction, PageSize, PointPt, Pt, RectPt, SaveOptions, TextBoxOptions,
+};
+
+/// Each script's line, its paragraph and the paragraph's direction, in the order of the fonts.
+const SCRIPTS: [(&str, &str, Direction); 5] = [
+    (
+        "Latin: the office staff fill the affine waffle flask",
+        "A paragraph breaks at spaces and fits the width of its box, line by line.",
+        Direction::LeftToRight,
+    ),
+    (
+        "مرحبا بالعالم السلام عليكم",
+        "مرحبا بالعالم السلام عليكم مرحبا بالعالم السلام عليكم",
+        Direction::RightToLeft,
+    ),
+    (
+        "नमस्ते दुनिया। हिन्दी पाठ का परीक्षण",
+        "नमस्ते दुनिया। हिन्दी पाठ का परीक्षण नमस्ते दुनिया।",
+        Direction::LeftToRight,
+    ),
+    (
+        "שלום עולם וברוכים הבאים",
+        "שלום עולם וברוכים הבאים שלום עולם וברוכים הבאים",
+        Direction::RightToLeft,
+    ),
+    (
+        "你好世界，这是中文字体子集测试。",
+        "你好世界，这是中文字体子集测试。你好世界，这是中文。",
+        Direction::LeftToRight,
+    ),
+];
+const MARGIN: f64 = 56.0;
+const FIRST_BASELINE: f64 = 80.0;
+/// The distance from one script's line to the next one's.
+const SCRIPT_HEIGHT: f64 = 140.0;
+/// The paragraph's box: this far below the line, this wide and this tall.
+const PARAGRAPH_DROP: f64 = 14.0;
+const PARAGRAPH_WIDTH: f64 = 220.0;
+const PARAGRAPH_HEIGHT: f64 = 100.0;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut args: Vec<String> = std::env::args().skip(1).collect();
+    let out = PathBuf::from(if args.len() > SCRIPTS.len() {
+        args.remove(SCRIPTS.len())
+    } else {
+        "target/examples-out".into()
+    });
+    let fonts = args.iter().map(std::fs::read).collect::<Result<Vec<_>, _>>()?;
+    std::fs::create_dir_all(&out)?;
+    std::fs::write(out.join("multilingual.pdf"), build(BuildOptions::new(), fonts)?)?;
+    Ok(())
+}
+
+/// The document's bytes, with one font per script in `fonts` (in the order of [`SCRIPTS`]).
+/// `options` can fix the file ID, the producer and the creation date.
+pub(crate) fn build(options: BuildOptions, fonts: Vec<Vec<u8>>) -> Result<Vec<u8>, Box<dyn Error>> {
+    if fonts.len() != SCRIPTS.len() {
+        return Err(format!("{} fonts, one per script, are needed", SCRIPTS.len()).into());
+    }
+    let mut b = Builder::new(options);
+    let fonts = fonts
+        .into_iter()
+        .map(|bytes| b.font_bytes(bytes))
+        .collect::<Result<Vec<_>, _>>()?;
+    let mut page = b.page(PageSize::A4);
+    let s = page.surface();
+    for (row, ((line, paragraph, direction), font)) in (0_u32..).zip(SCRIPTS.iter().zip(&fonts)) {
+        let y = FIRST_BASELINE + SCRIPT_HEIGHT * f64::from(row);
+        s.text(line, font, Pt::new(16.0), PointPt::from_points(MARGIN, y))?;
+        // A narrow box breaks the paragraph into lines; right-to-left paragraphs start at the right.
+        let options = TextBoxOptions::new()
+            .with_direction(*direction)
+            .with_align(Alignment::Start);
+        let area = RectPt::from_points(MARGIN, y + PARAGRAPH_DROP, PARAGRAPH_WIDTH, PARAGRAPH_HEIGHT);
+        s.text_box(paragraph, font, Pt::new(12.0), area, &options)?;
+    }
+    page.finish()?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+````
+
+**Result:** [multilingual.pdf](https://docs.laminapdf.com/examples/pdf/multilingual.pdf)
+
+The result is one A4 page, with each script set in its own Noto font. The Result tab shows it, with a link to the PDF.
+
+## How it works
+
+- `Font.fromBytes` (`font_bytes` in Rust) loads each font, which must cover its script. The builder embeds only the glyphs the page draws.
+- Lamina PDF shapes the text with each font, so Arabic letters join, Devanagari letters combine into clusters and the Latin line forms ligatures.
+- `textBox` breaks each paragraph into lines that fit its 220-point-wide box. It breaks where Unicode's line-breaking rules allow: between words, and between Chinese characters.
+- `direction: "rtl"` (`Direction::RightToLeft`) makes the Arabic and Hebrew paragraphs right to left, so `align: "start"` starts their lines at the box's right edge.
+- Each font is embedded with its [ToUnicode](../../pages/reference/glossary.md#tounicode) mapping, so text copied or extracted from the PDF equals the strings you passed in, ligatures included.
+
+## What to change
+
+- **Your own scripts:** change `SCRIPTS` and pass one font per row, in the same order. A character the font lacks fails with `missing-glyph`.
+- **The paragraph's box:** `PARAGRAPH_WIDTH` and `PARAGRAPH_HEIGHT` set its size. Lines that don't fit are left out, unless you pass `overflow: "error"` (`Overflow::Error`) to fail with `text-overflow` instead.
+- **Alignment and spacing:** `align` also takes `"end"`, `"left"`, `"right"` or `"center"`, and `lineHeight` (`with_line_height`) sets the distance between baselines, 1.2 times the size by default.
+- **Ligatures and other OpenType features:** `features: ["liga=0"]` on `text` or `textBox` turns the ligatures off. In Rust, call `features` on the run or `with_feature` on the text box's options. See [Text and fonts](../../pages/guides/fonts-and-text.md).
+
+Next: [images and vectors](../../pages/recipes/images-and-vectors.md), with shapes, colour, transparency and two images.

package/docs/pages/recipes/open-untrusted.md

@@ -0,0 +1,65 @@
+---
+title: "Open someone else's file"
+description: "Open an uploaded PDF with an optional password and tighter limits, and get its page count and warnings, or the error, back as a value."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/recipes/open-untrusted/"
+---
+
+# Open someone else's file
+
+Open an uploaded PDF with an optional password and tighter limits, and get its page count and warnings, or the error, back as a value.
+
+You'll open a PDF from someone else, with a password if it needs one and tighter limits than the defaults, and get the outcome as a value. You need this wherever you accept uploads: a stranger's file can be damaged, locked or built to use up memory.
+
+The function opens the bytes under its limits and returns the page count and warning codes, or the error's code and hint:
+
+`packages/sdk/examples/open-untrusted.ts`:
+
+```ts
+// Open bytes from someone else: an optional password, tighter limits than the defaults, and the
+// outcome as a value rather than an exception. The example writes nothing: it returns what it found.
+import { Document, isLaminaPdfError } from "@laminapdf/sdk";
+
+const MiB = 1024 * 1024;
+/** Limits for an upload endpoint: each decoded stream, and all of them together. */
+const LIMITS = { maxStreamDecoded: 16 * MiB, maxDecodedTotal: 64 * MiB } as const;
+
+/** What opening a file gave: its page count and warning codes, or why it didn't open. */
+export type Opened =
+  | { readonly ok: true; readonly pages: number; readonly warnings: readonly string[] }
+  | { readonly ok: false; readonly code: string; readonly hint: string | undefined };
+
+/** Opens `bytes`, with `password` if the file needs one, under {@link LIMITS}. Needs `init()`. */
+export function openUntrusted(bytes: Uint8Array, password?: string): Opened {
+  try {
+    using doc = Document.open(bytes, { ...(password === undefined ? {} : { password }), limits: LIMITS });
+    // Repairs and dropped values are warnings: the file opened, but not exactly as written.
+    return { ok: true, pages: doc.pageCount, warnings: doc.warnings.map((w) => w.code) };
+  } catch (e) {
+    // `password-required`, `wrong-password`, `not-pdf`, `limit-exceeded`, …: a coded error whose
+    // message and hint never contain text from the file. Anything else is a bug: let it throw.
+    if (isLaminaPdfError(e)) return { ok: false, code: e.code, hint: e.hint };
+    throw e;
+  }
+}
+```
+
+It writes no PDF. The value it returns is the result: `{ ok: true, pages, warnings }` for a file that opened, or `{ ok: false, code, hint }`, such as `password-required` for a locked file opened without its password.
+
+## How it works
+
+- It needs only `init()`: opening a file uses the base module, without fonts or text.
+- `Document.open` gets the password only when you pass one, and tries it against both of the file's passwords. See [Open password-protected files](../../pages/guides/password-protected-files.md).
+- `LIMITS` allows 16 MiB decoded from one stream and 64 MiB in all, against defaults of 64 MiB and 1 GiB. A file that needs more fails with `limit-exceeded`, and every other limit keeps its default.
+- A file can open and still carry warnings: each one names a repair or a dropped value, and the function returns their codes.
+- `isLaminaPdfError(e)` picks out Lamina PDF's coded errors, whose message and hint never contain text from the file. Any other error is a bug, so the function throws it again.
+- `using` frees the document as soon as the function returns, so the WebAssembly side keeps no copy of the file.
+
+## What to change
+
+- **Ask for the password again:** on `password-required` or `wrong-password`, ask your user and call `openUntrusted` again with their answer.
+- **Name the limit:** on `limit-exceeded`, return `e.data?.limit` too. It names the limit the file went over as Rust spells it, such as `max_stream_decoded` for `maxStreamDecoded`.
+- **Other limits:** add any limit from the table in [Open files you don't trust](../../pages/guides/untrusted-files.md#hard-and-soft-limits), such as a lower `maxNestingDepth`.
+- **Refuse damaged files:** add `strict: true` to the options, and a file that needs repair fails with `strict` instead of opening with warnings.
+
+Next: [save in a Web Worker](../../pages/recipes/web-worker-client.md), so a large file never freezes the page.

package/docs/pages/recipes/pdf-a-archive.md

@@ -0,0 +1,212 @@
+---
+title: "A PDF/A archive"
+description: "An order confirmation for long-term archiving, written as PDF/A-2b and as PDF/A-2u that is also PDF/UA-1, with an embedded font and a photo."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/recipes/pdf-a-archive/"
+---
+
+# A PDF/A archive
+
+An order confirmation for long-term archiving, written as PDF/A-2b and as PDF/A-2u that is also PDF/UA-1, with an embedded font and a photo.
+
+You'll write a letter confirming an order as a PDF/A file, which looks the same in any viewer for decades. You need it for documents kept for years, often by law: contracts, records, letters to customers. The recipe writes the letter twice, at two PDF/A levels.
+
+The function takes the level, `2b` or `2u`, and builds the same letter under that level's profiles. In TypeScript it needs the text module, `init({ text: true })`. Both languages write the same bytes:
+
+**TypeScript**
+
+`packages/sdk/examples/pdf-a-archive.ts`:
+
+```ts
+// An archival letter, written as PDF/A-2b and as PDF/A-2u that is also PDF/UA-1.
+import { Builder, Font, Image, PAGE_SIZES, type Profile, type Surface } from "@laminapdf/sdk";
+
+const MARGIN = 56;
+const BAND_HEIGHT = 70;
+const TITLE_BASELINE = 110;
+/** The top of the letter's text and of the photo beside it, and the height of both. */
+const BLOCK_TOP = 130;
+const BLOCK_HEIGHT = 120;
+const LETTER_WIDTH = 300;
+const PHOTO_LEFT = 380;
+const PHOTO_WIDTH = 160;
+const FOOTER_BASELINE = 300;
+const TITLE = 22;
+const BODY = 11;
+const BAND_OPACITY = 0.35;
+const PHOTO_ALT = "A photograph of the sprockets, packed in a box";
+const LETTER =
+  "Thank you for your order of 12 sprockets. This letter confirms the delivery date and the price we agreed. " +
+  "Keep it: PDF/A files look the same in any viewer, now and in the future.";
+
+/** PDF/A-2b, or PDF/A-2u (whose text maps to Unicode) with PDF/UA-1. */
+const PROFILES: Record<"2b" | "2u", Profile[]> = {
+  "2b": ["PDF/A-2b"],
+  "2u": ["PDF/A-2u", "PDF/UA-1"],
+};
+
+/**
+ * The letter's bytes. Needs `init({ text: true })`.
+ *
+ * @param level - `2b` or `2u`.
+ * @param notoSans - the bytes of the Noto Sans font file.
+ * @param photo - the bytes of a JPEG photo.
+ */
+export function pdfAArchive(level: "2b" | "2u", notoSans: Uint8Array, photo: Uint8Array): Uint8Array<ArrayBuffer> {
+  using b = new Builder({ profiles: PROFILES[level], tagged: true });
+  b.metadata({ title: "Order confirmation 42", author: "Acme Widgets Ltd" });
+  b.lang("en-GB");
+  const font = Font.fromBytes(notoSans);
+  b.font(font);
+  const page = b.page("A4");
+  draw(page.surface(), font, Image.jpeg(photo));
+  page.finish();
+  using doc = b.finish();
+  return doc.save();
+}
+
+function draw(s: Surface, font: Font, photo: Image): void {
+  // A translucent band across the top: decoration, and transparency, which PDF/A-2 allows.
+  const [width] = PAGE_SIZES.A4;
+  s.artifact("layout", (s) => {
+    s.save().opacity(BAND_OPACITY, 1).fillColor([0.12, 0.47, 0.78]);
+    s.path((p) => p.rect([0, 0, width, BAND_HEIGHT])).fill();
+    s.restore();
+  });
+  s.tag("H1", (s) => s.text("Order confirmation 42", { font, size: TITLE, at: [MARGIN, TITLE_BASELINE] }));
+  s.tag("P", (s) => s.textBox(LETTER, { font, size: BODY, box: [MARGIN, BLOCK_TOP, LETTER_WIDTH, BLOCK_HEIGHT] }));
+  s.image(photo, [PHOTO_LEFT, BLOCK_TOP, PHOTO_WIDTH, BLOCK_HEIGHT], PHOTO_ALT);
+  s.tag("P", (s) =>
+    s.text("Acme Widgets Ltd, 1 Example Street, London", { font, size: BODY, at: [MARGIN, FOOTER_BASELINE] }),
+  );
+}
+```
+
+**Rust**
+
+`crates/laminapdf/examples/pdf_a_archive.rs`:
+
+```rust
+//! An archival letter, written as PDF/A-2b and as PDF/A-2u that is also PDF/UA-1.
+//!
+//! Run it with `cargo run -p laminapdf --example pdf_a_archive -- <font.ttf> <photo.jpg> [out-dir]`: it writes
+//! `pdf_a_archive-2b.pdf` and `pdf_a_archive-2u.pdf`.
+
+use std::error::Error;
+use std::path::PathBuf;
+
+use laminapdf::{
+    ArtifactKind, BuildError, BuildOptions, Builder, Color, FillRule, FontHandle, Image, Metadata, PageSize, PointPt,
+    Profile, Pt, RectPt, SaveOptions, Surface, TagKind, TextBoxOptions,
+};
+
+const MARGIN: f64 = 56.0;
+const BAND_HEIGHT: f64 = 70.0;
+const TITLE_AT: PointPt = PointPt::from_points(MARGIN, 110.0);
+/// The top of the letter's text and of the photo beside it, and the height of both.
+const BLOCK_TOP: f64 = 130.0;
+const BLOCK_HEIGHT: f64 = 120.0;
+const LETTER_WIDTH: f64 = 300.0;
+const PHOTO_LEFT: f64 = 380.0;
+const PHOTO_WIDTH: f64 = 160.0;
+const FOOTER_AT: PointPt = PointPt::from_points(MARGIN, 300.0);
+const TITLE: Pt = Pt::new(22.0);
+const BODY: Pt = Pt::new(11.0);
+const BAND_OPACITY: f64 = 0.35;
+const PHOTO_ALT: &str = "A photograph of the sprockets, packed in a box";
+const LETTER: &str = "Thank you for your order of 12 sprockets. This letter confirms the delivery date and the \
+                      price we agreed. Keep it: PDF/A files look the same in any viewer, now and in the future.";
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut args = std::env::args().skip(1);
+    let usage = "arguments: <font.ttf> <photo.jpg> [out-dir]";
+    let font = std::fs::read(args.next().ok_or(usage)?)?;
+    let photo = std::fs::read(args.next().ok_or(usage)?)?;
+    let out = PathBuf::from(args.next().unwrap_or_else(|| "target/examples-out".into()));
+    std::fs::create_dir_all(&out)?;
+    let a2b = build(Level::A2b, font.clone(), photo.clone())?;
+    std::fs::write(out.join("pdf_a_archive-2b.pdf"), a2b)?;
+    let a2u = build(Level::A2u, font, photo)?;
+    Ok(std::fs::write(out.join("pdf_a_archive-2u.pdf"), a2u)?)
+}
+
+/// Which archive to write.
+#[derive(Debug, Clone, Copy)]
+pub(crate) enum Level {
+    /// PDF/A-2b: the letter looks the same everywhere.
+    A2b,
+    /// PDF/A-2u, whose text maps to Unicode, and PDF/UA-1.
+    A2u,
+}
+
+/// The letter's bytes, in `font` (a TrueType or OpenType file) with `photo` (a JPEG).
+pub(crate) fn build(level: Level, font: Vec<u8>, photo: Vec<u8>) -> Result<Vec<u8>, Box<dyn Error>> {
+    let options = match level {
+        Level::A2b => BuildOptions::new().with_profile(Profile::PdfA2b),
+        Level::A2u => BuildOptions::new()
+            .with_profile(Profile::PdfA2u)
+            .with_profile(Profile::PdfUa1),
+    };
+    let mut b = Builder::new(options.with_tagged(true));
+    b.metadata(
+        Metadata::default()
+            .with_title("Order confirmation 42")
+            .with_author("Acme Widgets Ltd"),
+    );
+    b.lang("en-GB");
+    let font = b.font_bytes(font)?;
+    let photo = Image::jpeg(photo)?;
+    let mut page = b.page(PageSize::A4);
+    draw(page.surface(), &font, &photo)?;
+    page.finish()?;
+    let mut doc = b.finish()?;
+    Ok(doc.save(&SaveOptions::new())?.bytes)
+}
+
+fn draw(s: &mut Surface, font: &FontHandle, photo: &Image) -> Result<(), BuildError> {
+    // A translucent band across the top: decoration, and transparency, which PDF/A-2 allows.
+    let width = PageSize::A4.width.get();
+    s.artifact(ArtifactKind::Layout, |s| {
+        s.save()
+            .opacity(BAND_OPACITY, 1.0)
+            .fill_color(Color::rgb(0.12, 0.47, 0.78));
+        s.path(|p| _ = p.rect(RectPt::from_points(0.0, 0.0, width, BAND_HEIGHT)))
+            .fill(FillRule::NonZero);
+        s.restore();
+        Ok(())
+    })?;
+    s.tag(TagKind::H1, |s| {
+        s.text("Order confirmation 42", font, TITLE, TITLE_AT).map(drop)
+    })?;
+    let body = RectPt::from_points(MARGIN, BLOCK_TOP, LETTER_WIDTH, BLOCK_HEIGHT);
+    s.tag(TagKind::P, |s| {
+        s.text_box(LETTER, font, BODY, body, &TextBoxOptions::new()).map(drop)
+    })?;
+    let beside = RectPt::from_points(PHOTO_LEFT, BLOCK_TOP, PHOTO_WIDTH, BLOCK_HEIGHT);
+    s.figure(photo, beside, Some(PHOTO_ALT));
+    let footer = "Acme Widgets Ltd, 1 Example Street, London";
+    s.tag(TagKind::P, |s| s.text(footer, font, BODY, FOOTER_AT).map(drop))
+}
+```
+
+**Result:** [pdf_a_archive-2b.pdf](https://docs.laminapdf.com/examples/pdf/pdf_a_archive-2b.pdf), [pdf_a_archive-2u.pdf](https://docs.laminapdf.com/examples/pdf/pdf_a_archive-2u.pdf)
+
+The result is one A4 letter under a translucent blue band, with a photo beside its text: the Result tab shows both versions, PDF/A-2b and PDF/A-2u, with links to the PDFs.
+
+## How it works
+
+- PDF/A-2b makes the letter look the same everywhere. PDF/A-2u also maps every glyph to Unicode, so the text can be searched and copied. That copy is PDF/UA-1 too, so a screen reader can follow it.
+- PDF/A needs every font embedded, so the letter uses Noto Sans rather than one of the [standard 14 fonts](../../pages/reference/glossary.md#standard-14-fonts). `finish()` checks rules like this one and fails with a coded error for the first one the letter breaks.
+- The builder writes what PDF/A asks for: the PDF/A identification in the file's XMP metadata, and an sRGB output intent that says what its RGB colours mean. See [What PDF/A asks for](../../pages/guides/archival-pdfs.md#what-pdfa-asks-for).
+- Both copies draw the same tagged content: an `H1` title, `P` paragraphs and the photo as a figure with alternate text. PDF/A-2b doesn't ask for tags, but PDF/UA-1 does.
+- The blue band is drawn at 35% opacity, as a layout artifact that screen readers skip. PDF/A-2 allows transparency.
+- `textBox` breaks the letter into lines inside its box, beside the photo. The JPEG goes into the file as it is.
+
+## What to change
+
+- **The letter:** change `LETTER`. `textBox` leaves out lines that don't fit, so make `BLOCK_HEIGHT` larger for a longer letter, or pass `overflow: "error"` to fail with `text-overflow` instead.
+- **The photo:** pass any RGB or gray JPEG, or `Image.png(bytes)` for a PNG (`Image::png` in Rust). A CMYK JPEG fails `finish()` with `device-color-without-output-intent`, because the output intent is sRGB.
+- **Other profiles:** pass the ones you need, such as `["PDF/A-2u"]` alone or `["PDF/A-2b", "PDF/UA-1"]`. A document can claim PDF/UA-1 and at most one PDF/A profile.
+- **An attached file:** PDF/A-2 refuses attachments, so switch to PDF/A-3b, as the [PDF/A-3 invoice](../../pages/recipes/pdf-a3-invoice-with-xml.md) does.
+
+Next: [a PDF/A-3 invoice with XML](../../pages/recipes/pdf-a3-invoice-with-xml.md), with its data attached for software to read.