update docs

Author: azerupi

book-example/src/README.md

@@ -1,16 +1,16 @@
 # mdBook
 
-**mdBook** is a command line tool and Rust library to create books using Markdown. It's very similar to Gitbook but written in [Rust](http://www.rust-lang.org).
+**mdBook** is a command line tool and Rust crate to create books using Markdown files. It's very similar to Gitbook but written in [Rust](http://www.rust-lang.org).
 
-This book serves as an example of the output of mdBook and as the docs at the same time.
+What you are reading serves as an example of the output of mdBook and at the same time as high-level docs.
 
 mdBook is free and open source, you can find the source code on [Github](https://github.com/azerupi/mdBook). Issues and feature requests can be posted on the [Github Issue tracker](https://github.com/azerupi/mdBook/issues).
 
 ## API docs
 
 Alongside this book you can also read the [API docs](mdbook/index.html) generated by Rustdoc if you would like
-to use mdBook as a crate or write a new renderer.
+to use mdBook as a crate or write a new renderer and need a more low-level overview.
 
 ## License
 
-mdBook, all the code and this book, are released under the [Mozilla Public License v2.0](https://www.mozilla.org/MPL/2.0/)
+mdBook, all the source code, is released under the [Mozilla Public License v2.0](https://www.mozilla.org/MPL/2.0/)

book-example/src/cli/build.md

@@ -9,12 +9,12 @@ mdbook build
 It will try to parse your `SUMMARY.md` file to understand the structure of your book
 and fetch the corresponding files.
 
-The rendered ouput will maintain the same directory structure as the source for
+The rendered output will maintain the same directory structure as the source for
 convenience. Large books will therefore remain structured when rendered.
 
 #### Specify a directory
 
-Like init, the build command can take a directory as argument to use instead of the
+Like `init`, the `build` command can take a directory as argument to use instead of the
 current working directory.
 
 ```

book-example/src/cli/cli-tool.md

@@ -1,4 +1,21 @@
 # Command Line Tool
 
-mdBook can be used either as a command line tool or a Rust library.
+mdBook can be used either as a command line tool or a [Rust crate](https://crates.io/crates/mdbook).
 Let's focus on the command line tool capabilities first.
+
+## Install
+
+At the moment, the only way to install mdBook is by downloading the source code from Github and building it yourself. Fortunately
+this is made very easy with Cargo.
+
+If you haven't already, you should begin by installing [Rust](https://www.rust-lang.org/install.html) and [Git](https://git-scm.com/downloads)
+
+Open your terminal and navigate to the directory of you choice. We need to clone the git repository and then build it with Cargo.
+
+```
+git clone --depth=1 https://github.com/azerupi/mdBook.git
+cd mdBook
+cargo build --release
+```
+
+The executable `mdbook` will be in the `./target/release` folder, this should be added to the path.

book-example/src/cli/init.md

@@ -1,15 +1,16 @@
 # The init command
 
-The init command, used like this:
+The `init` command is used like this:
 
 ```
 mdbook init
 ```
 
-Will create a couple of files and directories in the working directory so that you can
+It will create a couple of files and directories in the working directory so that you can
 spend more time writing your book and less setting it up.
 
 The files set up for you are the following:
+
 ```
 book-test/
 ├── book
@@ -22,14 +23,15 @@ The `src` directory is were you write your book in markdown. It contains all the
 configuration files, etc.
 
 The `book` directory is where your book is rendered. All the output is ready to be uploaded
-to a serer to be seen by the internet.
+to a server to be seen by the internet.
+
+The `SUMMARY.md` file is the most important file, it's the skeleton of your book and is discussed in more detail in another  [chapter](../format/summary.html).
 
-The `SUMMARY.md` file is the most important file, it's the skeleton of your book.
-It's so important that it has it's own [chapter](../format/summary.html).
+When a `SUMMARY.md` file already exists, the `init` command will generate the files according to the paths used in the `SUMMARY.md`
 
 #### Specify a directory
 
-When using the init command, you can also specify a directory, instead of using the current directory,
+When using the `init` command, you can also specify a directory, instead of using the current working directory,
 by appending a path to the command:
 
 ```
@@ -43,10 +45,3 @@ called `theme` in your source directory so that you can modify it.
 
 The theme is selectively overwritten, this means that if you don't want to overwrite a
 specific file, just delete it and the default file will be used.
-
-## Not yet implemented
-
-In the future I would like `mdBook init` to be able to:
-
-- Generate files that are in `SUMMARY.md`. If the user has already created a `SUMMARY.md` file and added some entries but did
-not create the corresponding files, init command should create the files for him.

book-example/src/format/summary.md

@@ -14,17 +14,19 @@ allow for easy parsing. Let's see how you should format your `SUMMARY.md` file.
    But it is not mandatory, the parser just ignores it. So you can too
    if you feel like it.
 
-2. ***list link*** the other elements have to be list elements in form of a link
+2. ***Prefix Chapter*** Before the main numbered chapters you can add a couple of elements that will not be numbered. This is useful for
+   forewords, introductions, etc. There are however some constraints. You can not nest prefix chapters, they should all be on the root level. And you can not add prefix chapters once you have added numbered chapters.
    ```markdown
-   - [Title of the Chapter](relative/path/to/markdown.md)
+   [Title of prefix element](relative/path/to/markdown.md)
    ```
-   You can either use `-` or `*` to indicate a list. The lists can be nested,
-   resulting in a nice hierarchy (chapters, sub-chapters, etc.)
 
-All other elements are unsupported and will be ignored at best or result in an error.
+3. ***Numbered Chapter*** Numbered chapters are the main content of the book, they will be numbered and can be nested,
+   resulting in a nice hierarchy (chapters, sub-chapters, etc.)
+   ```markdown
+   - [Title of the Chapter](relative/path/to/markdown.md)
+   ```
+   You can either use `-` or `*` to indicate a numbered chapter.
 
-#### not yet implemented
+4. ***Sufix Chapter*** After the numbered chapters you can add a couple of non-numbered chapters. They are the same as prefix chapters but come after the numbered chapters instead of before.
 
-In the feature I would like to add support for links without the need to be list elements
-at the root level to add chapters that don't need numbering, like an index, appendix,
-contributor list, introduction, foreword, etc.
+All other elements are unsupported and will be ignored at best or result in an error.

book-example/src/format/theme/theme.md

@@ -11,6 +11,8 @@ Here are the files you can overwrite:
 
 - ***index.hbs*** is the handlebars template.
 - ***book.css*** is the style used in the output. If you want to change the design of your book, this is probably the file you want to modify. Sometimes in conjunction with `index.hbs` when you want to radically change the layout.
-- ***book.js*** is mostly used to add client side functionality.
+- ***book.js*** is mostly used to add client side functionality, like hiding / un-hiding the sidebar, changing the theme, ...
+- ***highlight.js*** is the JavaScript that is used to highlight code snippets, you should not need to modify this.  
+- ***highlight.css*** is the theme used for the code highlighting
 
 ***Note:*** *When you overwrite a file, it is possible that you break some functionality. Therefore I recommend to use the file from the default theme as template and only add / modify what you need. You can copy the default theme into your source directory automatically by using `mdbook init --theme`.*