Opened 11 months ago

Closed 11 months ago

Last modified 10 months ago

#647 closed defect (fixed)

Double quotes and <code>

Reported by: martin.thomson@gmail.com Owned by:
Priority: minor Milestone:
Component: Version_3_cli_txt Version:
Keywords: Cc:

Description

The current text rendering for <code> in xml2rfc adds double-quotes around the element. This is encouraging people to avoid the use of this decoration.

Please change the text rendering so that quotes are not used. Or, adjust the definition of <code> so that this can be controlled.

Rationale

In HTML, <code> is usually rendered with a fixed-width font, but no additional quoting. This is good, because it makes the code identifiable, but does not involve additional characters, which might make the quoted contents ambiguous.

Take the following example from RFC 7540:

That is, the connection preface starts with the string <code>PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n</code>. 

In HTML, this renders without quotes, which can mean that it is hard to clearly distinguish the content of the text from other content of the document. I would like to quote this string explicitly as follows:

That is, the connection preface starts with the string "<code>PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n</code>". 

But that would render with double double-quotes in text form, which would not be good. The difference in rendering between text and HTML is the main problem.

One thing that I have observed is that the code here reflects a desire to have some text-level signal whenever an XML element is employed. We can see that with <aside> also (https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/438) where I agree with Julian that the "|" rendering is unnecessarily being used to distinguish between asides and empty lists with no bullets.

This is another example of this incorrect principle being applied. The text rendering can't express all the things that HTML can. It shouldn't even try and it is creating inconsistencies that make authoring documents more difficult.

Change History (5)

comment:1 Changed 11 months ago by julian.reschke@gmx.de

You mean <tt>, not <code>, right?

comment:2 Changed 11 months ago by cabo@tzi.org

The text rendering should enable the specification of a text fallback, like the discussion about <sup> demonstrated.
(Oh, remember < spanx style="vbare" > in RFCXML classic?)

An interesting side observation when translating RFC 6125bis into markdown was that someone (the RPC?) had apparently translated all U+002D (hyphen) in snippets that looked like code into U+2011 (non-breaking hyphen). This is another example where we need to look at the rendering of codespans.

comment:3 Changed 11 months ago by cabo@tzi.org

#634 for the <sup> issue.

Last edited 11 months ago by cabo@tzi.org (previous) (diff)

comment:4 Changed 11 months ago by krathnayake@ietf.org

  • Resolution set to fixed
  • Status changed from new to closed

Fixed in [4012]:

Remove quotes from the text rendering of <tt>. Fixes #600 and #647. Commit ready for merge.

comment:5 Changed 10 months ago by rjsparks@nostrum.com

Fixed in [4024]:

Merged in [4012] from krathnayake@ietf.org:\n Remove quotes from the text rendering of <tt>. Fixes #600 and #647.

Note: See TracTickets for help on using tickets.