From 34356b87a03ec070fd5c6b7732a73adb3ca424c0 Mon Sep 17 00:00:00 2001 From: Matt Ickstadt Date: Thu, 6 Sep 2018 10:24:42 -0500 Subject: [PATCH 1/2] Document dest-dir relative path behavior --- book-example/src/cli/build.md | 5 +++-- book-example/src/cli/clean.md | 6 +++--- book-example/src/cli/serve.md | 5 +++-- book-example/src/cli/test.md | 5 +++-- book-example/src/cli/watch.md | 5 +++-- src/cmd/build.rs | 3 ++- src/cmd/clean.rs | 4 +++- src/cmd/serve.rs | 3 ++- src/cmd/test.rs | 3 ++- src/cmd/watch.rs | 3 ++- 10 files changed, 26 insertions(+), 16 deletions(-) diff --git a/book-example/src/cli/build.md b/book-example/src/cli/build.md index fd584e18..5d218b66 100644 --- a/book-example/src/cli/build.md +++ b/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 -in `book.toml`, or to `./book` relative to the book's root directory. +book. Relative paths are interpreted relative to the book's root directory. If +not specified it will default to the value of the `build.build-dir` key in +`book.toml`, or to `./book`. ------------------- diff --git a/book-example/src/cli/clean.md b/book-example/src/cli/clean.md index 7482e0d5..23efc450 100644 --- a/book-example/src/cli/clean.md +++ b/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 -default to the value of the `build.build-dir` key in `book.toml`, or to `./book` -relative to the book's root directory. +directory, which will be deleted by this command. Relative paths are interpreted +relative to the book's root directory. If not specified it will default to the +value of the `build.build-dir` key in `book.toml`, or to `./book`. ```bash mdbook clean --dest-dir=path/to/book diff --git a/book-example/src/cli/serve.md b/book-example/src/cli/serve.md index cfc3beec..96c7443a 100644 --- a/book-example/src/cli/serve.md +++ b/book-example/src/cli/serve.md @@ -40,8 +40,9 @@ 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 -in `book.toml`, or to `./book` relative to the book's root directory. +book. Relative paths are interpreted relative to the book's root directory. If +not specified it will default to the value of the `build.build-dir` key in +`book.toml`, or to `./book`. ----- diff --git a/book-example/src/cli/test.md b/book-example/src/cli/test.md index b558d6b4..c13e8809 100644 --- a/book-example/src/cli/test.md +++ b/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 -in `book.toml`, or to `./book` relative to the book's root directory. +book. Relative paths are interpreted relative to the book's root directory. If +not specified it will default to the value of the `build.build-dir` key in +`book.toml`, or to `./book`. diff --git a/book-example/src/cli/watch.md b/book-example/src/cli/watch.md index 33cfcd7e..68dcd562 100644 --- a/book-example/src/cli/watch.md +++ b/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 -in `book.toml`, or to `./book` relative to the book's root directory. +book. Relative paths are interpreted relative to the book's root directory. If +not specified it will default to the value of the `build.build-dir` key in +`book.toml`, or to `./book`. diff --git a/src/cmd/build.rs b/src/cmd/build.rs index f4c0cecd..4a5abbc0 100644 --- a/src/cmd/build.rs +++ b/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)'", diff --git a/src/cmd/clean.rs b/src/cmd/clean.rs index 09c8d912..fba49be8 100644 --- a/src/cmd/clean.rs +++ b/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)'", diff --git a/src/cmd/serve.rs b/src/cmd/serve.rs index aefd21ed..ba89c587 100644 --- a/src/cmd/serve.rs +++ b/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}\ diff --git a/src/cmd/test.rs b/src/cmd/test.rs index e215f028..63e1910d 100644 --- a/src/cmd/test.rs +++ b/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}\ diff --git a/src/cmd/watch.rs b/src/cmd/watch.rs index 1aaa633c..d800ae7d 100644 --- a/src/cmd/watch.rs +++ b/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)'", From a9f3be6f44af48b491a0df6883743f9d785ccfe6 Mon Sep 17 00:00:00 2001 From: Matt Ickstadt Date: Thu, 6 Sep 2018 10:24:56 -0500 Subject: [PATCH 2/2] Make serve command note more prominent --- book-example/src/cli/serve.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/book-example/src/cli/serve.md b/book-example/src/cli/serve.md index 96c7443a..40fae4dd 100644 --- a/book-example/src/cli/serve.md +++ b/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 @@ -43,8 +46,3 @@ The `--dest-dir` (`-d`) option allows you to change the output directory for the book. Relative paths are interpreted relative to the book's root directory. If 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.*