Re: [Rfc-markdown] Trying to mitigate "Re: The <tt> train wreck"

[Jay Daley <[e-mail]>]

> On 25 Apr 2022, at 10:16, Carsten Bormann <[e-mail]> wrote:
> 
>> On 2021-08-14, at 01:13, Carsten Bormann <[e-mail]> wrote:
>> 
>> The original RFCXML RFC 2629 did not have any elements to indicate emphasis (often rendered as italic/oblique and/or bold type).  More normatively in practice, XML2RFCv1 had »<spanx style=«, which provided text spans with the following properties:
>> 
>> | style   | nobreak | decorator | type      | tt |
>> |---------|---------|-----------|-----------|----|
>> | emph    |         | _         | em        | -  |
>> | strong  |         | *         | strong    | -  |
>> | nobreak | x       | none      | -         | -  |
>> | vbare   | x       | none      | -         | x  |
>> | verb    | x       | "         | -         | x  |
>> | vemph   | x       | _         | em        | x  |
>> | vstrong | x       | *         | strong    | x  |
>> | vdeluxe | x       | *_ and _* | em strong | x  |
> […]
>> For TXT, the “decorator" column indicates what character is used _around_ the span in plaintext rendering.  Note that only “nobreak" and “vbare” had no decorator.  Using »"« as a decorator for “verb” certainly was an unloved compromise that did, however, work well enough.
> 
> … which was then broken in xml2rfc 3.11.0, 2021-10-29.
> 
> Clearly, there are cases that benefit from this change (where <tt was decorative only and no information was needed in the plaintext version).  Where <tt was semantic (not to be lost in plaintext), the workaround for this change is now to manually insert double quotes, which will unfortunately mar the HTML/PDF rendering even if that is not needed.
> 
> I also wrote:
> 
>> PS.: I have CCed this to rfc-markdown because there also is no good way in markdown to keyboard the distinction between a decorative <tt that can be ignored in plaintext and one that *needs* a representation (“decorators”):  Like this part of XML2RFCv3, markdown also was not designed to format into plaintext.  It would be nice if there were a way to create a workaround from kramdown-rfc, but the problem is that the single piece of XML that kramdown-rfc puts out needs to generate both the TXT and the HTML/PDF version, and there is no way in RFCXMLv3 to indicate the variant processing needed for TXT.
> 
> As I implied, this is unfixable in an author tool with the current version of RFCXMLv3.
> However, a future version of RFCXML might have an indication for semantic <tt usage, which would cause the quotes to appear in the plain text but not the typographic (HTML/PDF) renderings.
> 
> We can prepare for that by already keyboarding documents as if we had semantic <tt.  This will translate into quotes for all renderings in today’s RFCXMLv3, so the only improvement will be to make this easier to type.  But as soon as RFCXMLv3 gains semantic <tt, kramdown-rfc can be changed to emit this for the code-spans marked semantic in the source.
> 
> I propose to use
> 
> ```d'oh```

In many flavours of markdown, including GitHub, triple backtick is used to indicate multi-line code blocks (code fences) and single backticks for code spans.  You appear to be switching the two.

Also, how do you see this intersecting with this discussion that we had: https://github.com/ietf-tools/xml2rfc/discussions/753 about a possible <term which lends itself much better to semantic markup.

Jay

> 
> for semantic codespans.
> 
> (1) this looks vaguely like "`d'oh`", so it should be mnemonic to those using the workaround, while much easier to type (and easier to not get wrong as `”d’oh”` which makes the quotes part of the monospaced string).
> (2) upstream kramdown already allows this syntax (*) as an alternative codespan syntax, so we don’t have to hack that in.
> 
> Again, this will not enable better rendering today than the manual workaround, but as soon as RFCXML updates, the documents will look better in the typographic renderings (HTML/PDF) without losing the semantic information in TXT.
> 
> Comments welcome before I sit down and code that.
> (Plan is to have that ready for the 6 month anniversary of xml2rfc 3.11.0, 2022-04-29.)
> 
> Grüße, Carsten
> 
> 
> (*) Markdown arcana:
> Kramdown allows multiple backquotes [1] so one can write about constructs like ```d’oh```:
> 
> ```` ```d’oh``` ````
> 
> So I plan to actually trigger semantic <tt by an odd number (≥ 3) of backquotes; the even numbers stay available to keyboard decorative <tt with embedded backquotes.
> 
> [1]: https://kramdown.gettalong.org/syntax.html#code-spans
> 
> _______________________________________________
> Rfc-markdown mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/rfc-markdown

-- 
Jay Daley
IETF Executive Director
[e-mail]