# Crowbook User Guide – <b>1.</b> Crowbook
Author: Élisabeth Henry

# 1. 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 focus is novels, and the default settings should (hopefully) generate readable books with correct typography (particularly for the french language[1]).

## 1.1. Example

To see what Crowbook's output looks like, you can read the Crowbook guide rendered in HTML, PDF or EPUB.

## 1.2. Installing

There are three ways to install Crowbook:

### Packages

If you are on Debian GNU/Linux or Ubuntu (on a PC architecture), you can download `.deb` packages on the releases page.

### Binaries

See the releases page to download a precompiled binary for your architecture (currently: 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.

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

### Using Cargo

Cargo is the Rust's package manager. You can install it here. Once it is down:

    $ cargo install crowbook

will automatically download the latest `crowbook` release on crates.io, 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`.

## 1.3. 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.

## 1.4. Quick tour

The simplest command is:

    $ crowbook <BOOK>

where `BOOK` is a configuration file. Crowbook will parse this file and generate a book in HTML, Epub, LaTeX, and/or PDF, according to the settings in the configuration file.

To create a new book, assuming you have a list of Markdown files, you can generate a template configuration file with the `--create` argument:

    $ 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.

For more information see the configuration file.

It is also possible to give additional parameters to `crowbook`; we have already seen `--create`, but if you want the full list, see the arguments.

## 1.5. Current features

### Output formats

Crowbook supports HTML, PDF and EPUB (either version 2 or 3) as output formats. See the Crowbook User Guide rendered in HTML, EPUB and 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 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 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 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 describing typographic rules if you want it to be implemented for another language.

### Links handling

Crowbook tries to correctly translate local links in the input Markdown files: e.g. if you have a link to a markdown file that is part of your book, it will be transformed into a link inside the document.

### Inline YAML blocks

Crowbook supports inline YAML blocks:

    ---
    author: Me
    title: My title
    ---

This is mostly useful when Crowbook is runned with the `--single` argument (receiving a single Markdown file instead of a book configuration file). E.g., the following Markdown file:

    ---
    author: John Doe
    title: A book

    output.html: book.html
    ---

    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 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.

### Bugs

See the github's issue tracker.

## 1.6. Contributors

- Stéphane Mourey `<s+crowbook AT stephanemourey DOT fr>`

## 1.7. Acknowledgements

Besides the Rust compiler and standard library, Crowbook uses the following libraries:

- pulldown-cmark
- yaml-rust
- mustache
- clap
- chrono
- uuid
- mime_guess
- crossbeam
- walkdir
- rustc-serialize
- caribon
- hyper
- url

It also embeds Highlight.js in HTML output to enable syntax highlighting for code blocks.

It also uses configuration files from rust-everywhere to use Travis and Appveyor to generate binaries for various platforms on each release.

While Crowbook directly doesn't use them, there was also inspiration from Pandoc and mdBook.

Also, the W3C HTML validator and the IDPF EPUB validator proved very useful during development.

## 1.8. ChangeLog

See ChangeLog.

## 1.9. Library

While the main purpose of Crowbook is to be runned as a command line, 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.

## 1.10. License

Crowbook is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License (LGPL), version 2.1 or (at your option) any ulterior version. See LICENSE for more information.

Crowbook's logo is licensed under the Creative Commons Attribution 4.0 International license, based on the Rust logo by Mozilla Corporation.

Crowbook includes binary (minified) CSS and Javascript files from Highlight.js, written by Ivan Sagalaev, licensed under the following terms:

> Copyright (c) 2006, Ivan Sagalaev

> All rights reserved.

> Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

> - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
> - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
> - Neither the name of highlight.js nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

> THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

## Notes

[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, or to submit a pull request.

2. Arguments »