From eeafee4c9b07c93d45d6a3fa85f92feb31cddbc9 Mon Sep 17 00:00:00 2001 From: Alan Andrade Date: Sat, 21 Dec 2013 17:29:48 -0600 Subject: [PATCH] Convert sub tutorials into Guides #10838 Ensure configure creates doc/guides directory Fix configure makefile and tests Remove old guides dir and configure option, convert testing to guide Remove ignored files Fix submodule issue prepend dir in makefile so that bor knows how to build the docs S to uppercase --- configure | 12 +++--- ...-borrowed-ptr.md => guide-borrowed-ptr.md} | 2 +- ...rial-conditions.md => guide-conditions.md} | 8 ++-- ...torial-container.md => guide-container.md} | 2 +- doc/{tutorial-ffi.md => guide-ffi.md} | 4 +- doc/{tutorial-macros.md => guide-macros.md} | 2 +- doc/{tutorial-rustpkg.md => guide-rustpkg.md} | 6 +-- doc/{tutorial-tasks.md => guide-tasks.md} | 4 +- doc/{tutorial-testing.md => guide-testing.md} | 2 +- doc/tutorial.md | 20 +++++----- mk/docs.mk | 40 +++++++++++-------- mk/tests.mk | 4 +- 12 files changed, 55 insertions(+), 51 deletions(-) rename doc/{tutorial-borrowed-ptr.md => guide-borrowed-ptr.md} (99%) rename doc/{tutorial-conditions.md => guide-conditions.md} (99%) rename doc/{tutorial-container.md => guide-container.md} (99%) rename doc/{tutorial-ffi.md => guide-ffi.md} (99%) rename doc/{tutorial-macros.md => guide-macros.md} (99%) rename doc/{tutorial-rustpkg.md => guide-rustpkg.md} (98%) rename doc/{tutorial-tasks.md => guide-tasks.md} (99%) rename doc/{tutorial-testing.md => guide-testing.md} (99%) diff --git a/configure b/configure index 1e3d8b30e11..89edb69f866 100755 --- a/configure +++ b/configure @@ -792,12 +792,12 @@ do make_dir $h/test/debug-info make_dir $h/test/codegen make_dir $h/test/doc-tutorial - make_dir $h/test/doc-tutorial-ffi - make_dir $h/test/doc-tutorial-macros - make_dir $h/test/doc-tutorial-borrowed-ptr - make_dir $h/test/doc-tutorial-container - make_dir $h/test/doc-tutorial-tasks - make_dir $h/test/doc-tutorial-conditions + make_dir $h/test/doc-guide-ffi + make_dir $h/test/doc-guide-macros + make_dir $h/test/doc-guide-borrowed-ptr + make_dir $h/test/doc-guide-container + make_dir $h/test/doc-guide-tasks + make_dir $h/test/doc-guide-conditions make_dir $h/test/doc-rust done diff --git a/doc/tutorial-borrowed-ptr.md b/doc/guide-borrowed-ptr.md similarity index 99% rename from doc/tutorial-borrowed-ptr.md rename to doc/guide-borrowed-ptr.md index c5933eb40f7..7ad1ee27729 100644 --- a/doc/tutorial-borrowed-ptr.md +++ b/doc/guide-borrowed-ptr.md @@ -1,4 +1,4 @@ -% Rust Borrowed Pointers Tutorial +% Rust Borrowed Pointers Guide # Introduction diff --git a/doc/tutorial-conditions.md b/doc/guide-conditions.md similarity index 99% rename from doc/tutorial-conditions.md rename to doc/guide-conditions.md index 52894c03e3c..5f278888cba 100644 --- a/doc/tutorial-conditions.md +++ b/doc/guide-conditions.md @@ -1,4 +1,4 @@ -% Rust Condition and Error-handling Tutorial +% Rust Condition and Error-handling Guide # Introduction @@ -12,12 +12,12 @@ The four mechanisms are: - Failure - Conditions -This tutorial will lead you through use of these mechanisms +This guide will lead you through use of these mechanisms in order to understand the trade-offs of each and relationships between them. # Example program -This tutorial will be based around an example program +This guide will be based around an example program that attempts to read lines from a file consisting of pairs of numbers, and then print them back out with slightly different formatting. @@ -823,7 +823,7 @@ There are three other things to note in this variant of the example program: # When to use which technique -This tutorial explored several techniques for handling errors. +This guide explored several techniques for handling errors. Each is appropriate to different circumstances: - If an error may be extremely frequent, expected, and very likely dealt with by an immediate caller, diff --git a/doc/tutorial-container.md b/doc/guide-container.md similarity index 99% rename from doc/tutorial-container.md rename to doc/guide-container.md index 65f536fa9f2..90a01603b1c 100644 --- a/doc/tutorial-container.md +++ b/doc/guide-container.md @@ -1,4 +1,4 @@ -% Containers and iterators +% Containers and Iterators Guide # Containers diff --git a/doc/tutorial-ffi.md b/doc/guide-ffi.md similarity index 99% rename from doc/tutorial-ffi.md rename to doc/guide-ffi.md index 39eff68afd1..e8eaf8153ec 100644 --- a/doc/tutorial-ffi.md +++ b/doc/guide-ffi.md @@ -1,8 +1,8 @@ -% Rust Foreign Function Interface Tutorial +% Rust Foreign Function Interface Guide # Introduction -This tutorial will use the [snappy](https://code.google.com/p/snappy/) +This guide will use the [snappy](https://code.google.com/p/snappy/) compression/decompression library as an introduction to writing bindings for foreign code. Rust is currently unable to call directly into a C++ library, but snappy includes a C interface (documented in diff --git a/doc/tutorial-macros.md b/doc/guide-macros.md similarity index 99% rename from doc/tutorial-macros.md rename to doc/guide-macros.md index 0ad8adf3cc7..f4917fdb484 100644 --- a/doc/tutorial-macros.md +++ b/doc/guide-macros.md @@ -1,4 +1,4 @@ -% Rust Macros Tutorial +% Rust Macros Guide # Introduction diff --git a/doc/tutorial-rustpkg.md b/doc/guide-rustpkg.md similarity index 98% rename from doc/tutorial-rustpkg.md rename to doc/guide-rustpkg.md index 1cd3209efea..149f89e7ff6 100644 --- a/doc/tutorial-rustpkg.md +++ b/doc/guide-rustpkg.md @@ -1,9 +1,9 @@ -% Rust Packaging Tutorial +% Rust Packaging Guide # Introduction Sharing is caring. Rust comes with a tool, `rustpkg`, which allows you to -package up your Rust code and share it with other people. This tutorial will +package up your Rust code and share it with other people. This guide will get you started on all of the concepts and commands you need to give the gift of Rust code to someone else. @@ -92,7 +92,7 @@ There are also default file names you'll want to follow as well: Now that you've got workspaces down, let's build your own copy of `hello`. Go to wherever you keep your personal projects, and let's make all of the directories we'll need. I'll refer to this personal project directory as -`~/src` for the rest of this tutorial. +`~/src` for the rest of this guide. ## Creating our workspace diff --git a/doc/tutorial-tasks.md b/doc/guide-tasks.md similarity index 99% rename from doc/tutorial-tasks.md rename to doc/guide-tasks.md index 6213a0cfe1c..45977e48650 100644 --- a/doc/tutorial-tasks.md +++ b/doc/guide-tasks.md @@ -1,10 +1,10 @@ -% Rust Tasks and Communication Tutorial +% Rust Tasks and Communication Guide # Introduction Rust provides safe concurrency through a combination of lightweight, memory-isolated tasks and message passing. -This tutorial will describe the concurrency model in Rust, how it +This guide will describe the concurrency model in Rust, how it relates to the Rust type system, and introduce the fundamental library abstractions for constructing concurrent programs. diff --git a/doc/tutorial-testing.md b/doc/guide-testing.md similarity index 99% rename from doc/tutorial-testing.md rename to doc/guide-testing.md index b09ba605d2c..dce60f1f21d 100644 --- a/doc/tutorial-testing.md +++ b/doc/guide-testing.md @@ -1,4 +1,4 @@ -% Rust Testing Tutorial +% Rust Testing Guide # Quick start diff --git a/doc/tutorial.md b/doc/tutorial.md index 0eb228d8205..e25ac009de2 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -3035,8 +3035,6 @@ but for this tutorial it's only important to know that you can optionally annota extern mod rust = "github.com/mozilla/rust"; // pretend Rust is a simple library ~~~ -[rustpkg]: rustpkg.html - ## Crate metadata and settings For every crate you can define a number of metadata items, such as link name, version or author. @@ -3194,7 +3192,7 @@ re-export a bunch of 'officially blessed' crates that get managed with `rustpkg` # What next? Now that you know the essentials, check out any of the additional -tutorials on individual topics. +guides on individual topics. * [Borrowed pointers][borrow] * [Tasks and communication][tasks] @@ -3209,14 +3207,14 @@ tutorials on individual topics. There is further documentation on the [wiki], however those tend to be even more out of date than this document. -[borrow]: tutorial-borrowed-ptr.html -[tasks]: tutorial-tasks.html -[macros]: tutorial-macros.html -[ffi]: tutorial-ffi.html -[container]: tutorial-container.html -[conditions]: tutorial-conditions.html -[rustpkg]: tutorial-rustpkg.html -[testing]: tutorial-testing.html +[borrow]: guide-borrowed-ptr.html +[tasks]: guide-tasks.html +[macros]: guide-macros.html +[ffi]: guide-ffi.html +[container]: guide-container.html +[conditions]: guide-conditions.html +[rustpkg]: guide-rustpkg.html +[testing]: guide-testing.html [rustdoc]: rustdoc.html [wiki]: https://github.com/mozilla/rust/wiki/Docs diff --git a/mk/docs.mk b/mk/docs.mk index f211af700b9..2e109859b06 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -17,7 +17,11 @@ CDOCS := DOCS_L10N := BASE_DOC_OPTS := --from=markdown --standalone --toc --number-sections -HTML_OPTS = $(BASE_DOC_OPTS) --to=html5 --section-divs --css=rust.css --include-before-body=doc/version_info.html --include-in-header=doc/favicon.inc + +HTML_OPTS = $(BASE_DOC_OPTS) --to=html5 --section-divs --css=rust.css \ + --include-before-body=doc/version_info.html \ + --include-in-header=doc/favicon.inc + TEX_OPTS = $(BASE_DOC_OPTS) --to=latex EPUB_OPTS = $(BASE_DOC_OPTS) --to=epub @@ -112,57 +116,59 @@ doc/l10n/ja/tutorial.html: doc/l10n/ja/tutorial.md doc/version_info.html doc/rus --include-before-body=doc/version_info.html \ --output=$@ -DOCS += doc/tutorial-macros.html -doc/tutorial-macros.html: tutorial-macros.md doc/version_info.html doc/rust.css \ +# Guides + +DOCS += doc/guide-macros.html +doc/guide-macros.html: $(S)doc/guide-macros.md doc/version_info.html doc/rust.css \ doc/favicon.inc @$(call E, pandoc: $@) $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ $(CFG_PANDOC) $(HTML_OPTS) --output=$@ -DOCS += doc/tutorial-container.html -doc/tutorial-container.html: tutorial-container.md doc/version_info.html doc/rust.css \ +DOCS += doc/guide-container.html +doc/guide-container.html: $(S)doc/guide-container.md doc/version_info.html doc/rust.css \ doc/favicon.inc @$(call E, pandoc: $@) $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ $(CFG_PANDOC) $(HTML_OPTS) --output=$@ -DOCS += doc/tutorial-ffi.html -doc/tutorial-ffi.html: tutorial-ffi.md doc/version_info.html doc/rust.css \ +DOCS += doc/guide-ffi.html +doc/guide-ffi.html: $(S)doc/guide-ffi.md doc/version_info.html doc/rust.css \ doc/favicon.inc @$(call E, pandoc: $@) $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ $(CFG_PANDOC) $(HTML_OPTS) --output=$@ -DOCS += doc/tutorial-testing.html -doc/tutorial-testing.html: tutorial-testing.md doc/version_info.html doc/rust.css \ +DOCS += doc/guide-testing.html +doc/guide-testing.html: $(S)doc/guide-testing.md doc/version_info.html doc/rust.css \ doc/favicon.inc @$(call E, pandoc: $@) $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ $(CFG_PANDOC) $(HTML_OPTS) --output=$@ -DOCS += doc/tutorial-borrowed-ptr.html -doc/tutorial-borrowed-ptr.html: tutorial-borrowed-ptr.md doc/version_info.html doc/rust.css \ +DOCS += doc/guide-borrowed-ptr.html +doc/guide-borrowed-ptr.html: $(S)doc/guide-borrowed-ptr.md doc/version_info.html doc/rust.css \ doc/favicon.inc @$(call E, pandoc: $@) $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ $(CFG_PANDOC) $(HTML_OPTS) --output=$@ -DOCS += doc/tutorial-tasks.html -doc/tutorial-tasks.html: tutorial-tasks.md doc/version_info.html doc/rust.css \ +DOCS += doc/guide-tasks.html +doc/guide-tasks.html: $(S)doc/guide-tasks.md doc/version_info.html doc/rust.css \ doc/favicon.inc @$(call E, pandoc: $@) $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ $(CFG_PANDOC) $(HTML_OPTS) --output=$@ -DOCS += doc/tutorial-conditions.html -doc/tutorial-conditions.html: tutorial-conditions.md doc/version_info.html doc/rust.css \ +DOCS += doc/guide-conditions.html +doc/guide-conditions.html: $(S)doc/guide-conditions.md doc/version_info.html doc/rust.css \ doc/favicon.inc @$(call E, pandoc: $@) $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ $(CFG_PANDOC) $(HTML_OPTS) --output=$@ -DOCS += doc/tutorial-rustpkg.html -doc/tutorial-rustpkg.html: tutorial-rustpkg.md doc/version_info.html doc/rust.css \ +DOCS += doc/guide-rustpkg.html +doc/guide-rustpkg.html: $(S)doc/guide-rustpkg.md doc/version_info.html doc/rust.css \ doc/favicon.inc @$(call E, pandoc: $@) $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ diff --git a/mk/tests.mk b/mk/tests.mk index 9792ea5cbc9..6204c536911 100644 --- a/mk/tests.mk +++ b/mk/tests.mk @@ -20,8 +20,8 @@ TEST_HOST_CRATES = rustpkg rustc rustdoc syntax TEST_CRATES = $(TEST_TARGET_CRATES) $(TEST_HOST_CRATES) # Markdown files under doc/ that should have their code extracted and run -DOC_TEST_NAMES = tutorial tutorial-ffi tutorial-macros tutorial-borrowed-ptr \ - tutorial-tasks tutorial-conditions tutorial-container rust +DOC_TEST_NAMES = tutorial guide-ffi guide-macros guide-borrowed-ptr \ + guide-tasks guide-conditions guide-container rust ###################################################################### # Environment configuration