http-extensions
http-extensions copied to clipboard
httpwg
Monospace variable names in draft-variants.
This made it easier for me to read some of the algorithms, but feel free to reject it if it doesn't help you.
We've tried this syntax in the past, but the "`" marks get into the .txt, and then we have to work with the RFC Editor to remove them before publication.
I see " quotes in the .txt, but I would believe the formal RFC process does something different. That said, "`" backticks are arguably a better text syntax than quotes for variable names, and would, IMO help readability in the text format too.
But I won't be mad if you don't want this change. :)
As @jyasskin says, backticks turn into double quotes with no issue. Some other specs in this repo used that with reasonable outcomes. You just have to be sure that you wanted those quotes.
Yes. I'm saying that my experience is that the RFC Editor and others don't like to see variable names surrounded by "`".
Ah - so are you saying that something in between .md and .txt (kramdown-rfc2629 or xml2rfc) now produces a double quote instead of a backtick? When / where did that happen?
In my experience it's always done that, at least when I build my .txt files locally. (Where "always" means "for at least a couple of years".)
For example, search these documents for "n00" -- in the HTML it renders as <span class="tt">n00</span> and in the text it is "n00":
- https://httpwg.org/http-extensions/bcp56bis.html
- https://httpwg.org/http-extensions/bcp56bis.txt
kramdown-rfc2629 turns backticks into <spanx style="verb">, and xml2rfc converts that to quotes at https://trac.tools.ietf.org/tools/xml2rfc/trac/browser/trunk/cli/xml2rfc/writers/raw_txt.py?rev=2843#L486.
There is some risk to using typography in RFCs: https://mozphab-ietf.devsvcdev.mozaws.net/D4234#inline-7837 shows CDDL describing typewriter text, while the reviewer saw quotes.
OK. I may have been confusing "`" with something else.
The only issue I see here is that lines like this:
- If "identity" is not a member of
preferred-codings, append "identity".
will become in .txt:
- If "identity" is not a member of "preferred-codings", append "identity".
... so there won't be any discriminator between a variable reference and a literal. That doesn't seem good.
Right now we depend on the uniqueness of the term to identify variables, reserving double-quotes for literals. I agree that the HTML rendering is MUCH better, but sadly that still isn't the authoritative version.
The discussion is useful, but I wouldn't go there for specs that are planned to be published anytime soon.
