Em Tue, 3 Jun 2025 15:44:42 -0400
Nícolas F. R. A. Prado <nfraprado@xxxxxxxxxxxxx> escreveu:
> On Tue, Jun 03, 2025 at 11:20:16AM -0600, Jonathan Corbet wrote:
> > The automarkup code generates markup and a cross-reference links for
> > functions, structs, etc. for which it finds kerneldoc documentation.
> > Undocumented entities are left untouched; that creates an inconsistent
> > reading experience and has caused some writers to go to extra measures to
> > cause the markup to happen.
> >
> > Mark up detected C entities regardless of whether they are documented.
> > Change the CSS, though, to underline the entities that actually link to
> > documentation, making our docs a bit more consistent with longstanding WWW
> > practice and allowing readers to tell the difference.
> >
> > Signed-off-by: Jonathan Corbet <corbet@xxxxxxx>
> > ---
> > Documentation/sphinx-static/custom.css | 5 +++++
> > Documentation/sphinx/automarkup.py | 9 +++++++--
> > 2 files changed, 12 insertions(+), 2 deletions(-)
> >
> > diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> > index f4285417c71a..771984f77307 100644
> > --- a/Documentation/sphinx-static/custom.css
> > +++ b/Documentation/sphinx-static/custom.css
> > @@ -136,3 +136,8 @@ div.language-selection:hover ul {
> > div.language-selection ul li:hover {
> > background: #dddddd;
> > }
> > +
> > +/* Mark xrefs with an underline, but elide it for those that
> > + don't lead anywhere */
> > +.xref { text-decoration: underline; }
> > +.broken_xref { text-decoration: none !important; }
>
> 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;
> }
I like the idea of having different CSS classes for xref and broken_xref,
as it allows better formatting. I didn't test, but IMO we can either
change a.reference to use text-decoration: underline or to override
border-bottom for .xref (does it need also for .broken_xref?), e.g.:
.xref {
text-decoration: underline;
border-bottom: none;
}
By placing both text-decoration and border-bottom, we can ensure that
whatever default on whatever CSS used, this will display just one
underline(*).
(*) such default can still be overridden with:
make DOCS_CSS=custom.css
>
> So when you add this underline text-decoration to the .xref tags, the ones
> inside <a> tags (valid xrefs) end up with two underlines.
>
> I've checked the result for both struct and functions and they work the same.
>
> So I suggest just dropping these CSS rules.
I suggest keep them ;-)
>
> > diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
> > index 347de81c1ab7..cede07e758a7 100644
> > --- a/Documentation/sphinx/automarkup.py
> > +++ b/Documentation/sphinx/automarkup.py
> > @@ -241,8 +241,13 @@ def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None):
> >
> > if xref:
> > return xref
> > -
> > - return None
> > + #
> > + # We didn't find the xref; if a container node was supplied,
> > + # mark it as a broken xref
> > + #
> > + if contnode:
> > + contnode.set_class("broken_xref")
> > + return contnode
>
> And accordingly changing this to just:
Better to keep it. Having a different class here helps if someone wants to
have a custom CSS that, for instance, would bold the undocumented functions
(for instance using a red background).
>
> + #
> + # We didn't find the xref; return contnode so that if one was supplied the
> + # resulting node can have the same styling (eg literal formatting for
> + # struct/functions)
> + #
> + return contnode
>
> With that,
>
> Reviewed-by: Nícolas F. R. A. Prado <nfraprado@xxxxxxxxxxxxx>
>
> Thanks,
> Nícolas
Thanks,
Mauro
