Skip to content

Commit

Permalink
Merge branch 'master' into over-9000
Browse files Browse the repository at this point in the history
  • Loading branch information
martinthomson committed May 3, 2021
2 parents 04349bb + 46091a5 commit e30fb0f
Show file tree
Hide file tree
Showing 8 changed files with 190 additions and 35 deletions.
11 changes: 6 additions & 5 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,4 +1,10 @@
PYTHON := $(shell which python3)
ifeq ($(PYTHON),)
PYTHON := $(shell which python)
endif

MD_PREPROCESSOR := sed -e 's/{DATE}/$(shell date '+%Y-%m-%d')/g'
XML_TIDY := $(PYTHON) ./xml2rfc-tidy.py

LIBDIR := lib
include $(LIBDIR)/main.mk
Expand All @@ -15,11 +21,6 @@ endif
latest:: lint
.PHONY: lint

PYTHON := $(shell which python3)
ifeq ($(PYTHON),)
PYTHON := $(shell which python)
endif

ifneq ($(PYTHON),)
lint::
@$(PYTHON) ./.lint.py $(addsuffix .md,$(drafts))
Expand Down
5 changes: 4 additions & 1 deletion draft-ietf-quic-http.md
Original file line number Diff line number Diff line change
Expand Up @@ -218,7 +218,10 @@ Additional resources are provided in the final sections:

## Conventions and Terminology

{::boilerplate bcp14}
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in BCP 14 {{!RFC2119}} {{!RFC8174}}
when, and only when, they appear in all capitals, as shown here.

This document uses the variable-length integer encoding from
{{QUIC-TRANSPORT}}.
Expand Down
5 changes: 4 additions & 1 deletion draft-ietf-quic-qpack.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,10 @@ with substantially less head-of-line blocking under the same loss conditions.

## Conventions and Definitions

{::boilerplate bcp14}
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in BCP 14 {{!RFC2119}} {{!RFC8174}}
when, and only when, they appear in all capitals, as shown here.

Definitions of terms that are used in this document:

Expand Down
14 changes: 9 additions & 5 deletions rfc8999.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,10 @@ every version of QUIC.

# Conventions and Definitions

{::boilerplate bcp14}
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in BCP 14 {{!RFC2119}} {{!RFC8174}}
when, and only when, they appear in all capitals, as shown here.

This document defines requirements on future QUIC versions, even where normative
language is not used.
Expand All @@ -137,15 +140,16 @@ x (A):

x (A..B):
: Indicates that x can be any length from A to B; A can be omitted to indicate
a minimum of zero bits and B can be omitted to indicate no set upper limit;
a minimum of zero bits, and B can be omitted to indicate no set upper limit;
values in this format always end on a byte boundary

x (L) = C:
: Indicates that x, with a length described by L, has a fixed value of C
: Indicates that x has a fixed value of C; the length of x is described by
L, which can use any of the length forms above

x (L) ...:
: Indicates that x is repeated zero or more times (and that each instance is
length L)
: Indicates that x is repeated zero or more times and that each instance has a
length of L

This document uses network byte order (that is, big endian) values. Fields
are placed starting from the high-order bits of each byte.
Expand Down
48 changes: 27 additions & 21 deletions rfc9000.md
Original file line number Diff line number Diff line change
Expand Up @@ -226,7 +226,10 @@ set of version-independent properties of QUIC can cite {{QUIC-INVARIANTS}}.

## Terms and Definitions

{::boilerplate bcp14}
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in BCP 14 {{!RFC2119}} {{!RFC8174}}
when, and only when, they appear in all capitals, as shown here.

Commonly used terms in the document are described below.

Expand Down Expand Up @@ -310,28 +313,28 @@ x (A):
: Indicates that x is A bits long

x (i):
: Indicates that x holds an integer value using the variable-length encoding in
{{integer-encoding}}
: Indicates that x holds an integer value using the variable-length encoding
described in {{integer-encoding}}

x (A..B):
: Indicates that x can be any length from A to B; A can be omitted to indicate
a minimum of zero bits and B can be omitted to indicate no set upper limit;
a minimum of zero bits, and B can be omitted to indicate no set upper limit;
values in this format always end on a byte boundary

x (L) = C:
: Indicates that x has a fixed value of C with the length described by
L, which can use any of the three length forms above
: Indicates that x has a fixed value of C; the length of x is described by
L, which can use any of the length forms above

x (L) = C..D:
: Indicates that x has a value in the range from C to D, inclusive,
with the length described by L, as above

\[x (L)\]:
: Indicates that x is optional (and has length of L)
: Indicates that x is optional and has a length of L

x (L) ...:
: Indicates that zero or more instances of x are present (and that each
instance is length L)
: Indicates that x is repeated zero or more times and that each instance has a
length of L

This document uses network byte order (that is, big endian) values. Fields
are placed starting from the high-order bits of each byte.
Expand Down Expand Up @@ -3752,6 +3755,20 @@ which could prevent the connection from ever becoming idle. Non-ack-eliciting
packets are eventually acknowledged when the endpoint sends an ACK frame in
response to other events.

An endpoint that is only sending ACK frames will not receive acknowledgments
from its peer unless those acknowledgments are included in packets with
ack-eliciting frames. An endpoint SHOULD send an ACK frame with other frames
when there are new ack-eliciting packets to acknowledge. When only
non-ack-eliciting packets need to be acknowledged, an endpoint MAY
choose not to send an ACK frame with outgoing frames until an
ack-eliciting packet has been received.

An endpoint that is only sending non-ack-eliciting packets might choose to
occasionally add an ack-eliciting frame to those packets to ensure that it
receives an acknowledgment; see {{ack-tracking}}. In that case, an endpoint
MUST NOT send an ack-eliciting frame in all packets that would otherwise be
non-ack-eliciting, to avoid an infinite feedback loop of acknowledgments.

In order to assist loss detection at the sender, an endpoint SHOULD generate
and send an ACK frame without delay when it receives an ack-eliciting packet
either:
Expand All @@ -3772,17 +3789,6 @@ should only deviate from these requirements after careful consideration of the
performance implications of a change, for connections made by the endpoint and
for other users of the network.

An endpoint that is only sending ACK frames will not receive acknowledgments
from its peer unless those acknowledgments are included in packets with
ack-eliciting frames. An endpoint SHOULD send an ACK frame with other frames
when there are new ack-eliciting packets to acknowledge. When only
non-ack-eliciting packets need to be acknowledged, an endpoint MAY wait until an
ack-eliciting packet has been received to include an ACK frame with outgoing
frames.

A receiver MUST NOT send an ack-eliciting frame in all packets that would
otherwise be non-ack-eliciting, to avoid an infinite feedback loop of
acknowledgments.

### Acknowledgment Frequency

Expand Down Expand Up @@ -6330,7 +6336,7 @@ Error Code:
: A variable-length integer error code that indicates the reason for
closing this connection. A CONNECTION_CLOSE frame of type 0x1c uses codes
from the space defined in {{transport-error-codes}}. A CONNECTION_CLOSE frame
of type 0x1d uses codes from the application protocol error code space; see
of type 0x1d uses codes defined by the application protocol; see
{{app-error-codes}}.

Frame Type:
Expand Down
5 changes: 4 additions & 1 deletion rfc9001.md
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,10 @@ This document describes how TLS acts as a security component of QUIC.

# Notational Conventions

{::boilerplate bcp14}
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in BCP 14 {{!RFC2119}} {{!RFC8174}}
when, and only when, they appear in all capitals, as shown here.

This document uses the terminology established in {{QUIC-TRANSPORT}}.

Expand Down
5 changes: 4 additions & 1 deletion rfc9002.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,10 @@ control mechanisms for QUIC.

# Conventions and Definitions

{::boilerplate bcp14}
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in BCP 14 {{!RFC2119}} {{!RFC8174}}
when, and only when, they appear in all capitals, as shown here.

Definitions of terms that are used in this document:

Expand Down
132 changes: 132 additions & 0 deletions xml2rfc-tidy.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
#!/usr/bin/env python3
# Tidy an xml2rfc file.
#
# This:
# * removes non-semantic content (comments, processing instructions, DOCTYPE
# declarations, broken entity references)
# * wraps BCP 14 language in <bcp14> elements
# * indents elements neatly

import sys
import xml.sax
import re
from xml.sax.saxutils import escape, quoteattr

class Tidy(xml.sax.handler.ContentHandler):
pattern = re.compile(
r"\b((?:(?:MUST|SHOULD|SHALL)(?:\s+NOT)?)|(?:(?:NOT\s+)?RECOMMENDED)|MAY|OPTIONAL|REQUIRED)\b"
)

def __init__(self):
self.tags = []
self.nesting = 0
self.c = ""
self.state = ""

def startDocument(self):
print('<?xml version="1.0" encoding="UTF-8"?>')

def preserve(tag):
return tag in ["artwork", "sourcecode"]

def textElement(tag):
return tag in [
"annotation",
"blockquote",
"dd",
"dt",
"em",
"li",
"preamble",
"refcontent",
"strong",
"sub",
"sup",
"t",
"td",
"th",
"tt",
]

def inline(tag):
return tag in ["code", "cref", "em", "eref", "iref", "sub", "sup", "tt", "xref"]

def flush(self, tag, start=None):
if Tidy.preserve(tag):
c = f"<![CDATA[{self.c}]]>"
else:
c = escape(self.c)
if Tidy.textElement(tag):
if self.state == "open":
# The element is opening, so strip left is safe.
c = c.lstrip()
if start is None or not Tidy.inline(start):
# The element is closing, or the element that is starting
# isn't inline, so strip right is safe.
c = c.rstrip()
c = Tidy.pattern.sub(r"<bcp14>\1</bcp14>", c)
else:
c = c.strip()

if c != "":
if self.state == "open":
print(">", end="")
print(c, end="")
self.state = "text"
self.nl = False

self.c = ""

def currentTag(self):
return next(reversed(self.tags), False)

def startElement(self, tag, attributes):
parent = self.currentTag()
self.flush(parent, tag)

if self.state == "open":
print(">", end="")
if not Tidy.inline(tag):
print()

self.tags.append(tag)
if not Tidy.inline(tag):
print(" " * self.nesting, end="")
self.nesting = self.nesting + 1

print(f"<{tag}", end="")
for name, value in attributes.items():
print(f" {name}={quoteattr(value)}", end="")

self.state = "open"
self.nl = False

def endElement(self, tag):
self.flush(self.tags.pop())

if not Tidy.inline(tag):
self.nesting = self.nesting - 1
if self.nl and not Tidy.inline(self.currentTag()):
print(" " * self.nesting, end="")
if self.state == "open":
print("/>", end="")
else:
print(f"</{tag}>", end="")
self.nl = not Tidy.inline(tag)
if self.nl:
print()
self.state = "close"

def characters(self, content):
self.c = self.c + content

def processingInstruction(self, target, data):
pass


parser = xml.sax.make_parser()
parser.setContentHandler(Tidy())
if len(sys.argv) >= 2:
parser.parse(sys.argv[1])
else:
parser.parse(sys.stdin)

0 comments on commit e30fb0f

Please sign in to comment.