Remove apologies about the Reference
Right now the Reference, in its README and introduction, contains a
number of warnings and caveats that amount to apologies about the
document. These have outlived their usefulness and should be removed.
The Reference is the reference on Rust. It's the product of an
enormous amount of careful work by many people. It's a good document,
and we don't need to apologize about it.
In particular, these apologies don't need to be the very first things
we say about the document. We don't need to warn people off from it.
Given how we frame it at the moment, a reader could reasonably think,
"well, if that's all its own authors think of this document, why
should I waste my time with it?", and anecdotally, this is something
that I've observed people reflecting back to us.
Let's stop this negative cueing.
Does the Reference have bugs or omissions? Sure. It always will. So
does and will our compiler. We can simply point people to our issue
tracker in a note; we don't need for this to be a warning, and we
don't need to elaborate.
Do we need to say the Reference is non-normative? No. We treat it
with all the care and respect that we would any normative document,
and we have for many years. We author it in normative language, and
we take care to ensure that the substance of this normative language
accords with normative lang team decisions. The lang team directly
FCPs changes to the Reference when those changes affect the guarantees
that are made by the language.
Do we need to say that our descriptions of the language are
"informal"? No, not in general. We work to describe things as
precisely and correctly as we can. While such statements might not be
"formal" ones, neither are they "informal".
Do we need to say that it's not a specification? No. What is a
specification anyway? We'd have to answer that before saying that
it's not one.
The Reference is the Reference. That's all we need to say. The text
speaks for itself. Let's remove those things that have outlived their
usefulness to us.
diff --git a/README.md b/README.md
index 0c7f3c4..cfcd0b8 100644
--- a/README.md
+++ b/README.md
@@ -3,11 +3,6 @@
This document is the primary reference for the Rust programming
language.
-This document is not normative. It may include details that are specific
-to `rustc` itself, and should not be taken as a specification for the
-Rust language. We intend to produce such a document someday, but this is
-what we have for now.
-
## Dependencies
- Nightly Rust
diff --git a/src/introduction.md b/src/introduction.md
index a59a84f..3e926ed 100644
--- a/src/introduction.md
+++ b/src/introduction.md
@@ -1,15 +1,9 @@
# Introduction
This book is the primary reference for the Rust programming language.
-It provides three kinds of material:
- - Chapters that informally describe each language construct and their use.
- - Chapters that informally describe the memory model, concurrency model, runtime services, linkage model, and debugging facilities.
- - Appendix chapters providing rationale and references to languages that influenced the design.
-
-> [!WARNING]
-> This book is incomplete. Documenting everything takes a while.
-> See the [GitHub issues] for what is not documented in this book.
+> [!NOTE]
+> For known bugs in and omissions of this book, see our [GitHub issues]. If you see a case where the compiler behavior and the text here do not agree, file an issue so we can think about which is correct.
## Rust releases
@@ -45,10 +39,6 @@
You can only probe by running it, feeding it input and observing its output.
Everything that happens that way must conform to what the reference says.
-Finally, this book is not normative.
-It may include details that are specific to `rustc` itself, and should not be taken as a specification for the Rust language.
-We intend to produce such a book someday, and until then, the reference is the closest thing we have to one.
-
## How to use this book
This book does not assume you are reading this book sequentially.
@@ -127,7 +117,7 @@
You can contribute to this book by opening an issue or sending a pull request to [the Rust Reference repository].
If this book does not answer your question, and you think its answer is in scope of it, please do not hesitate to [file an issue] or ask about it in the `t-lang/doc` stream on [Zulip].
Knowing what people use this book for the most helps direct our attention to making those sections the best that they can be.
-We also want the reference to be as normative as possible, so if you see anything that is wrong or is non-normative but not specifically called out, please also [file an issue].
+And of course, if you see anything that is wrong or is non-normative but not specifically called out as such, please also [file an issue].
[book]: ../book/index.html
[github issues]: https://github.com/rust-lang/reference/issues
