From 3b7b0040270399b133083d69b633bc9e42994bc5 Mon Sep 17 00:00:00 2001
From: Jaimos Skriletz <jaimosskriletz@gmail.com>
Date: Thu, 21 Nov 2024 20:55:11 -0700
Subject: [PATCH] Add hidden span labels for help links.

This adds a hidden span that gives a label for the help links for
the main help link using the helpMacro and the help links on the
course configuration page.

The page title is used for the description for the main help link.
For the course configuration links, the setting short description
is used for the title. A few of the short descriptions ended in a
period, those were all removed to make the description "desc help."
consistent and not have a period before the help statement.
---
 lib/WeBWorK/ConfigValues.pm                    | 10 +++++-----
 lib/WeBWorK/ContentGenerator.pm                | 18 ++++++++++++------
 .../CourseAdmin/add_course_form.html.ep        |  5 ++++-
 .../CourseAdmin/archive_course_confirm.html.ep |  5 ++++-
 .../CourseAdmin/archive_course_form.html.ep    |  5 ++++-
 .../CourseAdmin/delete_course_confirm.html.ep  |  5 ++++-
 .../CourseAdmin/delete_course_form.html.ep     |  5 ++++-
 .../CourseAdmin/edit_location_form.html.ep     |  5 ++++-
 .../hide_inactive_course_form.html.ep          |  5 ++++-
 .../CourseAdmin/manage_location_form.html.ep   |  5 ++++-
 .../manage_lti_course_map_form.html.ep         |  5 ++++-
 .../CourseAdmin/rename_course_confirm.html.ep  |  5 ++++-
 .../rename_course_confirm_short.html.ep        |  5 ++++-
 .../CourseAdmin/rename_course_form.html.ep     |  5 ++++-
 .../unarchive_course_confirm.html.ep           |  5 ++++-
 .../CourseAdmin/unarchive_course_form.html.ep  |  5 ++++-
 .../CourseAdmin/upgrade_course_confirm.html.ep |  5 ++++-
 .../CourseAdmin/upgrade_course_form.html.ep    |  5 ++++-
 .../Instructor/Config/config_help.html.ep      |  5 ++++-
 .../browse_library_panel_advanced.html.ep      |  2 +-
 20 files changed, 86 insertions(+), 29 deletions(-)

diff --git a/lib/WeBWorK/ConfigValues.pm b/lib/WeBWorK/ConfigValues.pm
index 58955fc34e..09be39bc20 100644
--- a/lib/WeBWorK/ConfigValues.pm
+++ b/lib/WeBWorK/ConfigValues.pm
@@ -135,7 +135,7 @@ sub getConfigValues ($ce) {
 			},
 			{
 				var  => 'perProblemLangAndDirSettingMode',
-				doc  => x('Mode in which the LANG and DIR settings for a single problem are determined.'),
+				doc  => x('Mode in which the LANG and DIR settings for a single problem are determined'),
 				doc2 => x(
 					'<p>Mode in which the LANG and DIR settings for a single problem are determined.</p><p>The '
 						. 'system will set the LANGuage attribute to either a value determined from the problem, a '
@@ -331,7 +331,7 @@ sub getConfigValues ($ce) {
 			},
 			{
 				var  => 'mail{achievementEmailFrom}',
-				doc  => x('Email address to use when sending Achievement notifications.'),
+				doc  => x('Email address to use when sending Achievement notifications'),
 				doc2 => x(
 					'This email address will be used as the sender for achievement notifications. '
 						. 'Achievement notifications will not be sent unless this is set.'
@@ -481,7 +481,7 @@ sub getConfigValues ($ce) {
 			},
 			{
 				var  => 'pg{options}{showCorrectOnRandomize}',
-				doc  => x('Show the correct answer to the current problem before re-randomization.'),
+				doc  => x('Show the correct answer to the current problem before re-randomization'),
 				doc2 => x(
 					'Show the correct answer to the current problem on the last attempt before a new version is '
 						. 'requested.'
@@ -648,7 +648,7 @@ sub getConfigValues ($ce) {
 			},
 			{
 				var  => 'pg{specialPGEnvironmentVars}{entryAssist}',
-				doc  => x('Assist with the student answer entry process.'),
+				doc  => x('Assist with the student answer entry process'),
 				doc2 => x(
 					'<p>MathQuill renders students answers in real-time as they type on the keyboard.</p><p>MathView '
 						. 'allows students to choose from a variety of common math structures (such as fractions and '
@@ -849,7 +849,7 @@ sub getConfigValues ($ce) {
 			},
 			{
 				var  => 'feedback_by_section',
-				doc  => x('Feedback by Section.'),
+				doc  => x('Feedback by Section'),
 				doc2 => x(
 					'By default, feedback is always sent to all users specified to receive feedback. This '
 						. 'variable sets the system to only email feedback to users who have the same section as '
diff --git a/lib/WeBWorK/ContentGenerator.pm b/lib/WeBWorK/ContentGenerator.pm
index c3cf25ac9e..46d1d7cd40 100644
--- a/lib/WeBWorK/ContentGenerator.pm
+++ b/lib/WeBWorK/ContentGenerator.pm
@@ -957,10 +957,11 @@ This method outputs a link that opens a modal dialog containing the results of r
 HelpFiles template.  The template file that is rendered is $name.html.  If that file does not
 exist, then nothing is output.
 
-The optional argument $args is a hash that may contain the keys label, label_size, or class.
-$args->{label} is the displayed label, $args->{label_size} is a font awesome size class and is
-only used if $args->{label} is not set, and $args->{class} is added to the html class attribute
-if defined.
+The optional argument $args is a hash that may contain the keys label, label_size, help_label,
+or class. $args->{label} is the displayed label. $args->{label_size} is a font awesome size class
+and is only used if $args->{label} is not set. $args->{help_label} is the hidden description of
+the help button, "help_label help.", which defaults to the page title, and is only used if
+$args->{label} is not set. $args->{class} is added to the html class attribute if defined.
 
 =cut
 
@@ -972,11 +973,16 @@ sub helpMacro ($c, $name, $args = {}) {
 		'i',
 		class         => 'icon fa-solid fa-circle-question ' . ($args->{label_size} // ''),
 		'aria-hidden' => 'true',
-		data          => { alt => ' ? ' },
 		''
-	);
+		)
+		. $c->tag(
+			'span',
+			class => 'visually-hidden',
+			$c->maketext('[_1] help.', $args->{help_label} // $c->page_title)
+		);
 	delete $args->{label};
 	delete $args->{label_size};
+	delete $args->{help_label};
 
 	return $c->include("HelpFiles/$name", name => $name, label => $label, args => $args);
 }
diff --git a/templates/ContentGenerator/CourseAdmin/add_course_form.html.ep b/templates/ContentGenerator/CourseAdmin/add_course_form.html.ep
index a822b4b0e7..0ee53cd47b 100644
--- a/templates/ContentGenerator/CourseAdmin/add_course_form.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/add_course_form.html.ep
@@ -14,7 +14,10 @@
 % }
 % my $number_of_additional_users = $c->param('number_of_additional_users') || 0;
 %
-<h2><%= maketext('Add Course') %> <%= $c->helpMacro('AdminAddCourse') %></h2>
+<h2>
+	<%= maketext('Add Course') %>
+	<%= $c->helpMacro('AdminAddCourse', { help_label => maketext('Add Course') }) %>
+</h2>
 %
 <%= form_for current_route, method => 'POST', begin =%>
 	<%= $c->hidden_authen_fields =%>
diff --git a/templates/ContentGenerator/CourseAdmin/archive_course_confirm.html.ep b/templates/ContentGenerator/CourseAdmin/archive_course_confirm.html.ep
index 9385d07be3..ee80ef1c25 100644
--- a/templates/ContentGenerator/CourseAdmin/archive_course_confirm.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/archive_course_confirm.html.ep
@@ -1,4 +1,7 @@
-<h2><%= maketext('Archive Course') %> <%= $c->helpMacro('AdminArchiveCourse') %></h2>
+<h2>
+	<%= maketext('Archive Course') %>
+	<%= $c->helpMacro('AdminArchiveCourse', { help_label => maketext('Archive Course') }) %>
+</h2>
 % # Report on databases
 <h3 class="my-3"><%= maketext('Report on database structure for course [_1]:', $archive_courseID) %></h3>
 % if (@$upgrade_report) {
diff --git a/templates/ContentGenerator/CourseAdmin/archive_course_form.html.ep b/templates/ContentGenerator/CourseAdmin/archive_course_form.html.ep
index 39106e4990..9b88702541 100644
--- a/templates/ContentGenerator/CourseAdmin/archive_course_form.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/archive_course_form.html.ep
@@ -1,4 +1,7 @@
-<h2><%= maketext('Archive Course') %> <%= $c->helpMacro('AdminArchiveCourse') %></h2>
+<h2>
+	<%= maketext('Archive Course') %>
+	<%= $c->helpMacro('AdminArchiveCourse', { help_label => maketext('Archive Course') }) %>
+</h2>
 %
 % if (@$courseIDs) {
 	<p>
diff --git a/templates/ContentGenerator/CourseAdmin/delete_course_confirm.html.ep b/templates/ContentGenerator/CourseAdmin/delete_course_confirm.html.ep
index 90e6653e8f..51ee8d8e82 100644
--- a/templates/ContentGenerator/CourseAdmin/delete_course_confirm.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/delete_course_confirm.html.ep
@@ -1,4 +1,7 @@
-<h2><%= maketext('Delete Course') %> <%= $c->helpMacro('AdminDeleteCourse') %></h2>
+<h2>
+	<%= maketext('Delete Course') %>
+	<%= $c->helpMacro('AdminDeleteCourse', { help_label => maketext('Delete Course') }) %>
+</h2>
 <p>
 	<%== maketext(
 		'Are you sure you want to delete the course [_1]? All course files and data will be destroyed. '
diff --git a/templates/ContentGenerator/CourseAdmin/delete_course_form.html.ep b/templates/ContentGenerator/CourseAdmin/delete_course_form.html.ep
index 0306c31f29..225f7573cd 100644
--- a/templates/ContentGenerator/CourseAdmin/delete_course_form.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/delete_course_form.html.ep
@@ -1,4 +1,7 @@
-<h2><%= maketext('Delete Course') %> <%= $c->helpMacro('AdminDeleteCourse') %></h2>
+<h2>
+	<%= maketext('Delete Course') %>
+	<%= $c->helpMacro('AdminDeleteCourse', { help_label => maketext('Delete Course') }) %>
+</h2>
 %
 % if (@$courseIDs) {
 	<%= form_for current_route, method => 'POST', begin =%>
diff --git a/templates/ContentGenerator/CourseAdmin/edit_location_form.html.ep b/templates/ContentGenerator/CourseAdmin/edit_location_form.html.ep
index 2bd8a8eca5..a7353f7ef0 100644
--- a/templates/ContentGenerator/CourseAdmin/edit_location_form.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/edit_location_form.html.ep
@@ -1,4 +1,7 @@
-<h2><%= maketext('Editing location [_1]', $locationID) %> <%= $c->helpMacro('AdminManageLocations') %></h2>
+<h2>
+	<%= maketext('Editing location [_1]', $locationID) %>
+	<%= $c->helpMacro('AdminManageLocations', { help_label => maketext('Manage Locations') }) %>
+</h2>
 <p>
 	<%= maketext(
 		'Edit the current value of the location description, if desired, then add and select addresses to delete, '
diff --git a/templates/ContentGenerator/CourseAdmin/hide_inactive_course_form.html.ep b/templates/ContentGenerator/CourseAdmin/hide_inactive_course_form.html.ep
index 152bb1cbf2..13cac9167d 100644
--- a/templates/ContentGenerator/CourseAdmin/hide_inactive_course_form.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/hide_inactive_course_form.html.ep
@@ -1,4 +1,7 @@
-<h2><%= maketext('Hide Courses') %> <%= $c->helpMacro('AdminHideCourses') %></h2>
+<h2>
+	<%= maketext('Hide Courses') %>
+	<%= $c->helpMacro('AdminHideCourses', { help_label => maketext('Hide Courses') }) %>
+</h2>
 <p>
 	<%= maketext(
 		'Select the course(s) you want to hide (or unhide) and then click "Hide Courses" (or "Unhide Courses"). '
diff --git a/templates/ContentGenerator/CourseAdmin/manage_location_form.html.ep b/templates/ContentGenerator/CourseAdmin/manage_location_form.html.ep
index f1e5f25f76..39e0b8d3cc 100644
--- a/templates/ContentGenerator/CourseAdmin/manage_location_form.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/manage_location_form.html.ep
@@ -1,4 +1,7 @@
-<h2><%= maketext('Manage Locations') %> <%= $c->helpMacro('AdminManageLocations') %></h2>
+<h2>
+	<%= maketext('Manage Locations') %>
+	<%= $c->helpMacro('AdminManageLocations', { help_label => maketext('Manage Locations') }) %>
+</h2>
 <p><strong><%= maketext('Currently defined locations are listed below.') %></strong></p>
 <%= form_for current_route, method => 'POST', begin =%>
 	% my @locationIDs = map  { $_->location_id } @$locations;
diff --git a/templates/ContentGenerator/CourseAdmin/manage_lti_course_map_form.html.ep b/templates/ContentGenerator/CourseAdmin/manage_lti_course_map_form.html.ep
index 1265bcfa13..75cd09b004 100644
--- a/templates/ContentGenerator/CourseAdmin/manage_lti_course_map_form.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/manage_lti_course_map_form.html.ep
@@ -1,4 +1,7 @@
-<h2><%= maketext('Manage LTI Course Map') %> <%= $c->helpMacro('AdminManageLTICourseMap') %></h2>
+<h2>
+	<%= maketext('Manage LTI Course Map') %>
+	<%= $c->helpMacro('AdminManageLTICourseMap', { help_label => maketext('Manage LTI Course Map') }) %>
+</h2>
 <%= form_for current_route, method => 'POST', begin =%>
 	<%= $c->hidden_authen_fields =%>
 	<%= $c->hidden_fields('subDisplay') =%>
diff --git a/templates/ContentGenerator/CourseAdmin/rename_course_confirm.html.ep b/templates/ContentGenerator/CourseAdmin/rename_course_confirm.html.ep
index e32033dc85..e64b7eb905 100644
--- a/templates/ContentGenerator/CourseAdmin/rename_course_confirm.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/rename_course_confirm.html.ep
@@ -1,4 +1,7 @@
-<h2><%= maketext('Rename Course') %> <%= $c->helpMacro('AdminRenameCourse') %></h2>
+<h2>
+	<%= maketext('Rename Course') %>
+	<%= $c->helpMacro('AdminRenameCourse', { help_label => maketext('Rename Course') }) %>
+</h2>
 % # Report on databases
 <h3 class="my-3"><%= maketext('Report on database structure for course [_1]:', $rename_oldCourseID) %></h3>
 % if (@$upgrade_report) {
diff --git a/templates/ContentGenerator/CourseAdmin/rename_course_confirm_short.html.ep b/templates/ContentGenerator/CourseAdmin/rename_course_confirm_short.html.ep
index c498ccf0f1..a75e7f62d0 100644
--- a/templates/ContentGenerator/CourseAdmin/rename_course_confirm_short.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/rename_course_confirm_short.html.ep
@@ -1,4 +1,7 @@
-<h2><%= maketext('Rename Course') %> <%= $c->helpMacro('AdminRenameCourse') %></h2>
+<h2>
+	<%= maketext('Rename Course') %>
+	<%= $c->helpMacro('AdminRenameCourse', { help_label => maketext('Rename Course') }) %>
+</h2>
 <%= form_for current_route, method => 'POST', begin =%>
 	<%= $c->hidden_authen_fields =%>
 	<%= $c->hidden_fields('subDisplay') =%>
diff --git a/templates/ContentGenerator/CourseAdmin/rename_course_form.html.ep b/templates/ContentGenerator/CourseAdmin/rename_course_form.html.ep
index 9cb34b3546..c4158b51e9 100644
--- a/templates/ContentGenerator/CourseAdmin/rename_course_form.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/rename_course_form.html.ep
@@ -1,6 +1,9 @@
 % use WeBWorK::Utils::CourseManagement qw(listCourses);
 %
-<h2><%= maketext('Rename Course') %> <%= $c->helpMacro('AdminRenameCourse') %></h2>
+<h2>
+	<%= maketext('Rename Course') %>
+	<%= $c->helpMacro('AdminRenameCourse', { help_label => maketext('Rename Course') }) %>
+</h2>
 %
 % my @courseIDs = sort { lc($a) cmp lc($b) } grep { $_ ne stash('courseID') } listCourses($ce);
 %
diff --git a/templates/ContentGenerator/CourseAdmin/unarchive_course_confirm.html.ep b/templates/ContentGenerator/CourseAdmin/unarchive_course_confirm.html.ep
index 8568088bf3..c909bf96e6 100644
--- a/templates/ContentGenerator/CourseAdmin/unarchive_course_confirm.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/unarchive_course_confirm.html.ep
@@ -1,4 +1,7 @@
-<h2><%= maketext('Unarchive Course') %> <%= $c->helpMacro('AdminUnarchiveCourse') %></h2>
+<h2>
+	<%= maketext('Unarchive Course') %>
+	<%= $c->helpMacro('AdminUnarchiveCourse', { help_label => maketext('Unarchive Course') }) %>
+</h2>
 <%= form_for current_route, method => 'POST', begin =%>
 	<div class="row mb-2">
 		<%= label_for new_courseID => maketext('Unarchive [_1] to course:', $unarchive_courseID),
diff --git a/templates/ContentGenerator/CourseAdmin/unarchive_course_form.html.ep b/templates/ContentGenerator/CourseAdmin/unarchive_course_form.html.ep
index 0dcda1fbfc..991d0d2f80 100644
--- a/templates/ContentGenerator/CourseAdmin/unarchive_course_form.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/unarchive_course_form.html.ep
@@ -1,6 +1,9 @@
 % use WeBWorK::Utils::CourseManagement qw(listArchivedCourses);
 %
-<h2><%= maketext('Unarchive Course') %> <%= $c->helpMacro('AdminUnarchiveCourse') %></h2>
+<h2>
+	<%= maketext('Unarchive Course') %>
+	<%= $c->helpMacro('AdminUnarchiveCourse', { help_label => maketext('Unarchive Course') }) %>
+</h2>
 %
 % # Find courses which have been archived.
 % my @courseIDs = sort { lc($a) cmp lc($b) } listArchivedCourses($ce);
diff --git a/templates/ContentGenerator/CourseAdmin/upgrade_course_confirm.html.ep b/templates/ContentGenerator/CourseAdmin/upgrade_course_confirm.html.ep
index 3d5e4ca7d0..8fd6275d8a 100644
--- a/templates/ContentGenerator/CourseAdmin/upgrade_course_confirm.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/upgrade_course_confirm.html.ep
@@ -1,4 +1,7 @@
-<h2><%= maketext('Upgrade Courses') %> <%= $c->helpMacro('AdminUpgradeCourses') %></h2>
+<h2>
+	<%= maketext('Upgrade Courses') %>
+	<%= $c->helpMacro('AdminUpgradeCourses', { help_label => maketext('Upgrade Courses') }) %>
+</h2>
 <%= form_for current_route, method => 'POST', begin =%>
 	<% my $checkALLs = begin =%>
 		% if ($extra_database_tables_exist) {
diff --git a/templates/ContentGenerator/CourseAdmin/upgrade_course_form.html.ep b/templates/ContentGenerator/CourseAdmin/upgrade_course_form.html.ep
index 2219923131..26c2c23068 100644
--- a/templates/ContentGenerator/CourseAdmin/upgrade_course_form.html.ep
+++ b/templates/ContentGenerator/CourseAdmin/upgrade_course_form.html.ep
@@ -4,7 +4,10 @@
 %
 % my @courseIDs = sort { lc($a) cmp lc($b) } listCourses($ce);
 %
-<h2><%= maketext('Upgrade Courses') %> <%= $c->helpMacro('AdminUpgradeCourses') %></h2>
+<h2>
+	<%= maketext('Upgrade Courses') %>
+	<%= $c->helpMacro('AdminUpgradeCourses', { help_label => maketext('Upgrade Courses') }) %>
+</h2>
 <div class="mb-2"><%= maketext('Update the checked directories?') %></div>
 <%= form_for current_route, method => 'POST', id => 'courselist', name => 'courselist', begin =%>
 	<div class="mb-2">
diff --git a/templates/ContentGenerator/Instructor/Config/config_help.html.ep b/templates/ContentGenerator/Instructor/Config/config_help.html.ep
index 05092135c7..fe16baec54 100644
--- a/templates/ContentGenerator/Instructor/Config/config_help.html.ep
+++ b/templates/ContentGenerator/Instructor/Config/config_help.html.ep
@@ -10,7 +10,10 @@
 	</div>
 	<div>
 		<%= link_to '#', data => { bs_toggle => 'modal', bs_target => "#$configObject->{name}_help_modal" }, begin =%>
-			<i class="icon fas fa-question-circle" aria-hidden="true" data-alt="help"></i>
+			<i class="icon fas fa-question-circle" aria-hidden="true"></i>
+			<span class="visually-hidden">
+				<%= maketext('[_1] help.', $configObject->{doc}) %>
+			</span>
 		<% end =%>
 		<% content_for 'modal-dialog-area', begin =%>
 			<div class="modal fade" id="<%= "$configObject->{name}_help_modal" %>" tabindex="-1"
diff --git a/templates/ContentGenerator/Instructor/SetMaker/browse_library_panel_advanced.html.ep b/templates/ContentGenerator/Instructor/SetMaker/browse_library_panel_advanced.html.ep
index bc3c24af09..57f3ab1397 100644
--- a/templates/ContentGenerator/Instructor/SetMaker/browse_library_panel_advanced.html.ep
+++ b/templates/ContentGenerator/Instructor/SetMaker/browse_library_panel_advanced.html.ep
@@ -85,7 +85,7 @@
 								</label>
 							</div>
 						% }
-						<%= $c->helpMacro('Levels') =%>
+						<%= $c->helpMacro('Levels', { help_label => 'Levels' }) =%>
 					</div>
 				</div>
 			</div>