"The Rust Programming Language"

[steveklabnik]

This is a preliminary PR that significantly changes Rust's documentation.

TL;DR: Remove the distinction between "the guide" and "the guides", and merge them into one big 'ol "The Rust Programming Language." You can see it rendered here: http://steveklabnik.github.io/the_rust_programming_language/

This uses https://github.com/aturon/rust-book to generate said final product.

Basically, the new "book" as I'm calling it looks like this:

Part I: Basics <- this is the first half of the current Guide. Linear.
Part II: Intermediate <- this is some of the current Guide, with the invididual Guides replacing chapters where relevant. Can be read in any order.
Part III: Adavanced <- the most advanced of the previous Guides. Can be read in any order.

Conceivably, this could even fix rust-lang/rust-by-example#278 by making Rust by example a part IV or something. While Rust By Example doesn't currently use Rustbook, it could.

I don't think the Makefile is currently up to snuff, but it works, at least. Ish. Feedback very welcome.

This also adds an optional dependency on rustbook, which may not be something that we want.

[Gankra]

I haven't had a lot of love for Rustbook's stability and style as used on aturon's style guide. However your build seems considerably more stable, did you do anything different? Style things can of course be worked out.

Like the general direction, though. This is a much more coherent vision for our high-level documentation.

[steveklabnik]

@gankro what do you mean by 'stable' in this context?

[Gankra]

http://aturon.github.io/ frequently flickers the content or will just not load it at all. Actually it just seems totally broken to me now. Possibly just bitrot? Has the official version been moved?

[steveklabnik]

Loads just fine here. Odd.

I just built it with my own compiled version. But as you say, style is fixable regardless.

Sent from my iPhone

On Dec 2, 2014, at 18:31, Alexis Beingessner notifications@github.com wrote:

http://aturon.github.io/ frequently flickers the content or will just not load it at all. Actually it just seems totally broken to me now. Possibly just bitrot? Has the official version been moved?

�
Reply to this email directly or view it on GitHub.

[MatejLach]

Loads and looks fine on my end as well...

[Gankra]

Hmm, whenever I click on a menu item the page just goes white. I have to refresh to get it to actually render :/ (on aturon's not yours).

[MatejLach]

This would be one of the problems, where one's results will wary greatly depending on what fonts, browser, packages they have/not have installed etc.
The discrepancy between various browsers and their many possible configurations it just a pain.
Case in point:
So for me both http://aturon.github.io and http://steveklabnik.github.io/the_rust_programming_language work fine (and exactly the same), so in this case I happen to have my browser/system configured "correctly", but in an unrelated case, I don't have fonts on rust-lang.org showing up correctly until I install the Fira Sans font, so clearly in that case, my browser is being configured "incorrectly".

sigh

[brson]

I'd like to take some time to think about how the build and automation around such a change will work before we merge.

The font problem with the docs in general is frustrating. Maybe we should get rid of Fira and use a more typical local font until the bug is figured out.

[LaoZhongGu]

Great Job.

[adrientetar]

I don't have fonts on rust-lang.org showing up correctly until I install the Fira Sans font, so clearly in that case, my browser is being configured "incorrectly".

AFAICT, it’s an Arch Linux-specific bug that has little to do with configuration.

[MatejLach]

@adrientetar It may be, but it's similar in nature nonetheless. (the same thing showing up differently depending on your system)
However, since I have been consistently unable to reproduce it on ANY other website, it must be a very obscure bug that is only triggered by something at rust-lang.org

[adrientetar]

I get Resource interpreted as Font but transferred with MIME type binary/octet-stream: "http://doc.rust-lang.org/Heuristica-Italic.woff". in the console when opening a rust page.

Not sure if it’s related but it looks like that needs fixing server-side: http://stackoverflow.com/questions/15521130/google-warning-resource-interpreted-as-font-but-transferred-with-mime-type-appl
cc @alexcrichton

[alexcrichton]

@adrientetar that is worrisome! Our instance of doc.rust-lang.org actually just proxies requests to S3, and it looks like when publishing docs to S3 (using s3cmd) there's no way to instruct it that these *.woff files have a particular content type (one way or another). You wouldn't happen to know how to add this header on-the-fly with nginx would you?

[adrientetar]

I do not use nginx. Can you pass the MIME type manually with -m to s3cmd?

[mdinger]

@gankro Could be corrupted browser profile. See rust-lang/rust-by-example#201 (comment) if it's an issue in firefox. Other browsers probably have cleaning instructions as well.

[MatejLach]

@mdinger I tried with a fresh profile, it still happens.
What about using the CSS from Google Web Fonts? They have Fira Sans and fonts embedded from Google Web Fonts always work correctly for me.

[mdinger]

@MatejLach Ah, I didn't notice that you and @gankro were describing the same issue. That makes sense then.

[steveklabnik]

This no longer cleanly merges, and I intend to revamp the Tasks guide before merging this all together anyway, so I'm giving this PR a close for now. @brson let's tallk automation sometime soon as well.