crowbook/README.md

Crowbook
========

Creates a book in HTML, Epub or PDF format from markdown files.

[![Build Status](https://travis-ci.org/lise-henry/crowbook.svg?branch=master)](https://travis-ci.org/lise-henry/crowbook)

Usage
-----

The simplest command is:

```bash
$ crowbook <BOOK>
$ # or runninng from cargo:
$ cargo run <BOOK>
```

Where `BOOK` is a configuration file. Crowbook will then parse the
config file and generate book in HTML, Epub, LaTeX, and/or PDF,
according to the setting in the configuration file.

This configuration file contains some metadata, options, and list the
Markdown files. Here is a basic example:

```
author: Joan Doe
title: Some book
lang: en

output_html: some_book.html

+ chapter_1.md
+ chapter_2.md
+ chapter_3.md
+ ...
```

For more information see
[the configuration file](book-example/config.md), or the whole
[book_example](book_example) directory.

It is also possible to give additional paramaters to `crowbook`;
arguments set from the command line will override the ones set in the
`BOOK` configuration file.

```
USAGE:
        crowbook [FLAGS] [OPTIONS] <BOOK>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information
    -v, --verbose    Activate verbose mode

OPTIONS:
        --autoclean <BOOL>    Try to clean input markdown [values: true, false]
        --numbering <BOOL>    Number chapters or not [values: true, false]
    -o, --output <FILE>       Specify output file
    -t, --to <FORMAT>         Generate specific format [values: epub, epub, pdf, html, tex]

ARGS:
    <BOOK>    A file containing the book configuration

Command line options allow to override options defined in <BOOK> configuration file. 
E.g., even if this file specifies 'verbose: false', calling 'crowbook --verbose <BOOK>' 
will activate verbose mode.

Note that Crowbook generates output files relatively to the directory where <BOOK> is:
$ crowbook foo/bar.book --to pdf --output baz.pdf
will thus generate baz.pdf in directory foo and not in current
directory.
```

Features
--------

### Done ###
* Support for some simple formatconfiguration files to
  list chapters and metadatas, so you just run `crowbook
  some_file` and you don't have to pass more options, it generates the
  rest.
* Support for basic Markdown features useful in writing novels.
* Support for Epub2 and Epub3 format as output.
* Very basic support for LaTeX format as output, and PDF through it.
* Support for HTML format as output.
* Support for basic french typography in HTML/Epub format, and by
that I mostly mean non-breaking spaces.
* Decent default templates and CSS.
* Some configuration for HTML/Epub templates and CSS.

### ToDo ###
* Real support for LaTeX.
* Allow more customization.
* Provide a binary which accepts some option and not just an input
file.
* Support for easily embedding custom fonts (and other files) in
Epub/HTML.
* Correct support for technical books.
* Support for ODT as output format?

See also [Bugs](Bugs.md).

License 
-------

Currently, MIT but this might change.

Acknowledgements
----------------

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

* [pulldown-cmark](https://crates.io/crates/pulldown-cmark) (for
parsing markdown)
* [mustache](https://crates.io/crates/pulldown-cmark) (for templating)
* [chrono](https://crates.io/crates/chrono) (date and time library)
* [uuid](https://crates.io/crates/uuid) (to generate uuid)

While Crowbook directly doesn't use them, there was also some
inspiration from [Pandoc](http://pandoc.org/) and [mdBook](https://github.com/azerupi/mdBook).