Merge pull request #782 from mattico/document-dest-dir-rel

Document dest-dir relative path behavior

book-example/src/cli/build.md

@@ -29,8 +29,9 @@ your default web browser after building it.
 #### --dest-dir
 
 The `--dest-dir` (`-d`) option allows you to change the output directory for the
-book. If not specified it will default to the value of the `build.build-dir` key
+book. Relative paths are interpreted relative to the book's root directory. If
-in `book.toml`, or to `./book` relative to the book's root directory.
+not specified it will default to the value of the `build.build-dir` key in
+`book.toml`, or to `./book`.
 
 -------------------
 

book-example/src/cli/clean.md

@@ -19,9 +19,9 @@ mdbook clean path/to/book
 #### --dest-dir
 
 The `--dest-dir` (`-d`) option allows you to override the book's output
-directory, which will be deleted by this command. If not specified it will
+directory, which will be deleted by this command. Relative paths are interpreted
-default to the value of the `build.build-dir` key in `book.toml`, or to `./book`
+relative to the book's root directory. If not specified it will default to the
-relative to the book's root directory.
+value of the `build.build-dir` key in `book.toml`, or to `./book`.
 
 ```bash
 mdbook clean --dest-dir=path/to/book

book-example/src/cli/serve.md

@@ -5,6 +5,9 @@ The serve command is used to preview a book by serving it over HTTP at
 changes, rebuilding the book and refreshing clients for each change. A websocket
 connection is used to trigger the client-side refresh.
 
+***Note:*** *The `serve` command is for testing a book's HTML output, and is not
+intended to be a complete HTTP server for a website.*
+
 #### Specify a directory
 
 The `serve` command can take a directory as an argument to use as the book's
@@ -40,10 +43,6 @@ default web browser after starting the server.
 #### --dest-dir
 
 The `--dest-dir` (`-d`) option allows you to change the output directory for the
-book. If not specified it will default to the value of the `build.build-dir` key
+book. Relative paths are interpreted relative to the book's root directory. If
-in `book.toml`, or to `./book` relative to the book's root directory.
+not specified it will default to the value of the `build.build-dir` key in
-
+`book.toml`, or to `./book`.
------
-
-***Note:*** *The `serve` command is for testing, and is not intended to be a
-complete HTTP server for a website.*

book-example/src/cli/test.md

@@ -48,5 +48,6 @@ comma-delimited list (`-L foo,bar`).
 #### --dest-dir
 
 The `--dest-dir` (`-d`) option allows you to change the output directory for the
-book. If not specified it will default to the value of the `build.build-dir` key
+book. Relative paths are interpreted relative to the book's root directory. If
-in `book.toml`, or to `./book` relative to the book's root directory.
+not specified it will default to the value of the `build.build-dir` key in
+`book.toml`, or to `./book`.

book-example/src/cli/watch.md

@@ -22,5 +22,6 @@ your default web browser.
 #### --dest-dir
 
 The `--dest-dir` (`-d`) option allows you to change the output directory for the
-book. If not specified it will default to the value of the `build.build-dir` key
+book. Relative paths are interpreted relative to the book's root directory. If
-in `book.toml`, or to `./book` relative to the book's root directory.
+not specified it will default to the value of the `build.build-dir` key in
+`book.toml`, or to `./book`.

src/cmd/build.rs

@@ -9,7 +9,8 @@ pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> {
         .about("Builds a book from its markdown files")
         .arg_from_usage(
             "-d, --dest-dir=[dest-dir] 'Output directory for the book{n}\
-             (If omitted, uses build.build-dir from book.toml or defaults to ./book)'",
+             Relative paths are interpreted relative to the book's root directory.{n}\
+             If omitted, mdBook uses build.build-dir from book.toml or defaults to `./book`.'",
         ).arg_from_usage(
             "[dir] 'Root directory for the book{n}\
              (Defaults to the Current Directory when omitted)'",

src/cmd/clean.rs

@@ -10,7 +10,9 @@ pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> {
         .about("Deletes a built book")
         .arg_from_usage(
             "-d, --dest-dir=[dest-dir] 'Output directory for the book{n}\
-             (If omitted, uses build.build-dir from book.toml or defaults to ./book)'",
+             Relative paths are interpreted relative to the book's root directory.{n}\
+             Running this command deletes this directory.{n}\
+             If omitted, mdBook uses build.build-dir from book.toml or defaults to `./book`.'",
         ).arg_from_usage(
             "[dir] 'Root directory for the book{n}\
              (Defaults to the Current Directory when omitted)'",

src/cmd/serve.rs

@@ -22,7 +22,8 @@ pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> {
         .about("Serves a book at http://localhost:3000, and rebuilds it on changes")
         .arg_from_usage(
             "-d, --dest-dir=[dest-dir] 'Output directory for the book{n}\
-             (If omitted, uses build.build-dir from book.toml or defaults to ./book)'",
+             Relative paths are interpreted relative to the book's root directory.{n}\
+             If omitted, mdBook uses build.build-dir from book.toml or defaults to `./book`.'",
         )
         .arg_from_usage(
             "[dir] 'Root directory for the book{n}\

src/cmd/test.rs

@@ -9,7 +9,8 @@ pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> {
         .about("Tests that a book's Rust code samples compile")
         .arg_from_usage(
             "-d, --dest-dir=[dest-dir] 'Output directory for the book{n}\
-             (If omitted, uses build.build-dir from book.toml or defaults to ./book)'",
+             Relative paths are interpreted relative to the book's root directory.{n}\
+             If omitted, mdBook uses build.build-dir from book.toml or defaults to `./book`.'",
         )
         .arg_from_usage(
             "[dir] 'Root directory for the book{n}\

src/cmd/watch.rs

@@ -16,7 +16,8 @@ pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> {
         .about("Watches a book's files and rebuilds it on changes")
         .arg_from_usage(
             "-d, --dest-dir=[dest-dir] 'Output directory for the book{n}\
-             (If omitted, uses build.build-dir from book.toml or defaults to ./book)'",
+             Relative paths are interpreted relative to the book's root directory.{n}\
+             If omitted, mdBook uses build.build-dir from book.toml or defaults to `./book`.'",
         ).arg_from_usage(
             "[dir] 'Root directory for the book{n}\
              (Defaults to the Current Directory when omitted)'",