Add backlinks to elements in solutions sections

[skiadas]

This should be addressing #2606 but also includes a fair amount of refactoring:

• Created a heading-generic template to uniformly handle the common elements to all heading generations (determining tag from heading, adding heading class). All other heading-generating templates now call on this one.
• Add boolean parameter to this heading-generic template and any others that needed it to indicate that the headings should actually become links back to the original location of those headings.
• Added some test cases to the sample article for heading cases that appeared to not be getting tested.

[Alex-Jordan]

I haven't looked closely at this, but I note that it touches on a lot of delciate code that ensures heading levels elevate correctly. Like, not following an h2 with an h4 without using an h3 in between. Are you confident that this behavior is preserved?

I used the Firefox headingsMap extension a lot when we put all that together. It highlights when headings are out of line like that. There are still things that it won't catch, that need manual eyes. For example, if there are adjacent headings that should be h2, h3, but this change makes them h2, h2, then only manual oversight can see that.

One of the complications is that the heading level of something where it is born might be (for example) 3. But then when that thing appears somewhere else, like in a "solutions" page, it may need a different heading level.

[skiadas]

I haven't looked closely at this, but I note that it touches on a lot of delicate code that ensures heading levels elevate correctly. Like, not following an h2 with an h4 without using an h3 in between. Are you confident that this behavior is preserved?

I'm as confident as I can be I suppose. So the first two commits add new "tests", then the moving around is done on the 3rd and 4th commit, and my guide throughout that process was a before- and after- diff of the sample-article build with the publication-crc settings, and observing that the versions are identical (except for the obviously different compile-time timestamp). So at least on the sample-article source code the results of the refactoring should be identical to the before state.

Then the last commit, which adds the backlinks, simply surrounds the title part with an anchor tag (does this need any accessibility extras btw?).

The algorithm for determining what heading level to use has remained unaffected as far as I can tell, in the mode="hN" template. But yes it's a biggish change, which is why I wanted as many eyes on it as possible.

Are there other projects that I should use as test cases, beyond the sample article?

[Alex-Jordan]

If you were doing diffs on the output HTML from the sample article, that is great. It has all of the complicated cases from when this was tested before, and no other projects were used in testing at that time. If you didn't see any "hN" changing their level, I'd be confident things are good in that front.

If it's not much trouble, if you can post the sample article build somewhere public, I'd look at the accessibility question you asked.

[skiadas]

Let's see if this works: https://skiadas.github.io/temp-sample-backlinks/derivatives.html

[skiadas]

Let's see if this works: https://skiadas.github.io/temp-sample-backlinks/derivatives.html

@Alex-Jordan Did you have a chance to review this by any chance?

[rbeezer]

Back to this one, since it seems to have gotten hung up.

Like @Alex-Jordan, the refactoring of hN values looks pretty involved and will take more study. But Claude Code likes it (based on before/after testing), so I have confidence. I may also take a close look at the hN levels, perhaps after this goes in.

Why is there a new section about literate programming? What is it testing? Commits with new source material should be rotated to be last when making a PR, so I can do before/after testing easily without them.

Next comment will be from Claude Code. aria-label could be added now, but I won't let this sit just for that. And CSS could be an add-on, especially if some -dev discussion is needed.

This rebases nicely on master, so you could do that, make any edits and move the new source material commit to the tip, and force-push. The review is lengthy, but it looks like it'll be a good guide for me once I hop in to look more carefully.

[rbeezer]

I reviewed this PR after rebasing on current master (clean, no conflicts). I built the sample article HTML before and after, with the literate-programming section and exercisegroup introduction changes removed from the source so the diff would isolate XSL-driven changes only.

The refactoring is behavior-preserving. With identical source, only solutions pages and pages containing inline <solutions> divisions differ. All other pages are identical (except timestamps). Heading levels (h3/h4/h5/h6) are preserved throughout.

The backlinks work correctly. Exercise, project, and task headings in all solutions sections get <a> links back to their birthplace. Inline solutions divisions on born pages (e.g., "Solutions for This Subsection" on the section-interesting-corollary page) also get backlinks, which is consistent behavior.

Some concerns:

1. Exercisegroup introduction change (commit 2) -- The change wraps the exercisegroup introduction content in <title> and <statement>. I believe <introduction> does not allow these as children -- it takes block-level content directly. This needs to be checked against the schema.

2. Accessibility (following up on @Alex-Jordan's question) -- The <a> elements wrapping heading content have no aria-label, title attribute, or visually-hidden text indicating they are backlinks. A screen reader would encounter a link but have no indication that it navigates back to the exercise's origin rather than being the heading itself. Something like aria-label="Back to Checkpoint 4.9" could help.

3. No CSS for heading links -- The <a> tags inside headings will pick up default browser link styling (blue, underline). Is there existing CSS that handles links inside .heading elements, or does this need a companion CSS change?

4. Minor: same-page backlinks use full paths -- When a <solutions> division appears on the same page as its exercises, the links are href="page.html#id" rather than just #id. Not broken, but slightly redundant.

The refactoring itself is solid -- funneling all heading generation through heading-generic is a nice simplification and the b-make-link parameter is a clean way to opt in to backlinks.

Claude Opus 4.6, acting as a review assistant for Rob Beezer

[rbeezer]

Not so long after all - I got a much longer tour through the changes, which will help me, and not add much here. Also, the "full URLS" is not a real problem.

[skiadas]

It's been a while so I don't fully recall the details, but I think both of the new examples I added were because they appeared to me as cases that the algorithm I was going to refactor would possibly affect but that were not covered in the examples yet, so it made sense to add them before the refactoring so they could be used to test the refactoring didn't change them: The <xsl:template match="fragment" mode="heading-birth"> for the fragment case is what I was trying to capture with the fragment example. It does look like the exercisegroup example might not be valid pretext to begin with according to the current spec at least.

Should I just remove both example cases?

I can add aria-label entries I think.

[rbeezer]

Let's leave the literate programming stuff, that'll be good to have. The introduction should just launch into some p.

I put examples on first commit, develop new code, then with an interactive rebase I put them last so I can test without them. Too many spurious numbering and ToC changes otherwise.

I'll wait on the aria-label. Apologies for taking so long on this, I'm trying to finally get on top of my backlog.

[skiadas]

OK I think I've rebased it correctly? The aria-label now should say something like "Back to 2.4.1.". I'm not sure how feasible it is to specify what the back-referenced element is (solution, heading etc)?

[rbeezer]

Thanks, @skiadas, for the changes (and so quickly!). That was a lot of detailed work to put all of this together.

I've run tests by hand, and they look good. Claude Code confirms that it looks good, and found a stray colon, which I have silently fixed. That report is next.

[rbeezer]

I rebased the force-pushed version on current master (clean, no conflicts) and ran three before/after HTML build comparisons of the sample article.

Test 1: First two commits only (hN refactor + heading-generic helper). The only differences are build timestamps. The refactoring is perfectly behavior-preserving — zero changes to any heading tag, class, level, or content across all pages and knowls.

Test 2: First four commits (adds backlinks + aria-label). Nine files differ, all expected: four solutions pages gain backlinks, three born pages with inline <solutions> divisions gain backlinks, plus two timestamp-only pages. Heading levels are unchanged. The backlinks now include aria-label attributes — examples:

• aria-label="Back to Checkpoint 4.6. Essay Question: Compare and Contrast."
• aria-label="Back to Activity 4.3. Hints, Answers, Solutions."
• aria-label="Back to 4.12.c.ii" (tasks without titles)
• aria-label="Back to 11.3.6." (divisional exercises, number only)

This addresses the accessibility concern from the earlier review.

Test 3: All five commits (adds literate programming section). Many files differ due to section renumbering (30→31, etc.). The new section itself renders correctly — fragments display with angle-bracket notation and the ≡ symbol, fragment cross-references work as knowl links, and the knowl content page includes an "in-context" link. Two issues in the new source:

1. Indentation loss: The return a line in the GCD fragment appears flush left in the output instead of indented under the while. The source comment acknowledges this ("indentation is hard to get right at the moment").

2. Stray colon outside </p>: Line 13533 of the source has <p>The key part is the inner part of the loop</p>: — the colon sits outside the closing tag. It's silently dropped in output. Should be moved inside the <p>.

Claude Opus 4.6, acting as a review assistant for Rob Beezer

[rbeezer]

Nicely done. Merged with new commit messages. Will put on pretext-announce just now.