test691 / book

The Rust Programming Language

NOTICE ABOUT STATUS

The second edition of The Rust Programming Language is getting ever closer to being printed! This means we're not able to make large changes to chapters that are in any column to the right of, and including, the "Frozen" column on our Project board. Issues or pull requests submitted for frozen chapters are welcome but will be closed until we start work on a third edition. Thank you!

The Rust Programming Language

This repo contains two editions of “The Rust Programming Language”.

The second edition is a rewrite that will be printed by NoStarch Press, available around October 2017.

You can read the very latest online; the last few chapters aren't completed yet, but the first half of the book is much improved from the first edition. We recommend starting with the second edition.

Note that links to the standard library won't work in this version; this is intentional so that links work with the book and API docs shipped with Rust installations for offline reading. For a version of the book where these links do work, please see the book as shipped with the latest stable, beta, or nightly Rust releases. Be aware that issues in those versions may have been fixed in this repository already.

The first edition is still available to read online.

Requirements

Building the book requires mdBook, ideally the same version that rust-lang/rust uses in this file. To get it:

$ cargo install mdbook --vers [version-num]

Building

To build the book, first cd into either the first-edition or second-edition directory depending on which edition of the book you would like to build. Then type:

$ mdbook build

The output will be in the book subdirectory. To check it out, open it in your web browser.

Firefox:

$ firefox book/index.html                       # Linux
$ open -a "Firefox" book/index.html             # OS X
$ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
$ start firefox.exe .\book\index.html           # Windows (Cmd)

Chrome:

$ google-chrome book/index.html                 # Linux
$ open -a "Google Chrome" book/index.html       # OS X
$ Start-Process "chrome.exe" .\book\index.html  # Windows (PowerShell)
$ start chrome.exe .\book\index.html            # Windows (Cmd)

To run the tests:

$ mdbook test

Contributing

We'd love your help! Please see CONTRIBUTING.md to learn about the kinds of contributions we're looking for.

Translations

We'd especially love help translating the second edition of the book! See the Translations label to join in efforts that are currently in progress. Open a new issue to start working on a new language! We're waiting on mdbook support for multiple languages before we merge any in, but feel free to start! The chapters in the frozen column of the project won't see major changes, so if you start with those, you won't have to redo work :)

No Starch

As the second edition of the book will be published by No Starch, we first iterate here, then ship the text off to No Starch. Then they do editing, and we fold it back in.

As such, there’s a directory, nostarch, which corresponds to the text in No Starch’s system.

When we've started working with No Starch in a word doc, we will also check those into the repo in the nostarch/odt directory. To extract the text from the word doc as markdown in order to backport changes to the online book:

1. Open the doc file in LibreOffice
2. Accept all tracked changes
3. Save as Microsoft Word 2007-2013 XML (.docx) in the tmp directory
4. Run ./doc-to-md.sh
5. Inspect changes made to the markdown file in the nostarch directory and copy the changes to the src directory as appropriate.

Graphviz dot

This is mostly for Carol's reference because she keeps having to look it up.

We're using Graphviz for some of the diagrams in the book. The source for those files live in the dot directory. To turn a dot file, for example, dot/trpl04-01.dot into an svg, run:

$ dot dot/trpl04-01.dot -Tsvg > src/img/trpl04-01.svg

In the generated SVG, remove the width and the height attributes from the svg element and set the viewBox attribute to 0.00 0.00 1000.00 1000.00 or other values that don't cut off the image.

Spellchecking

To scan source files for spelling errors, you can use the spellcheck.sh script. It needs a dictionary of valid words, which is provided in dictionary.txt. If the script produces a false positive (say, you used word BTreeMap which the script considers invalid), you need to add this word to dictionary.txt (keep the sorted order for consistency).