src/doc/README.md

   1 # Cargo documentation
   2
   3 This directory contains Cargo's documentation. There are two parts, [The Cargo
   4 Book] which is built with [mdbook] and the man pages, which are built with
   5 [mdman].
   6
   7 [The Cargo Book]: https://doc.rust-lang.org/cargo/
   8 [mdBook]: https://github.com/rust-lang/mdBook
   9 [mdman]: https://github.com/rust-lang/cargo/tree/master/crates/mdman/
  10
  11 ### Building the book
  12
  13 Building the book requires [mdBook]. To get it:
  14
  15 ```console
  16 $ cargo install mdbook
  17 ```
  18
  19 To build the book:
  20
  21 ```console
  22 $ mdbook build
  23 ```
  24
  25 `mdbook` provides a variety of different commands and options to help you work
  26 on the book:
  27
  28 * `mdbook build --open`: Build the book and open it in a web browser.
  29 * `mdbook serve`: Launches a web server on localhost. It also automatically
  30   rebuilds the book whenever any file changes and automatically reloads your
  31   web browser.
  32
  33 The book contents are driven by the [`SUMMARY.md`](src/SUMMARY.md) file, and
  34 every file must be linked there.
  35
  36 ### Building the man pages
  37
  38 The man pages use a tool called [mdman] to convert markdown to a man page
  39 format. Check out the documentation at
  40 [`mdman/doc/`](../../crates/mdman/doc/)
  41 for more details.
  42
  43 The man pages are converted from a templated markdown (located in the
  44 [`src/doc/man/`](man)
  45 directory) to three different formats:
  46
  47 1. Troff-style man pages, saved in [`src/etc/man/`](../etc/man).
  48 2. Markdown (with some HTML) for the Cargo Book, saved in
  49    [`src/doc/src/commands/`](src/commands).
  50 3. Plain text (needed for embedded man pages on platforms without man such as
  51    Windows), saved in [`src/doc/man/generated_txt/`](man/generated_txt).
  52
  53 To rebuild the man pages, run the script `build-man.sh` in the `src/doc` directory.
  54
  55 ```console
  56 $ ./build-man.sh
  57 ```
  58
  59 ## Contributing
  60
  61 We'd love your help with improving the documentation! Please feel free to
  62 [open issues](https://github.com/rust-lang/cargo/issues) about anything, and
  63 send in PRs for things you'd like to fix or change. If your change is large,
  64 please open an issue first, so we can make sure that it's something we'd
  65 accept before you go through the work of getting a PR together.