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

diff --git a/html.c b/html.c
index 07ca63f7ee01cad9b3bab43af78761fe4558e069..bda1947be297a65c57553501e1790d305a2e56ba 100644 (file)
--- a/html.c
+++ b/html.c
@@ -1,4 +1,4 @@
-/* $Id: html.c,v 1.277 2022/07/03 14:29:44 schwarze Exp $ */
+/* $Id: html.c,v 1.278 2022/07/06 14:34:59 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2011-2015, 2017-2021 Ingo Schwarze <schwarze@openbsd.org>
@@ -81,8 +81,8 @@ static        const struct htmldata htmltags[TAG_MAX] = {
        {"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},

diff --git a/html.h b/html.h
index 7c73fa4b5a8e85e6510cf02c50b0d6fb9fbc1763..49ae0f72960c2452c6c9b816174d7a3fdcbaf6de 100644 (file)
--- a/html.h
+++ b/html.h
@@ -1,4 +1,4 @@
-/* $Id: html.h,v 1.111 2022/07/03 14:29:44 schwarze Exp $ */
+/* $Id: html.h,v 1.112 2022/07/06 14:34:59 schwarze Exp $ */
 /*
  * Copyright (c) 2017, 2018, 2019, 2020 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
@@ -40,8 +40,8 @@ enum  htmltag {
        TAG_DL,
        TAG_DT,
        TAG_DD,
-       TAG_H1,
        TAG_H2,
+       TAG_H3,
        TAG_P,
        TAG_PRE,
        TAG_A,

diff --git a/man_html.c b/man_html.c
index 19337a10321cb2959ac91104eebc09760a049b46..6ad355787a2df20a8f216f30d06e3507e69e9cbe 100644 (file)
--- a/man_html.c
+++ b/man_html.c
@@ -1,4 +1,4 @@
-/* $Id: man_html.c,v 1.182 2022/07/05 21:25:29 schwarze Exp $ */
+/* $Id: man_html.c,v 1.183 2022/07/06 14:34:59 schwarze Exp $ */
 /*
  * Copyright (c) 2013-2015,2017-2020,2022 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2008-2012, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
@@ -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) {

diff --git a/mandoc.css b/mandoc.css
index f2b5e733f79243bde16eba613c0637d721e97870..1dae127059d6534801de892bdce6ab338585ff72 100644 (file)
--- a/mandoc.css
+++ b/mandoc.css
@@ -1,4 +1,4 @@
-/* $Id: mandoc.css,v 1.51 2022/07/05 21:25:29 schwarze Exp $ */
+/* $Id: mandoc.css,v 1.52 2022/07/06 14:34:59 schwarze Exp $ */
 /*
  * Standard style sheet for mandoc(1) -Thtml and man.cgi(8).
  *
@@ -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::before, .Sx::before, .Sy::before,
 .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::before, .Sx::before, .Sy::before,
 
 @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; }

diff --git a/mdoc_html.c b/mdoc_html.c
index bd731ddf4be98d67b52209b9c709bf83a228c240..1193c61c21d7613fc0559641e3260fb9a880b96a 100644 (file)
--- a/mdoc_html.c
+++ b/mdoc_html.c
@@ -1,4 +1,4 @@
-/* $Id: mdoc_html.c,v 1.347 2022/07/05 21:25:29 schwarze Exp $ */
+/* $Id: mdoc_html.c,v 1.348 2022/07/06 14:34:59 schwarze Exp $ */
 /*
  * Copyright (c) 2014-2022 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
@@ -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;

diff --git a/regress/man/IP/literal.out_html b/regress/man/IP/literal.out_html
index ceb26a561ece73b87a19437dfe34ac23af934424..00042b90868e48ce75699e2337fbbeb613f3c784 100644 (file)
--- a/regress/man/IP/literal.out_html
+++ b/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>

diff --git a/regress/man/SH/paragraph.out_html b/regress/man/SH/paragraph.out_html
index abe932b4d5ad037f9a5b3df11fc4c1b863a65a56..aef8d35c311f9cd661d5b7236f758d6a4f1e4c96 100644 (file)
--- a/regress/man/SH/paragraph.out_html
+++ b/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>

diff --git a/regress/man/SS/paragraph.out_html b/regress/man/SS/paragraph.out_html
index 22591deb759666be038a5e1c391f7d74e5d6762e..dcfaf5914fabe5a550398c202d7c9d258431ba90 100644 (file)
--- a/regress/man/SS/paragraph.out_html
+++ b/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>

diff --git a/regress/man/TP/vert.out_html b/regress/man/TP/vert.out_html
index 4499432b1a5a37effe8f4a2b8ac140e1e4089c1f..96544b3e53e2f191758e12fc3d445b248d1f2a21 100644 (file)
--- a/regress/man/TP/vert.out_html
+++ b/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>

diff --git a/regress/mdoc/Er/tag.out_html b/regress/mdoc/Er/tag.out_html
index 80daa28b798989e10a812590d0d63a41ac06edb1..081ca1ea0fcc2c6dc5d5a44c8d21900ec0fb0e7b 100644 (file)
--- a/regress/mdoc/Er/tag.out_html
+++ b/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>

diff --git a/regress/mdoc/Rs/paragraph.out_html b/regress/mdoc/Rs/paragraph.out_html
index bfb0a7240c2df2d0f7040022cd52de0440a803cd..0a4fc8a3ac3b8b11a12c8785f62a374780d7ef8a 100644 (file)
--- a/regress/mdoc/Rs/paragraph.out_html
+++ b/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>

diff --git a/regress/mdoc/Sh/paragraph.out_html b/regress/mdoc/Sh/paragraph.out_html
index 82ede5beac54d8e6397dbbeb49ac5650fad8c79e..7dc93653a321a991adb8a74e0b4aa0703ed3e9e7 100644 (file)
--- a/regress/mdoc/Sh/paragraph.out_html
+++ b/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>

diff --git a/regress/mdoc/Sh/tag.out_html b/regress/mdoc/Sh/tag.out_html
index 0dd39398470a2c6b6b408661901b42d41fa39eac..94332652d0d3e5a70c4f9d8de9bbae334dba41f9 100644 (file)
--- a/regress/mdoc/Sh/tag.out_html
+++ b/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>

diff --git a/regress/mdoc/Tg/warn.out_html b/regress/mdoc/Tg/warn.out_html
index a7f925740d010d366faebc55261344af7807f6f5..cd542ba93aadd95028f826ff2c848562b46b34a7 100644 (file)
--- a/regress/mdoc/Tg/warn.out_html
+++ b/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>