Documentation hides imports too aggressively

[huonw]

There are a lot of imports in code segments in the tutorial that are hidden in the final output (prefixed with #), which makes the code meet a pile of name-resolution errors.

In fact, use std:: is only mentioned 4 times in the whole thing. (The angle code of the pattern matching section is a good example of this.)

[zslayton]

@huonw I wouldn't mind tackling this if no one else is working on it. Is it as simple as removing the prefixed '#' in the .md files?

Following the README file in the doc directory, I'm using:

pandoc --from=markdown --to=html --number-sections -o tutorial.html tutorial.md

to generate tutorial.html. However, the page it produces doesn't include the stylesheets necessary to make it look like the tutorial on rust-lang.org. (http://static.rust-lang.org/doc/tutorial.htm)

Do you happen to know how to reproduce the official format?

[huonw]

@zslayton yes it is just removing the #, and make docs will create the official format. This will do a full compile once to get the latest rustdoc, and then should just regenerate the docs themselves on later runs.

[zslayton]

@huonw Cool, thanks -- I didn't have NodeJS installed so 'make docs' wasn't doing it initially.

I notice that in addition to the 'use' statements, there are also traits and functions that are commented out but referenced. Should I uncomment those as well? They're required in order to compile the examples, but add a fair amount of reading overhead.

[huonw]

@zslayton yes, but some of them are defined earlier and are just there to make that snippet pass the tests, or are functions in the standard library, so use your discretion about which to uncomment. (Maybe keep that as a separate commit, so it can be more easily modified/dropped if it is deemed too much extra code for the tutorial.)

[zslayton]

@huonw Good call, will do!