fmaury/seirdy.one
1
0
Fork 0
mirror of https://git.sr.ht/~seirdy/seirdy.one synced 2024-11-14 01:32:11 +00:00
Code Issues Projects Releases Wiki Activity

Re-do my approach to image transcripts.

Browse source 
Way better now. Also introduce a way to emphasize some keywords in code
blocks without going full syntax-highlighting.
This commit is contained in:
Rohan Kumar 2022-04-20 17:55:13 -07:00
parent 50c3ec981c
commit 120232a403
No known key found for this signature in database
GPG key ID: 1E892DB2A5F84479
7 changed files with 124 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
content/posts/website-best-practices.gmi
View file

@ -511,21 +511,52 @@ A "longdesc" attribute used to be another way to reference an image transcript.
=> https://html.spec.whatwg.org/multipage/obsolete.html#non-conforming-features HTML Living Standard: non-conforming features => https://html.spec.whatwg.org/multipage/obsolete.html#non-conforming-features HTML Living Standard: non-conforming features
The recommended way to link to a transcript is by hyperlinking the image (i.e., wrapping it with <a>) or semantically grouping the image with its transcript. Put a short summary in the alt-text, and mention the availability of a transcript. I do this by adding a transcript in a <details> element at the end of a <figcaption>. The recommended way to link to a transcript is by hyperlinking the image (i.e., wrapping it with <a>) or semantically grouping the image with its transcript. Put a short summary in the alt-text, and mention the availability of a transcript.
A StackOverflow thread about comic transcripts outlines a good approach to semantically group images and transcripts, but I disagree with their interpretation of <figcaption>: A StackOverflow thread about comic transcripts outlines a good approach to semantically group images and transcripts:
=> https://stackoverflow.com/questions/65564539/what-is-the-semantically-correct-way-to-include-transcript-from-a-comic What is the semantically correct way to include transcript from a comic? => https://stackoverflow.com/questions/65564539/what-is-the-semantically-correct-way-to-include-transcript-from-a-comic What is the semantically correct way to include transcript from a comic?
Nothing in the spec seems to imply that appending a <details> element to the end of a <figcaption> would be improper. Adding <details> to a caption seems to tick all the right boxes: the <figcaption> has semantics indicating a description of the <figure> content; the figure, caption, and transcript are visually close together; and <details> indicates additional hidden-by-default information without presenting it to uninterested readers. Other information is available in the alt-text, surrounding context, and rest of the caption; a blind reader who got the necessary information should only have to expand the transcript if they're interested enough. Having an unusually long caption seems like a small price to pay. My approach is similar. I group an image, alt-text, and caption in a <figure> element and follow it with a transcript in a <details> element. I use "aria-describedby" to semantically link the figure and the transcript.
The xkcd comic included earlier in the page had this alt-text: An image, alt-text, figure caption, and transcript combine to form a complex relationship that should be grouped together in a single landmark. I put all three inside an <article> with a heading, and give the group an "aria-label" that indicates the presence of the three sub-elements. Using an `article` landmark ensures that the figure and caption remain together as a single unit. The html code for the xkcd comic earlier in the page (well, the Web version of this page) is a representative example. Here's a simplified version of it:
``` ```
Comic: if books had infinite-scroll, we'd have to turn pages carefully or risk losing the page. Transcript in caption. <article aria-label="comic, caption, and transcript">
<h4>Infinite scrolling</h4>
<figure aria-describedby="transcript-xkcd-1309">
<img
src="SRC"
alt="Comic: if books had infinite-scroll, we'd have to
turn pages carefully or risk losing the page.">
<figcaption>
Infinite-scrolling means that accidentally navigating
to a link will result in losing your place.
See <a href=#transcript-xkcd-1309>transcript</a>.
</figcaption>
</figure>
<details id="transcript-xkcd-1309">
<summary>Toggle transcript</summary>
<p>
Megan stands at a desk, reading a book, touching
it very gingerly. Cueball is standing behind her.
</p>
<dl>
<dt>Cueball</dt>
<dd>Why are you turning the pages like that?</dd>
<dt>Megan</dt>
<dd>If I touch the wrong thing, I’ll lose my place and
have to start over.</dd>
<dt>Caption below the panel</dt>
<dd>If books worked like infinite-scrolling webpages</dd>
</dl>
</details>
</article>
``` ```
Image transcripts also help users relying on machine-translation, since translation tools rely on textual content (OCR is error-prone). These users won't read alt-text; have an alternative way to discover a transcript. Wherever you put the transcript, ensure it's semantically connected to the image. I linked a transcript in the figure caption. Of course, I take care of most of the boilerplate with shortcodes.
Image transcripts also help users relying on machine-translation, since translation tools rely on textual content. These users won't read alt-text; have an alternative way to discover a transcript. Wherever you put the transcript, ensure it's semantically connected to the image. I linked a transcript in the figure caption.
I describe best practices for preparing pictures of text in the "Pictures of text" subsection of "Narrow viewports". I describe best practices for preparing pictures of text in the "Pictures of text" subsection of "Narrow viewports".

80
content/posts/website-best-practices.md
View file

@ -317,14 +317,21 @@ One example is pagination. It's easier to download one long article ahead of tim
Another common offender is infinite-scrolling. In addition to requiring JavaScript, infinite-scrolling also makes it difficult for readers to find their old place upon re-visiting a page. This creates harsh consequences for accidental navigation. WordPress documentation [lists more problems](https://make.wordpress.org/accessibility/handbook/markup/infinite-scroll/)[^6]. Another common offender is infinite-scrolling. In addition to requiring JavaScript, infinite-scrolling also makes it difficult for readers to find their old place upon re-visiting a page. This creates harsh consequences for accidental navigation. WordPress documentation [lists more problems](https://make.wordpress.org/accessibility/handbook/markup/infinite-scroll/)[^6].
<figure> {{< transcribed-image type="comic" id="xkcd-1309" >}}
{{< picture name="infinite_scrolling" alt="Comic: if books had infinite-scroll, we'd have to turn pages carefully or risk losing the page. Transcript in caption." >}}
<figcaption> #### Infinite scrolling {#infinite-scrolling}
{{< transcribed-image-figure id="xkcd-1309" >}}
{{< picture name="infinite_scrolling" alt="Comic: if books had infinite-scroll, we'd have to turn pages carefully or risk losing the page." >}}
{{< transcribed-image-figcaption >}}
Infinite-scrolling means that accidentally navigating to a link will result in losing your place. Source: [xkcd](https://xkcd.com/1309/). Infinite-scrolling means that accidentally navigating to a link will result in losing your place. Source: [xkcd](https://xkcd.com/1309/).
<details> {{< /transcribed-image-figcaption >}} {{< /transcribed-image-figure >}}
<summary>Transcript</summary>
{{< transcribed-image-transcript >}}
Megan stands at a desk, reading a book, touching it very gingerly. Cueball is standing behind her. Megan stands at a desk, reading a book, touching it very gingerly. Cueball is standing behind her.
@ -338,10 +345,7 @@ Megan
Caption below the panel Caption below the panel
: If books worked like infinite-scrolling webpages : If books worked like infinite-scrolling webpages
</details> {{< /transcribed-image-transcript >}} {{< /transcribed-image >}}
</figcaption>
</figure>
A hybrid between the two is paginated content in which users click a "load next page" link to load the next page below the current page (typically using "dynamic content replacement"). It's essentially the same as infinite scrolling, except additional content is loaded after a click rather than by scrolling. This is only slightly less bad than infinite scrolling; it still has the same fundamental issue of allowing readers to lose their place. A hybrid between the two is paginated content in which users click a "load next page" link to load the next page below the current page (typically using "dynamic content replacement"). It's essentially the same as infinite scrolling, except additional content is loaded after a click rather than by scrolling. This is only slightly less bad than infinite scrolling; it still has the same fundamental issue of allowing readers to lose their place.
@ -545,20 +549,52 @@ If the image is a screenshot of text from a website, link to that website to all
A <dfn>`longdesc`</dfn> attribute used to be another way to reference an image transcript. The `longdesc` attribute contained a hyperlink (often an anchor link) to a location with more information about an image. This attribute [has been obsoleted](https://html.spec.whatwg.org/multipage/obsolete.html#non-conforming-features) in the HTML Living Standard. A <dfn>`longdesc`</dfn> attribute used to be another way to reference an image transcript. The `longdesc` attribute contained a hyperlink (often an anchor link) to a location with more information about an image. This attribute [has been obsoleted](https://html.spec.whatwg.org/multipage/obsolete.html#non-conforming-features) in the HTML Living Standard.
The recommended way to link to a transcript is by hyperlinking the image (i.e., wrapping it with `<a>`) or semantically grouping the image with its transcript. Put a short summary in the alt-text, and mention the availability of a transcript. I do this by adding a transcript in a `<details>` element at the end of a `<figcaption>`. The recommended way to link to a transcript is by hyperlinking the image (i.e., wrapping it with `<a>`) or semantically grouping the image with its transcript. Put a short summary in the alt-text, and mention the availability of a transcript.
A [StackOverflow thread about comic transcripts](https://stackoverflow.com/questions/65564539/what-is-the-semantically-correct-way-to-include-transcript-from-a-comic) outlines a good approach to semantically group images and transcripts, but I disagree with their interpretation of `<figcaption>`. Nothing in the spec seems to imply that appending a `<details>` element to the end of a `<figcaption>` would be improper. Adding `<details>` to a caption seems to tick all the right boxes: the `<figcaption>` has semantics indicating a description of the `<figure>` content; the figure, caption, and transcript are visually close together; and `<details>` indicates additional hidden-by-default information without presenting it to uninterested readers. Other information is available in the alt-text, surrounding context, and rest of the caption; a blind reader who got the necessary information should only have to expand the transcript if they're interested enough. Having an unusually long caption seems like a small price to pay. A [StackOverflow thread about comic transcripts](https://stackoverflow.com/questions/65564539/what-is-the-semantically-correct-way-to-include-transcript-from-a-comic) outlines a good approach to semantically group images and transcripts, and my approach is similar. I group an image, alt-text, and caption in a `<figure>` element and follow it with a transcript in a `<details>` element. I use `aria-describedby` to semantically link the figure and the transcript.
<figure> An image, alt-text, figure caption, and transcript combine to form a complex relationship that should be grouped together in a single landmark. I put all three inside an `<article>` with a heading, and give the group an `aria-label` that indicates the presence of the three sub-elements. Using an `article` landmark ensures that the figure and caption remain together as a single unit. The [html code](#xkcd-html) for the [xkcd comic earlier in the page](#xkcd-comic) is a representative example.
<figcaption>
The xkcd comic <a href="#related-issues">included earlier in the page</a> had this alt-text:
</figcaption>
> Comic: if books had infinite-scroll, we'd have to turn pages carefully or risk losing the page. Transcript in caption. {{<codefigure>}}
</figure> {{< codecaption lang="HTML" id="xkcd-html" >}} here's a simplified version of the HTML used to embed a comic in this article. Of course, I take care of most of the boilerplate with shortcodes. {{< /codecaption >}}
Image transcripts also help users relying on [machine-translation](#machine-translation), since translation tools rely on textual content (OCR is error-prone). These users won't read alt-text; have an alternative way to discover a transcript. Wherever you put the transcript, ensure it's semantically connected to the image. I linked a transcript in the figure caption. ```figure {var1="SRC" str1="figure" str2="img" str3="alt" str4="details" str5="article", str6="figcaption" str7="aria-label" str8="aria-describedby"}
<article aria-label="comic, caption, and transcript">
<h4>Infinite scrolling</h4>
<figure aria-describedby="transcript-xkcd-1309">
<img
src="SRC"
alt="Comic: if books had infinite-scroll, we'd have to
turn pages carefully or risk losing the page.">
<figcaption>
Infinite-scrolling means that accidentally navigating
to a link will result in losing your place.
See <a href=#transcript-xkcd-1309>transcript</a>.
</figcaption>
</figure>
<details id="transcript-xkcd-1309">
<summary>Toggle transcript</summary>
<p>
Megan stands at a desk, reading a book, touching
it very gingerly. Cueball is standing behind her.
</p>
<dl>
<dt>Cueball</dt>
<dd>Why are you turning the pages like that?</dd>
<dt>Megan</dt>
<dd>If I touch the wrong thing, I’ll lose my place and
have to start over.</dd>
<dt>Caption below the panel</dt>
<dd>If books worked like infinite-scrolling webpages</dd>
</dl>
</details>
</article>
```
{{</codefigure>}}
Image transcripts also help users relying on [machine-translation](#machine-translation), since translation tools rely on textual content. These users won't read alt-text; have an alternative way to discover a transcript. Wherever you put the transcript, ensure it's semantically connected to the image. I linked a transcript in the figure caption.
I describe best practices for preparing pictures of text in [the "Pictures of text" section](#pictures-of-text). I describe best practices for preparing pictures of text in [the "Pictures of text" section](#pictures-of-text).
@ -706,9 +742,9 @@ Most of my images will probably be screenshots that start as PNGs. My typical fl
6. Create a lossy AVIF image from the cropped full-color PNG, and include it in the `<picture>` element if it's smaller than the WebP. If color isn't important, use the YUV400 color space. 6. Create a lossy AVIF image from the cropped full-color PNG, and include it in the `<picture>` element if it's smaller than the WebP. If color isn't important, use the YUV400 color space.
7. If the image is too light, repeat for a dark version of the image to display according to a `prefers-color-scheme: dark` media query. 7. If the image is too light, repeat for a dark version of the image to display according to a `prefers-color-scheme: dark` media query.
{{<codefigure>}} {{< codefigure id="png-pipeline" >}}
{{< codecaption lang="shell" id="png-pipeline" >}} {{< codecaption lang="shell">}}
this is a sample command to compress a PNG image using ImageMagick, `pngquant`, and `oxipng`. It shrinks the image, turns it grayscale, reduces the color palette, and then applies lossless Zopfli compression. this is a sample command to compress a PNG image using ImageMagick, `pngquant`, and `oxipng`. It shrinks the image, turns it grayscale, reduces the color palette, and then applies lossless Zopfli compression.
@ -983,7 +1019,9 @@ Increasing the line-spacing a bit will make tap targets larger and improve compr
<figure itemscope itemtype="https://schema.org/Quotation"> <figure itemscope itemtype="https://schema.org/Quotation">
<blockquote itemprop="text"> <blockquote itemprop="text">
<p>Line spacing (leading) is at least space-and-a-half within paragraphs, and paragraph spacing is at least 1.5 times larger than the line spacing.</p>
Line spacing (leading) is at least space-and-a-half within paragraphs, and paragraph spacing is at least 1.5 times larger than the line spacing.
</blockquote> </blockquote>
{{< quotecaption partOfType="TechArticle" >}} {{< quotecaption partOfType="TechArticle" >}}
{{< cited-work name="WCAG 2.2" extraName="headline" url="https://www.w3.org/TR/WCAG22/" >}}, {{< cited-work name="WCAG 2.2" extraName="headline" url="https://www.w3.org/TR/WCAG22/" >}},

3
layouts/_default/_markup/render-codeblock-figure.html
View file

@ -5,6 +5,9 @@
{{ if strings.HasPrefix $k "var" }} {{ if strings.HasPrefix $k "var" }}
{{ $after := printf `<var translate="yes">%s</var>` $v }} {{ $after := printf `<var translate="yes">%s</var>` $v }}
{{ $contents = $contents | replaceRE $v $after }} {{ $contents = $contents | replaceRE $v $after }}
{{ else if strings.HasPrefix $k "str" }}
{{ $after := printf `<strong translate="yes">%s</strong>` $v }}
{{ $contents = $contents | replaceRE $v $after }}
{{ else if and (eq $k "samp")}} {{ else if and (eq $k "samp")}}
{{ $samp = $v }} {{ $samp = $v }}
{{ end }} {{ end }}

3
layouts/shortcodes/transcribed-image-figcaption.html Normal file
View file

@ -0,0 +1,3 @@
<figcaption>
{{ .Inner | markdownify | safeHTML }} See <a href="#transcript-{{ .Parent.Get "id" }}">transcript</a>.
</figcaption>

5
layouts/shortcodes/transcribed-image-figure.html Normal file
View file

@ -0,0 +1,5 @@
{{ with .Parent -}}
<figure aria-describedby="transcript-{{ .Get "id" }}">
{{- end }}
{{ .Inner | markdownify | safeHTML }}
</figure>

9
layouts/shortcodes/transcribed-image-transcript.html Normal file
View file

@ -0,0 +1,9 @@
<details
{{ with .Parent -}}
id="transcript-{{ .Get "id" }}"
{{- end -}}>
<summary>Toggle transcript</summary>
<div itemprop="embeddedTextCaption">
{{ .Inner | markdownify | safeHTML }}
</div>
</details>

8
layouts/shortcodes/transcribed-image.html Normal file
View file

@ -0,0 +1,8 @@
{{- $type := "picture" -}}
{{- with .Get "type" -}}
{{- $type = . -}}
{{- end -}}
<article aria-label="{{ $type }}, caption, and transcript" itemscope itemtype="https://schema.org/ImageObject" id="{{ .Get "id" }}">
{{ .Inner | markdownify | safeHTML }}
</article>