Wrap .Sh/.SH sections and .Ss/.SS subsections in HTML <section> elements

as recommended for accessibility by the HTML 5 standard.
Triggered by a similar, but slightly different suggestion
from Laura Morales <lauretas at mail dot com>.

12 files changed, 53 insertions, 29 deletions

diff --git a/TODO b/TODO
index 15ce410b..80009d67 100644
--- a/TODO
+++ b/TODO
@@ -1,6 +1,6 @@
 ************************************************************************
 * Official mandoc TODO.
-* $Id: TODO,v 1.284 2019/02/28 16:36:13 schwarze Exp $
+* $Id: TODO,v 1.285 2019/03/01 10:57:17 schwarze Exp $
 ************************************************************************
 
 Many issues are annotated for difficulty as follows:
@@ -342,13 +342,6 @@ are mere guesses, and some may be wrong.
 
 --- HTML issues --------------------------------------------------------
 
-- wrap Sh and Ss content into <div>
-  Laura Morales <lauretas at mail dot com> 21 Apr 2018 18:10:48 +0200
-  (Evaluate whether this is really useful and has no adverse
-   side effects before implementing; if it is possible,
-   it does seem cleaner.)
-  loc **  exist **  algo *  size *  imp ***
-
 - format ".IP *" etc. as <ul> rather than <dl>
   https://github.com/Debian/debiman/issues/67
   reminded by Pali Rohar 25 Nov 2018 14:34:26 +0100
diff --git a/html.c b/html.c
index 18141d60..a9a667ce 100644
--- a/html.c
+++ b/html.c
@@ -1,4 +1,4 @@
-/*	$Id: html.c,v 1.252 2019/01/18 14:36:21 schwarze Exp $ */
+/*	$Id: html.c,v 1.253 2019/03/01 10:57:17 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2011-2015, 2017-2019 Ingo Schwarze <schwarze@openbsd.org>
@@ -63,6 +63,7 @@ static	const struct htmldata htmltags[TAG_MAX] = {
 	{"title",	HTML_NLAROUND},
 	{"div",		HTML_NLAROUND},
 	{"div",		0},
+	{"section",	HTML_NLALL},
 	{"h1",		HTML_NLAROUND},
 	{"h2",		HTML_NLAROUND},
 	{"span",	0},
diff --git a/html.h b/html.h
index 7bdf698c..a6bf8911 100644
--- a/html.h
+++ b/html.h
@@ -1,4 +1,4 @@
-/*	$Id: html.h,v 1.101 2019/01/18 14:36:21 schwarze Exp $ */
+/*	$Id: html.h,v 1.102 2019/03/01 10:57:18 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2017, 2018, 2019 Ingo Schwarze <schwarze@openbsd.org>
@@ -24,6 +24,7 @@ enum	htmltag {
 	TAG_TITLE,
 	TAG_DIV,
 	TAG_IDIV,
+	TAG_SECTION,
 	TAG_H1,
 	TAG_H2,
 	TAG_SPAN,
diff --git a/man_html.c b/man_html.c
index 190a3b01..8a36680f 100644
--- a/man_html.c
+++ b/man_html.c
@@ -1,4 +1,4 @@
-/*	$Id: man_html.c,v 1.171 2019/02/28 16:36:13 schwarze Exp $ */
+/*	$Id: man_html.c,v 1.172 2019/03/01 10:57:18 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2012, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2013-2015, 2017-2019 Ingo Schwarze <schwarze@openbsd.org>
@@ -310,18 +310,25 @@ man_root_post(const struct roff_meta *man, struct html *h)
 static int
 man_SH_pre(MAN_ARGS)
 {
-	char	*id;
-
+	const char	*class;
+	char		*id;
+	enum htmltag	 tag;
+
+	if (n->tok == MAN_SH) {
+		tag = TAG_H1;
+		class = "Sh";
+	} else {
+		tag = TAG_H2;
+		class = "Ss";
+	}
 	switch (n->type) {
 	case ROFFT_BLOCK:
 		html_close_paragraph(h);
+		print_otag(h, TAG_SECTION, "c", class);
 		break;
 	case ROFFT_HEAD:
 		id = html_make_id(n, 1);
-		if (n->tok == MAN_SH)
-			print_otag(h, TAG_H1, "ci", "Sh", id);
-		else
-			print_otag(h, TAG_H2, "ci", "Ss", id);
+		print_otag(h, tag, "ci", class, id);
 		if (id != NULL)
 			print_otag(h, TAG_A, "chR", "permalink", id);
 		break;
diff --git a/mandoc.css b/mandoc.css
index 9526c74b..085f5c08 100644
--- a/mandoc.css
+++ b/mandoc.css
@@ -1,4 +1,4 @@
-/* $Id: mandoc.css,v 1.44 2019/01/11 12:56:43 schwarze Exp $ */
+/* $Id: mandoc.css,v 1.45 2019/03/01 10:57:18 schwarze Exp $ */
 /*
  * Standard style sheet for mandoc(1) -Thtml and man.cgi(8).
  *
@@ -66,11 +66,13 @@ td.foot-os {	text-align: right; }
 .manual-text {
 		margin-left: 3.8em; }
 .Nd { }
-.Sh {		margin-top: 1.2em;
+section.Sh { }
+h1.Sh {		margin-top: 1.2em;
 		margin-bottom: 0.6em;
 		margin-left: -3.2em;
 		font-size: 110%; }
-.Ss {		margin-top: 1.2em;
+section.Ss { }
+h2.Ss {		margin-top: 1.2em;
 		margin-bottom: 0.6em;
 		margin-left: -1.2em;
 		font-size: 105%; }
@@ -256,7 +258,7 @@ a.In { }
 
 /* Tooltip support. */
 
-.Sh, .Ss {	position: relative; }
+h1.Sh, h2.Ss {	position: relative; }
 .An, .Ar, .Cd, .Cm, .Dv, .Em, .Er, .Ev, .Fa, .Fd, .Fl, .Fn, .Ft,
 .Ic, code.In, .Lb, .Lk, .Ms, .Mt, .Nd, code.Nm, .Pa, .Rs,
 .St, .Sx, .Sy, .Va, .Vt, .Xr {
@@ -286,8 +288,8 @@ code.In::before { content: "In"; }
 code.Nm::before { content: "Nm"; }
 .Pa::before {	content: "Pa"; }
 .Rs::before {	content: "Rs"; }
-.Sh::before {	content: "Sh"; }
-.Ss::before {	content: "Ss"; }
+h1.Sh::before {	content: "Sh"; }
+h2.Ss::before {	content: "Ss"; }
 .St::before {	content: "St"; }
 .Sx::before {	content: "Sx"; }
 .Sy::before {	content: "Sy"; }
@@ -301,7 +303,7 @@ code.Nm::before { content: "Nm"; }
 .Ic::before, code.In::before, .Lb::before, .Lk::before,
 .Ms::before, .Mt::before, .Nd::before, code.Nm::before,
 .Pa::before, .Rs::before,
-.Sh::before, .Ss::before, .St::before, .Sx::before, .Sy::before,
+h1.Sh::before, h2.Ss::before, .St::before, .Sx::before, .Sy::before,
 .Va::before, .Vt::before, .Xr::before {
 		opacity: 0;
 		transition: .15s ease opacity;
@@ -322,7 +324,7 @@ code.Nm::before { content: "Nm"; }
 .Ft:hover::before, .Ic:hover::before, code.In:hover::before,
 .Lb:hover::before, .Lk:hover::before, .Ms:hover::before, .Mt:hover::before,
 .Nd:hover::before, code.Nm:hover::before, .Pa:hover::before,
-.Rs:hover::before, .Sh:hover::before, .Ss:hover::before, .St:hover::before,
+.Rs:hover::before, h1.Sh:hover::before, h2.Ss:hover::before, .St:hover::before,
 .Sx:hover::before, .Sy:hover::before, .Va:hover::before, .Vt:hover::before,
 .Xr:hover::before {
 		opacity: 1;
@@ -333,7 +335,7 @@ code.Nm::before { content: "Nm"; }
 @media (max-width: 37.5em) {
 .manual-text {
 		margin-left: 0.5em; }
-.Sh, .Ss {	margin-left: 0em; }
+h1.Sh, h2.Ss {	margin-left: 0em; }
 .Bd-indent {	margin-left: 2em; }
 .Bl-hang > dd {
 		margin-left: 2em; }
diff --git a/mdoc_html.c b/mdoc_html.c
index ea750cdb..87bf42a7 100644
--- a/mdoc_html.c
+++ b/mdoc_html.c
@@ -1,4 +1,4 @@
-/*	$Id: mdoc_html.c,v 1.327 2019/01/18 14:36:21 schwarze Exp $ */
+/*	$Id: mdoc_html.c,v 1.328 2019/03/01 10:57:18 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2014-2019 Ingo Schwarze <schwarze@openbsd.org>
@@ -531,8 +531,10 @@ mdoc_sh_pre(MDOC_ARGS)
 		html_close_paragraph(h);
 		if ((h->oflags & HTML_TOC) == 0 ||
 		    h->flags & HTML_TOCDONE ||
-		    n->sec <= SEC_SYNOPSIS)
+		    n->sec <= SEC_SYNOPSIS) {
+			print_otag(h, TAG_SECTION, "c", "Sh");
 			break;
+		}
 		h->flags |= HTML_TOCDONE;
 		sc = 0;
 		for (sn = n->next; sn != NULL; sn = sn->next)
@@ -573,6 +575,7 @@ mdoc_sh_pre(MDOC_ARGS)
 			print_tagq(h, tsec);
 		}
 		print_tagq(h, t);
+		print_otag(h, TAG_SECTION, "c", "Sh");
 		break;
 	case ROFFT_HEAD:
 		id = html_make_id(n, 1);
@@ -598,6 +601,7 @@ mdoc_ss_pre(MDOC_ARGS)
 	switch (n->type) {
 	case ROFFT_BLOCK:
 		html_close_paragraph(h);
+		print_otag(h, TAG_SECTION, "c", "Ss");
 		return 1;
 	case ROFFT_HEAD:
 		break;
diff --git a/regress/man/IP/literal.out_html b/regress/man/IP/literal.out_html
index 844eb1dd..dce47df1 100644
--- a/regress/man/IP/literal.out_html
+++ b/regress/man/IP/literal.out_html
@@ -24,6 +24,7 @@ literal
 paragraph
 </pre>
 regular text
+<section class="Ss">
 <h2 class="Ss" id="literal_into_indented_paragraph"><a class="permalink" href="#literal_into_indented_paragraph">literal
   into indented paragraph</a></h2>
 regular text
@@ -42,6 +43,8 @@ text
     indented regular text</dd>
 </dl>
 <p class="Pp">new regular paragraph</p>
+</section>
+<section class="Ss">
 <h2 class="Ss" id="literal_out_of_indented_paragraph"><a class="permalink" href="#literal_out_of_indented_paragraph">literal
   out of indented paragraph</a></h2>
 regular text
diff --git a/regress/man/SH/paragraph.out_html b/regress/man/SH/paragraph.out_html
index 49627f19..6423855a 100644
--- a/regress/man/SH/paragraph.out_html
+++ b/regress/man/SH/paragraph.out_html
@@ -1,6 +1,10 @@
 BEGINTEST
+</section>
+<section class="Sh">
 <h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
 This text immediately follows a section header.
 <p class="Pp">This is a paragraph.</p>
+</section>
+<section class="Sh">
 <h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
 ENDTEST
diff --git a/regress/man/SS/paragraph.out_html b/regress/man/SS/paragraph.out_html
index bc803f86..fa385635 100644
--- a/regress/man/SS/paragraph.out_html
+++ b/regress/man/SS/paragraph.out_html
@@ -1,8 +1,11 @@
 BEGINTEST
+<section class="Ss">
 <h2 class="Ss" id="First_subsection"><a class="permalink" href="#First_subsection">First
   subsection</a></h2>
 This text immediately follows a subsection header.
 <p class="Pp">This is a paragraph.</p>
+</section>
+<section class="Ss">
 <h2 class="Ss" id="Second_subsection"><a class="permalink" href="#Second_subsection">Second
   subsection</a></h2>
 ENDTEST
diff --git a/regress/mdoc/Rs/paragraph.out_html b/regress/mdoc/Rs/paragraph.out_html
index ab2575e5..251d0d0c 100644
--- a/regress/mdoc/Rs/paragraph.out_html
+++ b/regress/mdoc/Rs/paragraph.out_html
@@ -4,6 +4,8 @@ initial reference: <cite class="Rs"><span class="RsA">author name</span>,
   <i class="RsB">book title</i>.</cite>
 <p class="Pp">in a paragraph: <cite class="Rs"><span class="RsA">another
     author</span>, <i class="RsB">another book</i>.</cite></p>
+</section>
+<section class="Sh">
 <h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
   ALSO</a></h1>
 initial reference:
diff --git a/regress/mdoc/Sh/paragraph.out_html b/regress/mdoc/Sh/paragraph.out_html
index 7d4f0d40..3b5154de 100644
--- a/regress/mdoc/Sh/paragraph.out_html
+++ b/regress/mdoc/Sh/paragraph.out_html
@@ -1,7 +1,11 @@
 BEGINTEST
 <p class="Pp">descriptive text</p>
+<section class="Ss">
 <h2 class="Ss" id="Subsection"><a class="permalink" href="#Subsection">Subsection</a></h2>
 initial subsection text
 <p class="Pp">subsection paragraph</p>
+</section>
+</section>
+<section class="Sh">
 <h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
 ENDTEST
diff --git a/regress/roff/ft/badargs.out_html b/regress/roff/ft/badargs.out_html
index 8b30ab05..5d98e988 100644
--- a/regress/roff/ft/badargs.out_html
+++ b/regress/roff/ft/badargs.out_html
@@ -6,4 +6,4 @@ default font <i></i><i>italic</i> <b><i></i></b><b><i>bold italic</i></b>
   <i></i> <i>italic</i> <b></b><b>bold</b> <b>still bold</b>
   <i></i><i>italic</i> <i></i><i>back to bold</i> <i></i><i>back to italic</i>
 <br/>
-ENDTEST</div>
+ENDTEST