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.0 required=5.0 tests=T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 10856 invoked from network); 6 Jul 2022 14:40:47 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 6 Jul 2022 14:40:47 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 6729bac6 for ; Wed, 6 Jul 2022 09:40:46 -0500 (EST) Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id ae40c9b8 for ; Wed, 6 Jul 2022 09:40:40 -0500 (EST) Received: from hekate.asta.kit.edu ([2a00:1398:5:f401::77]) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.3:ECDHE_SECP256R1__RSA_PSS_RSAE_SHA256__AES_256_GCM:256) (envelope-from ) id 1o96Ck-00H6jZ-Pc; Wed, 06 Jul 2022 16:40:39 +0200 Received: from login-1.asta.kit.edu ([2a00:1398:5:f400::72]) by hekate.asta.kit.edu with esmtp (Exim 4.94.2) (envelope-from ) id 1o96Ci-006LLj-Lx; Wed, 06 Jul 2022 16:40:37 +0200 Received: from schwarze by login-1.asta.kit.edu with local (Exim 4.92) (envelope-from ) id 1o96Cj-0008Vb-25; Wed, 06 Jul 2022 16:40:37 +0200 Date: Wed, 6 Jul 2022 16:40:37 +0200 From: Ingo Schwarze To: Anna 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: Hello Anna, Anna wrote on Wed, Jul 06, 2022 at 06:15:47PM +0500: > a11y assessment tools[1] report no issues in using multiple

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

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

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

for the site name. I committed the patch shown below. Yours, Ingo Log Message: ----------- While the HTML standard allows multiple

elements in the same document,

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

only for the main title of the document of for the site name. Consequently, move .Sh/.SH from

to

and .Ss/.SS from

to

, freeing

for use by header.html in man.cgi(8). Discussed with Anna Vyalkova . 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 @@
-

+

Text in duplicate description section.

-

+

Text introducing examples.

-

+

Example text.

-

+

More example text.

-

+

Text in weird section.

-

 

+

 

Text in section with empty header.

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

descriptive text

-

+

initial subsection text

subsection paragraph

-

+

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 regular text
-

+

regular text

literal
 text
@@ -34,8 +34,8 @@ text

new regular paragraph

-

+

regular text

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

+

This text immediately follows a section header.

This is a paragraph.

-

+

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

+

This text immediately follows a subsection header.

This is a paragraph.

-

+

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

+

text
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 @@
-

+

[]
text
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, another book.

-

+

initial reference:

author name, book title.

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 @@ too many badstart badend whitespace

-

+

subtext

-

+

example text

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