From: Anna <cyber@sysrq.in>
To: Ingo Schwarze <schwarze@usta.de>
Cc: tech@mandoc.bsd.lv
Subject: Re: patch: avoid multiple <h1>
Date: Wed, 6 Jul 2022 18:15:47 +0500 [thread overview]
Message-ID: <YsWLA7tcka2rZfHK@sysrq.in> (raw)
In-Reply-To: <YsWDjxGjXhNvV5lw@asta-kit.de>
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
next prev parent reply other threads:[~2022-07-06 13:15 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-07-06 12:43 Ingo Schwarze
2022-07-06 13:15 ` Anna [this message]
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=YsWLA7tcka2rZfHK@sysrq.in \
--to=cyber@sysrq.in \
--cc=schwarze@usta.de \
--cc=tech@mandoc.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).