File size: 7,665 Bytes
d9ecc7c
bfb97c5
b6f361a
d9ecc7c
 
b6f361a
d9ecc7c
 
6f7a34c
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b6f361a
 
d9ecc7c
b6f361a
d9ecc7c
6f7a34c
 
b6f361a
6f7a34c
d9ecc7c
 
 
 
 
b6f361a
 
bfb97c5
d9ecc7c
5a2d8c8
 
 
d9ecc7c
bfb97c5
b6f361a
9a3cbf9
d9ecc7c
 
 
9a3cbf9
d9ecc7c
 
 
 
 
b6f361a
583f6ac
9a3cbf9
 
 
d9ecc7c
 
bbe4867
d9ecc7c
 
 
 
bbe4867
b6f361a
9a3cbf9
 
 
 
 
 
 
 
 
 
 
d9ecc7c
b6f361a
5a2d8c8
b6f361a
5a2d8c8
b6f361a
9a3cbf9
b6f361a
b12bb48
8fb4d34
b6f361a
8fb4d34
b6f361a
 
9a3cbf9
 
 
cf53b59
 
 
 
 
 
 
9a3cbf9
5a2d8c8
 
 
 
 
4f17788
 
 
 
 
9a3cbf9
 
4f17788
9a3cbf9
 
 
 
4f17788
 
 
5a2d8c8
9a3cbf9
4f17788
 
5a2d8c8
4f17788
9a3cbf9
4f17788
9a3cbf9
0c2c651
 
 
 
 
 
3c265ff
b863381
f697ee6
0c2c651
b6f361a
 
8fb4d34
 
 
 
 
6f7a34c
 
bfb97c5
 
 
 
6f7a34c
 
 
 
 
d61b118
d9ecc7c
b6f361a
d61b118
b6f361a
 
d9ecc7c
2f32611
b6f361a
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
<!DOCTYPE html>
<html lang="{{ lang or 'en' }}">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ title }}</title>
  {% if description %}<meta name="description" content="{{ description }}">{% endif %}
  {% include "_doc_styles.html" %}
  {% if mathjax %}
  <script>
    MathJax = {
      tex: {
        inlineMath: [['\\(', '\\)']],
        displayMath: [['\\[', '\\]']]
      },
      options: {
        enableMenu: true,
        menuOptions: { settings: { assistiveMml: true, explorer: true } }
      }
    };
  </script>
  <script id="MathJax-script" async src="{{ mathjax_src }}"></script>
  {% endif %}
</head>
<body>
  <a href="#main-content" class="skip-link">Skip to main content</a>

  <header class="doc-header" role="banner">
    {% if module %}<p class="doc-header__eyebrow">{{ module }}</p>
    {% else %}<p class="doc-header__eyebrow">{{ eyebrow }}</p>{% endif %}
    <h1>{{ title }}</h1>
    {% if subtitle %}<p class="doc-header__subtitle">{{ subtitle }}</p>{% endif %}
    {% if meta_lines %}
    <p class="doc-header__meta">
      {% for line in meta_lines %}<span>{{ line }}</span>{% endfor %}
    </p>
    {% endif %}
  </header>

  {% if has_draft_alts %}
  <div class="alt-warning" role="note">
    <strong>Author note:</strong> Some image descriptions below are
    still automated drafts. Review and rewrite each one to convey the
    image's purpose before publishing this guide to end users.
  </div>
  {% endif %}

  {% if (segments | selectattr('include') | list | length) > 1 %}
  <nav class="toc" aria-label="Table of contents">
    <h2>Contents</h2>
    <ol>
      {% for seg in segments if seg.include %}
      <li><a href="#section-{{ seg.index }}">{{ seg.section_title }}</a></li>
      {% endfor %}
    </ol>
  </nav>
  {% endif %}

  <main id="main-content" class="content" tabindex="-1">
    {# Only sections the editor left included are published. An excluded
       section carries over neither to the body nor the table of contents. #}
    {% for seg in segments if seg.include %}
    <section class="section" id="section-{{ seg.index }}" aria-labelledby="heading-{{ seg.index }}">
      <h2 class="section__heading" id="heading-{{ seg.index }}">{{ seg.section_title }}</h2>
      {% if not seg.untimed %}
      <p class="meta-time">
        <time datetime="PT{{ seg.start_seconds | int }}S">{{ seg.start_seconds | timestamp }}</time>
        – <time datetime="PT{{ seg.end_seconds | int }}S">{{ seg.end_seconds | timestamp }}</time>
      </p>
      {% endif %}

      {# Per-element include flags decide what carries over. A scene
         description (when present AND included) is the long-form image
         description, so the <img alt> drops to "" β€” screen readers skip
         the image and read the description in body text. Alt-text is only
         emitted when its own include flag is on AND no description is
         carrying the meaning. We never add role="presentation" β€” alt=""
         alone is the WAI-recommended decorative pattern. #}
      {% set show_description = seg.description and seg.description.strip() and seg.description_included %}
      {% set show_alt = seg.alt_text_included and not show_description %}
      {% set img_alt = seg.alt_draft if show_alt else '' %}
      {% set draft_attr = ' data-alt-draft="true"' if (show_alt and not seg.alt_text_reviewed) else '' %}
      <figure class="figure">
        {% if inline_images and seg.image_data_uri %}
        <img src="{{ seg.image_data_uri }}" alt="{{ img_alt }}"{{ draft_attr|safe }} loading="lazy">
        {% else %}
        <img src="{{ image_dir }}/{{ seg.image_filename }}" alt="{{ img_alt }}"{{ draft_attr|safe }} loading="lazy">
        {% endif %}
        {% if show_alt and not seg.alt_text_reviewed %}
        <figcaption>
          <span class="figure__timestamp" aria-hidden="true">{{ seg.start_seconds | timestamp }}</span>
          Alt-text needs author review.
        </figcaption>
        {% endif %}
      </figure>

      {# Scene description β€” open paragraph(s) below the figure that serve
         as the long-form image description for everyone. #}
      {% if show_description %}
      <div class="section__description">
        {% for para in seg.description.split('\n\n') if para.strip() %}
        <p>{{ para.strip() }}</p>
        {% endfor %}
      </div>
      {% endif %}

      {% if seg.ocr_text and seg.on_screen_text_included %}
      {# No aria-label on the <details>: the <summary> is the accessible
         name. Adding aria-label would either override the summary
         (inconsistent visual/AT names β€” WCAG 2.5.3 violation) or just
         duplicate it. #}
      <details class="onscreen-text">
        <summary>On-screen text from video</summary>
        <div class="onscreen-text__body">{{ seg.ocr_text|format_ocr }}</div>
      </details>
      {% endif %}

      {% set show_transcript = seg.narration and seg.transcript_included %}
      {% if seg.audio_included and (seg.audio_data_uri or seg.audio_filename) %}
      {% set audio_label = 'Narration audio for ' ~ seg.section_title ~ ' at ' ~ (seg.start_seconds | timestamp) %}
      {# Only reference the transcript via aria-describedby when it's
         actually rendered. A dangling describedby is an ARIA validity
         bug (WCAG 4.1.2 / 1.3.1) some screen readers silently swallow. #}
      {% set audio_describedby = ' aria-describedby="narration-' ~ seg.index ~ '"' if show_transcript else '' %}
      {% if seg.audio_data_uri %}
      <audio class="narration__audio" controls preload="none"
             src="{{ seg.audio_data_uri }}"
             aria-label="{{ audio_label }}"{{ audio_describedby|safe }}></audio>
      {% else %}
      <audio class="narration__audio" controls preload="none"
             src="{{ image_dir }}/{{ seg.audio_filename }}"
             aria-label="{{ audio_label }}"{{ audio_describedby|safe }}></audio>
      {% endif %}
      {% endif %}

      {% if show_transcript %}
      {# Transcript β€” collapsed by default. The <summary> labels the
         block for AT, replacing the prior sr-only <h3>. The narration
         body keeps a stable id so the section's <audio> aria-describedby
         can point at it. #}
      <details class="narration">
        <summary>Transcript</summary>
        <div class="narration__body" id="narration-{{ seg.index }}">
          {% for para in seg.narration %}<p>{{ para }}</p>{% endfor %}
        </div>
      </details>
      {% endif %}

      {# Per-section key-term list intentionally omitted from the final
         guide β€” definitions are surfaced inline via the highlighter
         (hover tooltips on each first occurrence) and collected at the
         end of the document in the auto-built glossary. Showing the same
         data three times was noisy without adding utility. #}

      {% for eq in seg.math_equations %}
      {# MathJax (assistiveMml: true) injects accessible MathML inside the
         expression itself; adding role="math" + aria-label on the wrapper
         would either be ignored or override the proper assistive output. #}
      <figure class="equation">
        {% if eq.label %}<span class="equation__label">{{ eq.label }}</span>{% endif %}
        {% if eq.inline %}\({{ eq.latex }}\){% else %}\[{{ eq.latex }}\]{% endif %}
        {% if eq.caption %}<figcaption>{{ eq.caption }}</figcaption>{% endif %}
      </figure>
      {% endfor %}

    </section>
    {% endfor %}

  </main>

  <footer class="doc-footer" role="contentinfo">
    <p>Generated by The Describatron. Targets WCAG 2.2 Level AA.</p>
  </footer>
</body>
</html>