From b11f3d35073663c016556660abf3545ef10c12b0 Mon Sep 17 00:00:00 2001 From: tannevaled Date: Sun, 25 Oct 2026 23:18:14 +0100 Subject: [PATCH] go-slides/slides v0.13.0: version strings, the tagged PDF in seven languages params.slides.version is v0.13.0 (published under /docs/0.13/); every page that says which version it describes says v0.13.0, in the seven languages. The tagged PDF is "since v0.12.0" (was "after v0.9.0"), and its section, merged in English only while the translations were in review, is now translated in fr, de, es, zh, ko and ja. The i18n check passes with -strict. Co-Authored-By: Claude Sonnet 5.5 --- README.md | 2 +- content/de/_index.md | 6 +++--- content/de/cli.md | 34 +++++++++++++++++++++++++++++++++- content/de/getting-started.md | 2 +- content/de/playground.md | 2 +- content/en/_index.md | 6 +++--- content/en/cli.md | 4 ++-- content/en/getting-started.md | 2 +- content/en/playground.md | 2 +- content/es/_index.md | 6 +++--- content/es/cli.md | 35 ++++++++++++++++++++++++++++++++++- content/es/getting-started.md | 2 +- content/es/playground.md | 2 +- content/fr/_index.md | 6 +++--- content/fr/cli.md | 33 ++++++++++++++++++++++++++++++++- content/fr/getting-started.md | 2 +- content/fr/playground.md | 2 +- content/ja/_index.md | 6 +++--- content/ja/cli.md | 33 ++++++++++++++++++++++++++++++++- content/ja/getting-started.md | 2 +- content/ja/playground.md | 2 +- content/ko/_index.md | 6 +++--- content/ko/cli.md | 34 +++++++++++++++++++++++++++++++++- content/ko/getting-started.md | 2 +- content/ko/playground.md | 2 +- content/zh/_index.md | 6 +++--- content/zh/cli.md | 31 ++++++++++++++++++++++++++++++- content/zh/getting-started.md | 2 +- content/zh/playground.md | 2 +- hugo.yaml | 2 +- 30 files changed, 233 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 107400a..bcc8ebc 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ A version of the documentation is **the minor version of | the newest release (else `main`) | also `https://go-slides.github.io/docs/latest/` | `https://go-slides.github.io/docs/` redirects to `latest/`. The pages describe -v0.9.0 (`params.slides.version`) and are published under `0.9/`. At the next +v0.13.0 (`params.slides.version`) and are published under `0.13/`. At the next minor release: set `params.slides.version` to its tag and check every page against that release (flags from its `slides -h`). diff --git a/content/de/_index.md b/content/de/_index.md index 0cbd709..01f8993 100644 --- a/content/de/_index.md +++ b/content/de/_index.md @@ -18,9 +18,9 @@ den Folien, `![bg]`-Hintergründe, Sprechernotizen, die Themes `default`, `gaia` (`title`, `section` …), statt immer wieder zu wiederholen, wie sie aussieht. {{< callout type="warning" >}} -**v0.9.0.** Diese Seiten beschreiben -[go-slides/slides v0.9.0](https://github.com/go-slides/slides/releases/tag/v0.9.0) -und sind unter `/docs/0.9/` veröffentlicht. +**v0.13.0.** Diese Seiten beschreiben +[go-slides/slides v0.13.0](https://github.com/go-slides/slides/releases/tag/v0.13.0) +und sind unter `/docs/0.13/` veröffentlicht. {{< /callout >}} ## Was es heute kann {#what-it-does-today} diff --git a/content/de/cli.md b/content/de/cli.md index 1be3f1f..74e5c74 100644 --- a/content/de/cli.md +++ b/content/de/cli.md @@ -6,7 +6,7 @@ tags: [cli] --- {{< callout type="warning" >}} -Diese Seite beschreibt v0.9.0. +Diese Seite beschreibt v0.13.0. {{< /callout >}} ```text @@ -326,6 +326,38 @@ wird als Bitmap nur dieses Elements gezeichnet, mit unsichtbar darübergelegtem auswählbar bleibt. Formeln sind weiterhin Bitmaps. `--pdf-raster` schreibt ein Bild pro Seite, wie es v0.3.0 tat. +### Barrierefreies, getaggtes PDF {#accessible-tagged-pdf} + +Seit v0.12.0 ist das Vektor-PDF getaggt. Es trägt seine logische Struktur, die ein +Screenreader der Reihe nach liest, wie er eine Webseite liest: + +| Im Foliensatz | Im PDF | +| --- | --- | +| eine Folie | ein Abschnitt (`Sect`) | +| `#` … `######` | `H1` … `H6` | +| ein Absatz, eine Liste, eine Tabelle | `P`; `L` mit Marke und Inhalt jedes Eintrags; `Table`, Kopfzellen mit ihrem Bezugsbereich | +| ein Link | ein `Link`, einschließlich seiner anklickbaren Fläche, sein Text als Beschreibung | +| ein Bild | eine `Figure` mit ihrem Alternativtext; `![](…)` ohne Alternativtext ist Dekoration | +| `$…$`, `$$…$$` | eine `Formula`, ihr TeX-Quelltext als Beschreibung | +| Code | `Code`, ohne Zeilennummern und Callout-Scheiben | +| `` | ein Span in dieser Sprache | +| Hintergründe, Rahmen, Seitenzahlen | Artefakte, die ein Reader überspringt | +| Sprechernotizen (`--pdf-notes`) | Annotationen in der Struktur | + +Die Datei deklariert PDF/UA-1, den Standard für barrierefreies PDF. Sie trägt den +`title` des Foliensatzes, den der Viewer anzeigt, und seine `lang` (`--lang`, wenn der +Foliensatz keine setzt, sonst `en`). + +Ein mit veraPDF geprüfter Foliensatz besteht PDF/UA-1, es sei denn, seine eigenen +Überschriften verletzen die Reihenfolge des Standards. PDF/UA verlangt, dass die erste +Überschrift eine `H1` ist und keine Ebene übersprungen wird (`#`, dann `###`). Das kann +nur der Autor des Foliensatzes beheben. Das PDF von Chrome für denselben Foliensatz, das +marp-cli schreibt, ist ebenfalls getaggt, verletzt aber sieben Regeln von PDF/UA, hat +keinen Abschnitt pro Folie und keine Formeln. + +Das Taggen des Benchmark-Foliensatzes mit 100 Folien kostet 4 % an Größe (788 gegenüber +757 KiB) und keine messbare Zeit. `--pdf-tags=false` schreibt das PDF ohne Tags. + ## `slides.yaml` {#slidesyaml} Eine Konfigurationsdatei neben dem Foliensatz gilt für ihn, sodass sich ein Ordner voller Foliensätze diff --git a/content/de/getting-started.md b/content/de/getting-started.md index ab33347..1dd7553 100644 --- a/content/de/getting-started.md +++ b/content/de/getting-started.md @@ -14,7 +14,7 @@ go install github.com/go-slides/slides/cmd/slides@latest ``` `slides` ist ein einzelnes statisches Go-Binary ohne cgo: Sie müssen nichts weiter installieren, kein -Node, kein Chrome. Diese Seite beschreibt v0.9.0. +Node, kein Chrome. Diese Seite beschreibt v0.13.0. ## Ein erster Foliensatz {#a-first-deck} diff --git a/content/de/playground.md b/content/de/playground.md index b723d35..99eb8e5 100644 --- a/content/de/playground.md +++ b/content/de/playground.md @@ -7,7 +7,7 @@ tags: [playground, browser] **[Playground öffnen →](https://go-slides.github.io/playground/)** -Der Playground ist go-slides selbst, v0.9.0, nach WebAssembly kompiliert und +Der Playground ist go-slides selbst, v0.13.0, nach WebAssembly kompiliert und in Ihrem Browser ausgeführt. Tippen Sie links einen Foliensatz; rechts folgen die Folien. Nichts wird an einen Server gesendet: weder der Foliensatz noch ein Link zum Teilen. diff --git a/content/en/_index.md b/content/en/_index.md index 7e117e3..9cbb85f 100644 --- a/content/en/_index.md +++ b/content/en/_index.md @@ -18,9 +18,9 @@ slides, `![bg]` backgrounds, speaker notes, the `default`, `gaia` and (`title`, `section`…) instead of repeating how it looks. {{< callout type="warning" >}} -**v0.9.0.** These pages describe -[go-slides/slides v0.9.0](https://github.com/go-slides/slides/releases/tag/v0.9.0) -and are published under `/docs/0.9/`. +**v0.13.0.** These pages describe +[go-slides/slides v0.13.0](https://github.com/go-slides/slides/releases/tag/v0.13.0) +and are published under `/docs/0.13/`. {{< /callout >}} ## What it does today diff --git a/content/en/cli.md b/content/en/cli.md index db9d7e8..43abb2a 100644 --- a/content/en/cli.md +++ b/content/en/cli.md @@ -6,7 +6,7 @@ tags: [cli] --- {{< callout type="warning" >}} -This page describes v0.9.0. +This page describes v0.13.0. {{< /callout >}} ```text @@ -332,7 +332,7 @@ per page, as v0.3.0 did. ### Accessible, tagged PDF -After v0.9.0 the vector PDF is tagged. It carries its logical structure, which +Since v0.12.0 the vector PDF is tagged. It carries its logical structure, which a screen reader reads in order, as it reads a web page: | In the deck | In the PDF | diff --git a/content/en/getting-started.md b/content/en/getting-started.md index aa9095c..64156d8 100644 --- a/content/en/getting-started.md +++ b/content/en/getting-started.md @@ -14,7 +14,7 @@ go install github.com/go-slides/slides/cmd/slides@latest ``` `slides` is one static Go binary with no cgo: nothing else to install, no -Node, no Chrome. This page describes v0.9.0. +Node, no Chrome. This page describes v0.13.0. ## A first deck diff --git a/content/en/playground.md b/content/en/playground.md index 6c04b9b..dd1db32 100644 --- a/content/en/playground.md +++ b/content/en/playground.md @@ -7,7 +7,7 @@ tags: [playground, browser] **[Open the playground →](https://go-slides.github.io/playground/)** -The playground is go-slides itself, v0.9.0, compiled to WebAssembly and +The playground is go-slides itself, v0.13.0, compiled to WebAssembly and running in your browser. Type a deck on the left; the slides follow on the right. Nothing is sent to a server: not the deck, not a share link. diff --git a/content/es/_index.md b/content/es/_index.md index 0a54ac0..608e467 100644 --- a/content/es/_index.md +++ b/content/es/_index.md @@ -20,9 +20,9 @@ tiene: que es (`title`, `section`…) en lugar de repetir cómo se ve. {{< callout type="warning" >}} -**v0.9.0.** Estas páginas describen -[go-slides/slides v0.9.0](https://github.com/go-slides/slides/releases/tag/v0.9.0) -y se publican en `/docs/0.9/`. +**v0.13.0.** Estas páginas describen +[go-slides/slides v0.13.0](https://github.com/go-slides/slides/releases/tag/v0.13.0) +y se publican en `/docs/0.13/`. {{< /callout >}} ## Qué hace hoy {#what-it-does-today} diff --git a/content/es/cli.md b/content/es/cli.md index 5ea1be1..c8d0701 100644 --- a/content/es/cli.md +++ b/content/es/cli.md @@ -6,7 +6,7 @@ tags: [cli] --- {{< callout type="warning" >}} -Esta página describe v0.9.0. +Esta página describe v0.13.0. {{< /callout >}} ```text @@ -355,6 +355,39 @@ dibuja como un mapa de bits solo de ese elemento, con su texto superpuesto de forma invisible para que siga siendo seleccionable. Las fórmulas siguen siendo mapas de bits. `--pdf-raster` escribe una imagen por página, como hacía v0.3.0. +### PDF accesible y etiquetado {#accessible-tagged-pdf} + +Desde v0.12.0 el PDF vectorial está etiquetado. Lleva su estructura lógica, que +un lector de pantalla lee en orden, como lee una página web: + +| En la presentación | En el PDF | +| --- | --- | +| una diapositiva | una sección (`Sect`) | +| `#` … `######` | `H1` … `H6` | +| un párrafo, una lista, una tabla | `P`; `L` con la etiqueta y el cuerpo de cada elemento; `Table`, con celdas de encabezado y su ámbito | +| un enlace | un `Link`, con su área clicable incluida y su texto como descripción | +| una imagen | una `Figure` con su texto alternativo; `![](…)` sin texto alternativo es decoración | +| `$…$`, `$$…$$` | una `Formula`, con su código fuente TeX como descripción | +| código | `Code`, sin sus números de línea ni sus círculos de llamada | +| `` | un tramo en ese idioma | +| fondos, bordes, números de página | artefactos, que un lector omite | +| notas del orador (`--pdf-notes`) | anotaciones en la estructura | + +El archivo declara PDF/UA-1, el estándar del PDF accesible. Lleva el `title` de +la presentación, que el visor muestra, y su `lang` (`--lang` cuando la +presentación no define ninguno, `en` en caso contrario). + +Una presentación verificada con veraPDF cumple PDF/UA-1, salvo que sus propios +encabezados rompan el orden del estándar. PDF/UA exige que el primer encabezado +sea un `H1` y que no se salte ningún nivel (`#` y luego `###`). Solo el autor de +la presentación puede corregirlo. El PDF de Chrome de la misma presentación, el +que escribe marp-cli, también está etiquetado, pero incumple siete de las reglas +de PDF/UA, no tiene una sección por diapositiva ni fórmulas. + +Etiquetar la presentación de prueba de 100 diapositivas cuesta un 4 % de tamaño +(788 frente a 757 KiB) y ningún tiempo medible. `--pdf-tags=false` escribe el PDF +sin etiquetas. + ## `slides.yaml` {#slidesyaml} Un archivo de configuración junto a la presentación se aplica a ella, de modo que diff --git a/content/es/getting-started.md b/content/es/getting-started.md index a8f17e8..cb29932 100644 --- a/content/es/getting-started.md +++ b/content/es/getting-started.md @@ -14,7 +14,7 @@ go install github.com/go-slides/slides/cmd/slides@latest ``` `slides` es un único binario estático de Go, sin cgo: no hay nada más que -instalar, ni Node ni Chrome. Esta página describe v0.9.0. +instalar, ni Node ni Chrome. Esta página describe v0.13.0. ## Una primera presentación {#a-first-deck} diff --git a/content/es/playground.md b/content/es/playground.md index fe62a3f..284e405 100644 --- a/content/es/playground.md +++ b/content/es/playground.md @@ -7,7 +7,7 @@ tags: [playground, browser] **[Abrir el playground →](https://go-slides.github.io/playground/)** -El playground es el propio go-slides, v0.9.0, compilado a WebAssembly y +El playground es el propio go-slides, v0.13.0, compilado a WebAssembly y ejecutándose en su navegador. Escriba una presentación a la izquierda; las diapositivas la siguen a la derecha. No se envía nada a ningún servidor: ni la presentación, ni un enlace para compartir. diff --git a/content/fr/_index.md b/content/fr/_index.md index 3ca6db5..85d85bc 100644 --- a/content/fr/_index.md +++ b/content/fr/_index.md @@ -18,9 +18,9 @@ les diapositives, les arrière-plans `![bg]`, les notes de l'orateur, les thème (`title`, `section`…) au lieu de répéter à quoi elle ressemble. {{< callout type="warning" >}} -**v0.9.0.** Ces pages décrivent -[go-slides/slides v0.9.0](https://github.com/go-slides/slides/releases/tag/v0.9.0) -et sont publiées sous `/docs/0.9/`. +**v0.13.0.** Ces pages décrivent +[go-slides/slides v0.13.0](https://github.com/go-slides/slides/releases/tag/v0.13.0) +et sont publiées sous `/docs/0.13/`. {{< /callout >}} ## Ce qu'il fait aujourd'hui {#what-it-does-today} diff --git a/content/fr/cli.md b/content/fr/cli.md index 66b3c4a..4e1373c 100644 --- a/content/fr/cli.md +++ b/content/fr/cli.md @@ -6,7 +6,7 @@ tags: [cli] --- {{< callout type="warning" >}} -Cette page décrit la v0.9.0. +Cette page décrit la v0.13.0. {{< /callout >}} ```text @@ -330,6 +330,37 @@ dessiné comme un bitmap de ce seul élément, son texte étant posé dessus de rester sélectionnable. Les formules sont encore des bitmaps. `--pdf-raster` écrit une image par page, comme le faisait la v0.3.0. +### PDF accessible et balisé {#accessible-tagged-pdf} + +Depuis la v0.12.0, le PDF vectoriel est balisé. Il porte sa structure logique, qu'un lecteur +d'écran lit dans l'ordre, comme il lit une page web : + +| Dans la présentation | Dans le PDF | +| --- | --- | +| une diapositive | une section (`Sect`) | +| `#` … `######` | `H1` … `H6` | +| un paragraphe, une liste, un tableau | `P` ; `L` avec l'étiquette et le corps de chaque élément ; `Table`, cellules d'en-tête avec leur portée | +| un lien | un `Link`, sa zone cliquable comprise, son texte comme description | +| une image | une `Figure` avec son texte alternatif ; `![](…)` sans texte alternatif est décoratif | +| `$…$`, `$$…$$` | une `Formula`, sa source TeX comme description | +| du code | `Code`, sans ses numéros de ligne ni ses pastilles d'annotation | +| `` | un segment dans cette langue | +| arrière-plans, bordures, numéros de page | des artefacts, qu'un lecteur ignore | +| notes de l'orateur (`--pdf-notes`) | des annotations dans la structure | + +Le fichier déclare PDF/UA-1, la norme du PDF accessible. Il porte le `title` de la +présentation, que la visionneuse affiche, et sa `lang` (`--lang` si la présentation +n'en définit pas, `en` sinon). + +Une présentation vérifiée avec veraPDF satisfait PDF/UA-1, sauf si ses propres titres enfreignent +l'ordre qu'impose la norme. PDF/UA demande que le premier titre soit un `H1` et +qu'aucun niveau ne soit sauté (`#` puis `###`). Seul l'auteur de la présentation peut corriger cela. +Le PDF de Chrome pour la même présentation, celui qu'écrit marp-cli, est lui aussi balisé, mais enfreint +sept des règles de PDF/UA, n'a pas de section par diapositive et pas de formules. + +Baliser la présentation de référence de 100 diapositives coûte 4% en taille (788 contre 757 Kio) +et aucun temps mesurable. `--pdf-tags=false` écrit le PDF sans balises. + ## `slides.yaml` {#slidesyaml} Un fichier de configuration placé à côté de la présentation s'y applique : un dossier de présentations diff --git a/content/fr/getting-started.md b/content/fr/getting-started.md index 4ee751a..bea1465 100644 --- a/content/fr/getting-started.md +++ b/content/fr/getting-started.md @@ -14,7 +14,7 @@ go install github.com/go-slides/slides/cmd/slides@latest ``` `slides` est un binaire Go statique, sans cgo : rien d'autre à installer, ni -Node ni Chrome. Cette page décrit la v0.9.0. +Node ni Chrome. Cette page décrit la v0.13.0. ## Une première présentation {#a-first-deck} diff --git a/content/fr/playground.md b/content/fr/playground.md index 8c45d2c..555b7de 100644 --- a/content/fr/playground.md +++ b/content/fr/playground.md @@ -7,7 +7,7 @@ tags: [playground, browser] **[Ouvrir le playground →](https://go-slides.github.io/playground/)** -Le playground, c'est go-slides lui-même, en v0.9.0, compilé en WebAssembly et +Le playground, c'est go-slides lui-même, en v0.13.0, compilé en WebAssembly et exécuté dans votre navigateur. Tapez une présentation à gauche ; les diapositives suivent à droite. Rien n'est envoyé à un serveur : ni la présentation, ni un lien de partage. diff --git a/content/ja/_index.md b/content/ja/_index.md index f56aa2a..a666d4f 100644 --- a/content/ja/_index.md +++ b/content/ja/_index.md @@ -16,9 +16,9 @@ description: "純粋な Go（CGO=0）で書かれた Marp 互換のスライド （`title`、`section`…）を宣言します。 {{< callout type="warning" >}} -**v0.9.0。** このページ群は -[go-slides/slides v0.9.0](https://github.com/go-slides/slides/releases/tag/v0.9.0) -について説明しており、`/docs/0.9/` で公開されています。 +**v0.13.0。** このページ群は +[go-slides/slides v0.13.0](https://github.com/go-slides/slides/releases/tag/v0.13.0) +について説明しており、`/docs/0.13/` で公開されています。 {{< /callout >}} ## 現在できること {#what-it-does-today} diff --git a/content/ja/cli.md b/content/ja/cli.md index 3494e93..cd9f05c 100644 --- a/content/ja/cli.md +++ b/content/ja/cli.md @@ -6,7 +6,7 @@ tags: [cli] --- {{< callout type="warning" >}} -このページは v0.9.0 について説明しています。 +このページは v0.13.0 について説明しています。 {{< /callout >}} ```text @@ -323,6 +323,37 @@ marp-cli の 837 KiB、v0.3.0 の画像 PDF の 10 MiB と比べて小さく、0 数式は現在もビットマップです。`--pdf-raster` は、v0.3.0 と同じくページごとに 1 枚の画像を 書き出します。 +### アクセシブルなタグ付き PDF {#accessible-tagged-pdf} + +v0.12.0 以降、ベクター PDF にはタグが付きます。PDF は論理構造を持ち、スクリーンリーダーは +Web ページを読むのと同じように、それを順番に読み上げます： + +| スライドデッキでは | PDF では | +| --- | --- | +| スライド | セクション（`Sect`） | +| `#` … `######` | `H1` … `H6` | +| 段落、リスト、表 | `P`。各項目のラベルと本文を持つ `L`。`Table` と、スコープ付きの見出しセル | +| リンク | クリック領域を含む `Link`。そのテキストが説明になります | +| 画像 | 代替テキスト付きの `Figure`。代替テキストのない `![](…)` は装飾として扱われます | +| `$…$`、`$$…$$` | `Formula`。その TeX ソースが説明になります | +| コード | 行番号やコールアウトの丸数字を除いた `Code` | +| `` | その言語のスパン | +| 背景、枠線、ページ番号 | アーティファクト（読み上げ時にスキップされます） | +| スピーカーノート（`--pdf-notes`） | 構造内の注釈 | + +ファイルは、アクセシブルな PDF の規格である PDF/UA-1 への準拠を宣言します。また、ビューアーに +表示されるスライドデッキの `title` と、その `lang`（スライドデッキで指定されていなければ `--lang`、 +それもなければ `en`）を持ちます。 + +veraPDF で検査したスライドデッキは、見出し自体が規格の順序に反していない限り、PDF/UA-1 に合格します。 +PDF/UA では、最初の見出しが `H1` であり、レベルを飛ばさない（`#` の次に `###` としない）ことが +求められます。これを直せるのはスライドデッキの作成者だけです。marp-cli が書き出す、同じスライドデッキの +Chrome の PDF にもタグは付いていますが、PDF/UA のルールのうち 7 つに違反し、スライドごとのセクションも +数式もありません。 + +100 枚のベンチマーク用スライドデッキにタグを付けるコストは、サイズで 4%（757 KiB に対して 788 KiB）で、 +時間は計測できないほどわずかです。`--pdf-tags=false` は、タグなしの PDF を書き出します。 + ## `slides.yaml` {#slidesyaml} スライドデッキと同じ場所にある設定ファイルはそのスライドデッキに適用されるので、フォルダー内の diff --git a/content/ja/getting-started.md b/content/ja/getting-started.md index bac0f1f..6b3f36e 100644 --- a/content/ja/getting-started.md +++ b/content/ja/getting-started.md @@ -14,7 +14,7 @@ go install github.com/go-slides/slides/cmd/slides@latest ``` `slides` は cgo を使わない単一の静的 Go バイナリです。ほかにインストールするものはなく、 -Node も Chrome も不要です。このページは v0.9.0 について説明しています。 +Node も Chrome も不要です。このページは v0.13.0 について説明しています。 ## 最初のスライドデッキ {#a-first-deck} diff --git a/content/ja/playground.md b/content/ja/playground.md index 9e539ad..a1f971f 100644 --- a/content/ja/playground.md +++ b/content/ja/playground.md @@ -7,7 +7,7 @@ tags: [playground, browser] **[Playground を開く →](https://go-slides.github.io/playground/)** -Playground は go-slides v0.9.0 そのものを WebAssembly にコンパイルし、 +Playground は go-slides v0.13.0 そのものを WebAssembly にコンパイルし、 ブラウザー内で動かしたものです。左側にスライドデッキを入力すると、右側にスライドが追従して表示されます。 スライドデッキも共有リンクも、サーバーには何も送信されません。 diff --git a/content/ko/_index.md b/content/ko/_index.md index 53f97b4..e4eb107 100644 --- a/content/ko/_index.md +++ b/content/ko/_index.md @@ -18,9 +18,9 @@ description: "순수 Go(CGO=0)로 만드는 Marp 호환 프레젠테이션. Go 보이는지를 반복하는 대신 자신이 무엇인지(`title`, `section`…)를 밝힙니다. {{< callout type="warning" >}} -**v0.9.0.** 이 문서는 -[go-slides/slides v0.9.0](https://github.com/go-slides/slides/releases/tag/v0.9.0)을 -설명하며 `/docs/0.9/` 아래에 게시됩니다. +**v0.13.0.** 이 문서는 +[go-slides/slides v0.13.0](https://github.com/go-slides/slides/releases/tag/v0.13.0)을 +설명하며 `/docs/0.13/` 아래에 게시됩니다. {{< /callout >}} ## 현재 지원하는 기능 {#what-it-does-today} diff --git a/content/ko/cli.md b/content/ko/cli.md index 3be0414..73d64fe 100644 --- a/content/ko/cli.md +++ b/content/ko/cli.md @@ -6,7 +6,7 @@ tags: [cli] --- {{< callout type="warning" >}} -이 페이지는 v0.9.0을 기준으로 설명합니다. +이 페이지는 v0.13.0을 기준으로 설명합니다. {{< /callout >}} ```text @@ -337,6 +337,38 @@ v0.4.0부터 PDF는 벡터로 그려집니다. go-webengine이 레이아웃된 합니다. 수식은 아직 비트맵입니다. `--pdf-raster`는 v0.3.0처럼 페이지마다 이미지 한 장을 씁니다. +### 접근성 있는 태그 PDF {#accessible-tagged-pdf} + +v0.12.0부터 벡터 PDF에는 태그가 붙습니다. PDF에 논리 구조가 담기므로, 화면 +낭독기는 웹 페이지를 읽을 때처럼 이를 순서대로 읽습니다. + +| 프레젠테이션에서 | PDF에서 | +| --- | --- | +| 슬라이드 | 섹션(`Sect`) | +| `#` … `######` | `H1` … `H6` | +| 문단, 목록, 표 | `P`, 항목마다 레이블과 본문이 있는 `L`, 머리글 셀에 범위가 지정된 `Table` | +| 링크 | 클릭 영역을 포함하고 텍스트를 설명으로 갖는 `Link` | +| 이미지 | 대체 텍스트를 갖는 `Figure`. 대체 텍스트가 없는 `![](…)`는 장식으로 처리 | +| `$…$`, `$$…$$` | TeX 소스를 설명으로 갖는 `Formula` | +| 코드 | 줄 번호와 콜아웃 원을 뺀 `Code` | +| `` | 해당 언어의 스팬 | +| 배경, 테두리, 페이지 번호 | 낭독기가 건너뛰는 아티팩트 | +| 발표자 노트(`--pdf-notes`) | 구조 안의 주석 | + +파일은 접근성 있는 PDF의 표준인 PDF/UA-1을 선언합니다. 뷰어가 표시하는 +프레젠테이션의 `title`과, `lang`(프레젠테이션에 지정이 없으면 `--lang`, 그것도 +없으면 `en`)을 담습니다. + +veraPDF로 검사한 프레젠테이션은 PDF/UA-1을 통과합니다. 단, 프레젠테이션 자체의 +제목이 표준의 순서를 어기는 경우는 예외입니다. PDF/UA는 첫 제목이 `H1`이어야 하고 +수준을 건너뛰지 않아야 한다고(`#` 다음에 `###`) 요구합니다. 이는 프레젠테이션 +작성자만 고칠 수 있습니다. marp-cli가 만드는 같은 프레젠테이션의 Chrome PDF에도 +태그가 있지만, PDF/UA 규칙 일곱 가지를 어기고, 슬라이드별 섹션도 수식도 없습니다. + +슬라이드 100장 벤치마크 프레젠테이션에 태그를 붙이면 크기가 4% 늘어나며(757 KiB +대비 788 KiB) 측정할 만한 시간은 들지 않습니다. `--pdf-tags=false`는 태그 없는 +PDF를 씁니다. + ## `slides.yaml` {#slidesyaml} 프레젠테이션 옆의 설정 파일이 그 프레젠테이션에 적용되므로, 한 폴더의 diff --git a/content/ko/getting-started.md b/content/ko/getting-started.md index 983e2c7..a85ec3f 100644 --- a/content/ko/getting-started.md +++ b/content/ko/getting-started.md @@ -14,7 +14,7 @@ go install github.com/go-slides/slides/cmd/slides@latest ``` `slides`는 cgo를 쓰지 않는 정적 Go 바이너리 하나입니다. Node도 Chrome도 필요 -없고, 따로 설치할 것이 없습니다. 이 페이지는 v0.9.0을 기준으로 설명합니다. +없고, 따로 설치할 것이 없습니다. 이 페이지는 v0.13.0을 기준으로 설명합니다. ## 첫 프레젠테이션 {#a-first-deck} diff --git a/content/ko/playground.md b/content/ko/playground.md index e5815de..9fce165 100644 --- a/content/ko/playground.md +++ b/content/ko/playground.md @@ -7,7 +7,7 @@ tags: [playground, browser] **[Playground 열기 →](https://go-slides.github.io/playground/)** -Playground는 WebAssembly로 컴파일되어 브라우저에서 실행되는 go-slides v0.9.0 +Playground는 WebAssembly로 컴파일되어 브라우저에서 실행되는 go-slides v0.13.0 그 자체입니다. 왼쪽에 프레젠테이션을 입력하면 오른쪽에 슬라이드가 따라 나타납니다. 프레젠테이션도, 공유 링크도 서버로 전송되지 않습니다. diff --git a/content/zh/_index.md b/content/zh/_index.md index 78c6021..f646d0e 100644 --- a/content/zh/_index.md +++ b/content/zh/_index.md @@ -18,9 +18,9 @@ Marp 没有的功能： （`title`、`section`…），而不必反复描述自己的外观。 {{< callout type="warning" >}} -**v0.9.0。** 本文档描述的是 -[go-slides/slides v0.9.0](https://github.com/go-slides/slides/releases/tag/v0.9.0)， -发布于 `/docs/0.9/` 下。 +**v0.13.0。** 本文档描述的是 +[go-slides/slides v0.13.0](https://github.com/go-slides/slides/releases/tag/v0.13.0)， +发布于 `/docs/0.13/` 下。 {{< /callout >}} ## 现有功能 {#what-it-does-today} diff --git a/content/zh/cli.md b/content/zh/cli.md index 6d14c98..28c4baa 100644 --- a/content/zh/cli.md +++ b/content/zh/cli.md @@ -6,7 +6,7 @@ tags: [cli] --- {{< callout type="warning" >}} -本页描述的是 v0.9.0。 +本页描述的是 v0.13.0。 {{< /callout >}} ```text @@ -288,6 +288,35 @@ v0.3.0 的图片 PDF 为 10 MiB，写出耗时 0.3 s。 透明度渐变的渐变色）只会将该元素绘制为位图，其上覆盖不可见的文本，以保持可选中。 公式目前仍是位图。`--pdf-raster` 与 v0.3.0 一样，每页写出一张图片。 +### 无障碍的带标签 PDF {#accessible-tagged-pdf} + +自 v0.12.0 起，矢量 PDF 带有标签。它包含文档的逻辑结构，屏幕阅读器会按顺序朗读， +就像朗读网页一样： + +| 演示文稿中 | PDF 中 | +| --- | --- | +| 一张幻灯片 | 一个节（`Sect`） | +| `#` … `######` | `H1` … `H6` | +| 段落、列表、表格 | `P`；`L`，包含每一项的标号和正文；`Table`，表头单元格带有其作用范围 | +| 链接 | `Link`，包含其可点击区域，以其文本作为描述 | +| 图片 | `Figure`，带有替代文本；没有替代文本的 `![](…)` 视为装饰 | +| `$…$`、`$$…$$` | `Formula`，以其 TeX 源码作为描述 | +| 代码 | `Code`，不含行号和标注圆点 | +| `` | 使用该语言的文本片段 | +| 背景、边框、页码 | 工件（artifact），阅读器会跳过 | +| 演讲者备注（`--pdf-notes`） | 结构中的批注 | + +该文件声明符合 PDF/UA-1，即无障碍 PDF 的标准。它包含演示文稿的 `title`（由阅读器显示） +及其 `lang`（演示文稿未设置时取 `--lang`，否则为 `en`）。 + +用 veraPDF 检查的演示文稿可以通过 PDF/UA-1，除非其自身的标题违反了标准规定的层级顺序。 +PDF/UA 要求第一个标题为 `H1`，且不得跳级（如 `#` 之后直接 `###`）。这只能由演示文稿的作者修正。 +同一演示文稿由 Chrome 生成的 PDF（marp-cli 写出的就是它）也带有标签，但违反了 PDF/UA 的 +七条规则，没有按幻灯片划分的节，也没有公式。 + +为 100 张幻灯片的基准演示文稿添加标签，体积增加 4%（788 KiB 对 757 KiB）， +耗时没有可测量的增加。`--pdf-tags=false` 写出不带标签的 PDF。 + ## `slides.yaml` {#slidesyaml} 演示文稿旁边的配置文件会作用于该演示文稿，因此一个文件夹中的演示文稿可以共享同一个配置文件： diff --git a/content/zh/getting-started.md b/content/zh/getting-started.md index c0a6668..a028755 100644 --- a/content/zh/getting-started.md +++ b/content/zh/getting-started.md @@ -14,7 +14,7 @@ go install github.com/go-slides/slides/cmd/slides@latest ``` `slides` 是一个不使用 cgo 的静态 Go 二进制文件：无需安装其他任何东西， -不需要 Node，也不需要 Chrome。本页描述的是 v0.9.0。 +不需要 Node，也不需要 Chrome。本页描述的是 v0.13.0。 ## 第一个演示文稿 {#a-first-deck} diff --git a/content/zh/playground.md b/content/zh/playground.md index 8178ea8..3bfa51c 100644 --- a/content/zh/playground.md +++ b/content/zh/playground.md @@ -7,7 +7,7 @@ tags: [playground, browser] **[打开 Playground →](https://go-slides.github.io/playground/)** -Playground 就是 go-slides 本身（v0.9.0），编译为 WebAssembly 后在你的浏览器中运行。 +Playground 就是 go-slides 本身（v0.13.0），编译为 WebAssembly 后在你的浏览器中运行。 在左侧输入演示文稿，右侧的幻灯片会随之更新。不会向服务器发送任何内容：演示文稿不会，分享链接也不会。 ## 功能 {#what-it-has} diff --git a/hugo.yaml b/hugo.yaml index 837fa78..f4c4eb6 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -157,7 +157,7 @@ params: # "main" while nothing is released: the pages then describe the branch # being written, and say so. slides: - version: "v0.9.0" + version: "v0.13.0" # The ref of go-slides/slides whose examples/ the gallery shows, and from # which tools/gallery builds the slides command that renders the thumbnails # (the CI reads it here). "main" until a release has an examples/ folder;