Subject: [rfc-i] Text rendering of <spanx style=verb> and <tt>

From: Jeffrey Yasskin <[email-masked]>
Date: Sun, 16 Dec 2018 21:02:44 -0800

Right now, xml2rfc's text output renders RFC7749's <spanx style=verb>
and RFC7991's <tt> by surrounding the contents with double quotes (").
This is ambiguous with actual quoted strings in the body of the RFC.

This confused an area director in the review of CDDL
(https://mozphab-ietf.devsvcdev.mozaws.net/D4234#inline-7837), and has
led to an apparent consensus in the HTTPWG not to use these pieces of
the XML markup at all
(https://github.com/httpwg/http-extensions/pull/738).

It seems silly to leave traps like this, where a piece of markup is
defined, and useful in the HTML output, but actually forbidden in any
RFC that wants to be published.

An ASCII alternative could be to wrap the contents in backticks (`)
instead of quotes, but this would break any v2 documents that describe
the effect of <spanx style=verb> in words. Doing it for just v3 (<tt>)
might force the automatic v2->v3 conversion to leave <spanx
style=verb> alone instead of converting that to <tt>.

Do folks have other ideas for removing the trap? Do folks agree that
the trap is worth removing?

Jeffrey
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 17 Dec 2018 14:51:10 +0100

Hi Jeffrey,

On 2018-12-17 06:02, Jeffrey Yasskin wrote:
> the effect of <spanx style=verb> in words.

I think that if it's the right thing to do to change the double quotes to
backticks for <tt> and 'verb', then we could do so, even if it changes the
v2 renderer.

> Doing it for just v3 (<tt>)

No, I'd leave that conversion in place, even if the rendering differs
between v2 and v3.  There are other places where the rendering differs,
too, when there are good reasons for that.

> the trap is worth removing?

Yes, I'd like to hear from more people before making changes.

Best regards,

	Henrik (maintainer)

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 17 Dec 2018 15:27:04 +0100

On Dec 17, 2018, at 14:51, Henrik Levkowetz <[email-masked]> wrote:
> Signed PGP part

I thought about proposing this change, too.

In traditional ASCII plain text, there is a longstanding convention to use ` and ‘ as a weak form of pairwise (“smart”) quotes.  See RFC 20, which identifies 0x60 as “Grave Accent [2,3] (Opening Single Quotation Mark)”.

I have no idea how to obtain statistics about that, but it is likely only a small fraction of the RFC readers are very familiar with this convention.  It has been in wide use in RFCs; the last instance I find is in RFC 5690; see RFC 4782 for a decade-old example with more extensive usage of that convention (it seems it has been most widespread in RFCs with authors from the academic community; e.g., RFC 3780/3781, many of the MIME RFCs, etc.).  Mostly, the `’ pair is used both for textual quoting and for delimiting what would be called code spans today.

The convention to use `foo` for <code>foo</foo> is of course well-known to people using markdown.  It is a convention that would need to be explained at the start of the RFC with a sentence such as:

Variable names and code excerpts that occur in running text, such as `false`, `true`, and `uint = #0`, are rendered in a typewriter font (monospaced) in the HTML and PDF versions of this document, and in between “backticks” (ASCII grave accent characters) in the ASCII plaintext version.

With this explanation, I think the potential for misunderstanding is low, but without it, only people used to markdown will understand immediately.
I think it would be best to be able to opt in to this behavior for v2, e.g. using a PI.

Note that the HTML writer produces <samp/>, not <code/>; I think this is suboptimal, but it could be controlled by the same (or a related) PI.

(Some statistics about the actual use of “verb” and related styles would be useful here.
There used to be other spanx styles, no?  “vbare”?  RFC 6716 and RFC 7468…)

Grüße, Carsten

---

From: "Paul Hoffman" <[email-masked]>
Date: Mon, 17 Dec 2018 07:32:32 -0800

> RFC that wants to be published.

Agree.

> style=verb> alone instead of converting that to <tt>.

For ASCII output of v2, the definition of <spanx style=verb>, the 
definition is:
    verb  "Verbatim" text (usually displayed using a monospaced
       font face).

For ASCII output of v3, the definition of <tt> is:
    Causes the text to be displayed in a constant-width font.  This
    element can be combined with other character formatting elements, 
and
    the formatting will be additive.

In ASCII output for both v2 and v3, the text is already in a monospaced 
or constant-width font.

> the trap is worth removing?

The way to remove the trap is to not add anything to the ASCII output 
for <spanx style=verb> or <tt>, and only use those tags for changing 
HTML or other outputs.

--Paul Hoffman

---

From: Julian Reschke <[email-masked]>
Date: Mon, 17 Dec 2018 16:39:52 +0100

On 2018-12-17 16:32, Paul Hoffman wrote:
> ...
> ...

Yes - I believe this is the right direction.

Keep in mind that in v3 world, the plain text output essentially is 
deprecated.

Best regards, Julian