Opened 6 months ago

Closed 5 months ago

Last modified 4 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 6 months ago by julian.reschke@gmx.de

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

comment:2 Changed 5 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 5 months ago by cabo@tzi.org

#634 for the <sup> issue.

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

comment:4 Changed 5 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 4 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.