From edf6c62857a2395115a6805e24578206a97fdd4e Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Thu, 23 Aug 2018 21:10:11 -0700 Subject: [PATCH 1/8] Expand the introduction. * Added another paragraph explaining that we don't document tools. * Expanded the contribution section. * Remove the part saying we may document some unstable stuff. * Added a how-to-read paragraph. --- src/introduction.md | 40 ++++++++++++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index 9281e27b4..15903857d 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -13,34 +13,54 @@ This document 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 document also does not serve as a reference to the [standard] library +This document 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 document does not usually document the specifics of `rustc` as a +tool or of Cargo. 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 document also only serves as a reference to what is available in stable -Rust. For unstable features being worked on, see the [Unstable Book]. This was -a recent change in scope, so unstable features are still documented, but are -in the process of being removed. +Rust. For unstable features being worked on, see the [Unstable Book]. Finally, 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. +the Rust language. We intend to produce such a document someday, and until then, +the reference is the closest thing we have to one. + +You sould not read this document sequentially. As a reference document, you +should skim the table of contents until you find the section you are interested +in and read that section. If you are viewing this in a browser and have +JavaScript enabled, you can also press `s` or click the magnifying glass on the +top bar to open a search bar. You may also be interested in the [grammar]. You can contribute to this document by opening an issue or sending a pull -request to [the Rust Reference repository]. +request to [the Rust Reference repository]. If this document 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 Rust docs channels on IRC or +discord. Knowing what people use this document for the most helps direct our +attention to making those sections the best that they can be. -N. B. This document may be incomplete. Documenting everything might take a +
+ +Warning: This document may be incomplete. Documenting everything takes a while. We have a [big issue] to track documentation for every Rust feature, so check that out if you can't find something here. +
+ [book]: ../book/index.html -[standard]: ../std/index.html +[standard library]: ../std/index.html [grammar]: ../grammar.html [the Rust Reference repository]: https://github.com/rust-lang-nursery/reference/ [big issue]: https://github.com/rust-lang-nursery/reference/issues/9 -[Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/ \ No newline at end of file +[Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/ +[cargo book]: ../cargo/index.html +[cargo reference]: ../cargo/reference/index.html +[linkage]: linkage.html \ No newline at end of file From 9d4b36de12479223cb47787140ab5b8d4c508cad Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Thu, 23 Aug 2018 21:13:46 -0700 Subject: [PATCH 2/8] Add structure (headers) to introduction This involved moving paragraphs around as well. --- src/introduction.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index 15903857d..ae478a387 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -9,6 +9,18 @@ provides three kinds of material: - Appendix chapters providing rationale and references to languages that influenced the design. +You may also be interested in the [grammar]. + +
+ +Warning: This document is incomplete. Documenting everything takes a +while. We have a [big issue] to track documentation for every Rust feature, +so check that out if you can't find something here. + +
+ +## What *The Reference* is Not + This document 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. @@ -32,13 +44,17 @@ specific to `rustc` itself, and should not be taken as a specification for the Rust language. We intend to produce such a document someday, and until then, the reference is the closest thing we have to one. +## How to Read The Reference + You sould not read this document sequentially. As a reference document, you should skim the table of contents until you find the section you are interested in and read that section. If you are viewing this in a browser and have JavaScript enabled, you can also press `s` or click the magnifying glass on the top bar to open a search bar. -You may also be interested in the [grammar]. +## Contributing + +We welcome contributions of all kind. You can contribute to this document by opening an issue or sending a pull request to [the Rust Reference repository]. If this document does not answer @@ -47,14 +63,6 @@ hesitate to file an issue or ask about it in the Rust docs channels on IRC or discord. Knowing what people use this document for the most helps direct our attention to making those sections the best that they can be. -
- -Warning: This document may be incomplete. Documenting everything takes a -while. We have a [big issue] to track documentation for every Rust feature, -so check that out if you can't find something here. - -
- [book]: ../book/index.html [standard library]: ../std/index.html [grammar]: ../grammar.html From c2da8328f98e58e658887a51ad26201a7cff6b05 Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Thu, 23 Aug 2018 22:07:16 -0700 Subject: [PATCH 3/8] Conventions and more on how to use this book --- src/introduction.md | 80 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 73 insertions(+), 7 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index ae478a387..fff72c2f9 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -9,7 +9,7 @@ provides three kinds of material: - Appendix chapters providing rationale and references to languages that influenced the design. -You may also be interested in the [grammar]. +> **Note**: You may also be interested in the [grammar].
@@ -44,13 +44,76 @@ specific to `rustc` itself, and should not be taken as a specification for the Rust language. We intend to produce such a document someday, and until then, the reference is the closest thing we have to one. -## How to Read The Reference +## How to Use This Book -You sould not read this document sequentially. As a reference document, you -should skim the table of contents until you find the section you are interested -in and read that section. If you are viewing this in a browser and have -JavaScript enabled, you can also press `s` or click the magnifying glass on the -top bar to open a search bar. +This book does not assume you are reading this document 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 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. + +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. + +* 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 beind defined. + +* 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. + +
+ + Warning: This is an example warning. + +
+ +* 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. + + ```rust + # // This is a hidden line. + fn main() { + println!("This is a code example"); + } + ``` + +* The grammar and lexical structure is in blockquotes with either "Lexer" or + "Syntax" in **bold** as the first line in superscript. + + > **Syntax**\ + > _ExampleGrammar_:\ + >       `~` [_Expression_]\ + >    | `box` [_Expression_] ## Contributing @@ -69,6 +132,9 @@ attention to making those sections the best that they can be. [the Rust Reference repository]: https://github.com/rust-lang-nursery/reference/ [big issue]: https://github.com/rust-lang-nursery/reference/issues/9 [Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/ +[_Expression_]: expressions.html [cargo book]: ../cargo/index.html [cargo reference]: ../cargo/reference/index.html +[expressions chapter]: expressions.html +[lifetime of temporaries]: expressions.html#temporary-lifetimes [linkage]: linkage.html \ No newline at end of file From 3f6388450cecaa3886c24a6b5492a9a1da064151 Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Thu, 23 Aug 2018 22:16:45 -0700 Subject: [PATCH 4/8] Change 'this document' to 'this book' in introduction --- src/introduction.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index fff72c2f9..8c6b38e17 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -1,6 +1,6 @@ # Introduction -This document is the primary reference for the Rust programming language. It +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. @@ -13,7 +13,7 @@ provides three kinds of material:
-Warning: This document is incomplete. Documenting everything takes a +Warning: This book is incomplete. Documenting everything takes a while. We have a [big issue] to track documentation for every Rust feature, so check that out if you can't find something here. @@ -21,32 +21,32 @@ so check that out if you can't find something here. ## What *The Reference* is Not -This document does not serve as an introduction to the language. Background +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 document also does not serve as a reference to the [standard library] +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 document does not usually document the specifics of `rustc` as a +Similarly, this book does not usually book the specifics of `rustc` as a tool or of Cargo. 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 document also only serves as a reference to what is available in stable +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]. -Finally, this document is not normative. It may include details that are +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 document someday, and until then, +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 document sequentially. Each +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. @@ -119,11 +119,11 @@ information. These conventions are documented here. We welcome contributions of all kind. -You can contribute to this document by opening an issue or sending a pull -request to [the Rust Reference repository]. If this document does not answer +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 Rust docs channels on IRC or -discord. Knowing what people use this document for the most helps direct our +discord. Knowing what people use this book for the most helps direct our attention to making those sections the best that they can be. [book]: ../book/index.html From b6600c4da7263339048a462ebbc81b458996a91a Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Sat, 25 Aug 2018 01:07:54 -0700 Subject: [PATCH 5/8] rustc has a book. Fix typo --- src/introduction.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index 8c6b38e17..3b8c2ed14 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -32,9 +32,9 @@ 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 book the specifics of `rustc` as a -tool or of Cargo. 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. +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]. @@ -117,7 +117,7 @@ information. These conventions are documented here. ## Contributing -We welcome contributions of all kind. +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 @@ -137,4 +137,5 @@ attention to making those sections the best that they can be. [cargo reference]: ../cargo/reference/index.html [expressions chapter]: expressions.html [lifetime of temporaries]: expressions.html#temporary-lifetimes -[linkage]: linkage.html \ No newline at end of file +[linkage]: linkage.html +[rustc book]: ../rustc/index.html \ No newline at end of file From 0d7a0625d3a3041441c6691929f5452fc744bfb6 Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Sat, 25 Aug 2018 02:55:40 -0700 Subject: [PATCH 6/8] Adress Matthew Jasper's comments --- src/introduction.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index 3b8c2ed14..1fc723db8 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -13,9 +13,8 @@ provides three kinds of material:
-Warning: This book is incomplete. Documenting everything takes a -while. We have a [big issue] to track documentation for every Rust feature, -so check that out if you can't find something here. +Warning: This book is incomplete. Documenting everything takes a while. See +the [undocumented] page for what is not documented in this book.
@@ -81,10 +80,10 @@ information. These conventions are documented here. An *example term* is an example of a term beind defined. * 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**. + useful, but mostly out of scope, information are in blockquotes that start + with the word "Note:" in **bold**. - > Note: This is an example note. + > **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. @@ -108,7 +107,7 @@ information. These conventions are documented here. ``` * The grammar and lexical structure is in blockquotes with either "Lexer" or - "Syntax" in **bold** as the first line in superscript. + "Syntax" in **bold** superscript as the first line. > **Syntax**\ > _ExampleGrammar_:\ @@ -138,4 +137,5 @@ attention to making those sections the best that they can be. [expressions chapter]: expressions.html [lifetime of temporaries]: expressions.html#temporary-lifetimes [linkage]: linkage.html -[rustc book]: ../rustc/index.html \ No newline at end of file +[rustc book]: ../rustc/index.html +[undocumented]: undocumeted.html \ No newline at end of file From 6c13d8e495ff134a4ecc9be29a8212c4dd9e4630 Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Sat, 1 Sep 2018 23:41:31 -0700 Subject: [PATCH 7/8] Bold the word superscript too --- src/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/introduction.md b/src/introduction.md index 1fc723db8..7c8f4b3f2 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -107,7 +107,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. + "Syntax" in **bold superscript** as the first line. > **Syntax**\ > _ExampleGrammar_:\ From 99134b2538924d6cdb9974472aa0050b88ef2a4a Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Wed, 5 Sep 2018 13:38:08 -0700 Subject: [PATCH 8/8] Typo: book the => document the --- src/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/introduction.md b/src/introduction.md index 7c8f4b3f2..6a940b2ac 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -30,7 +30,7 @@ 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 book the specifics of `rustc` as a +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.