search

oauth-wg / oauth-selective-disclosure-jwt

https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt/
Other
56 stars 27 forks source link

quote claim name literals #379

Closed bc-pi closed 7 months ago

bc-pi commented 8 months ago

Enclosing claim names (and similar things) in backticks (`) in the markdown results in the text being enclosed in <tt> in the xml. In the html and pdf outputs of xml2rfc, that text enclosed in <tt> is output in a fixed-width font. Which is nice. However, in the txt output and subsequently the htmlized version, there is nothing distinguishing such text (xml2rfc did previously surround with quotation marks but is no longer doing so). And even in the html version the fixed-width font with short values like claim names isn't always particularly distinguishing.

All this is to say that I think a pass should be made through the whole markdown document to add (where appropriate) quotation marks around claim and header names and any other suitable items.

I've previously seen questions/comments about this from the RFC Editor as well as IESG and directorate reviews. So it wouldn't be a bad thing to do before getting to that stage.

danielfett commented 8 months ago

I remember similar discussions from RFC9449 and RFC9207 and AFAIR the outcome was to keep the current form (i.e., optimize for html and PDF output, not txt and htmlized txt).

Sakurann commented 8 months ago

I don't have a strong opinion, but keeping as-is seems ok, since backticks (`) are reflected in the html version

selfissued commented 8 months ago

I agree that we should be using backquotes to annotate identifiers in running text. I oppose switching to doublequotes.

I asked the authors of XML2RFC v3 about the change in behavior for .txt files when the "new" (now a few years old) IETF RFC format was put in place. They didn't seem concerned about it at the time - I believe being focused on formatted outputs such as HTML and PDF.

I don't think it would be productive for us to invent different conventions that try to contravene what the tools we're using do.

danielfett commented 7 months ago

Agreed in the call to stick to backticks.