Skip to content

Commit d5c72e5

Browse files
committed
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.
1 parent e8c651f commit d5c72e5

File tree

2 files changed

+5
-15
lines changed

2 files changed

+5
-15
lines changed

README.md

-5
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,6 @@
33
This document is the primary reference for the Rust programming
44
language.
55

6-
This document is not normative. It may include details that are specific
7-
to `rustc` itself, and should not be taken as a specification for the
8-
Rust language. We intend to produce such a document someday, but this is
9-
what we have for now.
10-
116
## Dependencies
127

138
- Nightly Rust

src/introduction.md

+5-10
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,12 @@
33
This book is the primary reference for the Rust programming language.
44
It provides three kinds of material:
55

6-
- Chapters that informally describe each language construct and their use.
7-
- Chapters that informally describe the memory model, concurrency model, runtime services, linkage model, and debugging facilities.
6+
- Chapters that describe each language construct and their use.
7+
- Chapters that describe the memory model, concurrency model, runtime services, linkage model, and debugging facilities.
88
- Appendix chapters providing rationale and references to languages that influenced the design.
99

10-
> [!WARNING]
11-
> This book is incomplete. Documenting everything takes a while.
12-
> See the [GitHub issues] for what is not documented in this book.
10+
> [!NOTE]
11+
> For known bugs in and omissions of this book, see our [GitHub issues].
1312
1413
## Rust releases
1514

@@ -45,10 +44,6 @@ Instead, think of the compiled program as a black box.
4544
You can only probe by running it, feeding it input and observing its output.
4645
Everything that happens that way must conform to what the reference says.
4746

48-
Finally, this book is not normative.
49-
It may include details that are specific to `rustc` itself, and should not be taken as a specification for the Rust language.
50-
We intend to produce such a book someday, and until then, the reference is the closest thing we have to one.
51-
5247
## How to use this book
5348

5449
This book does not assume you are reading this book sequentially.
@@ -134,7 +129,7 @@ We welcome contributions of all kinds.
134129
You can contribute to this book by opening an issue or sending a pull request to [the Rust Reference repository].
135130
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].
136131
Knowing what people use this book for the most helps direct our attention to making those sections the best that they can be.
137-
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].
132+
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].
138133

139134
[book]: ../book/index.html
140135
[github issues]: https://github.com/rust-lang/reference/issues

0 commit comments

Comments
 (0)