src/doc/book/README.md

   1 # The Rust Programming Language
   2
   3 [![Build Status](https://travis-ci.org/rust-lang/book.svg?branch=master)](https://travis-ci.org/rust-lang/book)
   4
   5 This repository contains the source of all editions of "the Rust Programming
   6 Language".
   7
   8 The second edition will also be available in dead-tree form by No Starch
   9 Press, available around May 2018. Check [the No Starch Page][nostarch] for
  10 the latest information on the release date and how to order.
  11
  12 [nostarch]: https://nostarch.com/rust
  13
  14 You can read all editions of the book for free online! Please see the book as
  15 shipped with the latest [stable], [beta], or [nightly] Rust releases. Be
  16 aware that issues in those versions may have been fixed in this repository
  17 already, as those releases are updated less frequently.
  18
  19 [stable]: https://doc.rust-lang.org/stable/book/
  20 [beta]: https://doc.rust-lang.org/beta/book/
  21 [nightly]: https://doc.rust-lang.org/nightly/book/
  22
  23 ## Requirements
  24
  25 Building the book requires [mdBook], ideally the same version that
  26 [rust-lang/rust uses in this file][rust-mdbook]. To get it:
  27
  28 [mdBook]: https://github.com/azerupi/mdBook
  29 [rust-mdbook]: https://github.com/rust-lang/rust/blob/master/src/tools/rustbook/Cargo.toml
  30
  31 ```bash
  32 $ cargo install mdbook --vers [version-num]
  33 ```
  34
  35 ## Building
  36
  37 To build the book, first `cd` into one of the directory of the edition of the
  38 book you'd like to build. For example, the `first-edition` or
  39 `second-edition` directory. Then type:
  40
  41 ```bash
  42 $ mdbook build
  43 ```
  44
  45 The output will be in the `book` subdirectory. To check it out, open it in
  46 your web browser.
  47
  48 _Firefox:_
  49 ```bash
  50 $ firefox book/index.html                       # Linux
  51 $ open -a "Firefox" book/index.html             # OS X
  52 $ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
  53 $ start firefox.exe .\book\index.html           # Windows (Cmd)
  54 ```
  55
  56 _Chrome:_
  57 ```bash
  58 $ google-chrome book/index.html                 # Linux
  59 $ open -a "Google Chrome" book/index.html       # OS X
  60 $ Start-Process "chrome.exe" .\book\index.html  # Windows (PowerShell)
  61 $ start chrome.exe .\book\index.html            # Windows (Cmd)
  62 ```
  63
  64 To run the tests:
  65
  66 ```bash
  67 $ mdbook test
  68 ```
  69
  70 ## Contributing
  71
  72 We'd love your help! Please see [CONTRIBUTING.md][contrib] to learn about the
  73 kinds of contributions we're looking for.
  74
  75 ### Second Edition
  76
  77 The second edition of The Rust Programming Language is getting ever closer to being printed!
  78
  79 ### First Edition
  80
  81 The first edition is frozen, and is not accepting any changes at this time.
  82
  83
  84 [contrib]: https://github.com/rust-lang/book/blob/master/CONTRIBUTING.md
  85
  86 ### Translations
  87
  88 We'd especially love help translating the second edition of the book! See the
  89 [Translations] label to join in efforts that are currently in progress. Open
  90 a new issue to start working on a new language! We're waiting on [mdbook
  91 support] for multiple languages before we merge any in, but feel free to
  92 start! The chapters in [the frozen column] of the project won't see major
  93 changes, so if you start with those, you won't have to redo work :)
  94
  95 [Translations]: https://github.com/rust-lang/book/issues?q=is%3Aopen+is%3Aissue+label%3ATranslations
  96 [mdbook support]: https://github.com/azerupi/mdBook/issues/5
  97 [the frozen column]: https://github.com/rust-lang/book/projects/1
  98
  99 ## No Starch
 100
 101 As the second edition of the book will be published by No Starch, we first
 102 iterate here, then ship the text off to No Starch. Then they do editing, and we
 103 fold it back in.
 104
 105 As such, there’s a directory, *nostarch*, which corresponds to the text in No
 106 Starch’s system.
 107
 108 When we've started working with No Starch in a word doc, we will also check
 109 those into the repo in the *nostarch/odt* directory. To extract the text from
 110 the word doc as markdown in order to backport changes to the online book:
 111
 112 1. Open the doc file in LibreOffice
 113 1. Accept all tracked changes
 114 1. Save as Microsoft Word 2007-2013 XML (.docx) in the *tmp* directory
 115 1. Run `./doc-to-md.sh`
 116 1. Inspect changes made to the markdown file in the *nostarch* directory and
 117    copy the changes to the *src* directory as appropriate.
 118
 119 ## Graphviz dot
 120
 121 We're using [Graphviz](http://graphviz.org/) for some of the diagrams in the
 122 book. The source for those files live in the `dot` directory. To turn a `dot`
 123 file, for example, `dot/trpl04-01.dot` into an `svg`, run:
 124
 125 ```bash
 126 $ dot dot/trpl04-01.dot -Tsvg > src/img/trpl04-01.svg
 127 ```
 128
 129 In the generated SVG, remove the width and the height attributes from the `svg`
 130 element and set the `viewBox` attribute to `0.00 0.00 1000.00 1000.00` or other
 131 values that don't cut off the image.
 132
 133 ## Spellchecking
 134
 135 To scan source files for spelling errors, you can use the `spellcheck.sh`
 136 script. It needs a dictionary of valid words, which is provided in
 137 `dictionary.txt`. If the script produces a false positive (say, you used word
 138 `BTreeMap` which the script considers invalid), you need to add this word to
 139 `dictionary.txt` (keep the sorted order for consistency).