From acd84c2f82e303fbc135e69f0d4e2c68d7218f1d Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 6 Feb 2017 15:05:37 -0500 Subject: [PATCH 1/2] Re-write the doc index page Clarify and reorganize. Add the section for the bookshelf. More to come here in the near future! Part of #39588 --- src/doc/index.md | 52 +++++++++++++++++++++++++++++------------------- 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/src/doc/index.md b/src/doc/index.md index 71dfcf0b067ec..0533f8d751866 100644 --- a/src/doc/index.md +++ b/src/doc/index.md @@ -6,32 +6,44 @@ nav { } -This is an index of the documentation included with the Rust -compiler. For more comprehensive documentation see [the -website](https://www.rust-lang.org). +This page is an overview of the documentation included with your Rust install. +Other unofficial documentation may exist elsewhere; for example, the [Rust +Learning] project collects documentation from the community, and [Docs.rs] +builds documentation for individual Rust packages. -[**The Rust Programming Language**][book]. Also known as "The Book", -The Rust Programming Language is the most comprehensive resource for -all topics related to Rust, and is the primary official document of -the language. +## API Documentation -[**The Rust Reference**][ref]. While Rust does not have a -specification, the reference tries to describe its working in -detail. It is accurate, but not necessarily complete. +Rust provides a standard library with a number of features; you can browse +its documentation [here][api]. -[**Standard Library API Reference**][api]. Documentation for the -standard library. +## Reference Documentation -[**The Rustonomicon**][nomicon]. An entire book dedicated to -explaining how to write unsafe Rust code. It is for advanced Rust -programmers. +Rust does not yet have a formal specification, but we have a reference document +[ref][ref]. It is guaranteed to be accurate, but not complete. We now have a +policy that all new features must be included in the reference before +stabilization; however, we are still back-filling things that landed before +then. That work is being tracked [here][38643]. -[**Compiler Error Index**][err]. Extended explanations of -the errors produced by the Rust compiler. +## Extended Error Documentation -[book]: book/index.html -[ref]: reference.html +All of Rust's errors code with error codes, and you can request extended +diagnostics from the compiler on those errors. We also produce those +diagnostics on the web [here][err], if you prefer to read them that way. + +## The Rust Bookshelf + +Rust provides a number of book-length sets of documentation, collectively +nicknamed 'The Rust Bookshelf.' + +* [The Rust Programming Language][book] teaches you how to program in Rust. +* [The Rustinomicon][nomicon] is your guidebook to the dark arts of unsafe Rust. + +[Rust Learning]: https://github.com/ctjhoa/rust-learning +[Docs.rs]: https://docs.rs/ [api]: std/index.html -[nomicon]: nomicon/index.html +[ref]: reference.html +[38643]: https://github.com/rust-lang/rust/issues/38643 [err]: error-index.html +[book]: book/index.html +[nomicon]: nomicon/index.html From 78dd2ec2c28e8238770d1a04a419b8193a7567c1 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 7 Feb 2017 13:04:57 -0500 Subject: [PATCH 2/2] review nits --- src/doc/index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/doc/index.md b/src/doc/index.md index 0533f8d751866..144b786f58d24 100644 --- a/src/doc/index.md +++ b/src/doc/index.md @@ -13,22 +13,22 @@ builds documentation for individual Rust packages. ## API Documentation -Rust provides a standard library with a number of features; you can browse -its documentation [here][api]. +Rust provides a standard library with a number of features; [we host its +documentation here][api]. ## Reference Documentation -Rust does not yet have a formal specification, but we have a reference document -[ref][ref]. It is guaranteed to be accurate, but not complete. We now have a +Rust does not yet have a formal specification, but we have [a reference document +][ref]. It is guaranteed to be accurate, but not complete. We now have a policy that all new features must be included in the reference before stabilization; however, we are still back-filling things that landed before then. That work is being tracked [here][38643]. ## Extended Error Documentation -All of Rust's errors code with error codes, and you can request extended -diagnostics from the compiler on those errors. We also produce those -diagnostics on the web [here][err], if you prefer to read them that way. +Many of Rust's errors come with error codes, and you can request extended +diagnostics from the compiler on those errors. We also [have the text of those +extended errors on the web][err], if you prefer to read them that way. ## The Rust Bookshelf @@ -36,7 +36,7 @@ Rust provides a number of book-length sets of documentation, collectively nicknamed 'The Rust Bookshelf.' * [The Rust Programming Language][book] teaches you how to program in Rust. -* [The Rustinomicon][nomicon] is your guidebook to the dark arts of unsafe Rust. +* [The Rustonomicon][nomicon] is your guidebook to the dark arts of unsafe Rust. [Rust Learning]: https://github.com/ctjhoa/rust-learning [Docs.rs]: https://docs.rs/