mirror of
https://github.com/lise-henry/crowbook
synced 2024-09-23 10:11:09 +02:00
Update first two chapters of the guide so they correspond to the actual version of Crowbook
This commit is contained in:
parent
455997df90
commit
0be42b105e
122
README.md
122
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.
|
||||
|
@ -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
|
||||
|
@ -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
|
Loading…
Reference in New Issue
Block a user