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

From: Eric Kinnear <[email-masked]>
Date: Mon, 20 Apr 2020 22:08:57 -0700

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

Bikeshed time! Let&#39;s pick between semicolons and parenthesis. 

This PR unifies the &quot;see Section X.Y.Z&quot; 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&#39;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&#39;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&#39;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 &quot;see&quot; 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&#39;ve changed all of the &quot;see Section X.Y.Z&quot; 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&#39;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

---

From: Martin Thomson <[email-masked]>
Date: Tue, 21 Apr 2020 00:19:48 -0700

@martinthomson approved this pull request.

We've been working toward this piecemeal.  This helps a lot.

-- 
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#pullrequestreview-397051498

---

From: ianswett <[email-masked]>
Date: Tue, 21 Apr 2020 06:39:45 -0700

If we're going in this direction, we should update the other drafts as well(in subsequent PRs).  I'm a fan of parens myself, but it's a bikeshed and I don't care that much.

-- 
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#issuecomment-617186241

---

From: Mike Bishop <[email-masked]>
Date: Tue, 21 Apr 2020 10:29:35 -0700

I'm fine with leaving the parens mid-sentence.  To me, the distinction is whether they're providing extra information about the entire sentence, or about a specific term in the sentence.  If it's about a specific term, use parens immediately after the term; if it's about the sentence in general, use a semicolon after the sentence.

-- 
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#issuecomment-617304100

---

From: Eric Kinnear <[email-masked]>
Date: Tue, 21 Apr 2020 11:14:05 -0700

Personally, I didn’t mind the parenthesis, but thanks @MikeBishop for putting some rationale together for mid vs. end of sentence refs like this — that sounds like a strategy I can live with.

-- 
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#issuecomment-617328508

---

From: Martin Thomson <[email-masked]>
Date: Tue, 21 Apr 2020 15:10:55 -0700

Merged #3591 into master.

-- 
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#event-3258089656

---

From: Martin Thomson <[email-masked]>
Date: Wed, 22 Apr 2020 18:11:29 -0700

Mike's rationale is excellent.  Though I would add that the good practice of one concept per sentence leads to using a semicolon more often than not.

-- 
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#issuecomment-618119114