Initial work on improving the book. #1338
Closed
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The book is in need of serious work and completion, as this crate is relatively new. Some work in building the book is a challenge due to an issue with mdbook.
After quite a bit of thinking about how best to approach this, I've found the changes in this PR should prove fruitful for future book updates.
Code should be executable directly.
For beginners, it's important that the code in the book be copy and pastable directly into their editor without changes, to help them have a smooth learning experience. This is already the case with the "Hello World" example, where the code has a main() function and everything.
Some of the later code, however, just looks like script snippets. This is odd in Rust, as Rust is not a scripting language, and these code fragments can not be executed.
I found out these code fragments exist AS fragments because the auto-testing facilities available in mdbook don't support some crates, where you need to specify the location. So the code was instead written in testable ".rs" files and imported into the book.
My PR and suggestion for future book updates - which I am likely to make several of if this is improved - is to make a very couple of simple modifications to the test anchors, splitting it out into a "top" (includes) and content, which allows for a very simple main() structure to be written inside the 'ignored' Rust code that the mdbook program can not execute.
To note, this PR should not be controversial because: