Manual: add mark / highlight documentation

[wlupton]

Please see this "Syntax for <mark>?" pandoc-discuss thread for context.

• I've added a new section after (and modeled on) the existing underline and small caps sections
• I've checked that <span class="mark">Mark</span> does indeed work (and uses the mark element)
• But is it true that this will work in all output formats that support mark / highlight? (I don't know... I'm just asking)

Also note:

• The pandoc-discuss thread points out that the mark class only works when it's the first class (and I've verified that this is also the case for the underline and smallcaps classes). Is this intentional (in which case it should be documented) or is it a bug?

• The default HTML template defines underline and smallcaps classes, but it doesn't define a mark class. This seems a bit inconsistent? My "try pandoc" below illustrates that in the "mark isn't the first class" case the HTML will use the (defined) underline and smallcaps classes and the (undefined) mark class

• I used this "try pandoc" to check out the various behaviors

[jgm]

Duplicate of #8191 , merged yesterday? If you think that commit needs modification, maybe you could rebase your PR against it.

[wlupton]

I think that the natural location for this new text is with the similar underline and smallcaps subsections at the end of the Inline formatting section.

• I've replaced my original commit with a new one that moves the newly-added text and adjusts the last line to match the last lines of the underline and smallcaps sections
• I've added a second commit that defines a span.mark HTML style

The following comment is still open:

• The pandoc-discuss thread points out that the mark class only works when it's the first class (and I've verified that this is also the case for the underline and smallcaps classes). Is this intentional (in which case it should be documented) or is it a bug?

[wlupton]

It looks like the test failures are due to the change to styles.html?

[jgm]

Why add the span.mark style? The HTML writer will use a <mark> tag in this case. (Never mind: I see you addressed this above.) ~~Is it to handle the case where mark is not the first class? That should probably be fixed in the writer instead. (Or maybe the behavior should be kept, but then I think it's confusing to add span.mark.)~~

[jgm]

OK, I've pushed a commit that allows these special classes to be combined in a single span. They are no longer required to be first in the list of classes. I think this means we could remove the special CSS for e.g. span.underline, but I want to check with @mb21 first.

[wlupton]

Re the span.mark style, maybe your "never mind" means that I don't need to say anything about it, but anyway:

• I added it because underline, smallcaps and mark seem to be a triple that are handled similarly, and there were already span.underline and span.smallcaps styles

• I had noted that, in the case where the special class wasn't first, then the span.underline class kicked in and resulted in the expected formatting, but the lack of a span.mark class meant that 'mark' spans didn't get special formatting

• If the special class no longer needs to be first then I agree with your rationale for getting rid of the span.underline class (and not adding the span.mark class)

• Note that the span.smallcaps class is still needed, because AFAIK the only way to get smallcaps is via CSS (there's no HTML element)

[mb21]

I think this means we could remove the special CSS for e.g. span.underline

You mean the span.underline selector ? yes, if we now always output <u> instead of <span class="underline"> doesn't seem to be needed anymore. Although I think that was changed quite some time ago in #6277 ...

[tarleb]

This is probably a good time to bring up the very related PR #7307 again.

[wlupton]

I was going through my open items and found this. I'm inclined simply to close (withdraw) this PR. If you think that this would be a pity (and that we should continue and resolve the discussion on this issue) then please speak up!

[tarleb]

Thank you, this is indeed a better place for that section. Just to make sure: is the CSS still used after all the rebases? I'm probably missing something, as I didn't see why it's needed.

[wlupton]

I see that the only span style in the latest templates/styles.html is span.smallcaps (so span.underline must have been removed). I therefore withdraw any suggestion that we should add a span.mark style.

[tarleb]

I've git cherry-picked the commit onto main as 9c272620340d8d737cf40f8fa4b3b5fb929a7c7d.

Thanks again!