Rework the introduction and add a scope chapter

[ehuss]

This reworks the introduction and adds a scope chapter to hopefully make it clearer exactly what the Reference is intended to cover. In summary, the changes are:

• Reworks the introduction.
• Moves some of the conventions to a dedicated chapter.
• Adds a scope chapter.

This is based on my understanding of how the Reference currently works.

The goal is to provide guidance on all the topics covered here. However, since a lot of these guidelines use subjective words (such as "significant" or "exceptional"), it may not provide enough guidance. I expect that some of this may need more elaboration in the future to resolve uncertainties.

Should we document when features are stabilized?

Closes #60

Answer: The scope now says version history is out of scope.

Clarify the audience and goals of the reference

Closes #550

Answer: Introduction now has an audience section.

Policy: Past behavior

Closes #2024

Answer: The scope now says past behavior is out of scope.

Guidelines for parts that are incomplete or undecided

Closes #2025

Answer: The completness section largely covers this. There's a few points here that aren't really covered, but I couldn't think of a way to incorporate them:

• Things should be marked as undecided when the teams say so. That seems fairly self-evident.
• There is no standard notation for stating something is undecided, incomplete, unspecified, undefined, etc. I'll follow-up on that.
• There's no real way to avoid accidentally documenting undecided behavior except for involving the teams with reviews. We generally try to do that as a matter of policy when documenting things we aren't confident about.

Guidelines for parts that are intentionally unspecified

Closes #2026

Answer: Covered in "unspecified behavior".

Guidelines for referring to rustc lints

Closes #2027

Answer: Covered in scope chapter.

Guidelines for documenting intended vs actual behavior

Closes #2037

Answer: This is largely covered in the intended behavior section. It uses subjective wording, which maybe isn't super helpful. It also doesn't get really explicit about when to link to an issue or how to handle future-incompatible-warnings. However, I think the spirit is there, and it's hard to be clearer.

Guidelines for deprecated language features and intended future changes

Closes #2038

Answer: Covered in the scope chapter. Notes:

• Future-incompatible warnings are briefly mentioned in intended behavior.
• Recommendations are excluded in out-of-scope.
• Future plans are excluded in out-of-scope.
• Lints are covered in out-of-scope.
• Editions are plainly described as differences to the present behavior.

Guidelines for linking to other documentation

Closes #2039

Answer: I think this is largely covered in out-of-scope, and other places.

Guidelines for implementation-specific rules

Closes #2040

Answer: Essentially we have decided that we won't have a special "implementation-defined" category for now. The Reference will be explicit about the allowed behavior (even if that means there are different options), leave it up to unspecified-behavior, or leave it up to special uncovered topics like certain target-specific behavior.

This is not explicitly stated in the scope since it is covered by other things.

Guidelines for documenting the why of something

Closes #2042

Answer: The new scope rationale section is brief, but I think largely covers this. There are subjective words for the guidelines, which maybe isn't super helpful. But I can't think of super clear guidance without going in too deep with examples and such.

Guidelines for referring to tools and compilers

Closes #2043

Answer: I think this is generally covered, though it still uses subjective adjectives like "significant" or "exceptional".

[RalfJung]

What exactly is meant by "Semantic properties of the runtime behavior"? This sounds vaguely opsem-related and yet I have no idea what you mean. ;)

FWIW, in a typical PL textbook, we'd typically have 3 stages for defining a language; I am not sure if the first three items are meant to match that.

• Formal grammar (corresponds to "valid syntax and forms" I think)
• Static semantics -- this is the type system and all the other static checks the compiler might be doing (in Rust that would include borrow checking [unless you consider that to be part of the type system], const checking, things like that)
• Dynamic semantics -- the set of legal "observable behaviors" or "outcomes" or whatever you want to call it of any program