HTML: give a class name respecting depth for duplicate heading spans

[Alex-Jordan]

This follows up on #1580.

Not important changes: Rob's xslt-fu for a span element. And changed "secondary-heading" to "duplicate-heading".

Collateral correction: the list-of generator in -common was bumping up the heading level by 1 more than it should.

Important change: The duplicate headings (which appear inside list-of or solutions output) are still spans, but they have additional classes on them like heading4, heading5, etc, indicating their depth on the page. So they could be styled to reflect their depth. If the class would be heading7, heading8, etc. it just prints heading6. This is to be consistent with what I have coming up for hN headings, and also to limit the number of classes @davidfarmer has to work with.

As a reminder, we are not using actual hN because in these places, it would clutter up the heading tree without offering much in terms of better navigation.

An example, built with chunk level 0: http://spot.pcc.edu/~ajordan/temp/derivatives.html

Appendices F and G have list-of. Appendices B–E have solutions. Section 4.2.7 is also a "solutions".

[Alex-Jordan]

Consider when a "solutions" comes out looking as follows:

4.2.3 Solutions for this section (h3)
    4.2.1 (Subsection)
        Checkpoint 4.2.1
    4.2.2 (Subsection)
        4.2.2.1 (Subsubsection)
            Checkpoint 4.2.2
        4.2.2.2 (Subsubsection)
            Checkpoint 4.2.3

What I am proposing is that none of the duplicate headings (the Subsection and Subsubsections) be hN. They are spans. Meanhwile, the three Checkpoints do use hN, and are in the heading tree. So I'm proposing a heading tree that looks like:

4.2.3 Solutions for this section (h3)
    Checkpoint 4.2.1
    Checkpoint 4.2.2
    Checkpoint 4.2.3

Now the Checkpoints need to be h4. So go back to the first block above:

4.2.3 Solutions for this section (h3)
    4.2.1 (Subsection)
        Checkpoint 4.2.1 (h4)
    4.2.2 (Subsection)
        4.2.2.1 (Subsubsection)
            Checkpoint 4.2.2 (h4)
        4.2.2.2 (Subsubsection)
            Checkpoint 4.2.3 (h4)

Now David would like to style "4.2.2 (Subsection)" differently from "4.2.2.1 (Subsubsection)". And this PR allows that, because it makes:

4.2.3 Solutions for this section (h3)
    4.2.1 (Subsection) (span.heading4)
        Checkpoint 4.2.1 (h4)
    4.2.2 (Subsection) (span.heading4)
        4.2.2.1 (Subsubsection) (span.heading5)
            Checkpoint 4.2.2 (h4)
        4.2.2.2 (Subsubsection) (span.heading5)
            Checkpoint 4.2.3 (h4)

If that differentiated styling is enacted, we have h4 things as apparent children of span.heading5 things. And I foresee the styling and indentation looking off.

I see four ways out of this:

(0) There is no problem like I "foresee". David's magic can style the above well.

(1) Scrap what I've been doing, and let things like the "4.2.2 (Subsection)" be hN. I don't really like this option because of what motivated me in the first place. These things really clutter up the heading tree for a heading tree navigator, compared to the second code block above. But this may be what needs to happen.

(2) Track the .headingN classes onto the hN. So the example becomes:

4.2.3 Solutions for this section (h3)
    4.2.1 (Subsection) (span.heading4)
        Checkpoint 4.2.1 (h4.heading5)
    4.2.2 (Subsection) (span.heading4)
        4.2.2.1 (Subsubsection) (span.heading5)
            Checkpoint 4.2.2 (h4.heading6)
        4.2.2.2 (Subsubsection) (span.heading5)
            Checkpoint 4.2.3 (h4.heading6)

Then things can be visually styled to reflect the apparent nesting.

(3) Do not try to differentiate styling among duplicate headings. So the example looks like:

4.2.3 Solutions for this section (h3)
    4.2.1 (Subsection) (span.duplicate-heading)
        Checkpoint 4.2.1 (h4)
    4.2.2 (Subsection) (span.duplicate-heading)
    4.2.2.1 (Subsubsection) (span.duplicate-heading)
        Checkpoint 4.2.2 (h4)
    4.2.2.2 (Subsubsection) (span.duplicate-heading)
        Checkpoint 4.2.3 (h4)

[rbeezer]

It might help if I was perhaps clearer with my previous comment elsewhere.

I do not care if the headings for 4.2.1, 4.2.2, 4.2.2.1, 4.2.2.2 all have identical appearance. But I do want them to be subordinate to "4.2.3 Solutions for this section" (and I guess that means the same for the exercises themselves).

In other words, the structure of a collection of solutions does not need to be visually represented (my opinion), but should not be so fixed as to look "bigger" than the heading on the division they live in.

[davidfarmer]

Of the "four ways out of this", I think only 1 makes sense for accessibility. Otherwise the hN are on checkpoints and the (sub)*sections are invisible in the hN tree.

Get the hN right for accessibility, and then worry about the headingN for styling.

[Alex-Jordan]

Of the "four ways out of this", I think only 1 makes sense for accessibility. Otherwise the hN are on checkpoints and the (sub)*sections are invisible in the hN tree.

We are of opposite minds about this. It was exactly the point to not have the (sub)*sections be part of the hN tree. They are distracting and contribute to the hN tree being too complicated to map out in one's head. They are often leading to an hN that immediately descends into h(N+1) without intermediate content. And they make things like "4.2.1" be an hN child of "4.2.3" which is disorienting.

[davidfarmer]

No: one of us understands what is going on, and the other doesn't. So ignore my previous comment and let me know when there is something for me to style.

David "just shut up and make it look pretty" Farmer

On Wed, 18 Aug 2021, Alex Jordan wrote:

  Of the "four ways out of this", I think only 1 makes sense for accessibility. Otherwise
  the hN
  are on checkpoints and the (sub)*sections are invisible in the hN tree.

We are of opposite minds about this. It was exactly the point to not have the (sub)*sections be part of the hN tree. They are distracting and contribute to the hN tree being too complicated to map out in one's head. They are often leading to an hN that immediately descends into h(N+1) without intermediate content. And they make things like "4.2.1" be an hN child of "4.2.3" which is disorienting.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS orAndroid.[AABTULEQTIWLNVVL6C3PG73T5QTFJA5CNFSM5CMRRNBKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN 5WW2ZLOORPWSZGOGW5RDLA.gif]

[Alex-Jordan]

I think if I were designing "solutions" or "list-of" from scratch, I might omit the duplicate section headings altogether. For example, Appendix F would look like:

Appendix F
     introduction
     Theorem 2.1
     Corollary 4.1
     Theorem 21.3
     ...

That is, I'd let each block's numbering communicate the (sub)*section that it came from. Is it a nonstarter to consider doing these this way?

[Alex-Jordan]

@davidfarmer

No: one of us understands what is going on, and the other doesn't.

No, you are right about something important that I am overlooking. In option (2) for example, "4.2.2.2 (Subsubsection) (span.heading5)" falls underneath "Checkpoint 4.2.2 (h4)" in the heading tree, which is just wrong. So you are right that only option (1) can be considered accessible. Even though it has its own problems.

I'll await any comments on my "just omit the duplicate headings altogether" post.

[rbeezer]

Is it a nonstarter

"RTFM". Can you imagine how many times I've wanted to say that, and to how many people? Will you be offended? I hope not. Just messing about. ;-)

list-of/@empty="no"

is what you seek. Example at

Section 4.22: Automatic Lists https://pretextbook.org/doc/guide/html/topic-automatic-lists.html

If it is not implemented for "solutions", then it should be.

[rbeezer]

Ooops, there I go. Not exctly what you want. But it will prevent consecutive headings at teh same level. Sorry. Mea culpa. Three Hail Marys.

[Alex-Jordan]

It is an honor to be RTFM'd by you.

Right, so as a publisher, if I just didn't want to see the headings for sections that are empty, I could use that. But it doesn't get to what this is about. For which I see your last comment, so after the rosary business, we are good.

Too complicated to do sporadically over email? Could discuss in person on Friday.

But a central question I'd like to meditate on is why do "solutions" and "list-of" use division headings at all? Why not just like:

Appendix F
     introduction: Here is a list of all theorems and corollaries!
     Theorem 2.1
     Corollary 4.1
     Theorem 21.3
     ...

and

Appendix B
    introduction: Here are solutions to some of the things!
    Checkpoint 4.4.
    Checkpoint 4.7.
    Activity 4.3
    Checkpoint 4.10
    Project 4.4
    4.2.4.1
    11.3.6
    11.3.7
    ...

[rbeezer]

Yes, a Friday discussion might be in order.

Perhaps it is the use of initialisms, but I can't imagine this instance without section headings:

http://linear.ups.edu/fcla/appendix-TL.html

An author can turn off all headings (I think) by leaving @divisions empty?

[davidfarmer]

Why is FCLA's appendix-TL organized according to sections and not according to chapters?

I like the idea of omitting most of the headings in "list-of" and similar (in particular don't put a heading when there is nothing under it), but some headings are needed. Maybe just the Chapters?

[Alex-Jordan]

Speaking out of turn.

It's not so much that the headings are organized by sections per se. Rob the author has applied @empty='no' to that list-of. Without that, we would see chapter headings too. But then since the book is uniformly structured for chapters to descend into sections before the real content happens, each chapter heading would be "empty", and these are suppressed. (I recently learned such headings [headings that immediately descend to subordinate headings] are called "stacked headings".)

Should this choice to eliminate stacked headings be a choice?

If yes, should it be an author decision or a publisher decision?

If it is permitted as an option, the default could be @empty='no' and the heading tree would come out with less clutter: the main heading, then only one level* of duplicate headings, then items. Using @empty='yes' could come along with a warning about accessibility.

*Things like "2", "4.2", and "21" would all come out as h3, using Appendix F as a reference. Same heading level, even though different book structure levels.

[Alex-Jordan]

There are some other hN things I can accomplish, but this PR is holding it up. So I changed the new duplicate-heading template to go back to using hN. It can easily be changed later once we know what we want to do. But for now, this is option (1) from my list before. It is the only option that can pass an automated heading accessibility check (even though a human expert will see that there are still heading accessibility issues.)

Chunk level 0 version posted at: http://spot.pcc.edu/~ajordan/temp/derivatives.html

Note that in Appendix F, there are stacked headings, and they are currently rendering on the same line. Appendix G has empty headings too, and these also render on the same line as the following heading. So if this is approved, there are CSS implications. (Sorry David, I may be pulling you back and forth.)

If I can table this issue (about making duplicate headings use span instead of hN) then I can continue cleanly with 2 or 3 other hN related things I am slogging through. So to be clear after all the back and forth in this thread, I'm requesting a review for a merge whenever you can get to it.

[davidfarmer]

This will not make the layout worse (those appendices have been bad for a while), so merging is fine with me.

[rbeezer]

Why is FCLA's appendix-TL organized according to sections and not according to chapters?

They are the main unit of content. Each is pretty self-contained (not independent). One section a day in class. Exercises by section. Etc. Note that section acronyms are not R.MR, just MR.

The lists in the back are the most useful device. Ctrl-F, open a knowl, in-context link, copy permalink. Done.

Rob the author has applied @empty='no'

I don't think you have that right. The chapters are not empty, there are descendants that will be shown. It is the choice of divisions to show. In this case sections are shown, chapters are not.

If an author does not like the headings, I think they could simply all not be requested.

[Alex-Jordan]

If an author does not like the headings, I think they could simply all not be requested.

Just to be clear though, the issues I am trying to solve are not issues of author choice or preference. This is about guaranteeing accessible HTML regardless of author/publisher decisions.

[Alex-Jordan]

Closing this. New plan is to (a) revert to using hN for headings in list-of and solutions, and then (b) explore ways to collapse stacked headings.