search

Debian / debiman

debiman generates a static manpage HTML repository out of a Debian archive
Apache License 2.0
195 stars 46 forks source link

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

Open n-peugnet opened 1 month ago

n-peugnet commented 1 month ago

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: 2024-10-09-161116_677x274_scrot

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 commented 1 month ago

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 commented 1 month ago

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: https://github.com/Debian/debiman/blob/4afba3a1fef8fc4215d59c13926082ac1001a987/internal/convert/convert.go#L340-L345