Debian theme's CSS leaks into the HTML elements of the manpage's content

[n-peugnet]

Description of the problem

1. Generated HTML elements of the manpage's content can have id attributes. This is useful, for example to be able to link to specific options, inside a manpage.
2. Debian theme's CSS mainly use id to target elements to style, for example #footer { ... }.
3. If a generated HTML element has an id used by Debian theme's CSS, it inherits its style.

See https://manpages.debian.org/unstable/lintian-ssg/lintian-ssg.1.en.html#footer for an example of this problem:

Solutions imagined

1. Use a prefix for the id of layout elements to prevent them conflicting with the manpage's content's HTML elements.
2. Use a prefix for the id of the generated HTML elements to prevent them conflicting with the layout elements.
3. Specify the css rules more precisely to avoid targeting the manpage's content HTML elements. For example using body > div#footer { ... }

I think (2) is not ideal, as it would add a processing step in the manpage rendering code, and it would also break existing links to anchors. So this leaves (1) and (3). I would say I prefer option (3) as it only involves modifying the CSS, which keeps it more similar to the rest of the Debian sites.

If you agree with my proposition, I can make a pull request that make the Debian theme's CSS selector stricter to avoid this problem in the future.

P.S. One last issue that option (3) leaves unresolved, is that multiple elements with the same id is forbidden by the HTML standard, but I think this is not a major issue as it is gracefully handled by Web browsers.

[n-peugnet]

After thinking a little more, I think solution (1) is the best. Because for occurrences of this bug where the id is the same as a previous element, in addition to inheriting the styles, it is also impossible to link to the correct element. See for example: https://manpages.debian.org/unstable/coreutils/numfmt.1.en.html#header

Seeing the kind of id than mandoc generates, I think prefixing the template ids with _ should probably be enough.

[stapelberg]

Hey @n-peugnet

Thanks for your report.

Ideally we’d prefix the ids (option 1), but given that this would break all links to manpages.d.o that specify a section, I don’t think we can do that.

Following option 3 sounds best, resorting to option 2 where absolutely needed.

Feel free to send a PR. Note that the debian assets live in https://salsa.debian.org/manpages-team/debian-assets, so you’d likely need to update both, the debian-assets and this repository’s fallback styles.

Thanks in advance

By the way: we already do post-processing of the "id" attribute to fix up what mandoc produces:

debiman/internal/convert/convert.go

Lines 340 to 345 in 4afba3a

	// HTML5 requires that ids must contain at least one character
	// and may not contain any spaces, see
	// http://stackoverflow.com/a/79022/712014
	id := strings.Replace(text, " ", "_", -1)
	u := url.URL{Fragment: id}
	replaceId(n, id)

[DakotaB75]

I’ve prepared a minimal fix following the approach discussed above.

Instead of renaming or post-processing generated IDs, the CSS selectors
for layout elements are now made more specific (e.g. body > div#header,
body > div#footer). This prevents Debian theme styles from leaking into
manpage content while preserving existing anchors and external links.

This keeps the rendering logic unchanged and aligns with the preference
to avoid breaking backward compatibility.

PR forthcoming.

[stapelberg]

I also did a -force_rerender run on manziarly.debian.org, which completed in roughly 2 hours.

The result should be picked up within the next day on manpages.debian.org.