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

Carsten Bormann cabo at tzi.org
Mon Dec 17 06:27:04 PST 2018

On Dec 17, 2018, at 14:51, Henrik Levkowetz <henrik at levkowetz.com> wrote:
> Signed PGP part
> Hi Jeffrey,
> On 2018-12-17 06:02, Jeffrey Yasskin wrote:
>> 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.
> 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.

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

>> 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>.
> 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.
>> Do folks have other ideas for removing the trap? Do folks agree that
>> the trap is worth removing?
> Yes, I'd like to hear from more people before making changes.
> Best regards,
> 	Henrik (maintainer)

More information about the rfc-interest mailing list