mirror of
https://github.com/lise-henry/crowbook
synced 2024-06-08 00:06:19 +02:00
Update guide
This commit is contained in:
Elisabeth Henry
parent
97cb4d3e44
commit
6e193a159d
48
README.md
48
README.md
|
|
@ -3,20 +3,12 @@ Crowbook
|
|||
|
||||
[](https://travis-ci.org/lise-henry/crowbook)
|
||||
|
||||
Render a book written in markdown to HTML, Epub or PDF.
|
||||
Render a book written in markdown to HTML, EPUB and/or PDF.
|
||||
|
||||
Crowbook's purpose is to allow you to automatically generate multiple
|
||||
outputs formats from a book written in Markdown. Its focus is
|
||||
novels, and the default settings should (hopefully) generate readable
|
||||
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.
|
||||
|
||||
books with correct typography without requiring you to worry about it.
|
||||
|
||||
|
||||
Example
|
||||
|
|
@ -25,7 +17,9 @@ Example
|
|||
To see what Crowbook's output looks like, you can read the Crowbook
|
||||
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). You can also play with the [online demo version here](http://vps.crowdagger.fr/crowbook/).
|
||||
[PDF](http://lise-henry.github.io/crowbook/book/book.pdf) or [EPUB](http://lise-henry.github.io/crowbook/book/book.epub).
|
||||
|
||||
You can also play with the [online demo version here](http://vps.crowdagger.fr/crowbook/).
|
||||
|
||||
|
||||
|
||||
|
|
@ -50,7 +44,7 @@ Linux, Windows and MacOSX). Just extract the archive and run
|
|||
the binary somewhere in your `PATH` for later usage.
|
||||
|
||||
> Note: only the Linux binaries are really tested, please contact me
|
||||
> if there you have any trouble executing the Windows or Mac binaries.
|
||||
> if you have any trouble executing the Windows or Mac binaries.
|
||||
|
||||
### Using Cargo ###
|
||||
|
||||
|
|
@ -67,23 +61,16 @@ will automatically download the latest `crowbook` release on
|
|||
[crates.io](https://crates.io/crates/crowbook), compile it, and
|
||||
install it on your system.
|
||||
|
||||
> 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
|
||||
While there should be, 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/).
|
||||
|
||||
|
||||
`xelatex`).
|
||||
|
||||
Quick tour
|
||||
----------
|
||||
|
|
@ -95,7 +82,7 @@ $ crowbook <BOOK>
|
|||
```
|
||||
|
||||
where `BOOK` is a configuration file. Crowbook will parse this
|
||||
file and generate a book in HTML, Epub, LaTeX, and/or PDF,
|
||||
file and generate a book in HTML, EPUB, and/or PDF,
|
||||
according to the settings in the configuration file.
|
||||
|
||||
To create a new book, assuming you have a
|
||||
|
|
@ -129,14 +116,6 @@ rendered in
|
|||
[EPUB](http://lise-henry.github.io/crowbook/book/book.epub) and
|
||||
[PDF](http://lise-henry.github.io/crowbook/book.pdf).
|
||||
|
||||
> 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.
|
||||
|
||||
|
||||
### Input format ###
|
||||
|
||||
Crowbook uses
|
||||
|
|
@ -145,7 +124,7 @@ 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 ODT).
|
||||
|
||||
### Input cleaning ###
|
||||
### Typographic "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,
|
||||
|
|
@ -260,11 +239,16 @@ See [ChangeLog](ChangeLog.md).
|
|||
Library
|
||||
-------
|
||||
|
||||
While the main purpose of Crowbook is to be runned as a command line,
|
||||
While the main purpose of Crowbook is to be runned as a standalone
|
||||
program,
|
||||
the code is written as a library, so if you want to build on it you can
|
||||
use it as such. You can look at the generated documentation on
|
||||
[docs.rs](https://docs.rs/releases/search?query=crowbook).
|
||||
|
||||
Additionally, [crowbook-text-processing](https://github.com/lise-henry/crowbook-text-processing/) is
|
||||
a separate library containing all the "typographic" functions (smart
|
||||
quotes, handling of non-breaking spaces in french, ...).
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
Arguments
|
||||
=========
|
||||
|
||||
Crowbook can takes a list of arguments:
|
||||
Crowbook can take a number of arguments:
|
||||
|
||||
```text
|
||||
Render a Markdown book in EPUB, PDF or HTML.
|
||||
|
|
@ -30,25 +30,20 @@ ARGS:
|
|||
```
|
||||
|
||||
Note that Crowbook generates output files relatively to the directory
|
||||
where <BOOK> is[^1]:
|
||||
|
||||
[^1]: Unless the option `output.base_path` is set, see
|
||||
[the configuration file](config.md).
|
||||
|
||||
where <BOOK> is:
|
||||
|
||||
```bash
|
||||
$ crowbook foo/bar.book --to pdf --output baz.pdf
|
||||
```
|
||||
will thus generate baz.pdf in directory foo and not in current directory.
|
||||
will thus generate "baz.pdf" in directory "foo" and not in the current directory.
|
||||
|
||||
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
|
||||
the only argument you'll need to pass, and `crowbook` will generate
|
||||
The most important option is obviously <BOOK>, i.e. the book
|
||||
configuration file. 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
|
||||
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`.
|
||||
It is, however, possible to pass more arguments to `crowbook`:
|
||||
|
||||
`--create`
|
||||
---------
|
||||
|
|
@ -157,7 +152,7 @@ documents (though they still appear in the TOC).
|
|||
|
||||
**usage**: `crowbook <BOOK> --set [KEY] [VALUE]...`
|
||||
|
||||
This argument takes a list `KEY` `VALUE` pairs and allows setting or
|
||||
This argument takes a list of `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).
|
||||
|
|
@ -172,7 +167,7 @@ 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
|
||||
$ crowbook foo.book --set author Foo title Bar
|
||||
```
|
||||
|
||||
will override the book title to `Bar` and its author to `Foo`.
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ editor, there is a
|
|||
nice [Markdown mode](http://jblevins.org/projects/markdown-mode/) to
|
||||
edit Markdown files.
|
||||
|
||||
It is possible to use Crowbook for HTML previewing in his mode, which
|
||||
It is possible to use Crowbook for HTML previewing in this mode, which
|
||||
[requires only minimal configuration and tweaking](http://xkcd.com/1742/):
|
||||
|
||||
```lisp
|
||||
|
|
@ -16,24 +16,23 @@ It is possible to use Crowbook for HTML previewing in his mode, which
|
|||
'(markdown-command-needs-filename t))
|
||||
```
|
||||
|
||||
You can then use `markdown-preview` (or `C-c C-c p`[^1]) to run
|
||||
crowbook on this file and preview it in your browser, or run
|
||||
You can then use `markdown-preview` (or `C-c C-c p`) to run
|
||||
Crowbook on this file and preview it in your browser, or run
|
||||
`markdown-live-preview-mode` to see a live preview (updated each time
|
||||
you save you file) in Emacs' integrated browser.
|
||||
|
||||
### Some explanations if it looks a bit cryptic to you
|
||||
|
||||
We set `markdown-command` to `crowbook`, the reason for this is a bit
|
||||
obvious. The arguments we give to crowbook might not be a bit less
|
||||
obvious. The arguments we give to crowbook might be a bit less
|
||||
obvious:
|
||||
|
||||
* `-qs` or `--quiet --single` tells crowbook that is a a standalone
|
||||
* `-qs` or `--quiet --single` tells Crowbook that is a a standalone
|
||||
markdown file, and not a book configuration file, and to be a bit
|
||||
quiet on error/info messages;
|
||||
* `--to html` specifies that HTML must be generated;
|
||||
* `--output /dev/stdout` forces crowbook to displays the result on the
|
||||
stdout, even if you set `output.html` to `some_file.html` (yes, this
|
||||
is a bit ugly).
|
||||
* `--output /dev/stdout` forces Crowbook to display the result on the
|
||||
stdout, even if you set `output.html` to `some_file.html`.
|
||||
|
||||
Also, `(markdown-command-needs-filename t)` is because at this point
|
||||
Crowbook can't read from the stdin and must be specified a file.
|
||||
|
|
@ -41,7 +40,7 @@ Crowbook can't read from the stdin and must be specified a file.
|
|||
### Limitations
|
||||
|
||||
While it renders correctly, this only works really nicely on standalone
|
||||
markdown files where you have specified, e.g.:
|
||||
Markdown files where you have specified, e.g.:
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
|
@ -50,8 +49,7 @@ title: Some title
|
|||
---
|
||||
```
|
||||
|
||||
Else, it will sets `author` and `title` to the default values
|
||||
(`anonymous` and `untitled`, respectively).
|
||||
Else, it will sets `author` and `title` to the default values.
|
||||
|
||||
## Embedding fonts in an EPUB file
|
||||
|
||||
|
|
@ -90,4 +88,3 @@ resources.files: my_font.ttf
|
|||
display correctly when there is some text in **bold**, *italics*, or **_both_**.)
|
||||
|
||||
|
||||
[^1]: Yes, this looks like a crypto-communist statement.
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ $ cargo build --release --features "proofread"
|
|||
Enabling proofreading
|
||||
---------------------
|
||||
|
||||
Since proofreading can take quite a lot of time, particularly for long
|
||||
Since proofreading can take quite a lot of time, particularly for a long
|
||||
book, it is disabled by default. You'll have to run
|
||||
|
||||
```bash
|
||||
|
|
@ -109,7 +109,7 @@ Grammar checking
|
|||
|
||||
Crowbook can also use [LanguageTool](https://languagetool.org/) to
|
||||
detect grammar errors in your text. It is, however, a bit more
|
||||
difficult to activate.
|
||||
complex to activate.
|
||||
|
||||
First, you'll have to activate this feature in your book configuration
|
||||
file:
|
||||
|
|
@ -146,7 +146,7 @@ Highlighting non-breaking spaces
|
|||
|
||||
The last proofreading feature is a bit less important, but it can be
|
||||
useful in some cases. It is is dis/activated by setting
|
||||
`proofread.nb_spaces` to "true" or false, and it will highlight
|
||||
`proofread.nb_spaces` to "true" or "false", and it will highlight
|
||||
different sort of non-breaking spaces in HTML proofreading output
|
||||
files. This can be useful in some cases, but it is mostly a debugging
|
||||
feature to check that the french cleaner of Crowbook correctly
|
||||
|
|
|
|||
Loading…
Reference in New Issue