It is hard to find arrays out in the TRPL

[lifthrasiir]

The table of contents does not mention anything about "arrays" (whatever does it mean). This, combined with the lack of full text search on the TRPL, means that the user has to read virtually everything til Chapter 5.3 to get the information about arrays, and yet he/she is confused about the lack of growable array (passing mention on Chapter 3.2, and fully explained on Chapter 5.17).

There are some recommendations I can think of:

• Provide a single-page version of the TRPL, probably for the printing and search.
• Provide an index for important terms. (I'm not sure rustbook can be easily made to produce such thing out of plain markdown files.)
• Expand Chapter 5.17 "Vectors" to explain both arrays and vectors, and rename its title to mention both.
• Or alternatively, cross-mention the existence of alternative types whenever one of them is first mentioned in the major way.

[Manishearth]

cc @steveklabnik

I think a "Quick intro to Rust" which covers all the types with links to reading more about them might help, actually

[lifthrasiir]

Some additional feedback that I've originally posted to IRC:

<Yurume> the truth is that, no one reads the book in the sequential order :)
<Yurume> we need a good index and ToC to faciliate such patterns
<Yurume> the beginner in the question was very confused since there seems to be vectors
         (he/she had C++ background) and slices but not arrays
<Yurume> actually, he/she almost got to the correct chapter, but didn't care to read all of them
         (yeah, we don't even have a *full* ToC, just a partial ToC two levels deep)

[killercup]

Provide a single-page version of the TRPL, probably for the printing and search.

Unofficial version, featuring single HTML as well as printable PDF: http://killercup.github.io/trpl-ebook/

Provide an index for important terms.

I'm not sure this would be an improvement over CMD+F, but it'd be fantastic for the print version. (From a technical perspective, it's not very complicated to hack together: I'd probably just introduce some convention like "Put index terms in <mark> tags" and then search-replace them for the PDF version.)

Or alternatively, cross-mention the existence of alternative types whenever one of them is first mentioned in the major way.

Yes, we should definitely improve TRPL for non-sequential reading! I've never read a programming book from front to back and the only technical books I actually kept are those with extensive cross-section linking. In my opinion, we should probably aim to cross-link everything: There is no reason not to link every type and trait in code blocks to the docs!

[lifthrasiir]

Provide an index for important terms.

I'm not sure this would be an improvement over CMD+F, but it'd be fantastic for the print version. (From a technical perspective, it's not very complicated to hack together: I'd probably just introduce some convention like "Put index terms in tags" and then search-replace them for the PDF version.)

I was saying that because I was not sure if the full text search with JS is doable or feasible. (It has to be JS, as it is being distributed as HTML form.) A separate index would give an alternative way to implement search. By the way, <dfn> would be a better fit I guess.

In my opinion, we should probably aim to cross-link everything: There is no reason not to link every type and trait in code blocks to the docs!

I'm much for this too, but less sure about how to implement that in the painless (or less painful) way. At the very least we need rustdoc support for an automatic link to items, which is rust-lang/rfcs#792.

[killercup]

I was saying that because I was not sure if the full text search with JS is doable or feasible. (It has to be JS, as it is being distributed as HTML form.)

There are libraries that do that (such as Lunr), but I'm not sure how easy this is, too.

By the way, <dfn> would be a better fit I guess.

"The dfn element represents the defining instance of a term." Semantically it would not be the best idea to use this if we want to just collect terms which can occur in more than one place.

At the very least we need rustdoc support for an automatic link to items, which is rust-lang/rfcs#792.

I was actually just talking about Rust code blocks. Those are tested and compiled, so there is an AST at some place and time with all the necessary information about types and where they come from. Using that we can generate links to the std docs. (Similar to how each type and trait is linked in rustdoc's function pages, e.g. Iterator, FnMut and Result here.)

[azerupi]

I was saying that because I was not sure if the full text search with JS is doable or feasible. (It has to be JS, as it is being distributed as HTML form.)

Just an idea, i'm not sure how helpful / feasible that would be. But you could build a "search friendly" index when you build the docs and store that in a javascript friendly file (json?).

[steveklabnik]

That's how rustdoc search works already, so it's certainly feasable.

[azerupi]

How hard would it be to make it more general and usable for rustbook ?

[steveklabnik]

I have no idea, but that would be the way forward, I'd imagine.

[steveklabnik]

In the new book, "array" is not a top-level header, but "data types" is http://rust-lang.github.io/book/ch03-02-data-types.html#Arrays

[steveklabnik]

I'm going to give this one a close; rustbook is gonna be replaced by mdbook, I'm not updating the current book text, and the next book isn't done yet. So this ticket is not going to be fixed, scheduled to be obsoleted, or maybe needs a request at mdbook's tracker.