* 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 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"> </h1> +<h2 class="Sh"> </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 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 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).