From aaf34be8d7e0582ee9e7b7e8432303763bf5e11e Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Tue, 26 Jan 2021 15:18:07 -0800 Subject: [PATCH 1/5] One Sentence is One Line the Introduction --- src/introduction.md | 125 ++++++++++++++++++-------------------------- 1 file changed, 51 insertions(+), 74 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index ff885b4b1..d42f935b5 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -1,102 +1,86 @@ # Introduction -This book is the primary reference for the Rust programming language. It -provides three kinds of material: +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. + - 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. +Warning: +This book is incomplete. Documenting everything takes a while. +See the [GitHub issues] for what is not documented in this book.
## What *The Reference* is Not -This book does not serve as an introduction to the language. Background -familiarity with the language is assumed. A separate [book] is available to -help acquire such background familiarity. +This book does not serve as an introduction to the language. +Background familiarity with the language is assumed. +A separate [book] is available to help acquire such background familiarity. -This book also does not serve as a reference to the [standard library] -included in the language distribution. Those libraries are documented -separately by extracting documentation attributes from their source code. Many -of the features that one might expect to be language features are library -features in Rust, so what you're looking for may be there, not here. +This book also does not serve as a reference to the [standard library] included in the language distribution. +Those libraries are documented separately by extracting documentation attributes from their source code. +Many of the features that one might expect to be language features are library features in Rust, so what you're looking for may be there, not here. -Similarly, this book does not usually document the specifics of `rustc` as a -tool or of Cargo. `rustc` has its own [book][rustc book]. Cargo has a -[book][cargo book] that contains a [reference][cargo reference]. There are a few -pages such as [linkage] that still describe how `rustc` works. +Similarly, this book does not usually document the specifics of `rustc` as a tool or of Cargo. +`rustc` has its own [book][rustc book]. +Cargo has a [book][cargo book] that contains a [reference][cargo reference]. +There are a few pages such as [linkage] that still describe how `rustc` works. -This book also only serves as a reference to what is available in stable -Rust. For unstable features being worked on, see the [Unstable Book]. +This book also only serves as a reference to what is available in stable Rust. +For unstable features being worked on, see the [Unstable Book]. -Rust compilers, including `rustc`, will perform optimizations. The reference -does not specify what optimizations are allowed or disallowed. Instead, think of -the compiled program as a black box. 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. +Rust compilers, including `rustc`, will perform optimizations. +The reference does not specify what optimizations are allowed or disallowed. +Instead, think of the compiled program as a black box. +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. +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. Each -chapter generally can be read standalone, but will cross-link to other chapters -for facets of the language they refer to, but do not discuss. +This book does not assume you are reading this book sequentially. +Each chapter generally can be read standalone, but will cross-link to other chapters for facets of the language they refer to, but do not discuss. There are two main ways to read this document. -The first is to answer a specific question. If you know which chapter answers -that question, you can jump to that chapter in the table of contents. Otherwise, -you can press `s` or the click the magnifying glass on the top bar to search for -keywords related to your question. For example, say you wanted to know when a -temporary value created in a let statement is dropped. If you didn't already -know that the [lifetime of temporaries] is defined in the [expressions chapter], -you could search "temporary let" and the first search result will take you to -that section. +The first is to answer a specific question. +If you know which chapter answers that question, you can jump to that chapter in the table of contents. +Otherwise, you can press `s` or the click the magnifying glass on the top bar to search for keywords related to your question. +For example, say you wanted to know when a temporary value created in a let statement is dropped. +If you didn't already know that the [lifetime of temporaries] is defined in the [expressions chapter], you could search "temporary let" and the first search result will take you to that section. The second is to generally improve your knowledge of a facet of the language. -In that case, just browse the table of contents until you see something you -want to know more about, and just start reading. If a link looks interesting, -click it, and read about that section. +In that case, just browse the table of contents until you see something you want to know more about, and just start reading. +If a link looks interesting, click it, and read about that section. -That said, there is no wrong way to read this book. Read it however you feel -helps you best. +That said, there is no wrong way to read this book. Read it however you feel helps you best. ### Conventions -Like all technical books, this book has certain conventions in how it displays -information. These conventions are documented here. +Like all technical books, this book has certain conventions in how it displays information. +These conventions are documented here. -* Statements that define a term contain that term in *italics*. Whenever that - term is used outside of that chapter, it is usually a link to the section that - has this definition. +* Statements that define a term contain that term in *italics*. + Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition. An *example term* is an example of a term being defined. -* Differences in the language by which edition the crate is compiled under are - in a blockquote that start with the words "Edition Differences:" in **bold**. +* Differences in the language by which edition the crate is compiled under are in a blockquote that start with the words "Edition Differences:" in **bold**. - > **Edition Differences**: In the 2015 edition, this syntax is valid that is - > disallowed as of the 2018 edition. + > **Edition Differences**: In the 2015 edition, this syntax is valid that is disallowed as of the 2018 edition. -* Notes that contain useful information about the state of the book or point out - useful, but mostly out of scope, information are in blockquotes that start - with the word "Note:" in **bold**. +* Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in blockquotes that start with the word "Note:" in **bold**. > **Note**: This is an example note. -* Warnings that show unsound behavior in the language or possibly confusing - interactions of language features are in a special warning box. +* Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box.
@@ -106,8 +90,7 @@ information. These conventions are documented here. * Code snippets inline in the text are inside `` tags. - Longer code examples are in a syntax highlighted box that has controls for - copying, executing, and showing hidden lines in the top right corner. + Longer code examples are in a syntax highlighted box that has controls for copying, executing, and showing hidden lines in the top right corner. ```rust # // This is a hidden line. @@ -116,8 +99,7 @@ information. These conventions are documented here. } ``` -* The grammar and lexical structure is in blockquotes with either "Lexer" or - "Syntax" in **bold superscript** as the first line. +* The grammar and lexical structure is in blockquotes with either "Lexer" or "Syntax" in **bold superscript** as the first line. > **Syntax**\ > _ExampleGrammar_:\ @@ -130,15 +112,10 @@ information. These conventions are documented here. We welcome contributions of all kinds. -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]. +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]. [book]: ../book/index.html [github issues]: https://github.com/rust-lang/reference/issues From a527233e308eee5f802d7e60c8c8a7a3685acaa6 Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Tue, 26 Jan 2021 16:04:36 -0800 Subject: [PATCH 2/5] Try to define Rust itself I'm not overly satisfied with what I've written. --- src/introduction.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/introduction.md b/src/introduction.md index d42f935b5..f737c2e9e 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -15,6 +15,18 @@ See the [GitHub issues] for what is not documented in this book.
+## Rust Releases + +Rust has a new language release every six weeks. +The first stable release of the language was Rust 1.0.0, followed by Rust 1.1.0 and so on. +Tools (`rustc`, `cargo`, etc.) and documentation ([Standard library], this book, etc.) are released with the language release. + +While tools often have the same version as the Rust language, the language exists as its own concept separately from them. + +The latest release of this book, matching the latest Rust version, can always be found at [https://doc.rust-lang.org/reference/](https://doc.rust-lang.org/reference/). +Prior versions can be found by adding the Rust version before the "reference" directory. +For example, the Reference for Rust 1.49.0 is located at [https://doc.rust-lang.org/1.49.0/reference/](https://doc.rust-lang.org/1.49.0/reference/). + ## What *The Reference* is Not This book does not serve as an introduction to the language. From ef79042faacd9e2b1ddec44513cc127dccc003f9 Mon Sep 17 00:00:00 2001 From: Ryan Scheel Date: Sun, 31 Jan 2021 21:01:50 -0800 Subject: [PATCH 3/5] Use Angle Bracket Links Co-authored-by: Eric Huss --- src/introduction.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index f737c2e9e..7952f8d8b 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -23,9 +23,9 @@ Tools (`rustc`, `cargo`, etc.) and documentation ([Standard library], this book, While tools often have the same version as the Rust language, the language exists as its own concept separately from them. -The latest release of this book, matching the latest Rust version, can always be found at [https://doc.rust-lang.org/reference/](https://doc.rust-lang.org/reference/). +The latest release of this book, matching the latest Rust version, can always be found at . Prior versions can be found by adding the Rust version before the "reference" directory. -For example, the Reference for Rust 1.49.0 is located at [https://doc.rust-lang.org/1.49.0/reference/](https://doc.rust-lang.org/1.49.0/reference/). +For example, the Reference for Rust 1.49.0 is located at . ## What *The Reference* is Not From 421be27df3fbd39d211a1f4cf22b7132ad6f64ed Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Sun, 31 Jan 2021 21:15:23 -0800 Subject: [PATCH 4/5] Remove callout of lang != compiler --- src/introduction.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index 7952f8d8b..a7968ade6 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -21,8 +21,6 @@ Rust has a new language release every six weeks. The first stable release of the language was Rust 1.0.0, followed by Rust 1.1.0 and so on. Tools (`rustc`, `cargo`, etc.) and documentation ([Standard library], this book, etc.) are released with the language release. -While tools often have the same version as the Rust language, the language exists as its own concept separately from them. - The latest release of this book, matching the latest Rust version, can always be found at . Prior versions can be found by adding the Rust version before the "reference" directory. For example, the Reference for Rust 1.49.0 is located at . From b16ae389daf1e0b7b61f9103b33591017422717d Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Sun, 31 Jan 2021 21:16:11 -0800 Subject: [PATCH 5/5] Capitalization style of titles on Introduction --- src/introduction.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index a7968ade6..d08d0b251 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -15,7 +15,7 @@ See the [GitHub issues] for what is not documented in this book. -## Rust Releases +## Rust releases Rust has a new language release every six weeks. The first stable release of the language was Rust 1.0.0, followed by Rust 1.1.0 and so on. @@ -25,7 +25,7 @@ The latest release of this book, matching the latest Rust version, can always be Prior versions can be found by adding the Rust version before the "reference" directory. For example, the Reference for Rust 1.49.0 is located at . -## What *The Reference* is Not +## What *The Reference* is not This book does not serve as an introduction to the language. Background familiarity with the language is assumed. @@ -53,7 +53,7 @@ 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 +## How to use this book This book does not assume you are reading this book sequentially. Each chapter generally can be read standalone, but will cross-link to other chapters for facets of the language they refer to, but do not discuss.