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

* Re: patch: avoid multiple <h1>
  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 14:40 ` J. Lewis Muir
  1 sibling, 1 reply; 7+ messages in thread
From: Anna @ 2022-07-06 13:15 UTC (permalink / raw)
  To: Ingo Schwarze; +Cc: tech

On 2022-07-06 14:43, Ingo Schwarze wrote:
> 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.

a11y assessment tools[1] report no issues in using multiple <H1> tags.

[0]: https://addons.mozilla.org/en-US/firefox/addon/ainspector-wcag/
[1]: https://wave.webaim.org/report#/https://man.bsd.lv/true
 
> 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.

I think the current document outline is fine overall. I'd make all
sections (including NAME) H2 though, but keep original font size so
presentation doesn't change (only structure and semantics).

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

I don't think NAME is somewhat special. And what about malformed
manpages that might have no NAME?

>  * Use <p role="doc-subtitle"> for the .Nd in the .Nm section.
> Or something like that.

I like that idea.

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

I don't think it's wrong. I prefer outline (headings should reflect the
structure, not presentation) to be like that:

- Site name
  - NAME
  - DESCRIPTION
    - Subsection
  - ...

> 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

* Re: patch: avoid multiple <h1>
  2022-07-06 12:43 patch: avoid multiple <h1> Ingo Schwarze
  2022-07-06 13:15 ` Anna
@ 2022-07-06 14:40 ` J. Lewis Muir
  2022-07-06 16:34   ` Ingo Schwarze
  1 sibling, 1 reply; 7+ messages in thread
From: J. Lewis Muir @ 2022-07-06 14:40 UTC (permalink / raw)
  To: tech; +Cc: Anna

On 07/06, Ingo Schwarze wrote:
> 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.

Hi, Ingo!

The MDN page at

  https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements

seems to agree with you; in the "Usage notes" section, it says

  Use only one <h1> per page or view.  It should concisely describe the
  overall purpose of the content.

and

  Using more than one <h1> is allowed by the HTML specification, but is
  not considered a best practice.  Using only one <h1> is beneficial for
  screen reader users.

  The HTML specification includes the concept of an outline formed
  by the use of <section> elements.  If this were implemented it
  would enable the use of multiple <h1> elements, giving user
  agents--including screen readers--a way to understand that an <h1>
  nested inside a defined section is a subheading.  This functionality
  has never been implemented; therefore it is important to use your
  headings to describe the outline of your document.

Regards,

Lewis
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv


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

* Re: patch: avoid multiple <h1>
  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
  0 siblings, 2 replies; 7+ messages in thread
From: Ingo Schwarze @ 2022-07-06 14:40 UTC (permalink / raw)
  To: Anna; +Cc: tech

Hello Anna,

Anna wrote on Wed, Jul 06, 2022 at 06:15:47PM +0500:

> a11y assessment tools[1] report no issues in using multiple <H1> tags.
> [1]: https://wave.webaim.org/report#/https://man.bsd.lv/true

Nice.  I just linked that one from https://mandoc.bsd.lv/links.html .

> [0]: https://addons.mozilla.org/en-US/firefox/addon/ainspector-wcag/

I don't trust browser plugins and never use any.

> I think the current document outline is fine overall. I'd make all
> sections (including NAME) H2 though, but keep original font size so
> presentation doesn't change (only structure and semantics).

My patch already did that.

> I don't think NAME is somewhat special. And what about malformed
> manpages that might have no NAME?

Those cause much worse problems than slight HTML misformatting.
For example, they usually work very poorly with the command-line man(1)
and apropos(1) programs.  So considering them is hardly relevant.
Then again, since you dislike the idea of treating NAME specially,
i'll drop that idea for now.

> On 2022-07-06 14:43, Ingo Schwarze wrote:

>>  * Use <p role="doc-subtitle"> for the .Nd in the .Nm section.
>> Or something like that.

> I like that idea.

I'll look into that later.

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

> I don't think it's wrong. I prefer outline (headings should reflect the
> structure, not presentation) to be like that:
> 
> - Site name
>   - NAME
>   - DESCRIPTION
>     - Subsection
>   - ...

Fair enough, so i'll drop that idea, too, and maybe even consider
recommending in the man.cgi(8) manual that header.html can use <h1>
for the site name.

I committed the patch shown below.

Yours,
  Ingo


Log Message:
-----------
While the HTML standard allows multiple <h1> elements in the same
document, <h1> is intended for top level headers, and most of the
sections in a manual page can hardly be considered top-level.
It is more usual to use <h1> only for the main title of the document
of for the site name.

Consequently, move .Sh/.SH from <h1> to <h2> and .Ss/.SS from <h2>
to <h3>, freeing <h1> for use by header.html in man.cgi(8).

Discussed with Anna Vyalkova <cyber at sysrq dot in>.

Modified Files:
--------------
    mandoc:
        html.c
        html.h
        man_html.c
        mandoc.css
        mdoc_html.c
    mandoc/regress/man/IP:
        literal.out_html
    mandoc/regress/man/SH:
        paragraph.out_html
    mandoc/regress/man/SS:
        paragraph.out_html
    mandoc/regress/man/TP:
        vert.out_html
    mandoc/regress/mdoc/Er:
        tag.out_html
    mandoc/regress/mdoc/Rs:
        paragraph.out_html
    mandoc/regress/mdoc/Sh:
        paragraph.out_html
        tag.out_html
    mandoc/regress/mdoc/Tg:
        warn.out_html

Revision Data
-------------
Index: tag.out_html
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/mdoc/Sh/tag.out_html,v
retrieving revision 1.4
retrieving revision 1.5
diff -Lregress/mdoc/Sh/tag.out_html -Lregress/mdoc/Sh/tag.out_html -u -p -r1.4 -r1.5
--- regress/mdoc/Sh/tag.out_html
+++ regress/mdoc/Sh/tag.out_html
@@ -2,26 +2,26 @@
 </section>
 </section>
 <section class="Sh">
-<h1 class="Sh" id="DESCRIPTION~2"><a class="permalink" href="#DESCRIPTION~2">DESCRIPTION</a></h1>
+<h2 class="Sh" id="DESCRIPTION~2"><a class="permalink" href="#DESCRIPTION~2">DESCRIPTION</a></h2>
 <p class="Pp">Text in duplicate description section.</p>
 </section>
 <section class="Sh">
-<h1 class="Sh" id="examples"><a class="permalink" href="#examples">EXAMPLES</a></h1>
+<h2 class="Sh" id="examples"><a class="permalink" href="#examples">EXAMPLES</a></h2>
 <p class="Pp">Text introducing examples.</p>
 <section class="Ss">
-<h2 class="Ss" id="example"><a class="permalink" href="#example">Subsection</a></h2>
+<h3 class="Ss" id="example"><a class="permalink" href="#example">Subsection</a></h3>
 <p class="Pp">Example text.</p>
 </section>
 <section class="Ss">
-<h2 class="Ss" id="Sub-section"><a class="permalink" href="#Sub-section">Sub-section</a></h2>
+<h3 class="Ss" id="Sub-section"><a class="permalink" href="#Sub-section">Sub-section</a></h3>
 <p class="Pp">More example text.</p>
 </section>
 </section>
 <section class="Sh">
-<h1 class="Sh" id="WEIRD_SECTION"><a class="permalink" href="#WEIRD_SECTION">	
-  WEIRD SECTION	 </a></h1>
+<h2 class="Sh" id="WEIRD_SECTION"><a class="permalink" href="#WEIRD_SECTION">	
+  WEIRD SECTION	 </a></h2>
 <p class="Pp">Text in weird section.</p>
 </section>
 <section class="Sh">
-<h1 class="Sh">&#x00A0;</h1>
+<h2 class="Sh">&#x00A0;</h2>
 <p class="Pp">Text in section with empty header.</p>
Index: paragraph.out_html
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/mdoc/Sh/paragraph.out_html,v
retrieving revision 1.4
retrieving revision 1.5
diff -Lregress/mdoc/Sh/paragraph.out_html -Lregress/mdoc/Sh/paragraph.out_html -u -p -r1.4 -r1.5
--- regress/mdoc/Sh/paragraph.out_html
+++ regress/mdoc/Sh/paragraph.out_html
@@ -1,9 +1,9 @@
 <p class="Pp">descriptive text</p>
 <section class="Ss">
-<h2 class="Ss" id="Subsection"><a class="permalink" href="#Subsection">Subsection</a></h2>
+<h3 class="Ss" id="Subsection"><a class="permalink" href="#Subsection">Subsection</a></h3>
 <p class="Pp">initial subsection text</p>
 <p class="Pp">subsection paragraph</p>
 </section>
 </section>
 <section class="Sh">
-<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
+<h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
Index: man_html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man_html.c,v
retrieving revision 1.182
retrieving revision 1.183
diff -Lman_html.c -Lman_html.c -u -p -r1.182 -r1.183
--- man_html.c
+++ man_html.c
@@ -316,10 +316,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: html.h
===================================================================
RCS file: /home/cvs/mandoc/mandoc/html.h,v
retrieving revision 1.111
retrieving revision 1.112
diff -Lhtml.h -Lhtml.h -u -p -r1.111 -r1.112
--- html.h
+++ html.h
@@ -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: mdoc_html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc_html.c,v
retrieving revision 1.347
retrieving revision 1.348
diff -Lmdoc_html.c -Lmdoc_html.c -u -p -r1.347 -r1.348
--- mdoc_html.c
+++ mdoc_html.c
@@ -541,7 +541,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");
@@ -576,7 +576,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)
@@ -597,7 +597,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;
Index: mandoc.css
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mandoc.css,v
retrieving revision 1.51
retrieving revision 1.52
diff -Lmandoc.css -Lmandoc.css -u -p -r1.51 -r1.52
--- mandoc.css
+++ mandoc.css
@@ -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%; }
+h1, 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: html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/html.c,v
retrieving revision 1.277
retrieving revision 1.278
diff -Lhtml.c -Lhtml.c -u -p -r1.277 -r1.278
--- html.c
+++ html.c
@@ -81,8 +81,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: literal.out_html
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/man/IP/literal.out_html,v
retrieving revision 1.7
retrieving revision 1.8
diff -Lregress/man/IP/literal.out_html -Lregress/man/IP/literal.out_html -u -p -r1.7 -r1.8
--- regress/man/IP/literal.out_html
+++ regress/man/IP/literal.out_html
@@ -18,8 +18,8 @@ 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>
+<h3 class="Ss" id="literal_into_indented_paragraph"><a class="permalink" href="#literal_into_indented_paragraph">literal
+  into indented paragraph</a></h3>
 <p class="Pp">regular text</p>
 <pre>literal
 text</pre>
@@ -34,8 +34,8 @@ text</pre>
 <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>
+<h3 class="Ss" id="literal_out_of_indented_paragraph"><a class="permalink" href="#literal_out_of_indented_paragraph">literal
+  out of indented paragraph</a></h3>
 <p class="Pp">regular text</p>
 <dl class="Bl-tag">
   <dt id="tag~4"><a class="permalink" href="#tag~4">tag</a></dt>
Index: paragraph.out_html
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/man/SH/paragraph.out_html,v
retrieving revision 1.4
retrieving revision 1.5
diff -Lregress/man/SH/paragraph.out_html -Lregress/man/SH/paragraph.out_html -u -p -r1.4 -r1.5
--- regress/man/SH/paragraph.out_html
+++ regress/man/SH/paragraph.out_html
@@ -1,8 +1,8 @@
 </section>
 <section class="Sh">
-<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
+<h2 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h2>
 <p class="Pp">This text immediately follows a section header.</p>
 <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>
+<h2 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h2>
Index: paragraph.out_html
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/man/SS/paragraph.out_html,v
retrieving revision 1.4
retrieving revision 1.5
diff -Lregress/man/SS/paragraph.out_html -Lregress/man/SS/paragraph.out_html -u -p -r1.4 -r1.5
--- regress/man/SS/paragraph.out_html
+++ regress/man/SS/paragraph.out_html
@@ -1,9 +1,9 @@
 <section class="Ss">
-<h2 class="Ss" id="First_subsection"><a class="permalink" href="#First_subsection">First
-  subsection</a></h2>
+<h3 class="Ss" id="First_subsection"><a class="permalink" href="#First_subsection">First
+  subsection</a></h3>
 <p class="Pp">This text immediately follows a subsection header.</p>
 <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>
+<h3 class="Ss" id="Second_subsection"><a class="permalink" href="#Second_subsection">Second
+  subsection</a></h3>
Index: vert.out_html
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/man/TP/vert.out_html,v
retrieving revision 1.3
retrieving revision 1.4
diff -Lregress/man/TP/vert.out_html -Lregress/man/TP/vert.out_html -u -p -r1.3 -r1.4
--- regress/man/TP/vert.out_html
+++ regress/man/TP/vert.out_html
@@ -1,6 +1,6 @@
 </section>
 <section class="Sh">
-<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
+<h2 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h2>
 <dl class="Bl-tag">
   <dt id="tag"><a class="permalink" href="#tag">tag</a></dt>
   <dd>text</dd>
Index: tag.out_html
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/mdoc/Er/tag.out_html,v
retrieving revision 1.2
retrieving revision 1.3
diff -Lregress/mdoc/Er/tag.out_html -Lregress/mdoc/Er/tag.out_html -u -p -r1.2 -r1.3
--- regress/mdoc/Er/tag.out_html
+++ regress/mdoc/Er/tag.out_html
@@ -5,7 +5,7 @@
 <a class="permalink" href="#two"><code class="Er" id="two">two</code></a>
 </section>
 <section class="Sh">
-<h1 class="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h1>
+<h2 class="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h2>
 <dl class="Bl-tag">
   <dt id="ENOENT">[<a class="permalink" href="#ENOENT"><code class="Er">ENOENT</code></a>]</dt>
   <dd>text</dd>
Index: paragraph.out_html
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/mdoc/Rs/paragraph.out_html,v
retrieving revision 1.5
retrieving revision 1.6
diff -Lregress/mdoc/Rs/paragraph.out_html -Lregress/mdoc/Rs/paragraph.out_html -u -p -r1.5 -r1.6
--- regress/mdoc/Rs/paragraph.out_html
+++ regress/mdoc/Rs/paragraph.out_html
@@ -5,8 +5,8 @@
     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>
+<h2 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
+  ALSO</a></h2>
 <p class="Pp">initial reference:</p>
 <p class="Pp"><cite class="Rs"><span class="RsA">author name</span>,
     <i class="RsB">book title</i>.</cite></p>
Index: warn.out_html
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/mdoc/Tg/warn.out_html,v
retrieving revision 1.3
retrieving revision 1.4
diff -Lregress/mdoc/Tg/warn.out_html -Lregress/mdoc/Tg/warn.out_html -u -p -r1.3 -r1.4
--- regress/mdoc/Tg/warn.out_html
+++ regress/mdoc/Tg/warn.out_html
@@ -2,10 +2,10 @@
     <a class="permalink" href="#macro"><code class="Ic" id="macro">macro</code></a>
     too many badstart badend whitespace <mark id="sub"></mark></p>
 <section class="Ss">
-<h2 class="Ss" id="double"><a class="permalink" href="#double">Subsection</a></h2>
+<h3 class="Ss" id="double"><a class="permalink" href="#double">Subsection</a></h3>
 <p class="Pp">subtext</p>
 </section>
 </section>
 <section class="Sh">
-<h1 class="Sh" id="examples"><a class="permalink" href="#examples">EXAMPLES</a></h1>
+<h2 class="Sh" id="examples"><a class="permalink" href="#examples">EXAMPLES</a></h2>
 <p class="Pp">example text</p>
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv


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

* Re: patch: avoid multiple <h1>
  2022-07-06 14:40   ` Ingo Schwarze
@ 2022-07-06 15:34     ` Ingo Schwarze
  2022-07-06 15:58     ` Ingo Schwarze
  1 sibling, 0 replies; 7+ messages in thread
From: Ingo Schwarze @ 2022-07-06 15:34 UTC (permalink / raw)
  To: Anna; +Cc: tech

Hi Anna,

Ingo Schwarze wrote on Wed, Jul 06, 2022 at 04:40:37PM +0200:
> Anna wrote on Wed, Jul 06, 2022 at 06:15:47PM +0500:
>> On 2022-07-06 14:43, Ingo Schwarze wrote:

>>>  * Use <p role="doc-subtitle"> for the .Nd in the .Nm section.
>>> Or something like that.

>> I like that idea.

> I'll look into that later.

That was simple, see the commit below.

Yours,
  Ingo


Log Message:
-----------
assign the ARIA role "doc-subtitle" to the .Nd element;
discussed with Anna Vyalkova <cyber at sysrq dot in>

Modified Files:
--------------
    mandoc:
        mdoc_html.c

Revision Data
-------------
Index: mdoc_html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc_html.c,v
retrieving revision 1.348
retrieving revision 1.349
diff -Lmdoc_html.c -Lmdoc_html.c -u -p -r1.348 -r1.349
--- mdoc_html.c
+++ mdoc_html.c
@@ -637,7 +637,7 @@ mdoc_nd_pre(MDOC_ARGS)
 		abort();
 	}
 	print_text(h, "\\(em");
-	print_otag(h, TAG_SPAN, "c", "Nd");
+	print_otag(h, TAG_SPAN, "cr", "Nd", "doc-subtitle");
 	return 1;
 }
 
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv


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

* Re: patch: avoid multiple <h1>
  2022-07-06 14:40   ` Ingo Schwarze
  2022-07-06 15:34     ` Ingo Schwarze
@ 2022-07-06 15:58     ` Ingo Schwarze
  1 sibling, 0 replies; 7+ messages in thread
From: Ingo Schwarze @ 2022-07-06 15:58 UTC (permalink / raw)
  To: Anna; +Cc: tech

Hi,

Ingo Schwarze wrote on Wed, Jul 06, 2022 at 04:40:37PM +0200:

> [...] i'll [...] maybe even consider recommending in the man.cgi(8)
> manual that header.html can use <h1> for the site name.

Done, see the commit below.

So i think this thread is now taken care of;
please remind me if i forgot something.

Yours,
  Ingo


Log Message:
-----------
improve the description of header.html and footer.html

Modified Files:
--------------
    mandoc:
        man.cgi.8

Revision Data
-------------
Index: man.cgi.8
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man.cgi.8,v
retrieving revision 1.23
retrieving revision 1.24
diff -Lman.cgi.8 -Lman.cgi.8 -u -p -r1.23 -r1.24
--- man.cgi.8
+++ man.cgi.8
@@ -381,11 +381,13 @@ or any character not contained in the
 .Nm
 reports an internal server error and exits without doing anything.
 .It Pa /man/header.html
-An optional file containing static HTML code to be inserted right
-after opening the <BODY> element.
+An optional file containing static HTML code to be wrapped in
+a <HEADER> element and inserted right after opening the <BODY> element.
+For example, it can contain an <H1> element
+specifying the name of the website.
 .It Pa /man/footer.html
-An optional file containing static HTML code to be inserted right
-before closing the <BODY> element.
+An optional file containing static HTML code to be wrapped in
+a <FOOTER> element and inserted right before closing the <BODY> element.
 .It Pa /man/OpenBSD-current/man1/mandoc.1
 An example
 .Xr mdoc 7
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv


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

* Re: patch: avoid multiple <h1>
  2022-07-06 14:40 ` J. Lewis Muir
@ 2022-07-06 16:34   ` Ingo Schwarze
  0 siblings, 0 replies; 7+ messages in thread
From: Ingo Schwarze @ 2022-07-06 16:34 UTC (permalink / raw)
  To: J. Lewis Muir; +Cc: tech

Hi Lewis,

J. Lewis Muir wrote on Wed, Jul 06, 2022 at 09:40:20AM -0500:

> The MDN page at
> 
>   https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements
> 
> seems to agree with you; in the "Usage notes" section, it says
> 
>   Use only one <h1> per page or view.  It should concisely describe the
>   overall purpose of the content.
> 
> and
> 
>   Using more than one <h1> is allowed by the HTML specification, but is
>   not considered a best practice.  Using only one <h1> is beneficial for
>   screen reader users.
> 
>   The HTML specification includes the concept of an outline formed
>   by the use of <section> elements.  If this were implemented it
>   would enable the use of multiple <h1> elements, giving user
>   agents--including screen readers--a way to understand that an <h1>
>   nested inside a defined section is a subheading.  This functionality
>   has never been implemented; therefore it is important to use your
>   headings to describe the outline of your document.

Thank you for that additional pointer, it's quite interesting and led me
to a few facts i did not yet know.

The most important takeaway probably is that what i committed is very
likely reasonable, as also confirmed by Anna.

One thing i didn't understand before following your pointer is that
wrapping <h1> inside nested <section> elements is particularly bad
because browsers do not support it.  What mandoc -T html did before
my commit wasn't quite as bad as that because at least all the <h1>
elements were on the same outline level, and all the headings on the
lower level used <h2>.

Yours,
  Ingo
--
 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).