Choose between semicolons and parenthesis

[erickinnear]

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.

[martinthomson]

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

[ianswett]

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.

[MikeBishop]

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.

[erickinnear]

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.

[martinthomson]

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.