From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=0.2 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, T_SCC_BODY_TEXT_LINE autolearn=no autolearn_force=no version=3.4.4 Received: (qmail 32516 invoked from network); 6 Jul 2022 13:15:57 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 6 Jul 2022 13:15:57 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 652b0a8e for ; Wed, 6 Jul 2022 08:15:54 -0500 (EST) Received: from sysrq.in (sysrq.in [37.79.202.136]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 02624b33 for ; Wed, 6 Jul 2022 08:15:53 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sysrq.in; s=sysrq.in; t=1657113348; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references:autocrypt:autocrypt; bh=AsE11Cuox4k1F0DzJgKY8W8mCswF5FKnvQGHQVWf0oc=; b=AXQskhCSwZfJKoAnCcx9uZn+Iv0SoRyEs1GZPfTQSuV1CxRp2OaHdO+xzPYG/5lycfsQls fpVoyCFnEBd6z2zB0OKUTv97oQJsZ//uPdLSlJ5R5pwiQHVxXbN/S7W6CoJxzPJQLB9Kax M987nW9WImddCfvLDEUDuEA7VRe8x0jMS1bKSaD1axDpdwZSeE2QmCuNGL57PbL6GQ4jrh rCvrAsmQ/Kwh0lzuqy23yRdZt5h57t+AHQbVjHO+piz6LpTFcUWkN6jPnR9+dg4OyAXUTU 6ZNnCXHXsFDZCFOUI0/UaO/VCpJYh37F5nNkP8y54eZbWgj9abQUSDOZaV9mDA== Received: from sysrq.in (localhost [127.0.0.1]) by sysrq.in (OpenSMTPD) with ESMTPSA id dfa91b4f (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Wed, 6 Jul 2022 13:15:48 +0000 (UTC) Date: Wed, 6 Jul 2022 18:15:47 +0500 From: Anna To: Ingo Schwarze Cc: tech@mandoc.bsd.lv Subject: Re: patch: avoid multiple

Message-ID: References: X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: Autocrypt: addr=cyber@sysrq.in; prefer-encrypt=mutual; keydata= mDMEYIFqhRYJKwYBBAHaRw8BAQdAmXuImZ3E4FYSZevE6xmeyqwBedA5TL3F0mA4nM8Jv5C0J0F ubmEg4oCcQ3liZXJUYWlsb3LigJ0gPGN5YmVyQHN5c3JxLmluPoiQBBMWCAA4FiEERA3R5VXjf5 x8ewz7f6gU36rhAzoFAmCBaoUCGwMFCwkIBwIGFQoJCAsCBBYCAwECHgECF4AACgkQf6gU36rhA zoeCwD/UbmIjoaPHgxAubn/yoHbqtix0p1W8BwVdZSBinqtoc8BAMX19adz5Zx71lYFinFG7Yav D4E0jClMEfnYJH2TeG4HuDgEYIFqhRIKKwYBBAGXVQEFAQEHQGL1LYMPZDabnCTPEuyg5QgIlnU bKBqoPjp5sNidRZJXAwEIB4h4BBgWCAAgFiEERA3R5VXjf5x8ewz7f6gU36rhAzoFAmCBaoUCGw wACgkQf6gU36rhAzpFxwD/Z0QQGqLgBcafYUcHmzYcYxuyazuKWIn3H6OkeFUYtTgBAJmK2E+Yo mSMc0Ds93+yNQU0KhN1Ipyp9PiLDSSm8Z4B User-Agent: Mutt/2.2.6 (2022-06-05) 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

, it contains several examples of header hierarchies, > and only a single one among these examples contains more than one

. > That example seems a bit contrived, too. > > Most users expect to find a single

containing the main title > of the document. As far as i understand, if there is more than > one

, that may easily confuse blind users. a11y assessment tools[1] report no issues in using multiple

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

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

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

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

> 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

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