Update first two chapters of the guide so they correspond to the actual version of Crowbook

2024-05-24 10:06:05 +02:00 · 2016-09-28 06:21:47 +02:00 · 2016-09-28 06:21:47 +02:00 · 0be42b105e
parent 455997df90
commit 0be42b105e
3 changed files with 108 additions and 55 deletions
--- a/README.md
+++ b/README.md
@ -6,23 +6,34 @@ Crowbook
 Render a book written in markdown to HTML, Epub or PDF.

 Crowbook's purpose is to allow you to automatically generate multiple
-outputs formats from a book written in Markdown. Its main focus is
+outputs formats from a book written in Markdown. Its focus is
 novels, and the default settings should (hopefully) generate readable
-books with correct typography.
+books with correct typography (particularly for the french
+language[^1]).
+
+[^1]: I don't know the rules for other languages well
+enough; If you want more support for the correct typographic rules in
+your language, don't hesitate to open an issue on
+[Github](https://github.com/lise-henry/crowbook/issues), or to submit 
+a pull request.
+
+    

 Example
 -------

 To see what Crowbook's output looks like, you can read (a
 not-necessarily up-to-date version of) the Crowbook
-guide (containing this README.md file and additional documentation)
-rendered in [HTML](http://lise-henry.github.io/crowbook/book.html),
-[PDF](http://lise-henry.github.io/crowbook/book.pdf) or [EPUB](http://lise-henry.github.io/crowbook/book.epub).
+guide rendered in
+[HTML](http://lise-henry.github.io/crowbook/book/book.html), 
+[PDF](http://lise-henry.github.io/crowbook/book/book.pdf) or [EPUB](http://lise-henry.github.io/crowbook/book/book.epub).


 Installing
 ----------

+There are three ways to install Crowbook:
+
 ### Packages ###

 If you are on Debian GNU/Linux or Ubuntu (on a PC architecture), you can
@ -37,22 +48,44 @@ Linux, Windows and MacOSX). Just extract the archive and run
 `crowbook` (or `crowbook.exe` on Windows). You might also want to copy
 the binary somewhere in your `PATH` for later usage.

-### Building ###
+> Note: only the Linux binaries are really tested, please contact me
+> if there you have any trouble executing the Windows or Mac binaries.

-You'll need to have the [Rust](https://www.rust-lang.org/) compiler
-on your machine first; you can
-[download and install it here](https://www.rust-lang.org/downloads.html). Once
-it is down:
+### Using Cargo ###
+
+[Cargo](https://crates.io/) is the
+[Rust](https://www.rust-lang.org/)'s package manager. You can
+[install it here](https://www.rust-lang.org/downloads.html). Once
+it is down: 

 ```bash
 $ cargo install crowbook
 ```

 will automatically download the latest `crowbook` release on
-[crates.io](https://crates.io/crates/crowbook) and install it.
+[crates.io](https://crates.io/crates/crowbook), compile it, and
+install it on your system.

-Usage
-----
+> By default, compiling Crowbook in this way doesn't activate the
+> proofreading features. If you want to use them, you'll have to run
+> `cargo install --features "proofread" crowbook`.
+
+Dependencies
+------------
+
+While there are, strictly speaking, no real dependencies to be able to
+run Crowbook (it is published a a statically compiled binary), some
+features require additional commands to work correctly:
+
+* EPUB rendering requires that the `zip` command be present on your system;
+* PDF rendering requires a working installation of LaTeX (preferably
+`xelatex`);
+* Grammar checking (for proofreading copies) requires [LanguageTool](https://languagetool.org/).
+
+
+
+Quick tour
+----------

 The simplest command is:

@ -88,24 +121,20 @@ Current features

 ### Output formats ###

-Crowbook should correctly support HTML and EPUB (either
-version 2 or 3) as output formats: rendered files should pass
-respectively the [W3C validator](https://validator.w3.org/) and the
-[IDPF EPUB validator](http://validator.idpf.org/) for a wide range of
-(correctly Markdown formatted) input files. See the example book
-rendered in [HTML](http://lise-henry.github.io/crowbook/book.html) and
-[EPUB](http://lise-henry.github.io/crowbook/book.epub) on github.io.
+Crowbook supports HTML, PDF and EPUB (either
+version 2 or 3) as output formats. See the Crowbook User Guide 
+rendered in
+[HTML](http://lise-henry.github.io/crowbook/book/book.html),
+[EPUB](http://lise-henry.github.io/crowbook/book/book.epub) and
+[PDF](http://lise-henry.github.io/crowbook/book.pdf).

-LaTeX/PDF output is a bit more tricky: it should work reasonably well for
-novels (the primary target of Crowbook), but `pdflatex` might occasionally
-choke on some "weird" unicode character. See the example book rendered
-in [PDF](http://lise-henry.github.io/crowbook/book.pdf) on github.io.
+> Note: in order to be able to render your books as PDF, you'll need
+> to have a working installation of LaTeX (preferably `xelatex`) on
+> your system. 
+
+Crowbook also provides some experimental support for rendering to ODT
+(Libre/Open/Office), but it needs more work.

-ODT output is currently experimental at best. It might work with very
-basic formatting but still needs a *lot* of work. You can still see
-the example book rendered in
-[ODT](http://lise-henry.github.io/crowbook/book.odt) on github.io to
-have an idea of the current status for this output format.

 ### Input format ###

@ -113,17 +142,20 @@ Crowbook uses
 [pulldown-cmark](https://crates.io/crates/pulldown-cmark) and thus
 should support most of CommonMark Markdown. Inline HTML, however, is
 not implemented, and probably won't be, as the goal is to have books
-that can also be generated in PDF (and maybe eventually ODT).
+that can also be generated in PDF (and maybe ODT).
+
+### Input cleaning ###

 Maybe the most specific "feature" of Crowbook is that (by default, it
-can be deactivated) it tries to "clean" the input files. By default this
-doesn't do much (except removing superfluous spaces), but if the
-book's language is set to french it tries to respect french
-typography, replacing spaces with non-breaking ones when it is
-appropriate (e.g. in french you are supposed to put a non-breaking
-space before '?', '!', ';' or ':'). This feature is relatively limited
-at the moment, but I might try to add more options and support for
-more languages.
+can be deactivated) it tries to "clean" the input files. By default,
+this doesn't do much (except removing superfluous spaces), but if the 
+book's language is set to frenc it tries its best to respect french
+typography by replacing spaces with non-breaking ones when it is
+appropriate (e.g. before '?', '!', ';' or ':').
+
+> This feature is currently limited to french language, but please
+> [open an issue](https://github.com/lise-henry/crowbook/issues/new) describing typographic rules if you want it to be
+> implemented for another language.

 ### Links handling ###

@ -160,7 +192,16 @@ This is a very tiny book!

 can be processed with `crowbook --single foo.md` or `crowbook -s
 foo.md` to produce the `book.html` file. This is useful for short
-texts that typically only contain one "chapter".
+texts that only contain one "chapter".
+
+### Proofreading ###
+
+Crowbook can also generate "proofreading" copies in HTML or PDF,
+highlighting grammar errors and repetitions.
+
+> This feature has been introduced in version `0.9.1` and is still
+> experimental. For more information, see
+> [the proofreading chapter of the guide](book_example/proofreading.md). 

 ### Bugs ###

@ -187,6 +228,9 @@ library, Crowbook uses the following libraries:
 * [crossbeam](https://crates.io/crates/crossbeam)
 * [walkdir](https://crates.io/crates/walkdir)
 * [rustc-serialize](https://crates.io/crates/rustc-serialize)
+* [caribon](https://crates.io/crates/caribon)
+* [hyper](https://crates.io/crates/hyper)
+* [url](https://crates.io/crates/url)

 It also embeds [Highlight.js](https://highlightjs.org/) in HTML output
 to enable syntax highlighting for code blocks.
--- a/book_example/arguments.md
+++ b/book_example/arguments.md
@ -28,14 +28,19 @@ ARGS:
 ```

 Note that Crowbook generates output files relatively to the directory
-where <BOOK> is:
+where <BOOK> is[^1]:
+
+[^1]: Unless the option `output.base_path` is set, see
+[the configuration file](book_example/config.md).
+
+

 ```bash
 $ 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 option obviously <BOOK>, i.e. the file
+The most important option is obviously <BOOK>, i.e. the file
 configuration book. It is mandatory for most options: if you don't
 pass it, `crowbook` 
 will simply display this help message. In a normal use case this is
@ -88,9 +93,9 @@ while
 crowbook --create README.md ChangeLog.md LICENSE.md
 ```

-will prints the same result, but to stdout (without creating a file).
+will print the same result, but to stdout (without creating a file).

-When `crowbook` is runned with `--create`, it can also uses the
+When `crowbook` is runned with `--create`, it can also use the
 keys/values set by `--set` (see below):

 ```bash
@ -116,7 +121,7 @@ lang: fr

 (or `crowbook -s <FILE>`)

-This options allows to pass `crowbook` a single Markdown file. This
+This argument allows to give `crowbook` a single Markdown file. This
 file can contain an inline YAML block to set some book options. Inline
 YAML blocks must start and end with a line with `---` (three dashes). E.g:

@ -124,6 +129,7 @@ YAML blocks must start and end with a line with `---` (three dashes). E.g:
 ---
 author: Joan Doe
 title: A short story
+output.html: short.html
 ---
 ```

@ -141,8 +147,8 @@ configuration file containing:
 That is, the chapter heading (if any) won't be displayed in the output
 documents (though they still appear in the TOC).

-Note that by default, using `--single` sets the `tex.short` option to
-`true`, using the LaTeX class of `article` instead of `book`.
+> Note that by default, using `--single` sets the default LaTeX class
+> of the book to `article` instead of `book`.


 `--set` 
@ -150,8 +156,8 @@ Note that by default, using `--single` sets the `tex.short` option to

 **usage**: `crowbook <BOOK> --set [KEY] [VALUE]...`

-This options takes a list `KEY` `VALUE` pairs and allows to set or
-override a book configuration option. All valid options in the
+This argument takes a list `KEY` `VALUE` pairs and allows setting or
+overriding a book configuration option. All valid options in the
 configuration files are valid as keys. For more information, see
 [the configuration file](config.md).

@ -161,7 +167,8 @@ configuration files are valid as keys. For more information, see
 $ crowbook foo.book --set html.css style.css
 ```

-will override the CSS for HTML generation (the `html.css` key) to `style.css`.
+will override the CSS for HTML generation (the `html.css` key) to the
+file `style.css`.

 ```bash
 $ crowbook foo.book --set author Foo --title Bar
@ -211,7 +218,7 @@ $ crowbook --print-template epub.template --set epub.version 3

 **usage**: `crowbook <BOOK> --verbose`

-If this flag is set, Crowbook will print the warnings it detect while
+If this flag is set, Crowbook will print the warnings it detects while
 parsing and rendering. These warnings are typically related to the
 inclusion of non-local images, linking to Markdown files that are not
 part of the book, and so on.
@ -227,8 +234,8 @@ 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
+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 ###
@ -256,7 +263,7 @@ will generate a `foo.pdf` file,.
 Specifies an output file. Only valid when `--to` is used.

 Note that Crowbook generates output files relatively to the directory
-where `BOOK` is:
+where `BOOK` is (unless the option `output.base_path` is set):

 ```bash
 $ crowbook foo/bar.book --to pdf --output baz.pdf
--- a/config.book
+++ b/config.book
@ -8,7 +8,7 @@ description: >-
 lang: en
 cover: cover.png
 version: 0.9.1
-date: "23th of september, 2016"
+date: "28th of september, 2016"

 # Options for generating files
 output.epub: book.epub
@ -19,12 +19,13 @@ output.odt: book.odt
 
 output.base_path: docs/book/
 output.proofread.html: book.proof.html
+output.proofread.html_dir: html_proof
 output.proofread.pdf: book.proof.pdf

 # Resources options
 resources.base_path.images: img/  # where to find the cover

-proofread.repetitions: true
+proofread.repetitions: false
 proofread.languagetool: true

 # Rendering options
@ -52,5 +53,6 @@ epub.version: 3
 + book_example/arguments.md
 + book_example/config.md
 + book_example/templates.md
+ book_example/proofreading.md
 - ChangeLog.md
 - LICENSE.md