Add html-xref-renderstyle publisher file setting

[ascholerChemeketa]

This is standalone, but the first in hopefully a series of refinements to xref knowls. I would like to make use of this sooner rather than later. But I am fine seeing how many other xref knowl commits are doable quickly and integrating those as a batch. If you prefer to batch them I'll change this to draft.

This provides a way to opt into rendering all xref's as web standard links. Ideally, it is a tool no one would want to use. But the option should exist.

[Alex-Jordan]

With the option 'mixed', is it "mixed" because divisions get links and blocks get knowls? Or mixed more broadly because in the future, nearby blocks can be links and faraway blocks can be knowls? (Or do I have that backwards?)

I was just wondering if 'mixed' is the right word. We will never knowlize a cross reference to a division. So at least until there are more options, what is 'mixed' here is more like all non-division cross-references. Also if you foresee a third option (or more), will "mixed" still characterize that option well?

[ascholerChemeketa]

I was thinking there might be more options. Maybe not - it is possible that everything else is just a variation on link or mixed. But if "mixed" gets complex enough, it might become desirable to make a distinction between two different master strategies.

My way of thinking about it is that the key detail here is "how are xref's rendered". They could only be rendered as knowls (not currently an option), they could be rendered as all links, they can be rendered as a mix of the two. mixed thus feels more natural than knowl or something as it is not the case that every xref turns into a knowl in the default mode. Have a suggestion other than mixed?

Open to making this strictly a kill switch force-xref-links that is either yes or no. That closes off reusing the variable for possible future strategies. But it would simplify the conceptual role of the variable down to being just a master off switch.

[rbeezer]

@ascholerChemeketa has brought up proximity as a criteria on the -dev forum, so definitely switches and names should reflect/allow that possibility.

• I would like the element to be publication/html/cross-references, in other words, not an abbreviation (xref).
• Knowls are the feature and the default, so an attribute like @knowl, @knowls, or @knowled? In other words, I find render-style too generic.
• I would call current/default state maximum - the most we consider reasonable (i.e. not divisions). Then we could have none, which is what I think I see being implemented.
• Footnotes are knowls, but "born hidden" so not under discussion here. xref point to many things, like equations, references, and contributors. LaTeX has several different schemes for the different types. I think there is a place for always doing citations to references as knowls. Maybe a scheme called minimum, a natural step above none. What else should go in this group?
• Then proximity can be a gradation between minimum and maximum.

[ascholerChemeketa]

Updated based on feedback.

• Changed to publication/html/cross-references
• attr is knowled with options never, cross-page, maximum. Max is traditional and default.

I started in on multiple levels - basically specifying a knowl-level. Decided that was more complex than current demands. cross-page feels like the main middle ground that people will reach for. e.g. It avoids the issue of generating broken knowls for runestone when an xref is on the same page as the target.

Questions/Concerns:

• make-xref-knowls has no idea where links are for the targets. In that case, xref-as-knowl behaves as if maximum is selected. So there may be knowl files generated that never get used.
• Note sure about the desirability of using logic within xref-link-display-math. Please check line 8046 and give me feedback.

[ascholerChemeketa]

Also updated docs for the Single Page HTML that @rbeezer brought up in an unrelated email on pretext-dev

[ascholerChemeketa]

@rbeezer

Made the syntax update for the selector

I tracked the "extra" knowls down to the pathway for generating the index knowls. That now also only generates knowls when appropriate (mode is maximal or cross-page).

I think this is all set

[rbeezer]

Looking real good. I think the xref inside of math/MathJax lose their styling when they become traditional hyperlinks. You added such an example here:

Figure 19.2 https://pretextbook.org/examples/sample-article/html/section-cross-referencing.html#section-cross-referencing-26

And there are five (in last two displays) in

Subsection 7.4: Advanced Mathematics https://pretextbook.org/examples/sample-article/html/section-mathematics.html#section-mathematics-6

If so, let's do that on a new PR, I'm likely to work this up sometime today, and putting it here will wreak havoc with that.

[rbeezer]

Well, now I have enough non-cosmetic edits that we should discuss them. Will you be at Friday Drop-In?

[ascholerChemeketa]

I can't make tomorrow. I should be able to make next Friday. Or I could catch the second half of the Monday drop in (5-6 Eastern / 2-3 Pascific).

[ascholerChemeketa]

There are lots of spots where <a>'s are not well styled. And lots of places where knowls are styled inconsistently. Those issues have nothing really to do with the HTML being generated in this PR.

Part of that is the interaction of various components. Part of it is the quick and dirty "apply old knowl CSS to summary/details and see how it goes" that we did when born-hiddens were swapped to that format.

My proposal is a separate PR that attempts to standardize knowl styling and make sure that plain <a>'s are visually indicated. That would address the styling issue above, https://github.com/PreTeXtBook/pretext/issues/2116, and probably other rendering inconsistencies.

There may be other issues to address in this PR - just proposing that those CSS ones go in a separate PR.

[rbeezer]

Thanks for all the work on this! Removed two stray tabs and repackaged as three commits.

This should go on pretext-announce. Wanna send me a short blurb and I will post under [NEW]? Keep it concise, but include a link to the publisher file reference (which should point back to other edited material, I forgot to check!).