From 4247a30bdd73ee3f1c9fa58a4130380a2e47f6ad Mon Sep 17 00:00:00 2001 From: Huon Wilson Date: Fri, 9 Jan 2015 19:47:09 +1100 Subject: [PATCH 1/4] Add stub deprecation files for each of the old guides. There are hundreds of stackoverflow answers, reddit posts and blog articles that link to these documents, so it's a nicer user experience if they're not plain 404s. The intention is to let these hang around only for relatively short while. The alpha is likely to bring in many new users and they will be reading the documents mentioned above. --- mk/docs.mk | 6 ++++++ src/doc/guide-crates.md | 4 ++++ src/doc/guide-error-handling.md | 4 ++++ src/doc/guide-ffi.md | 4 ++++ src/doc/guide-macros.md | 4 ++++ src/doc/guide-ownership.md | 4 ++++ src/doc/guide-plugins.md | 4 ++++ src/doc/guide-pointers.md | 4 ++++ src/doc/guide-strings.md | 4 ++++ src/doc/guide-tasks.md | 4 ++++ src/doc/guide-testing.md | 4 ++++ src/doc/guide-unsafe.md | 4 ++++ src/doc/guide.md | 4 ++++ 13 files changed, 54 insertions(+) create mode 100644 src/doc/guide-crates.md create mode 100644 src/doc/guide-error-handling.md create mode 100644 src/doc/guide-ffi.md create mode 100644 src/doc/guide-macros.md create mode 100644 src/doc/guide-ownership.md create mode 100644 src/doc/guide-plugins.md create mode 100644 src/doc/guide-pointers.md create mode 100644 src/doc/guide-strings.md create mode 100644 src/doc/guide-tasks.md create mode 100644 src/doc/guide-testing.md create mode 100644 src/doc/guide-unsafe.md create mode 100644 src/doc/guide.md diff --git a/mk/docs.mk b/mk/docs.mk index 1104c3eb6db..3f8b677185f 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -29,6 +29,12 @@ DOCS := index intro tutorial complement-bugreport \ complement-lang-faq complement-design-faq complement-project-faq \ rustdoc reference +# Legacy guides, preserved for a while to reduce the number of 404s +DOCS += guide-crates guide-error-handling guide-ffi guide-macros guide \ + guide-ownership guide-plugins guide-pointers guide-strings guide-tasks \ + guide-testing + + PDF_DOCS := reference RUSTDOC_DEPS_reference := doc/full-toc.inc diff --git a/src/doc/guide-crates.md b/src/doc/guide-crates.md new file mode 100644 index 00000000000..8277988b7fe --- /dev/null +++ b/src/doc/guide-crates.md @@ -0,0 +1,4 @@ +% The (old) Rust Crates and Modules Guide + +This content has moved into the +[the Rust Programming Language book](book/crates-and-modules.html). diff --git a/src/doc/guide-error-handling.md b/src/doc/guide-error-handling.md new file mode 100644 index 00000000000..215fe6a441e --- /dev/null +++ b/src/doc/guide-error-handling.md @@ -0,0 +1,4 @@ +% Error Handling in Rust + +This content has moved into the +[the Rust Programming Language book](book/error-handling.html). diff --git a/src/doc/guide-ffi.md b/src/doc/guide-ffi.md new file mode 100644 index 00000000000..4c818cacbfa --- /dev/null +++ b/src/doc/guide-ffi.md @@ -0,0 +1,4 @@ +% The (old) Rust Foreign Function Interface Guide + +This content has moved into the +[the Rust Programming Language book](book/ffi.html). diff --git a/src/doc/guide-macros.md b/src/doc/guide-macros.md new file mode 100644 index 00000000000..534ae3504c3 --- /dev/null +++ b/src/doc/guide-macros.md @@ -0,0 +1,4 @@ +% The (old) Rust Macros Guide + +This content has moved into the +[the Rust Programming Language book](book/macros.html). diff --git a/src/doc/guide-ownership.md b/src/doc/guide-ownership.md new file mode 100644 index 00000000000..26e059aeb26 --- /dev/null +++ b/src/doc/guide-ownership.md @@ -0,0 +1,4 @@ +% The (old) Rust Ownership Guide + +This content has moved into the +[the Rust Programming Language book](book/ownership.html). diff --git a/src/doc/guide-plugins.md b/src/doc/guide-plugins.md new file mode 100644 index 00000000000..abfe7a44703 --- /dev/null +++ b/src/doc/guide-plugins.md @@ -0,0 +1,4 @@ +% The (old) Rust Compiler Plugins Guide + +This content has moved into the +[the Rust Programming Language book](book/plugins.html). diff --git a/src/doc/guide-pointers.md b/src/doc/guide-pointers.md new file mode 100644 index 00000000000..e72eaf62720 --- /dev/null +++ b/src/doc/guide-pointers.md @@ -0,0 +1,4 @@ +% The (old) Rust Pointer Guide + +This content has moved into the +[the Rust Programming Language book](book/pointers.html). diff --git a/src/doc/guide-strings.md b/src/doc/guide-strings.md new file mode 100644 index 00000000000..fd1420024c6 --- /dev/null +++ b/src/doc/guide-strings.md @@ -0,0 +1,4 @@ +% The (old) Guide to Rust Strings + +This content has moved into the +[the Rust Programming Language book](book/strings.html). diff --git a/src/doc/guide-tasks.md b/src/doc/guide-tasks.md new file mode 100644 index 00000000000..be8cb670986 --- /dev/null +++ b/src/doc/guide-tasks.md @@ -0,0 +1,4 @@ +% The (old) Rust Threads and Communication Guide + +This content has moved into the +[the Rust Programming Language book](book/tasks.html). diff --git a/src/doc/guide-testing.md b/src/doc/guide-testing.md new file mode 100644 index 00000000000..79721300d94 --- /dev/null +++ b/src/doc/guide-testing.md @@ -0,0 +1,4 @@ +% The (old) Rust Testing Guide + +This content has moved into the +[the Rust Programming Language book](book/testing.html). diff --git a/src/doc/guide-unsafe.md b/src/doc/guide-unsafe.md new file mode 100644 index 00000000000..fe8fcc4c19d --- /dev/null +++ b/src/doc/guide-unsafe.md @@ -0,0 +1,4 @@ +% Writing Safe Low-level and Unsafe Code in Rust + +This content has moved into the +[the Rust Programming Language book](book/unsafe.html). diff --git a/src/doc/guide.md b/src/doc/guide.md new file mode 100644 index 00000000000..ba1e2590e7f --- /dev/null +++ b/src/doc/guide.md @@ -0,0 +1,4 @@ +% The (old) Rust Guide + +This content has moved into the +[the Rust Programming Language book](book/README.html). From 80fb5ca8744d220b7f86ed05d9cdbecc454f9970 Mon Sep 17 00:00:00 2001 From: Huon Wilson Date: Fri, 9 Jan 2015 20:25:45 +1100 Subject: [PATCH 2/4] Handle errors properly in rustbook. Silently ignoring errors is :( so lets not silently ignore them. huon is :) now. --- src/rustbook/book.rs | 7 ++++--- src/rustbook/build.rs | 27 +++++++++------------------ src/rustbook/error.rs | 1 + src/rustbook/main.rs | 7 ++++++- 4 files changed, 20 insertions(+), 22 deletions(-) diff --git a/src/rustbook/book.rs b/src/rustbook/book.rs index 1d16de2a2fe..20346449fd1 100644 --- a/src/rustbook/book.rs +++ b/src/rustbook/book.rs @@ -124,7 +124,7 @@ pub fn parse_summary(input: R, src: &Path) -> Result p, None => { - errors.push(format!("Paths in SUMMARY.md must be relative, \ + errors.push(format!("paths in SUMMARY.md must be relative, \ but path '{}' for section '{}' is not.", given_path.unwrap(), title)); Path::new("") @@ -148,8 +148,9 @@ pub fn parse_summary(input: R, src: &Path) -> Result stack.len() + 1 { - // FIXME: better error message - errors.push(format!("Section '{}' is indented too many levels.", item.title)); + errors.push(format!("section '{}' is indented too deeply; \ + found {}, expected {} or less", + item.title, level, stack.len() + 1)); } else if level <= stack.len() { collapse(&mut stack, &mut top_items, level); } diff --git a/src/rustbook/build.rs b/src/rustbook/build.rs index 1cb5e38e190..44b1630d9fb 100644 --- a/src/rustbook/build.rs +++ b/src/rustbook/build.rs @@ -73,10 +73,7 @@ fn write_toc(book: &Book, path_to_root: &Path, out: &mut Writer) -> IoResult<()> } fn render(book: &Book, tgt: &Path) -> CliResult<()> { - let tmp = TempDir::new("rust-book") - .ok() - // FIXME: lift to Result instead - .expect("could not create temporary directory"); + let tmp = try!(TempDir::new("rust-book")); for (section, item) in book.iter() { println!("{} {}", section, item.title); @@ -163,30 +160,24 @@ impl Subcommand for Build { tgt = Path::new(os::args()[3].clone()); } - let _ = fs::mkdir(&tgt, io::USER_DIR); // FIXME: handle errors + try!(fs::mkdir(&tgt, io::USER_DIR)); - // FIXME: handle errors - let _ = File::create(&tgt.join("rust-book.css")).write_str(css::STYLE); + try!(File::create(&tgt.join("rust-book.css")).write_str(css::STYLE)); - let summary = File::open(&src.join("SUMMARY.md")); + let summary = try!(File::open(&src.join("SUMMARY.md"))); match book::parse_summary(summary, &src) { Ok(book) => { // execute rustdoc on the whole book - try!(render(&book, &tgt).map_err(|err| { - term.err(&format!("error: {}", err.description())[]); - err.detail().map(|detail| { - term.err(&format!("detail: {}", detail)[]); - }); - err - })) + render(&book, &tgt) } Err(errors) => { + let n = errors.len(); for err in errors.into_iter() { - term.err(&err[]); + term.err(&format!("error: {}", err)[]); } + + Err(box format!("{} errors occurred", n) as Box) } } - - Ok(()) // lol } } diff --git a/src/rustbook/error.rs b/src/rustbook/error.rs index a5915ed4d73..7d5e7efcc94 100644 --- a/src/rustbook/error.rs +++ b/src/rustbook/error.rs @@ -79,4 +79,5 @@ impl Error for IoError { } } + //fn iter_map_err>>(iter: I, diff --git a/src/rustbook/main.rs b/src/rustbook/main.rs index acb4edb7a45..48dad14321a 100644 --- a/src/rustbook/main.rs +++ b/src/rustbook/main.rs @@ -54,7 +54,12 @@ fn main() { Ok(_) => { match subcmd.execute(&mut term) { Ok(_) => (), - Err(_) => os::set_exit_status(-1), + Err(err) => { + term.err(&format!("error: {}", err.description())[]); + err.detail().map(|detail| { + term.err(&format!("detail: {}", detail)[]); + }); + } } } Err(err) => { From 6fc0ac5ee3611a094e9462d9b54468bf1d59fa21 Mon Sep 17 00:00:00 2001 From: Huon Wilson Date: Fri, 9 Jan 2015 20:26:31 +1100 Subject: [PATCH 3/4] Ensure that the book is built after the doc/ directory. Without this, rustbook was failing because it was expecting the directory to exist. (Previously, rustbook was just silently failing to install the CSS files due to this.) --- mk/docs.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mk/docs.mk b/mk/docs.mk index 3f8b677185f..8af47700f25 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -283,6 +283,6 @@ compiler-docs: $(COMPILER_DOC_TARGETS) trpl: doc/book/index.html -doc/book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/trpl/*.md) +doc/book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/trpl/*.md) | doc/ $(Q)rm -rf doc/book $(Q)$(RUSTBOOK) build $(S)src/doc/trpl doc/book From afe260ff4b9968300a4c64a4fd1ce903ddec0619 Mon Sep 17 00:00:00 2001 From: Huon Wilson Date: Sat, 10 Jan 2015 00:54:18 +1100 Subject: [PATCH 4/4] rustbook: use a relative @import path to ensure it works offline. The URL previously caused the book to require an internet connection to get the full styling, this should mean no internet is required. --- src/rustbook/css.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/rustbook/css.rs b/src/rustbook/css.rs index 8eb66e71d3a..92433589155 100644 --- a/src/rustbook/css.rs +++ b/src/rustbook/css.rs @@ -11,7 +11,7 @@ // The rust-book CSS in string form. pub static STYLE: &'static str = r#" -@import url("//static.rust-lang.org/doc/master/rust.css"); +@import url("../rust.css"); body { max-width:none;