tech@mandoc.bsd.lv
 help / color / mirror / Atom feed
* patch: avoid multiple <h1>
@ 2022-07-06 12:43 Ingo Schwarze
  2022-07-06 13:15 ` Anna
  2022-07-06 14:40 ` J. Lewis Muir
  0 siblings, 2 replies; 7+ messages in thread
From: Ingo Schwarze @ 2022-07-06 12:43 UTC (permalink / raw)
  To: Anna; +Cc: tech

Hello Anna,

do we want the following patch?
I just installed it for testing on man.bsd.lv.

The rationale goes as follows:

While the HTML standard explicitely allows documents containing more
than one <h1>, it contains several examples of header hierarchies,
and only a single one among these examples contains more than one <h1>.
That example seems a bit contrived, too.

Most users expect to find a single <h1> containing the main title
of the document.  As far as i understand, if there is more than
one <h1>, that may easily confuse blind users.

I see no good reason why mandoc should write multiple <h1> headers
in a single manual page.  Logically, sections like ENVIRONMENT,
EXAMPLES, DIAGNOSTICS, HISTORY, AUTHORS can hardly be considered
top-level.  They feel like subdivisions of a document, the top
level title of which is provided in the NAME section.

If we do this, we could afterwards consider an optional second step:
 * Turn the mdoc(7)/man(7) NAME section into an <hgroup>.
 * Use <h1> for the .Nm in the NAME section.
 * Use <p role="doc-subtitle"> for the .Nd in the .Nm section.
Or something like that.

On a related note, i think the widespread practice of putting <h1>
into header.html (seen on man.bsd.lv, man.openbsd.org,
and www.freebsd.org/cgi/man.cgi) is wrong.  I think a more normal
element like <p> should be used there, but that is yet another
later step.

What do you think?
  Ingo


Index: html.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/html.c,v
retrieving revision 1.148
diff -u -p -r1.148 html.c
--- html.c	3 Jul 2022 14:28:26 -0000	1.148
+++ html.c	6 Jul 2022 11:45:33 -0000
@@ -79,8 +79,8 @@ static	const struct htmldata htmltags[TA
 	{"dl",		HTML_NLALL | HTML_INDENT},
 	{"dt",		HTML_NLAROUND},
 	{"dd",		HTML_NLAROUND | HTML_INDENT},
-	{"h1",		HTML_TOPHRASE | HTML_NLAROUND},
 	{"h2",		HTML_TOPHRASE | HTML_NLAROUND},
+	{"h3",		HTML_TOPHRASE | HTML_NLAROUND},
 	{"p",		HTML_TOPHRASE | HTML_NLAROUND | HTML_INDENT},
 	{"pre",		HTML_TOPHRASE | HTML_NLAROUND | HTML_NOINDENT},
 	{"a",		HTML_INPHRASE | HTML_TOPHRASE},
Index: html.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/html.h,v
retrieving revision 1.73
diff -u -p -r1.73 html.h
--- html.h	3 Jul 2022 14:28:27 -0000	1.73
+++ html.h	6 Jul 2022 11:45:33 -0000
@@ -40,8 +40,8 @@ enum	htmltag {
 	TAG_DL,
 	TAG_DT,
 	TAG_DD,
-	TAG_H1,
 	TAG_H2,
+	TAG_H3,
 	TAG_P,
 	TAG_PRE,
 	TAG_A,
Index: man_html.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man_html.c,v
retrieving revision 1.135
diff -u -p -r1.135 man_html.c
--- man_html.c	5 Jul 2022 21:25:23 -0000	1.135
+++ man_html.c	6 Jul 2022 11:45:33 -0000
@@ -314,10 +314,10 @@ man_SH_pre(MAN_ARGS)
 	enum htmltag	 tag;
 
 	if (n->tok == MAN_SH) {
-		tag = TAG_H1;
+		tag = TAG_H2;
 		class = "Sh";
 	} else {
-		tag = TAG_H2;
+		tag = TAG_H3;
 		class = "Ss";
 	}
 	switch (n->type) {
Index: mandoc.css
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.css,v
retrieving revision 1.38
diff -u -p -r1.38 mandoc.css
--- mandoc.css	5 Jul 2022 21:25:24 -0000	1.38
+++ mandoc.css	6 Jul 2022 11:45:33 -0000
@@ -16,7 +16,7 @@ html {		max-width: 65em;
 body {		background: var(--bg);
 		color: var(--fg);
 		font-family: Helvetica,Arial,sans-serif; }
-h1 {		font-size: 110%; }
+h2 {		font-size: 110%; }
 table {		margin-top: 0em;
 		margin-bottom: 0em;
 		border-collapse: collapse; }
@@ -81,11 +81,11 @@ div[role=doc-pagefooter] {
 main {		margin-left: 3.8em; }
 .Nd { }
 section.Sh { }
-h1.Sh {		margin-top: 1.2em;
+h2.Sh {		margin-top: 1.2em;
 		margin-bottom: 0.6em;
 		margin-left: -3.2em; }
 section.Ss { }
-h2.Ss {		margin-top: 1.2em;
+h3.Ss {		margin-top: 1.2em;
 		margin-bottom: 0.6em;
 		margin-left: -1.2em;
 		font-size: 105%; }
@@ -271,7 +271,7 @@ a.In { }
 
 /* Tooltip support. */
 
-h1.Sh, h2.Ss {	position: relative; }
+h2.Sh, h3.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 {
@@ -301,8 +301,8 @@ code.In::before { content: "In"; }
 code.Nm::before { content: "Nm"; }
 .Pa::before {	content: "Pa"; }
 .Rs::before {	content: "Rs"; }
-h1.Sh::before {	content: "Sh"; }
-h2.Ss::before {	content: "Ss"; }
+h2.Sh::before {	content: "Sh"; }
+h3.Ss::before {	content: "Ss"; }
 .St::before {	content: "St"; }
 .Sx::before {	content: "Sx"; }
 .Sy::before {	content: "Sy"; }
@@ -316,7 +316,7 @@ h2.Ss::before {	content: "Ss"; }
 .Ic::before, code.In::before, .Lb::before, .Lk::before,
 .Ms::before, .Mt::before, .Nd::before, code.Nm::before,
 .Pa::before, .Rs::before,
-h1.Sh::before, h2.Ss::before, .St::before, .Sx::before, .Sy::before,
+h2.Sh::before, h3.Ss::before, .St::before, .Sx::before, .Sy::before,
 .Va::before, .Vt::before, .Xr::before {
 		opacity: 0;
 		transition: .15s ease opacity;
@@ -337,7 +337,7 @@ h1.Sh::before, h2.Ss::before, .St::befor
 .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, h1.Sh:hover::before, h2.Ss:hover::before, .St:hover::before,
+.Rs:hover::before, h2.Sh:hover::before, h3.Ss:hover::before, .St:hover::before,
 .Sx:hover::before, .Sy:hover::before, .Va:hover::before, .Vt:hover::before,
 .Xr:hover::before {
 		opacity: 1;
@@ -347,7 +347,7 @@ h1.Sh::before, h2.Ss::before, .St::befor
 
 @media (max-width: 37.5em) {
 main {		margin-left: 0.5em; }
-h1.Sh, h2.Ss {	margin-left: 0em; }
+h2.Sh, h3.Ss {	margin-left: 0em; }
 .Bd-indent {	margin-left: 2em; }
 .Bl-hang > dd {
 		margin-left: 2em; }
Index: mdoc_html.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_html.c,v
retrieving revision 1.222
diff -u -p -r1.222 mdoc_html.c
--- mdoc_html.c	5 Jul 2022 21:25:24 -0000	1.222
+++ mdoc_html.c	6 Jul 2022 11:45:33 -0000
@@ -539,7 +539,7 @@ mdoc_sh_pre(MDOC_ARGS)
 		if (sc < 2)
 			break;
 		tnav = print_otag(h, TAG_NAV, "r", "doc-toc");
-		t = print_otag(h, TAG_H1, "c", "Sh");
+		t = print_otag(h, TAG_H2, "c", "Sh");
 		print_text(h, "TABLE OF CONTENTS");
 		print_tagq(h, t);
 		t = print_otag(h, TAG_UL, "c", "Bl-compact");
@@ -574,7 +574,7 @@ mdoc_sh_pre(MDOC_ARGS)
 		print_otag(h, TAG_SECTION, "c", "Sh");
 		break;
 	case ROFFT_HEAD:
-		print_otag_id(h, TAG_H1, "Sh", n);
+		print_otag_id(h, TAG_H2, "Sh", n);
 		break;
 	case ROFFT_BODY:
 		if (n->sec == SEC_AUTHORS)
@@ -595,7 +595,7 @@ mdoc_ss_pre(MDOC_ARGS)
 		print_otag(h, TAG_SECTION, "c", "Ss");
 		break;
 	case ROFFT_HEAD:
-		print_otag_id(h, TAG_H2, "Ss", n);
+		print_otag_id(h, TAG_H3, "Ss", n);
 		break;
 	case ROFFT_BODY:
 		break;
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv


^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2022-07-06 16:34 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-07-06 12:43 patch: avoid multiple <h1> Ingo Schwarze
2022-07-06 13:15 ` Anna
2022-07-06 14:40   ` Ingo Schwarze
2022-07-06 15:34     ` Ingo Schwarze
2022-07-06 15:58     ` Ingo Schwarze
2022-07-06 14:40 ` J. Lewis Muir
2022-07-06 16:34   ` Ingo Schwarze

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).