#6405 Add annotations wcag #7081

ghost · 2023-11-25T20:32:39Z

Status

Ready for review / Work in progress

Description of Changes

Added abbreviation descriptions to the html pages.
Fixes #6405.

Changes proposed in this pull request:

add abbr tag to html pages

Testing

How should the reviewer test this PR?
Write out any special testing steps here.

when looking through the page ensure the correct words have abbreviations

Deployment

Any special considerations for deployment? Consider both:

Upgrading existing production instances.
New installs.

Checklist

If you made changes to the server application code:

Linting (make lint) and tests (make test) pass in the development container

If you made changes to `securedrop-admin`:

Linting and tests (make -C admin test) pass in the admin development container

If you made changes to the system configuration:

Configuration tests pass

If you added or removed a file deployed with the application:

I have updated AppArmor rules to include the change

If you made non-trivial code changes:

I have written a test plan and validated it for this PR

Choose one of the following:

[ x] I have opened a PR in the docs repo for these changes, or will do so later
[ x] I would appreciate help with the documentation
These changes do not require documentation

If you added or updated a reference to a production code dependency:

Production code dependencies are defined in:

admin/requirements.in
admin/requirements-ansible.in
securedrop/requirements/python3/requirements.in
securedrop/requirements/python3/translation.in (used in the build
container)

If you changed another requirements.in file that applies only to development
or testing environments, then no diff review is required, and you can skip
(remove) this section.

Choose one of the following:

I have performed a diff review and pasted the contents to the packaging wiki
I would like someone else to do the diff review
I am silencing an alert related to a production dependency, because (please explain below):

cfm

@amnak1284, thanks for proposing these changes. I've left some feedback on specific annotations. In brief, some of these abbreviations benefit from annotation more than others in context, and we'd like to balance their benefit against their cost as changes requiring new translations.

cfm · 2023-11-28T19:42:25Z

securedrop/journalist_templates/account_new_two_factor.html

@@ -4,15 +4,15 @@

 {% block body %}
 {% if user.is_totp %}
-<h1>{{ gettext('Enable FreeOTP') }}</h1>
+<h1>{{ gettext('Enable <abbr title="two-factor authentication application">FreeOTP</abbr>') }}</h1>


"FreeOTP" is the name of a specific application, so it doesn't need a generic annotation.

cfm · 2023-11-28T19:43:39Z

securedrop/journalist_templates/account_new_two_factor.html

 <p>
  {{ gettext("You're almost done! To finish resetting your two-factor authentication, follow the instructions below to set up FreeOTP. Once you've added the entry for your account in the app, enter one of the 6-digit codes from the app to confirm that two-factor authentication is set up correctly.") }}
 </p>

 <ol>
  <li>{{ gettext('Install FreeOTP on your phone') }}</li>
  <li>{{ gettext('Open the FreeOTP app') }}</li>
-  <li>{{ gettext('Tap the QR code symbol at the top') }}</li>
+  <li>{{ gettext('Tap the <abbr title="quick response">QR</abbr> code symbol at the top') }}</li>


I wouldn't annotate an initialism that's (a) in common use and (b) cited far more widely (463 million Google results) than its expansion (2.1 million results).

cfm · 2023-11-28T19:44:58Z

securedrop/journalist_templates/account_new_two_factor.html

@@ -23,7 +23,7 @@ <h1>{{ gettext('Enable FreeOTP') }}</h1>
 <mark id="shared-secret">{{ user.formatted_otp_secret }}</mark>
 <p>{{ gettext("Once you have paired FreeOTP with this account, enter the 6-digit verification code below:") }}</p>
 {% else %}
-<h1>{{ gettext('Enable YubiKey (OATH-HOTP)') }}</h1>
+<h1>{{ gettext('Enable YubiKey (<abbr title="HMAC based one-time password algorithm">OATH-HOTP</abbr>)') }}</h1>


Suggested change

<h1>{{ gettext('Enable YubiKey (<abbr title="HMAC based one-time password algorithm">OATH-HOTP</abbr>)') }}</h1>

<h1>{{ gettext('Enable YubiKey (OATH-<abbr title="HMAC-based one-time password">HOTP</abbr>)') }}</h1>

fixed this change

cfm · 2023-11-28T19:50:21Z

securedrop/journalist_templates/admin.html

@@ -85,7 +85,7 @@ <h2 id="users-heading" class="visually-hidden">Users</h2>

 <a href="{{ url_for('admin.manage_config') }}" class="btn icon icon-edit section-spacing-inline"
  id="update-instance-config" aria-label="{{ gettext('Update instance config') }}">


See next comment:

Suggested change

id="update-instance-config" aria-label="{{ gettext('Update instance config') }}">

id="update-instance-config" aria-label="{{ gettext('Update instance configuration') }}">

cfm · 2023-11-28T19:50:25Z

securedrop/journalist_templates/admin.html

@@ -85,7 +85,7 @@ <h2 id="users-heading" class="visually-hidden">Users</h2>

 <a href="{{ url_for('admin.manage_config') }}" class="btn icon icon-edit section-spacing-inline"
  id="update-instance-config" aria-label="{{ gettext('Update instance config') }}">
-  {{ gettext('INSTANCE CONFIG') }}
+  {{ gettext('INSTANCE <abbr title="Configuration">CONFIG</abbr>') }}


Let's go ahead and just expand this, as we have in: :-)

securedrop/securedrop/journalist_templates/config.html

Line 10 in 4d9b74b

<h1>{{ gettext('Instance Configuration') }}</h1>

Suggested change

{{ gettext('INSTANCE <abbr title="Configuration">CONFIG</abbr>') }}

{{ gettext('INSTANCE CONFIGURATION') }}

cfm · 2023-11-28T19:52:24Z

securedrop/journalist_templates/config.html

@@ -94,7 +94,7 @@ <h2 id="config-preventuploads">{{ gettext('Submission Preferences') }}</h2>
 <section aria-labelledby="config-testalert">
  <h2 id="config-testalert">{{ gettext('Alerts') }}</h2>

-  <p>{{ gettext('Send an encrypted email to verify if OSSEC alerts work correctly:') }}</p>
+  <p>{{ gettext('Send an encrypted email to verify if <abbr title="Open Source HIDS SECurity">OSSEC</abbr> alerts work correctly:') }}</p>


OSSEC is the name of an application, and we only ever refer to it this way. I don't think it needs expanding.

cfm · 2023-11-28T19:54:41Z

securedrop/source_templates/footer.html

@@ -3,7 +3,7 @@
    {{ gettext('Powered by') }} <b>SecureDrop {{ version }}</b>.
  </p>
  <p id="footer-advisory">
-    {{ gettext('Please note: Sharing sensitive information may put you at risk, even when using Tor and SecureDrop.') }}
+    {{ gettext('Please note: Sharing sensitive information may put you at risk, even when using <abbr title="The Onion Router">Tor</abbr> and SecureDrop.') }}


I don't think this is worth expanding. It's no longer the official initialism of the Tor project or network, and users will reach this page via Tor Browser already.

cfm · 2023-11-28T19:55:25Z

securedrop/source_templates/index.html

@@ -22,7 +22,7 @@
  <div id="browser-security-level" class="warning" role="alert">
    <p>{{ gettext('Your Tor Browser\'s <a id="disable-js" href=""><b>Security Level</b></a> is too low. Use the <img src="{icon}" alt="&quot;Security Level&quot;"> button in your browser’s toolbar to change it.').format(icon=url_for("static", filename="i/font-awesome/white/guard.svg")) }}</p>
  </div>
-  {# Warning bubble to help TB users disable JavaScript with Tor Browser's Security Levels
+  {# Warning bubble to help <abbr title="Tor Browser">TB</abbr> users disable JavaScript with <abbr title="The Onion Router">Tor</abbr> Browser's Security Levels


This is a server-side Jinja comment for developers, so users will never see it, and HTML doesn't work here anyway. :-)

cfm · 2023-11-28T19:56:09Z

securedrop/source_templates/logout.html

@@ -10,7 +10,7 @@
 <section>
  <h2>{{ gettext('One more thing...') }}</h2>
  <p>
-    {{ gettext('Click the <img src={icon} alt="" width="16" height="16">&nbsp;<b>New Identity</b> button in your Tor Browser\'s toolbar. This will clear your Tor Browser activity data on this device.').format(icon=url_for('static', filename='i/torbroom.png'))  }}
+    {{ gettext('Click the <img src={icon} alt="" width="16" height="16">&nbsp;<b>New Identity</b> button in your <abbr title="The Onion Router">Tor</abbr> Browser\'s toolbar. This will clear your Tor Browser activity data on this device.').format(icon=url_for('static', filename='i/torbroom.png'))  }}


cfm · 2023-11-28T19:56:58Z

securedrop/source_templates/tor2web-warning.html

@@ -7,7 +7,7 @@ <h2>{{ gettext('Proxy Service Detected') }}</h2>
 <div class="center">
  {% include 'flashed.html' %}
 </div>
-<p>{{ gettext('You appear to be using a Tor proxy service to access SecureDrop. Proxy services do not protect your anonymity.') }}
+<p>{{ gettext('You appear to be using a <abbr title="The Onion Router">Tor</abbr> proxy service to access SecureDrop. Proxy services do not protect your anonymity.') }}


cfm · 2024-01-03T19:39:40Z

@amnak1284, I'm going to close this pull request for now, but feel free to reopen it if you're able to make these changes!

Amna Khan added 12 commits November 23, 2023 15:18

updated lookup.html annotation

402928d

updated logout page

ac1ba8d

updated index.html annotations

30df379

updated footer

ff2218b

updated why-public-key.html annotations

453619a

updated tor2web-warning annotations

88bc365

updated annotations on account_new_two_factor.html

e9f49ca

updated annotations

3a2cbd3

updated annotations

ea8789e

updated config annotations

ef8222b

updated config annotations

2788b85

updated annotations

fdb1be3

ghost self-requested a review as a code owner November 25, 2023 20:32

cfm requested changes Nov 28, 2023

View reviewed changes

cfm self-assigned this Nov 28, 2023

cfm closed this Jan 3, 2024

amnak613 mentioned this pull request Oct 30, 2024

#6405 Fix wcag annotations #7314

Open

11 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

#6405 Add annotations wcag #7081

#6405 Add annotations wcag #7081

ghost commented Nov 25, 2023

cfm left a comment

cfm Nov 28, 2023

cfm Nov 28, 2023

cfm Nov 28, 2023

amnak613 Oct 30, 2024

cfm Nov 28, 2023

cfm Nov 28, 2023

amnak613 Oct 30, 2024

cfm Nov 28, 2023

cfm Nov 28, 2023

cfm Nov 28, 2023

cfm Nov 28, 2023

cfm Nov 28, 2023

cfm commented Jan 3, 2024

	<h1>{{ gettext('Enable YubiKey (<abbr title="HMAC based one-time password algorithm">OATH-HOTP</abbr>)') }}</h1>
	<h1>{{ gettext('Enable YubiKey (OATH-<abbr title="HMAC-based one-time password">HOTP</abbr>)') }}</h1>

		@@ -85,7 +85,7 @@ <h2 id="users-heading" class="visually-hidden">Users</h2>

		<a href="{{ url_for('admin.manage_config') }}" class="btn icon icon-edit section-spacing-inline"
		id="update-instance-config" aria-label="{{ gettext('Update instance config') }}">

	{{ gettext('INSTANCE <abbr title="Configuration">CONFIG</abbr>') }}
	{{ gettext('INSTANCE CONFIGURATION') }}

#6405 Add annotations wcag #7081

#6405 Add annotations wcag #7081

Conversation

ghost commented Nov 25, 2023

Status

Description of Changes

Testing

Deployment

Checklist

If you made changes to the server application code:

If you made changes to securedrop-admin:

If you made changes to the system configuration:

If you added or removed a file deployed with the application:

If you made non-trivial code changes:

If you added or updated a reference to a production code dependency:

cfm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cfm commented Jan 3, 2024

If you made changes to `securedrop-admin`: