diff --git a/README.md b/README.md index 3e7691f..5d2ae37 100644 --- 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. diff --git a/book_example/arguments.md b/book_example/arguments.md index 19c9354..020f1d2 100644 --- 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 is: +where 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 , i.e. the file +The most important option is obviously , 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 `) -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 --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 --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 diff --git a/config.book b/config.book index 4c33b61..ef3168a 100644 --- 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 \ No newline at end of file