…eferential` `gen` block issues

* minor typos

* intro

* motivation

* guide

* reference

* implementation

* alternates

* rationale

* future

* whitespace

There were some places with erroneous or unclear punctuation and
capitalization.  Let's fix those and make some related typographic
and linguistic improvements.

We had said `[text][#foo]` when we had meant to say `[text][foo]`,
leading to broken internal link elements when referencing the
unresolved questions section.  Let's fix that.

The C# (CSharp) language has a `yield` statement.  Let's describe this
in a new prior art section.

(Thanks to @scottmcm for pointing this out.)

In the motivation, we enumerate some ways that people can create an
iterator.  One way we didn't demonstrate was the use of
`std::iter::from_fn`.  Let's do that, and let's add a mention of this
in the section about the ever-present option of doing nothing.

(Thanks to @estebank for pointing this out.)

We're specifying that `gen` blocks must diverge or return the unit
type.  Let's articulate exactly what that means.

(Thanks to @scottmcm for pointing this out.)

The section on error handling discussed very specifically the behavior
with `Option` and `Result` in a way that may have made the general
case less clear.  E.g., it did not discuss the handling of
`ControlFlow`, leaving unclear whether arbitrary types that implement
the `Try` trait could be used.  It also did not discuss whether
`From::from` was called as usual in case of short-circuiting.

Let's simplify this section a bit by first discussing the desugaring,
discussing the non-effect on the required type of trailing elements or
arguments to `return` in the block, and discussing the effect on the
type of the arguments required by `yield`.

Notably, we won't discuss here the details of how `None` is returned
to end iteration.  This behavior is the same as when `?` is not used,
and the desugaring we describe fills in all of the needed details.

(Thanks to @scottmcm for pointing out the ambiguous nature of this
section.)

Generators, iterators, and the `yield` keyword have a long history in
the programming language literature.  Let's describe some of this
history in the prior art section and add more examples of languages
with these features.

In the 2023-10-18 T-lang triage meeting, the team decided that this
RFC should settle of the question of the keyword.  Consequently, let's
commit to the `gen` keyword and use it throughout the document rather
than using an attribute placeholder.

Some of the language in this RFC implied that this is an experiment
and that another RFC would be required.  This isn't how we want to
frame things.  Another RFC could always be required, but it's also
possible that stabilization could occur on the basis of this RFC.

This is a normal RFC.  Let's remove all language about this being an
experiment.

…work.

We had listed self-referential `gen` blocks as a future possibility,
but in discussion with T-lang, it's become clear that this should
instead be listed as an open question, so let's do that.

For many years, we had a trait in nightly Rust called `Generator`.
We've now renamed this to `Coroutine`, but this RFC still referred to
it as `Generator`.  Let's use the new name and make a note of the old
one.

To give us better options for supporting self-referential generators
we may not want the type returned by `gen` blocks to implement
`Iterator` directly.  Let's call this out as an open question and
weaken claims throughout the document related to this.

The language about how to refer to the `gen` keyword in older editions
was changed in a recent commit from `k#gen` to `r#gen`.  This was
probably a search/replace error.  Let's fix that.

We meant to change `r#gen` to `k#gen` on one line to fix an apparent
earlier search/replace error, and we erroneously changed it on a
different line.  Let's fix the correct line and fix the mistaken fix.

We had already opened a tracking issue for this work, so let's fill
that in here.

In addition to giving the file the correct number, let's call this
`gen-blocks` rather than `gen-fn` since we removed `gen fn` from the
main body of this RFC.

The feature name in the draft was a placeholder.  Let's update this to
the actual feature name now in use.

We had a mix between hard wrapped lines of various widths and
unwrapped lines.  Let's unwrap all lines.

The main body of the RFC discusses how we might implement
`FusedIterator` for the iterators produced by `gen` blocks, but this
was not listed as a future possibility.  Let's do that.

There was a statement in the draft about, as a downside, something
needing to be pinned for the entire iteration rather than just for
each call to `next`.  But, of course, under the pinning guarantees,
these are equivalent.  Once something is pinned, unless it is `Unpin`,
it must be treated as pinned until it is destructed.  Let's remove
this statement.

In RFC 3101 we reserved in Rust 2021 prefixed identifiers such as
`prefix#ident`.  For this reason, we can make `gen` blocks available
in Rust 2021 using `k#gen` as was anticipated in the (currently
pending) RFC 3098.

It's less clear what to do about Rust 2015 and Rust 2018, however, so
let's mark this as an open question.

(Thanks to tmandry for raising this point.)

We had been meaning to do some final copyediting prior to this RFC
being merged, so let's do that.  In addition to making the text a bit
more regular and precise, fixing some minor errors, removing outdated
information, and adding references between sections, we've tried to
"tighten it up" a bit where possible.  We've been careful to not
change anything of semantic significance or otherwise of significance
to the consensus.

The Koka language provides an interesting alternative data point for
how generators and other powerful control flow constructs could work
in a typed language such as Rust.  Let's include an example in the
prior art section.

(Thanks to zesterer for asking for this.)

Using the no-op `Waker`, we can express generators and coroutines in
Rust.  Let's close our list of prior art examples with that.

Under this RFC, it's possible to yield one last value concisely with
`return yield EXPR`.  Let's make a note of that.

(Thanks to Nemo157 for pointing this out and to pnkfelix for
suggesting that this be noted in the RFC.)

The motivating example we had given for `gen` blocks admitted too easy
an implementation with existing stable iterator combinators.  Let's
make the example more *motivating* by showing a simple algorithm,
run-length encoding, that's more difficult to implement in other ways.

(Thanks to Ralf Jung for pointing out the need for a better example.)