"The Rust Programming Language," Take II #19897

steveklabnik · 2014-12-15T23:41:15Z

An updated version of #19461

This version vendors steveklabnik/rustbook@731f7bf and builds it when building the docs. This is almost great, except my make-foo is poor, so I have my own personal paths in mk/docs.mk. How should I best get around that?

/cc @brson

steveklabnik · 2014-12-16T00:49:01Z

Oh, and post make-fu, I need to actually update the source text with various fixes that have landed. I'll do that right before the merge.

steveklabnik · 2014-12-16T00:49:10Z

(and change the links on the homepage, etc)

sinistersnare · 2014-12-16T01:36:00Z

src/doc/trpl/src/looping.md

+
+In slightly more abstract terms,
+
+```{ignore,notrust}


why isn't this block marked as rust? It is technically valid (if var expression, and code are valid identifiers)

this is a question that's not relevant to the pull request, so let's not discuss it more here.

the answer is because i didn't do it that way ;) PR accepted.

How is it not part of the PR, It is code review? does this PR exist solely to be accepted without modification?

All of this content is imported from the existing guides. So the text isn't what's under review here.

Please make a new issue or a PR to discuss the content.

huonw · 2014-12-16T02:17:51Z

Just double checking: this PR changes none of the actual content?

(I guess we/you need to be careful to incorporate any changes that happen between now and when it finally merges.)

steveklabnik · 2014-12-16T02:37:48Z

Yes, the intention is that it changes none of the content.

We will need to be careful. and that's what I meant with #19897 (comment) . The text here is a little bit old, but as soon as we're happy with the rest of it, I'll update it and hold off on merging PRs till this is in.

aturon · 2014-12-17T03:35:25Z

I'm so excited about this, @steveklabnik!

I think after this is merged, my rust-book repo should go into hibernation -- this should be the place to develop on rust-book.

steveklabnik · 2014-12-17T20:32:54Z

@brson what do you think we need to do to land this?

brson · 2014-12-17T23:28:50Z

src/etc/licenseck.py

+    "src/rust-book/src/serve.rs", # imported
+    "src/rust-book/src/subcommand.rs", # imported
+    "src/rust-book/src/term.rs", # imported
+    "src/rust-book/src/test.rs", # imported


Let's not make these exceptions and fix the licensing of the files. Besides one patch that I would claim is non-copyrightable @aturon is the only author and he won't mind.

They're all covered by Apache, so I guess this involves copying this at the top of each file?

Put this at the top of each file:

// Copyright 2014 The Rust Project Developers. See the COPYRIGHT // file at the top-level directory of this distribution and at // http://rust-lang.org/COPYRIGHT. // // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your // option. This file may not be copied, modified, or distributed // except according to those terms.

It is adding the MIT license as well.

brson · 2014-12-17T23:30:07Z

Can we put rustbook under the directory 'src/rustbook' to match the name of the crate?

brson · 2014-12-17T23:30:43Z

src/rust-book/LICENSE-APACHE doesn't need to come along I think.

steveklabnik · 2014-12-17T23:33:24Z

@brson prefer that name too, only kept it with the dash because https://github.com/aturon/rust-book spelled it that way.

liigo · 2014-12-17T23:43:25Z

Could "trpl" be renamed to something else with more meaningful? Maybe just
"book"?

brson · 2014-12-17T23:44:01Z

mk/docs.mk

-    rustdoc guide-unsafe guide-strings reference
+DOCS := index intro tutorial complement-bugreport \
+    complement-lang-faq complement-design-faq complement-project-faq \
+    rustdoc reference


The DOCS variable is used both to generate these docs but also to test them. I don't see in this patch a mechanism that keeps the book tested.

I might suggest adding a variable TEST_DOCS=$DOCS $(wildcard $src/doc/trpl/*) and using TEST_DOCS in test.mk to drive the doc testing (though istm that rustbook might want to learn to --test itself someday).

brson · 2014-12-18T00:14:48Z

This rule needs to be updated to tell the installer not to install rustbook https://github.com/rust-lang/rust/blob/master/mk/prepare.mk#L73

steveklabnik · 2014-12-18T22:45:18Z

This is now conceptually good to go, I think. The last issue is removing the dependency on regexes, but that's internal to the rustbook code. I'd be interested in getting feedback on the makefile stuff, and then i can squash, fix regexes, import current guides and such, and then we should be good to go

/cc @aturon @alexcrichton @brson

brson · 2014-12-19T00:09:48Z

mk/docs.mk

+
+trpl: $(RUSTBOOK)
+	cd src/doc/trpl; $(S)/$(RUSTBOOK) build; cd ../../..;
+	cp -r src/doc/trpl/_book doc/book


This still does not look like it will support an out-of-tree build: 'src/doc/trpl' will not contain the source for rustbook in that case. These comments are still relevant. If that is implemented then the three additions to the .gitignore file are unnecessary. Out of tree build can be tested like

mkdir build && cd build && ../configure && make docs

Ahh, sorry, my instincts are still 'it doesn't matter where you build,' out of tree always feels wasteful. I guess I just haven't spent enough time building things.=

brson · 2014-12-19T00:10:15Z

This latest revision includes a directory 'src/rustbook/target' that should not be checked in.

alexcrichton · 2014-12-19T02:20:32Z

mk/tests.mk

@@ -311,6 +311,7 @@ tidy:
 		| grep '^$(S)src/doc' -v \
 		| grep '^$(S)src/compiler-rt' -v \
 		| grep '^$(S)src/libbacktrace' -v \
+		| grep '^$(S)src/rustbook' -v \


I don't think this line should be added (we should check this directory for binaries)

(I think this is still relevant)

brson · 2015-01-08T06:41:57Z

There appears to be an extra space in the path rustbook is trying to open "{space}tmp/trpl..."

steveklabnik · 2015-01-08T06:56:36Z

This is getting close to being good to go. Left to do:

write the makefile rule that calls rustbook test
integrate make trpl and make trpl-test into make docs.

Anything else?

alexcrichton · 2015-01-08T08:48:50Z

I've rebased this branch on the current master here: alexcrichton@6a5b558

In that commit I've also integrated tests into the default build (not via rustbook test though), and I've also integrated the docs into the regular build.

Some other agenda items I saw:

The main landing page needs to have many links updated
The guides need to be all brought back up to date as a bunch of changes have happened since they were moved.
A quick pass to make sure everything looks as expected.

Can't wait for this to land!

steveklabnik · 2015-01-08T13:04:28Z

Ah yes. I'm going to eat breakfast, and then I'll tackle that.

steveklabnik · 2015-01-08T16:06:10Z

Okay! This should be good to go, I think. I'd imagine we'd want to sqaush some of this, yeah?

steveklabnik · 2015-01-08T16:43:33Z

😢 it is done

alexcrichton · 2015-01-08T16:46:19Z

src/doc/trpl/SUMMARY.md

+    * [Compiler Plugins](src/plugins.md)
+* [Conclusion](src/conclusion.md)
+
+vim src/doc/trpl/src/installing-rust.md src/doc/trpl/src/hello-world.md src/doc/trpl/src/hello-cargo.md src/doc/trpl/src/variable-bindings.md src/doc/trpl/src/if.md src/doc/trpl/src/functions.md src/doc/trpl/src/comments.md src/doc/trpl/src/compound-data-types.md src/doc/trpl/src/match.md src/doc/trpl/src/looping.md src/doc/trpl/src/strings.md src/doc/trpl/src/arrays-vectors-and-slices.md src/doc/trpl/src/standard-input.md src/doc/trpl/src/guessing-game.md


lol i suck at vim

This pulls all of our long-form documentation into a single document, nicknamed "the book" and formally titled "The Rust Programming Language." A few things motivated this change: * People knew of The Guide, but not the individual Guides. This merges them together, helping discoverability. * You can get all of Rust's longform documentation in one place, which is nice. * We now have rustbook in-tree, which can generate this kind of documentation. While its style is basic, the general idea is much better: a table of contents on the left-hand side. * Rather than a almost 10,000-line guide.md, there are now smaller files per section.

@brson

An updated version of rust-lang#19461 This version vendors steveklabnik/rustbook@731f7bf and builds it when building the docs. This is almost great, except my `make`-foo is poor, so I have my own personal paths in `mk/docs.mk`. How should I best get around that? /cc @brson

alexcrichton · 2015-01-08T20:47:08Z

Merged in #20760

alexcrichton · 2015-01-08T20:50:34Z

Can't wait to see this on doc.rust-lang.org, really nice work here @steveklabnik!

steveklabnik · 2015-01-08T21:11:30Z

😍 🎊

Gankra · 2015-01-08T21:13:04Z

Woaaah! Congrats!

asterite · 2015-01-09T01:55:04Z

src/doc/trpl/README.md

+
+## Advanced
+
+In a similar fashion to "Intermediate," this setion is full of individual,


Should be 'section'

Totally! Please open an issue or PR about this. Thanks :)

@steveklabnik

Here's my PR for the changes discussed in #19823. I decided to leave `_these_` types of italics the way there were because it differentiates the use of italics for emphasis from `*key term*` italics. Otherwise, bolded terms have been changed to italics, and single and double quotes have been changed appropriately, depending on their context (my judgement may not be the best, though). r? @steveklabnik (congratulations on #19897 being finalized and merged, by the way!)

steveklabnik force-pushed the trpl branch 2 times, most recently from f4baf41 to 1c12032 Compare December 16, 2014 00:28

steveklabnik force-pushed the trpl branch from 785be26 to b29e7d0 Compare December 16, 2014 01:25

sinistersnare reviewed Dec 16, 2014
View reviewed changes

brson reviewed Dec 17, 2014
View reviewed changes

steveklabnik force-pushed the trpl branch from 2a48491 to 3fc5cc7 Compare December 18, 2014 18:19

steveklabnik force-pushed the trpl branch 2 times, most recently from ea5d31c to 3238e6e Compare December 18, 2014 22:28

brson reviewed Dec 19, 2014
View reviewed changes

alexcrichton reviewed Dec 19, 2014
View reviewed changes

steveklabnik force-pushed the trpl branch from d77938a to 845450a Compare January 8, 2015 14:36

steveklabnik force-pushed the trpl branch from 385e6b2 to f4e15b3 Compare January 8, 2015 16:42

alexcrichton reviewed Jan 8, 2015
View reviewed changes

steveklabnik force-pushed the trpl branch 2 times, most recently from 16a6ebd to bd5739e Compare January 8, 2015 17:49

alexcrichton closed this Jan 8, 2015

iKevinY mentioned this pull request Jan 9, 2015

Standardize punctuation & formatting of TRPL #20782

Merged

asterite reviewed Jan 9, 2015
View reviewed changes

liigo mentioned this pull request Nov 27, 2015

src/doc/trpl -> src/doc/book #29932

Merged

steveklabnik deleted the trpl branch October 25, 2017 18:27


		## Advanced

		In a similar fashion to "Intermediate," this setion is full of individual,

"The Rust Programming Language," Take II #19897

"The Rust Programming Language," Take II #19897

Conversation

steveklabnik commented Dec 15, 2014

steveklabnik commented Dec 16, 2014

steveklabnik commented Dec 16, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

huonw commented Dec 16, 2014

steveklabnik commented Dec 16, 2014

aturon commented Dec 17, 2014

steveklabnik commented Dec 17, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brson commented Dec 17, 2014

brson commented Dec 17, 2014

steveklabnik commented Dec 17, 2014

liigo commented Dec 17, 2014

Choose a reason for hiding this comment

brson commented Dec 18, 2014

steveklabnik commented Dec 18, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brson commented Dec 19, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brson commented Jan 8, 2015

steveklabnik commented Jan 8, 2015

alexcrichton commented Jan 8, 2015

steveklabnik commented Jan 8, 2015

steveklabnik commented Jan 8, 2015

steveklabnik commented Jan 8, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexcrichton commented Jan 8, 2015

alexcrichton commented Jan 8, 2015

steveklabnik commented Jan 8, 2015

Gankra commented Jan 8, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment