src/doc/book/README.md

   1 # The Rust Programming Language
   2
   3 [![Build Status](https://travis-ci.com/rust-lang/book.svg?branch=master)](https://travis-ci.com/rust-lang/book)
   4
   5 This repository contains the source of "The Rust Programming Language" book.
   6
   7 [The book is available in dead-tree form from No Starch Press][nostarch]
   8
   9 [nostarch]: https://nostarch.com/rust
  10
  11 You can also read the book for free online. Please see the book as shipped with
  12 the latest [stable], [beta], or [nightly] Rust releases. Be aware that issues
  13 in those versions may have been fixed in this repository already, as those
  14 releases are updated less frequently.
  15
  16 [stable]: https://doc.rust-lang.org/stable/book/
  17 [beta]: https://doc.rust-lang.org/beta/book/
  18 [nightly]: https://doc.rust-lang.org/nightly/book/
  19
  20 ## Requirements
  21
  22 Building the book requires [mdBook], ideally the same 0.2.x version that
  23 rust-lang/rust uses in [this file][rust-mdbook]. To get it:
  24
  25 [mdBook]: https://github.com/rust-lang-nursery/mdBook
  26 [rust-mdbook]: https://github.com/rust-lang/rust/blob/master/src/tools/rustbook/Cargo.toml
  27
  28 ```bash
  29 $ cargo install mdbook --vers [version-num]
  30 ```
  31
  32 ## Building
  33
  34 To build the book, type:
  35
  36 ```bash
  37 $ mdbook build
  38 ```
  39
  40 The output will be in the `book` subdirectory. To check it out, open it in
  41 your web browser.
  42
  43 _Firefox:_
  44 ```bash
  45 $ firefox book/index.html                       # Linux
  46 $ open -a "Firefox" book/index.html             # OS X
  47 $ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
  48 $ start firefox.exe .\book\index.html           # Windows (Cmd)
  49 ```
  50
  51 _Chrome:_
  52 ```bash
  53 $ google-chrome book/index.html                 # Linux
  54 $ open -a "Google Chrome" book/index.html       # OS X
  55 $ Start-Process "chrome.exe" .\book\index.html  # Windows (PowerShell)
  56 $ start chrome.exe .\book\index.html            # Windows (Cmd)
  57 ```
  58
  59 To run the tests:
  60
  61 ```bash
  62 $ mdbook test
  63 ```
  64
  65 ## Contributing
  66
  67 We'd love your help! Please see [CONTRIBUTING.md][contrib] to learn about the
  68 kinds of contributions we're looking for.
  69
  70 [contrib]: https://github.com/rust-lang/book/blob/master/CONTRIBUTING.md
  71
  72 ### Translations
  73
  74 We'd love help translating the book! See the [Translations] label to join in
  75 efforts that are currently in progress. Open a new issue to start working on
  76 a new language! We're waiting on [mdbook support] for multiple languages
  77 before we merge any in, but feel free to start!
  78
  79 [Translations]: https://github.com/rust-lang/book/issues?q=is%3Aopen+is%3Aissue+label%3ATranslations
  80 [mdbook support]: https://github.com/rust-lang-nursery/mdBook/issues/5
  81
  82 ## Graphviz dot
  83
  84 We're using [Graphviz](http://graphviz.org/) for some of the diagrams in the
  85 book. The source for those files live in the `dot` directory. To turn a `dot`
  86 file, for example, `dot/trpl04-01.dot` into an `svg`, run:
  87
  88 ```bash
  89 $ dot dot/trpl04-01.dot -Tsvg > src/img/trpl04-01.svg
  90 ```
  91
  92 In the generated SVG, remove the width and the height attributes from the `svg`
  93 element and set the `viewBox` attribute to `0.00 0.00 1000.00 1000.00` or other
  94 values that don't cut off the image.
  95
  96 ## Spellchecking
  97
  98 To scan source files for spelling errors, you can use the `spellcheck.sh`
  99 script. It needs a dictionary of valid words, which is provided in
 100 `dictionary.txt`. If the script produces a false positive (say, you used word
 101 `BTreeMap` which the script considers invalid), you need to add this word to
 102 `dictionary.txt` (keep the sorted order for consistency).