[rfc-i] Text rendering of <spanx style=verb> and <tt>
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
>> 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…)
>> 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