completed book example

README.md

@@ -17,8 +17,8 @@ it is down:
 $ cargo install crowbook
 ```
 
-will download `crowbook` and install it. If this is the first time you
-run `cargo install`, you'll like
+will download `crowbook` and install it. 
+
 
 Usage
 -----
@@ -31,9 +31,29 @@ $ crowbook <BOOK>
 
 Where `BOOK` is a configuration file. Crowbook will then parse the
 config file and generate book in HTML, Epub, LaTeX, and/or PDF,
-according to the setting in the configuration file.
+according to the setting in the configuration file. So if you clone
+this repository and run
 
-This configuration file contains some metadata, options, and list the
+```bash
+$ crowbook book_example/config.book
+```
+
+(or `cargo run -- book_example/config.book` if you don't want to
+install it), you'll generate the example book in various format. The
+HTML version should look
+[like that](http://lise-henry.github.io/crowbook/book.html).
+
+Now, let's say you want to make your own book. Assuming you have a
+list of Markdown files, you can generate a template configuration file
+with the `--create` argument:
+
+```bash
+$ crowbook --create my.book chapter_*.md
+```
+
+This will generate a default `my.book` file, which you'll need to complete.
+
+This configuration file contains some metadata, options, and lists the
 Markdown files. Here is a basic example:
 
 ```
@@ -50,40 +70,13 @@ output_html: some_book.html
 ```
 
 For more information see
-[the configuration file](book_example/config.md), or the whole
-[book_example](book_example) directory.
+[the configuration file page](book_example/config.md), or the whole
+[book_example](book_example) directory. (A (not necessarily
+up-to-date) [rendered version is available in HTML here](http://lise-henry.github.io/crowbook/book.html)).
 
 It is also possible to give additional parameters to `crowbook`;
-arguments set from the command line will override the ones set in the
-`BOOK` configuration file.
-
-```
-USAGE:
-        crowbook [FLAGS] [OPTIONS] <BOOK>
-
-FLAGS:
-    -h, --help       Prints help information
-    -V, --version    Prints version information
-    -v, --verbose    Activate verbose mode
-
-OPTIONS:
-        --autoclean <BOOL>    Try to clean input markdown [values: true, false]
-        --numbering <BOOL>    Number chapters or not [values: true, false]
-    -o, --output <FILE>       Specify output file
-    -t, --to <FORMAT>         Generate specific format [values: epub, epub, pdf, html, tex]
-
-ARGS:
-    <BOOK>    A file containing the book configuration
-
-Command line options allow to override options defined in <BOOK> configuration file. 
-E.g., even if this file specifies 'verbose: false', calling 'crowbook --verbose <BOOK>' 
-will activate verbose mode.
-
-Note that Crowbook generates output files relatively to the directory where <BOOK> is:
-$ crowbook foo/bar.book --to pdf --output baz.pdf
-will thus generate baz.pdf in directory foo and not in current
-directory.
-```
+we have already seen `--create`, but if you want the full list, see
+[the arguments page](book_example/arguments.md).
 
 Features
 --------

book_example/arguments.md

@@ -0,0 +1,159 @@
+Arguments 
+=========
+
+Crowbook can takes a list of arguments:
+
+```bash
+Render a markdown book in Epub, PDF or HTML.
+
+USAGE:
+        crowbook [OPTIONS] <BOOK> [--] [ARGS]
+
+OPTIONS:
+        --autoclean <BOOL>    Try to clean input markdown [values: true, false]
+        --create              Creates a new book file with existing markdown files
+    -h, --help                Prints help information
+        --numbering <BOOL>    Number chapters or not [values: true, false]
+    -o, --output <FILE>       Specify output file
+    -t, --to <FORMAT>         Generate specific format [values: epub, pdf, html, tex, odt]
+    -V, --version             Prints version information
+    -v, --verbose             Activate verbose mode
+
+ARGS:
+    <BOOK>     A file containing the book configuration
+    <FILES>...    Files to put in book when using --create
+
+Command line options allow to override options defined in <BOOK> configuration file. 
+E.g., even if this file specifies 'verbose: false', calling 'crowbook --verbose <BOOK>' 
+will activate verbose mode.
+
+Note that Crowbook generates output files relatively to the directory where <BOOK> is:
+$ crowbook foo/bar.book --to pdf --output baz.pdf
+will thus generate baz.pdf in directory foo and not in current
+directory.
+```
+
+The most important ones is obviously <BOOK>, i.e. the file
+configuration book. It is mandatory: if you don't pass it, `crowbook`
+will simply display this help message. In a normal use case this is
+the only argument you'll need to pass, and `crowbook` will generate
+the book in all formats specified in the configuration file.
+
+It is, however, possible to pass more arguments to `crowbook`.
+
+`--create`
+---------
+
+**Usage**: `crowbook --create <BOOK> file_1.md file_2.md ...`
+
+Creates a new book from a list of Markdown files. It will generate the
+file `BOOK` (or abort if it already exists) with all file names
+specified added as chapters.
+
+Most other `crowbook` options have no impact when using `--create`,
+but if `--numbering` is set to `false`, the files will be included
+with `-` instead of `+` in the Markdown file.
+
+### Example ###
+
+```
+crowbook --create foo.book README.md ChangeLog.md LICENSE.md
+```
+
+will generate a file `foo.book` containing:
+
+```
+author: Your name
+title: Your title
+lang: en
+
+# Uncomment and fill to generate files
+# output.html: some_file.html
+# output.epub: some_file.epub
+# output.pdf: some_file.pdf
+
+# Uncomment and fill to set cover image (for Epub)
+# cover: some_cover.png
+
+# List of chapters
++ README.md
++ ChangeLog.md
++ LICENSE.md
+```
+
+`--verbose`
+-----------
+
+**usage**: `crowbook --verbose <BOOK>`
+
+If this flag is set, Crowbook will print some more messages.
+
+`--to`
+------
+
+**usage**: `crowbook --to <FORMAT> <BOOK>`
+
+(or `crowbook -t <FORMAT> <BOOK>`)
+
+Generate only the specified format. `FORMAT` must be either `epub`,
+`pdf`, `html`, `odt` or `tex`.
+
+If an output file for the format is not specified in the book
+configuration file, `crowbook` will fail to render PDF, ODT and Epub
+(whereas it will print HTML and Tex files on stdout). It is however
+possible to specify a file with the `--output` option.
+
+### Examples ###
+
+```
+crowbook --to html foo.book
+```
+
+will generate some HTML, and prints it either to the file specified by
+`output.html` in `foo.book`, or to stdout.
+
+```
+crowbook --to pdf --output foo.pdf foo.book
+```
+
+will (try to) generate a `foo.pdf` file,.
+
+`--output`
+---------
+
+**usage**: `crowbook --to <FORMAT> --output <FILE> <BOOK>`
+
+(or `crowbook -t <FORMAT> -o <FILE> <BOOK>`)
+
+Specifies an output file. Only valid when `--to` is used.
+
+Note that Crowbook generates output files relatively to the directory
+where `BOOK` is:
+```
+$ crowbook foo/bar.book --to pdf --output baz.pdf
+```
+will thus generate `baz.pdf` in directory `foo` and not in current
+directory.
+
+`--numbering`
+-------------
+
+**usage**: `crowbook --numbering <BOOL> <BOOK>`
+
+Turns numbering on or off. Overrides the option set in `BOOK`
+configuration file.
+
+### Example ###
+
+```
+crowbook --numbering false foo.book
+```
+
+
+`--autoclean`
+-------------
+
+**usage**: `crowbook --autoclean <BOOL> <BOOK>`
+
+Turns autoclean on or off. Overrides the option set in `BOOK`
+configuration file. 

book_example/config.book

@@ -30,4 +30,5 @@ output.odt: book.odt
 # paths are relative to the directory where this file is
 +  ../README.md
 + config.md
++ arguments.md