Re: [PATCH] docs: automarkup: Mark up undocumented entities too

[Jonathan Corbet <corbet@lwn.net>]

Nícolas F. R. A. Prado <nfraprado@collabora.com> writes:

> On Tue, Jun 03, 2025 at 03:12:35PM -0600, Jonathan Corbet wrote:
>> Nícolas F. R. A. Prado <nfraprado@collabora.com> writes:
>> 
>> > To me the results look much better without these CSS rules, as they cause a
>> > double underline.
>> >
>> > The current CSS already adds a dotted underline to reference links through the
>> > following rule:
>> >
>> > 	a.reference {
>> > 	  border-bottom: 1px dotted #004B6B;
>> > 	}
>> 
>> OK, that is interesting ... I don't see that underline.
>> 
>> Are you using the (default) alabaster theme?  Alabaster explicitly sets
>> it to "none", as can be seen on docs.kernel.org.
>
> Yes. And I also see this same dotted underline on docs.kernel.org, for every URL
> on that page. I've also double-checked this is the case when accessing from my
> phone, and in incognito, so maybe this is something on your end?
>
> To be clear, you don't see underlines on any URLs on docs.kernel.org?
>
> You could find the CSS rule I mentioned above in
>
> https://docs.kernel.org/_static/alabaster.css

OK, this is downright mysterious.  It's using borders, which is
weird... for me, that "border" does not render, even though the browser
claims it has a 1px width, as expected.  I get this behavior both in
Firefox and with a bog-standard, thoroughly unconfigured Chromium I keep
around for just this kind of purpose.

Chrome on the phone shows a faint underline, firefox does not.

>> We need to figure out why you are seeing something different.  But I do
>> want rules to distinguish just-plain-function from
>> function-with-kerneldoc.
>
> Maybe I wasn't clear, but on my end they are already rendered
> differently with your change in automarkup.py, but without the CSS
> change. Both show up as bold monospaced texts, but only in the case
> where the link is valid is there a <a> tag, so only that one gets this
> dotted underline. When the xref doesn't exist there's no underline.

OK, I can see that would happen that way - at least, if it actually
worked as expected.

I wonder why they used a border rather than the text-decoration that is
there for exactly that purpose?  I'm inclined to change the CSS to get
reliable underlining for everybody.

Thanks,

jon