[quicwg/base-drafts] Choose between semicolons and parenthesis (#3591)

[Eric Kinnear <[e-mail]>]

This is beyond editorial, so skipping an issue for this, but since it came up in #3589.

Bikeshed time! Let's pick between semicolons and parenthesis. 

This PR unifies the "see Section X.Y.Z" at the ends of sentences into the form 
```
sentence words; see Section X.Y.Z.
```
instead of 
```
sentence words (see Section X.Y.Z).
```

However, this doesn't touch the middle of sentences: 
```
These are some sentence words (see Section X.Y.Z) about some stuff you should probably do.
```
Suggestions welcome for the semicolon form of that. 

There are other cases that don't quite seem to fit with semicolons, as well: 
```
- write data, understanding when stream flow control credit
  ({{data-flow-control}}) has successfully been reserved to send the written
  data;
- end the stream (clean termination), resulting in a STREAM frame
  ({{frame-stream}}) with the FIN bit set; and
- reset the stream (abrupt termination), resulting in a RESET_STREAM frame
  ({{frame-reset-stream}}), if the stream was not already in a terminal state.
```
and this seems like it wouldn't want to split between two different styles:
```
This section describes streams in terms of their send or receive components.
Two state machines are described: one for the streams on which an endpoint
transmits data ({{stream-send-states}}), and another for streams on which an
endpoint receives data ({{stream-recv-states}}).
```
One last example for this one:
```
A receiver sets initial credits for all streams by sending transport parameters
during the handshake ({{transport-parameters}}).  A receiver sends
MAX_STREAM_DATA ({{frame-max-stream-data}}) or MAX_DATA ({{frame-max-data}})
frames to the sender to advertise additional credit.
```

And, finally, direct references without "see" too:
```
as a connection error of type STREAM_LIMIT_ERROR (Section X.Y.Z).
```
vs. 
```
as a connection error of type STREAM_LIMIT_ERROR; Section X.Y.Z.
```

So, for now, I've changed all of the "see Section X.Y.Z" form to use semicolons, as they were pretty split between the two already.

Either way we choose, happy to switch this up to match (it's not consistent either way, so no matter what a change is necessary), so this PR can be used to go in either direction.
You can view, comment on, or merge this pull request online at:

  https://github.com/quicwg/base-drafts/pull/3591

-- Commit Summary --

  * Unify on semicolon

-- File Changes --

    M draft-ietf-quic-transport.md (158)

-- Patch Links --

https://github.com/quicwg/base-drafts/pull/3591.patch
https://github.com/quicwg/base-drafts/pull/3591.diff

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/3591