Add support for subscript extension

[liamwhite]

This adds simple support for a subscript extension delineated by single %-signs.

[digitalmoksha]

@liamwhite what would you think about following Pandoc's syntax, which uses ~. I've seen this syntax commonly in use.

[liamwhite]

That interferes with the existing strikethrough extension (if it used that character, both couldn't be enabled at the same time)

[digitalmoksha]

It should be possible. There is already an example of this in CommonMark, where _example_ is italics, and __example__ is bold.

Pandoc also supports both ~~ for strikethrough and ~ for subscript.

I think it would be worth a shot.

[liamwhite]

It would require a change so that single tilde is subscript and double tilde is strikethrough. Since single tilde currently also works for strikethrough, that would potentially break the rendering of older documents, would it not?

[digitalmoksha]

Ack, you're right - I forgot the single tilde is still active. That is unfortunate.

The tough thing is that's the only subscript syntax I've run across. GitHub only documents the ~~ for strikethrough, both in their documentation and in the GFM spec.

[digitalmoksha]

The GFM spec doesn't specify using ~. I think this is a holdover from the early days.

And while I know backward compatibility is important, since we're adding an optional extension for this (which I think is great), it seems like for the long run it would be better to use a common syntax.

So what about if the subscript extension is enabled, then ~ takes over duty for it, instead of strikethrough?

@kivikakk do you think this would be acceptable?

[liamwhite]

It is possible to use the single tildes on GitHub's GFM: ~strike~ renders as strike

[kivikakk]

Indeed; so @digitalmoksha's suggestion is that, iff the subscript extension is also enabled, then that would no longer be the case.

The support of single-tilde for strikethrough on GitHub is indeed a bit legacy and weird; I don't have references on hand but you can probably find related issues in the github/cmark-gfm repository where we went back and forth on that a few times, given its exclusion from the spec.

The question is, I guess, are there going to be documents rendered using both strikethrough and the new subscript extension where the single-tilde ~strikethru~ behaviour is already being relied on, and therefore would break? i.e. per @liamwhite:

Since single tilde currently also works for strikethrough, that would potentially break the rendering of older documents, would it not?

If so, then it's a bit of a non-starter, but if not, then I'm partial to aligning with Pandoc's syntax here too. In short, it depends on the use case of strikethrough+subscript, which is probably best answered by @Meow and/or @liamwhite as the proposer!

If you have a corpus of documents currently being rendered with Comrak which you're wanting to add subscript support to, my suggestion would be to actually inspect it for strikethrough use. IIRC I did that with GitHub's issue/PR bodies and comments and determined single-tilde strikethrough was actively in use and couldn't be deprecated here. Your use case may be more flexible.

[kivikakk]

@digitalmoksha:

GitHub only documents the ~~ for strikethrough, both in their documentation and in the GFM spec.

Actually, that's not quite accurate; quoting the GFM spec as you've linked:

Strikethrough text is any text wrapped in a matching pair of one or two tildes (~).

The first example to follow demonstrates both single and double tilde.

This happened two years ago when I (!!) requested this update: github/cmark-gfm#271 ¹. You can find a bunch of related issues and comments from that discussion.

Footnotes

1. lmaoing at "I have committed a slight error" ↩

[digitalmoksha]

Dang, you're right! My eyes totally glossed over that 🤦

[digitalmoksha]

You know, I had been looking at the spec.txt linked in the comrak repo. That one doesn't have this change (as far as my eyes can tell). https://github.com/kivikakk/cmark-gfm/blob/2f13eeedfe9906c72a1843b03552550af7bee29a/test/spec.txt

[kivikakk]

Yeah; they made the change to the HTML separately in response to my issue, I'm guessing. I don't know how they generate that HTML any more (but I also suspect it's probably not getting updated again anyways?). Either way, I think the live HTML version is to be considered canonical.

[digitalmoksha]

Are they still using cmark-gfm, or something else now?

[kivikakk]

That's a question for a GitHub employee! I believe it's one of the following, though: (a) cmark-gfm only, (b) cmark-gfm and Comrak fork (depending on endpoint/particular thing being displayed), (c) Comrak fork only. I say this based on cessation of cmark-gfm maintenance and some attention from our friends at GitHub resulting in a batch of nice security fixes to Comrak last year. I could be totally wrong.

It might be possible to determine if there's some edge-cases where cmark-gfm and Comrak generate slightly different HTML; such cases exist but are hard to find given the way the executable spec works!

[liamwhite]

Trying to understand the question posed to me in #480 (comment): I am able to rewrite my existing documents to remove single-tilde strikethrough and change it to double, and I could therefore support subscript in the single tilde case. If that is what you believe the best course of action is, then I would suggest closing this PR and I will follow up with that change at a later date.