tech@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Anna <cyber@sysrq.in>
Cc: tech@mandoc.bsd.lv
Subject: Re: [PATCH 5/8] man.cgi: add ARIA roles and semantics
Date: Mon, 4 Jul 2022 18:37:48 +0200	[thread overview]
Message-ID: <YsMXXPhbC3YzOk5U@asta-kit.de> (raw)
In-Reply-To: <20220621122749.11417-6-cyber@sysrq.in>

Hello Anna,

Anna wrote on Tue, Jun 21, 2022 at 05:27:46PM +0500:

>  cgi.c | 61 ++++++++++++++++++++++++++++++++++++++++++-----------------
>  1 file changed, 44 insertions(+), 17 deletions(-)

While i did a lot of nitpicking on your other patches, i decided to
commit this one almost unchanged with only tiny tweaks, see the commit
appended below.

Even in the existing code before your patch, there are likely some
ways how the structure of both the C and the HTML code can be
improved, and this patch clearly moves into the right direction,
so just moving ahead seemed better than excessive scrutiny in this
case.  We can polish it further in the tree when we see the need.

There is one exception.  I did not yet merge the part you marked
with FIXME:

>  		puts("<table class=\"results\">");
>  		for (i = 0; i < sz; i++) {
> +			// FIXME: there has to be a way to do this without
> +			// truncating
> +			name = mandoc_strdup(r[i].names);
> +			name[strlen(name)-3] = '\0';
> +			mandoc_asprintf(&label, "%s, section %d",
> +			    name, r[i].sec);
> +
>  			printf("  <tr>\n"
>  			       "    <td>"
> -			       "<a class=\"Xr\" href=\"/");
> +			       "<a class=\"Xr\" aria-label=\"%s\" href=\"/",
> +			       label);
>  			if (*scriptname != '\0')
>  				printf("%s/", scriptname);

While i agree with your intention, i think it's better to consider
in detail how to best do this before committing.

Yours,
  Ingo


Log Message:
-----------
Improve accessibility of man.cgi(8) in various respects,
in particular adding <header>, <main>, and <nav> elements 
and role and aria-label attributes in several places.
Patch from Anna Vyalkova <cyber at sysrq dot in>,
minimally tweaked by me.

Modified Files:
--------------
    mandoc:
        cgi.c

Revision Data
-------------
Index: cgi.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/cgi.c,v
retrieving revision 1.176
retrieving revision 1.177
diff -Lcgi.c -Lcgi.c -u -p -r1.176 -r1.177
--- cgi.c
+++ cgi.c
@@ -2,6 +2,7 @@
 /*
  * Copyright (c) 2014-2019, 2021 Ingo Schwarze <schwarze@usta.de>
  * Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
+ * Copyright (c) 2022 Anna Vyalkova <cyber@sysrq.in>
  *
  * Permission to use, copy, modify, and distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -431,7 +432,8 @@ resp_searchform(const struct req *req, e
 {
 	int		 i;
 
-	printf("<form action=\"/%s\" method=\"get\" "
+	printf("<header>\n"
+	       "<form role=\"search\" action=\"/%s\" method=\"get\" "
 	       "autocomplete=\"off\" autocapitalize=\"none\">\n"
 	       "  <fieldset>\n"
 	       "    <legend>Manual Page Search Parameters</legend>\n",
@@ -457,7 +459,7 @@ resp_searchform(const struct req *req, e
 
 	/* Write section selector. */
 
-	puts("    <select name=\"sec\">");
+	puts("    <select name=\"sec\" aria-label=\"manual section\">");
 	for (i = 0; i < sec_MAX; i++) {
 		printf("      <option value=\"%s\"", sec_numbers[i]);
 		if (NULL != req->q.sec &&
@@ -469,7 +471,7 @@ resp_searchform(const struct req *req, e
 
 	/* Write architecture selector. */
 
-	printf(	"    <select name=\"arch\">\n"
+	printf(	"    <select name=\"arch\" aria-label=\"CPU architecture\">\n"
 		"      <option value=\"default\"");
 	if (NULL == req->q.arch)
 		printf(" selected=\"selected\"");
@@ -499,7 +501,8 @@ resp_searchform(const struct req *req, e
 	}
 
 	puts("  </fieldset>\n"
-	     "</form>");
+	     "</form>\n"
+	     "</header>");
 }
 
 static int
@@ -557,13 +560,17 @@ pg_index(const struct req *req)
 
 	resp_begin_html(200, NULL, NULL);
 	resp_searchform(req, FOCUS_QUERY);
-	printf("<p>\n"
+	printf("<main>\n"
+	       "<p role=\"doc-notice\" aria-label=\"usage\">\n"
 	       "This web interface is documented in the\n"
-	       "<a class=\"Xr\" href=\"/%s%sman.cgi.8\">man.cgi(8)</a>\n"
+	       "<a class=\"Xr\" href=\"/%s%sman.cgi.8\""
+	       " aria-label=\"man dot CGI, section 8\">man.cgi(8)</a>\n"
 	       "manual, and the\n"
-	       "<a class=\"Xr\" href=\"/%s%sapropos.1\">apropos(1)</a>\n"
+	       "<a class=\"Xr\" href=\"/%s%sapropos.1\""
+	       " aria-label=\"apropos, section 1\">apropos(1)</a>\n"
 	       "manual explains the query syntax.\n"
-	       "</p>\n",
+	       "</p>\n"
+	       "</main>\n",
 	       scriptname, *scriptname == '\0' ? "" : "/",
 	       scriptname, *scriptname == '\0' ? "" : "/");
 	resp_end_html();
@@ -575,9 +582,11 @@ pg_noresult(const struct req *req, int c
 {
 	resp_begin_html(code, http_msg, NULL);
 	resp_searchform(req, FOCUS_QUERY);
-	puts("<p>");
+	puts("<main>");
+	puts("<p role=\"doc-notice\" aria-label=\"no result\">");
 	puts(user_msg);
 	puts("</p>");
+	puts("</main>");
 	resp_end_html();
 }
 
@@ -586,12 +595,14 @@ pg_error_badrequest(const char *msg)
 {
 
 	resp_begin_html(400, "Bad Request", NULL);
-	puts("<h1>Bad Request</h1>\n"
-	     "<p>\n");
+	puts("<main>\n"
+	     "<h1>Bad Request</h1>\n"
+	     "<p role=\"doc-notice\" aria-label=\"Bad Request\">");
 	puts(msg);
 	printf("Try again from the\n"
 	       "<a href=\"/%s\">main page</a>.\n"
-	       "</p>", scriptname);
+	       "</p>\n"
+	       "</main>", scriptname);
 	resp_end_html();
 }
 
@@ -599,7 +610,7 @@ static void
 pg_error_internal(void)
 {
 	resp_begin_html(500, "Internal Server Error", NULL);
-	puts("<p>Internal Server Error</p>");
+	puts("<main><p role=\"doc-notice\">Internal Server Error</p></main>");
 	resp_end_html();
 }
 
@@ -704,6 +715,7 @@ pg_searchres(const struct req *req, stru
 	    req->q.equal || sz == 1 ? FOCUS_NONE : FOCUS_QUERY);
 
 	if (sz > 1) {
+		puts("<nav>");
 		puts("<table class=\"results\">");
 		for (i = 0; i < sz; i++) {
 			printf("  <tr>\n"
@@ -722,6 +734,7 @@ pg_searchres(const struct req *req, stru
 			     "  </tr>");
 		}
 		puts("</table>");
+		puts("</nav>");
 	}
 
 	if (req->q.equal || sz == 1) {
@@ -743,7 +756,9 @@ resp_catman(const struct req *req, const
 	int		 italic, bold;
 
 	if ((f = fopen(file, "r")) == NULL) {
-		puts("<p>You specified an invalid manual file.</p>");
+		puts("<p role=\"doc-notice\">\n"
+		     "  You specified an invalid manual file.\n"
+		     "</p>");
 		return;
 	}
 
@@ -880,7 +895,9 @@ resp_format(const struct req *req, const
 	int		 usepath;
 
 	if (-1 == (fd = open(file, O_RDONLY))) {
-		puts("<p>You specified an invalid manual file.</p>");
+		puts("<p role=\"doc-notice\">\n"
+		     "  You specified an invalid manual file.\n"
+		     "</p>");
 		return;
 	}
 
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv


  reply	other threads:[~2022-07-04 16:37 UTC|newest]

Thread overview: 17+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-06-21 12:27 [PATCH 0/8] Make generated HTML more accessible Anna “CyberTailor”
2022-06-21 12:27 ` [PATCH 1/8] mdoc_html: Accessibility markup for ToC Anna “CyberTailor”
2022-06-21 12:27 ` [PATCH 2/8] mdoc_html: Add DPUB-ARIA roles to sections Anna “CyberTailor”
2022-06-24 13:58   ` Ingo Schwarze
2022-06-21 12:27 ` [PATCH 3/8] mdoc_html: Add DPUB-ARIA roles to subsections Anna “CyberTailor”
2022-06-21 12:27 ` [PATCH 4/8] man_html: Add DPUB-ARIA roles to (sub)sections Anna “CyberTailor”
2022-06-21 12:27 ` [PATCH 5/8] man.cgi: add ARIA roles and semantics Anna “CyberTailor”
2022-07-04 16:37   ` Ingo Schwarze [this message]
2022-06-21 12:27 ` [PATCH 6/8] mdoc_html: Add accessible description to crosslinks Anna “CyberTailor”
2022-06-25 12:58   ` Ingo Schwarze
2022-06-21 12:27 ` [PATCH 7/8] mdoc_html: Tell screen readers to skip the header Anna “CyberTailor”
2022-06-26 15:51   ` Ingo Schwarze
2022-06-28 16:33     ` Anna “CyberTailor”
2022-06-21 12:27 ` [PATCH 8/8] man_html: " Anna “CyberTailor”
2022-06-22 19:15 ` [PATCH 0/8] Make generated HTML more accessible Ingo Schwarze
2022-06-22 19:40   ` Anna “CyberTailor”
2022-06-23 13:34     ` Ingo Schwarze

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=YsMXXPhbC3YzOk5U@asta-kit.de \
    --to=schwarze@usta.de \
    --cc=cyber@sysrq.in \
    --cc=tech@mandoc.bsd.lv \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).