Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Backticks around parameter names #3609

Closed
MikeBishop opened this issue Apr 29, 2020 · 1 comment · Fixed by #3617
Closed

Backticks around parameter names #3609

MikeBishop opened this issue Apr 29, 2020 · 1 comment · Fixed by #3617
Labels
editorial An issue that does not affect the design of the protocol; does not require consensus.

Comments

@MikeBishop
Copy link
Contributor

We're somewhat inconsistent about whether transport parameters et al. get backticks or not across the documents. For example,

the ACK Delay field is scaled by multiplying the encoded value by 2 to the
power of the value of the ack_delay_exponent transport parameter set by the
sender of the ACK frame; see {{transport-parameter-definitions}}. Scaling in

The Retire Prior To field counts connection IDs established during connection
setup and the preferred_address transport parameter; see {{retiring-cids}}. The
Retire Prior To field MUST be less than or equal to the Sequence Number field.

Same goes for error code names, frame types, etc.

@MikeBishop MikeBishop added the editorial An issue that does not affect the design of the protocol; does not require consensus. label Apr 29, 2020
@larseggert larseggert added this to Triage in Late Stage Processing via automation Apr 29, 2020
@larseggert larseggert moved this from Triage to Editorial Issues in Late Stage Processing Apr 29, 2020
@martinthomson
Copy link
Member

martinthomson commented Apr 30, 2020

I think that - at this point - the overwhelming majority of parameter names are not quoted in any way and do go in and add backticks to all of them would be tiresome. However, most are in snake_case, CamelCase, Title Case, or SHOUTING_CASE so they are almost always distinguishable anyway.

I grepped through and we have 38 instances of backticks. Most of these are in -http and -qpack. Most of them are in the description of reserved codepoints. I'm going to suggest we remove the others.

martinthomson added a commit that referenced this issue Apr 30, 2020
This doesn't do qpack because qpack is weird and needs a lot more work.

The places where I kept backticks are for the inline formulae that were
used for the reserved codepoints.  That seemed like it was worth quoting
somehow still.  I also kept backticks for references to variables in
examples.

However, this last principle really hurts in qpack and I don't know what
to do about that.

Closes #3609 (we'll need another issue for qpack).
Late Stage Processing automation moved this from Editorial Issues to Issue Handled May 5, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
editorial An issue that does not affect the design of the protocol; does not require consensus.
Projects
Late Stage Processing
  
Issue Handled
Development

Successfully merging a pull request may close this issue.

2 participants