Annotate code that is following or followed by other code

[favonia]

Closes #696. The goal of this PR is to make

(** [f][ ][x] *)

look like

(** [f x] *)

with the default theme. The motivation is to write {!val:f}[ x] so that f is linked but the text still looks like [f x].

Technical details

This PR annotates adjacent <code> phrases with CSS classes following-code and followed-by-code so that one can turn off the padding between <code> via CSS. The comment [f][ ][x] will generate something like this:

<code class="followed-by-code">f</code><code class="following-code followed-by-code"> </code><code class="following-code">x</code>

and then the padding can be turned off using the CSS selectors code.following-code and code.followed-by-code. See the changes to src/odoc/etc/odoc.css. The annotation algorithm does not change the asymptotic complexity and I did not notice obvious slowdown. However, a serious benchmarking might still be useful.

Caveats

1. Due to Indentation changes rendering of <pre> ocsigen/tyxml#287, tyxml would insert spaces when indent is true, but it's no longer odoc's fault.
2. I did not check how other backends can benefit from the new annotations, but at very least it would not be worse. The LaTeX backend, for example, could benefit from them.

[dbuenzli]

The motivation is to write {!val:f}[ x] so that f is linked but the text still looks like [f x].

I don't understand. This is already the case.

[favonia]

The motivation is to write {!val:f}[ x] so that f is linked but the text still looks like [f x].

I don't understand. This is already the case.

The current default CSS theme contains this fragment:

p code,
li code {
  background-color: var(--li-code-background);
  color: var(--li-code-color);
  border-radius: 3px;
  padding: 0 0.3ex;
}

which introduces a 0.3ex padding on both sides of the code. Here's a real example from one of the libraries I wrote (except that I darkened the background for clarity):

[dbuenzli]

The current default CSS theme contains this fragment:

Well by all means fix the css (for example odig's default stylesheet doesn't suffer from these defects) but I don't think there's the need to complicate the HTML generator for that.

[favonia]

I see. I'm not sure how people want to change the default theme, then. I don't think it's technically possible to select <code> that is adjacent to other <code> using only CSS. Therefore, either we should avoid the padding altogether (e.g., the themes used by odig and the OCaml website v3 did that) or the CSS theme would need some help. On the other hand, I don't feel the code is that complicated---it's mostly just passing context along. In case it helps, I could further minimize the PR by making context an optional argument.

[dbuenzli]

To be clear your classes seem to be reinventing the + CSS selector.

[favonia]

To be clear your classes seem to be reinventing the + CSS selector.

+ is close but I don't think it would work because, for example, the <code> in {!val:f} is wrapped inside <a> and thus the inner <code> is not a sibling of the <code> generated by [ x]. In general there could be arbitrarily many layers of styles (bold, italic, etc.). That said, maybe some CSS guru can help us out.

[Octachron]

That sounds like a quite complicated temporary workaround to avoid implementing references inside code block (e.g [{!val:f} x]). Is that temporary workaround worth the implementation and future-compatibility cost?

[dbuenzli]

I may not be a CSS "guru" but I have lost enough useless hours of my life into it to tell you that this:

<code class="followed-by-code">f</code><code class="following-code followed-by-code"> </code><code class="following-code">x</code>

is the beginning of a nightmare.

If possible wouldn't adding a class on the a indicating that this is an id reference and/or swap the <a> and <code> be a simpler option ?

Also, @Octachron's comment.

[favonia]

Fair enough. I think we can use + to do half of it, but I don't know how to control the padding before a series of code phrases. The issue is that there's no adjacent sibling combinator in the opposite direction as far as I know.

And yes, supporting references within code (but still rendering records as they are) would be wonderful!

[dbuenzli]

The issue is that there's no adjacent sibling combinator in the opposite direction as far as I know.

I'm pretty sure you could manage to make the successor background bleed into the precessor so as to cover its right round corners via a judicious use of box-shadow and probably a z-index.

[favonia]

Alright. I am closing this while searching for other solutions. Just to clarify, do the developers prefer links within code (which might mess up syntax highlighting...?) or magical swapping of <a> and <code>?

[dbuenzli]

That sounds like a quite complicated temporary workaround to avoid implementing references inside code block (e.g [{!val:f} x]). Is that temporary workaround worth the implementation and future-compatibility cost?

Just FTR the issue that tracks that is #756