src/doc/reference/src/introduction.md

   1 # Introduction
   2
   3 This book is the primary reference for the Rust programming language. It
   4 provides three kinds of material:
   5
   6   - Chapters that informally describe each language construct and their use.
   7   - Chapters that informally describe the memory model, concurrency model,
   8     runtime services, linkage model, and debugging facilities.
   9   - Appendix chapters providing rationale and references to languages that
  10     influenced the design.
  11
  12 <div class="warning">
  13
  14 Warning: This book is incomplete. Documenting everything takes a while. See
  15 the [GitHub issues] for what is not documented in this book.
  16
  17 </div>
  18
  19 ## What *The Reference* is Not
  20
  21 This book does not serve as an introduction to the language. Background
  22 familiarity with the language is assumed. A separate [book] is available to
  23 help acquire such background familiarity.
  24
  25 This book also does not serve as a reference to the [standard library]
  26 included in the language distribution. Those libraries are documented
  27 separately by extracting documentation attributes from their source code. Many
  28 of the features that one might expect to be language features are library
  29 features in Rust, so what you're looking for may be there, not here.
  30
  31 Similarly, this book does not usually document the specifics of `rustc` as a
  32 tool or of Cargo. `rustc` has its own [book][rustc book]. Cargo has a
  33 [book][cargo book] that contains a [reference][cargo reference]. There are a few
  34 pages such as [linkage] that still describe how `rustc` works.
  35
  36 This book also only serves as a reference to what is available in stable
  37 Rust. For unstable features being worked on, see the [Unstable Book].
  38
  39 Finally, this book is not normative. It may include details that are
  40 specific to `rustc` itself, and should not be taken as a specification for
  41 the Rust language. We intend to produce such a book someday, and until then,
  42 the reference is the closest thing we have to one.
  43
  44 ## How to Use This Book
  45
  46 This book does not assume you are reading this book sequentially. Each
  47 chapter generally can be read standalone, but will cross-link to other chapters
  48 for facets of the language they refer to, but do not discuss.
  49
  50 There are two main ways to read this document.
  51
  52 The first is to answer a specific question. If you know which chapter answers
  53 that question, you can jump to that chapter in the table of contents. Otherwise,
  54 you can press `s` or the click the magnifying glass on the top bar to search for
  55 keywords related to your question. For example, say you wanted to know when a
  56 temporary value created in a let statement is dropped. If you didn't already
  57 know that the [lifetime of temporaries] is defined in the [expressions chapter],
  58 you could search "temporary let" and the first search result will take you to
  59 that section.
  60
  61 The second is to generally improve your knowledge of a facet of the language.
  62 In that case, just browse the table of contents until you see something you
  63 want to know more about, and just start reading. If a link looks interesting,
  64 click it, and read about that section.
  65
  66 That said, there is no wrong way to read this book. Read it however you feel
  67 helps you best.
  68
  69 ### Conventions
  70
  71 Like all technical books, this book has certain conventions in how it displays
  72 information. These conventions are documented here.
  73
  74 * Statements that define a term contain that term in *italics*. Whenever that
  75   term is used outside of that chapter, it is usually a link to the section that
  76   has this definition.
  77
  78   An *example term* is an example of a term being defined.
  79
  80 * Differences in the language by which edition the crate is compiled under are
  81   in a blockquote that start with the words "Edition Differences:" in **bold**.
  82
  83   > **Edition Differences**: In the 2015 edition, this syntax is valid that is
  84   > disallowed as of the 2018 edition.
  85
  86 * Notes that contain useful information about the state of the book or point out
  87   useful, but mostly out of scope, information are in blockquotes that start
  88   with the word "Note:" in **bold**.
  89
  90   > **Note**: This is an example note.
  91
  92 * Warnings that show unsound behavior in the language or possibly confusing
  93   interactions of language features are in a special warning box.
  94
  95   <div class="warning">
  96
  97   Warning: This is an example warning.
  98
  99   </div>
 100
 101 * Code snippets inline in the text are inside `<code>` tags.
 102
 103   Longer code examples are in a syntax highlighted box that has controls for
 104   copying, executing, and showing hidden lines in the top right corner.
 105
 106   ```rust
 107   # // This is a hidden line.
 108   fn main() {
 109       println!("This is a code example");
 110   }
 111   ```
 112
 113 * The grammar and lexical structure is in blockquotes with either "Lexer" or
 114   "Syntax" in <sup>**bold superscript**</sup> as the first line.
 115
 116   > **<sup>Syntax</sup>**\
 117   > _ExampleGrammar_:\
 118   > &nbsp;&nbsp; &nbsp;&nbsp; `~` [_Expression_]\
 119   > &nbsp;&nbsp; | `box` [_Expression_]
 120
 121   See [Notation] for more detail.
 122
 123 ## Contributing
 124
 125 We welcome contributions of all kinds.
 126
 127 You can contribute to this book by opening an issue or sending a pull
 128 request to [the Rust Reference repository]. If this book does not answer
 129 your question, and you think its answer is in scope of it, please do not
 130 hesitate to file an issue or ask about it in the `#docs` channels on
 131 [Discord]. Knowing what people use this book for the most helps direct our
 132 attention to making those sections the best that they can be.
 133
 134 [book]: ../book/index.html
 135 [github issues]: https://github.com/rust-lang/reference/issues
 136 [standard library]: ../std/index.html
 137 [the Rust Reference repository]: https://github.com/rust-lang/reference/
 138 [Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/
 139 [_Expression_]: expressions.md
 140 [cargo book]: ../cargo/index.html
 141 [cargo reference]: ../cargo/reference/index.html
 142 [expressions chapter]: expressions.md
 143 [lifetime of temporaries]: expressions.md#temporary-lifetimes
 144 [linkage]: linkage.md
 145 [rustc book]: ../rustc/index.html
 146 [Notation]: notation.md
 147 [Discord]: https://discord.gg/rust-lang