1
0
Fork 0
mirror of https://github.com/lise-henry/crowbook synced 2024-03-28 18:40:10 +01:00

Update documentation

This commit is contained in:
Elisabeth Henry 2016-03-01 21:41:23 +01:00
parent 690cdb76ac
commit aa6cc9f3a7
6 changed files with 121 additions and 104 deletions

View File

@ -3,12 +3,12 @@ ChangeLog
0.4.0 (unreleased)
------------------
* Crowbook now internally uses a true YAML parser, `yaml_rust` for its
options. Since the "old" Crowbooks's config format was similar, but somewhat
different, to markdown, this is somewhat of a breaking change:
* Crowbook now internally uses a true YAML parser, `yaml_rust`, for its
options. Since the "old" Crowbooks's config format was similar, but
had some subtle differences, this is somewhat of a breaking change:
* strings should now be escaped with "" in some cases (e.g. if it
contains special characters). On the other hand, it *allows* to
optionally espace a string with these quotes, which wasn't
optionally escape a string with these quotes, which wasn't
possible until then and might be useful in some cases.
* multiline strings now follow the YAML format, instead of the
previous "YAML-ish" format. This can impact the way newlines are

View File

@ -1,5 +1,6 @@
GNU LESSER GENERAL PUBLIC LICENSE
=================================
GNU LESSER GENERAL PUBLIC LICENSE
==================================
Version 2.1, February 1999

View File

@ -7,16 +7,27 @@ Render a markdown book in 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
novels, and the default settings should (hopefully) generate readables
book with correct typography.
novels, and the default settings should (hopefully) generate readable
books with correct typography.
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).
Installing
----------
There are two ways to get `crowbook`: either use a precompiled binary
or build it yourself.
### Packages ###
If you are on Debian GNU/Linux or Ubuntu (on a PC architecture), you can
download `.deb` packages on
[the releases page](https://github.com/lise-henry/crowbook/releases).
### Binaries ###
@ -49,13 +60,13 @@ The simplest command is:
$ crowbook <BOOK>
```
Where `BOOK` is a configuration file. Crowbook will then parse this
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. So if you clone
this repository and run
```bash
$ crowbook book_example/config.book
$ crowbook config.book
```
you'll generate the example book in various formats. The
@ -70,9 +81,8 @@ 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
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. Here is a basic example:
```
@ -89,13 +99,11 @@ output_html: some_book.html
```
For more information see
[the configuration file page](book_example/config.md), or the whole
`book_example` source directory. (A (not necessarily
up-to-date) [rendered version is available in HTML here](http://lise-henry.github.io/crowbook/book.html)).
[the configuration file](book_example/config.md).
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 page](book_example/arguments.md).
[the arguments](book_example/arguments.md).
Current features
----------------
@ -148,13 +156,36 @@ 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.
See also [Bugs](Bugs.md).
### Inline YAML blocks ###
Crowbook supports inline YAML blocks. These are blocks
delimited with lines containing `---` (three dashes). An example of
such block:
```markdown
---
author: Me
title: My title
---
```
These blocks must contain *valid* YAML syntax. If they are not at the
beginning of the Markdown file, they must also be preceded by an empty
line.
It is possible to use inline YAML blocks to modify options for the
book (`author` and `title` in the previous example). This is mostly
useful when Crowbook is runned with the `--single` argument (receiving
a single Markdown file instead of a book configuration file).
### Bugs ###
See [Bugs](Bugs.md).
Acknowledgements
----------------
Besides the Rust compiler and standard library, Crowbook uses the
Besides the [Rust](https://www.rust-lang.org/) compiler and standard library, Crowbook uses the
following libraries:
* [pulldown-cmark](https://crates.io/crates/pulldown-cmark) (for
@ -167,7 +198,7 @@ parsing markdown)
It also uses configuration files from
[rust-everywhere](https://github.com/japaric/rust-everywhere) to use
[Travis]]https://travis-ci.org/) and
[Travis](https://travis-ci.org/) and
[Appveyor](http://www.appveyor.com/) to generate binaries for
various platforms on each release.
@ -189,8 +220,7 @@ 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. The code is currently badly documented (and badly in a
general manner), but you can look at the generated documentation [here](http://lise-henry.github.io/rust/crowbook/).
use it as such. You can look at the generated documentation [here](http://lise-henry.github.io/rust/crowbook/).
License
-------
@ -198,6 +228,6 @@ 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](LICENSE.md) file for more information.
[LICENSE](LICENSE.md) for more information.

View File

@ -10,23 +10,21 @@ USAGE:
crowbook [FLAGS] [OPTIONS] [--] [ARGS]
FLAGS:
-d, --debug Print debugging information
-h, --help Prints help information
-l, --list-options Lists all possible option
--list-options-md List all options, formatted in Markdown.
-s, --single Use a single Markdown file instead of a book configuration file
-V, --version Prints version information
-v, --verbose Print warnings in parsing/rendering
-h, --help Prints help information
-l, --list-options Lists all possible option
-s, --single Use a single Markdown file instead of a book configuration file
-V, --version Prints version information
-v, --verbose Print warnings in parsing/rendering
OPTIONS:
--create <FILES>... Creates a new book with existing markdown files.
-o, --output <FILE> Specifies output file.
--print-template <TEMPLATE> Displays the default value of a template.
-c, --create <FILES>... Creates a new book with existing markdown files
-o, --output <FILE> Specifies output file
--print-template <TEMPLATE> Displays the default value of a template
--set <KEY_VALUES> Sets a list of book options
-t, --to <FORMAT> Generate specific format [values: epub, pdf, html, tex, odt]
-t, --to <FORMAT> Generate specific forma [values: epub, pdf, html, tex, odt]
ARGS:
<BOOK> File containing the book configuration, or a Markdown file when called with --single.
<BOOK> File containing the book configuration, or a Markdown file when called with --single
```
Note that Crowbook generates output files relatively to the directory
@ -51,8 +49,8 @@ It is, however, possible to pass more arguments to `crowbook`.
**Usage**: `crowbook [BOOK] --create file_1.md file_2.md ...`
Creates a new book from a list of Markdown files. It will generate a
book configuration file with alle file names specified as
chapter. It either prints the result to stdout (if `BOOK` is not
book configuration file with all file names specified as
chapters. It either prints the result to stdout (if `BOOK` is not
specified) or generate the file `BOOK` (or abort if it already
exists).
@ -131,7 +129,7 @@ title: A short story
If this YAML block is not at the beginning of a file, it must also be
preceded by a blank line.
This allows to not have to generate a `.book` configuration file for a
This allows to not have to write a `.book` configuration file for a
short story or an article. `crowbook --single foo.md` is rougly equivalent to having a book
configuration file containing:
@ -145,12 +143,12 @@ documents (though they still appear in the TOC).
`--set`
-------
**usage**: `crowbook <BOOK> --set [KEY] [VALUE]...
**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
configuration files are valid as keys. For more information, see
[the configuration file page](config.md).
[the configuration file](config.md).
### Examples ###
@ -173,9 +171,8 @@ will override the book title to `Bar` and its author to `Foo`.
(or `crowbook -l`)
Displays all the valid options to use either in a book configuration
file or with `--set`, with a short description. There is also
`--list-options-md`, which outputs markdown.
Displays all the valid options to use, whether in a book configuration
file, with `--set`, or in an inline YAML block.
`--print-template`
------------------
@ -198,7 +195,7 @@ Note that it is possible to use this option in conjonction with
```
$ crowbook --print-template epub.template --set epub.version 2
# Returns the template for Epub 2 (default one)
# Returns the template for Epub 2 (currently it is the default one)
$ crowbook --print-template epub.template --set epub.version 3
# Returns the template for Epub 3
```
@ -209,7 +206,10 @@ $ crowbook --print-template epub.template --set epub.version 3
**usage**: `crowbook <BOOK> --verbose`
If this flag is set, Crowbook will print some more messages.
If this flag is set, Crowbook will print the warnings it detect 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.
`--to`
------
@ -233,13 +233,13 @@ crowbook --to html foo.book
```
will generate some HTML, and prints it either to the file specified by
`output.html` in `foo.book`, or to stdout.
`output.html` in `foo.book`, or to stdout if it is not specified.
```
crowbook --to pdf --output foo.pdf foo.book
```
will (try to) generate a `foo.pdf` file,.
will generate a `foo.pdf` file,.
`--output`
---------

View File

@ -2,7 +2,7 @@ The configuration file
======================
If you want to use Crowbook for your book, this configuration file
is all you'll have to add (assuming you'll already have the book in
is all you'll have to add (assuming you already have the book in
Markdown files; if you don't, you'll also have to write a book first,
but that's besides the scope of this document).
@ -29,8 +29,7 @@ Basically, it is divided in two parts:
* a list of options, under the form `key: value`, following YAML syntax.
* a list of Markdown files.
Files starting with the `#` characters are comments and are discarded
when parsing the files.
Lines starting with the `#` characters are comments and are discarded.
The list of files
-----------------
@ -40,7 +39,7 @@ There are various options to include a markdown file.
* `+ file_name.md` includes a numbered chapter.
* `- file_name.md` includes an unnumbered chapter.
* `! file_name.md` includes a chapter whose title won't be displayed
(except in the toc for epub); this is useful for e.g. including a
(except in the table of contents); this is useful for e.g. including a
copyright at the beginning or the book, or for short stories where
there is only one chapter.
* `42. file_name.md` specifies the number for a chapter.
@ -54,13 +53,13 @@ So a typical usage might look like this:
0. chapter_0.md
# Next chapters can be numbered automatically
+ chapter_1.md
+ chapter_3.md
+ chapter_2.md
...
```
There are two important things to note:
1. you must *not* use quotes around the file names
1. you must *not* use quotes around the file names.
2. the path of these files are relative to the directory where your
config file is, *not* to the directory where you are when running
`crowbook`. E.g. you can run `crowbook
@ -88,34 +87,40 @@ The day I was born
You should have one and only one level-one header (i.e. chapter title)
in each markdown file.
If you have more than one, Crowbook won't get too angry at you and
will just print a warning and treat it as another chapter (numbered
according to the scheme specified for including the file). It will
however mess the table of contents if Crowbook tries to generate one
(e.g. for Epub).
If you have more than one, Crowbook will print a warning and treat it
as another chapter (numbered according to the scheme specified for
including the file). It might however mess the table of contents in
some cases (e.g. for Epub).
It's also a problem if you do *not* have a level-1 header in a
markdown file. If it is a numbered chapter Crowbook will still be
able to infer a chapter name, but if it is not numbered Crowbook
will fail to generate an Epub file.
****
So, to sum it up. *please*: one file = one chapter, a chapter starts with a
title, and this way this will work nice.
If you do *not* have a level-1 header in a
markdown file:
* if it is a numbered chapter, Crowbook will infer a chapter name from
the numbering scheme;
* if it is not numbered, chapter's title will default to the empty
string and won't be displayed in the TOC.
Crowbook options
----------------
The first part of the configuration file is dedicated to pass options
to Crowbook. This is YAML syntax, so each one is of the form `option:
value`. Note that in most cases you don't have to put string in quotes, e.g.:
to Crowbook. This is
[YAML syntax](https://en.wikipedia.org/wiki/YAML), so each line should
be of the form `key: value`. Note that in most cases you don't have to
put string in quotes, e.g.:
```
title: My title
```
It is however possible (and sometimes necessary to escape some
characters) to use quotes around strings:
```
title: "My title!"
```
It is possible to use multiline strings with `>-` and
then indenting the lines that are part of the string:
@ -129,10 +134,8 @@ author: Joan Doe
will set `title` to `"A long title"`. See
[block literals in YAML](https://en.wikipedia.org/wiki/YAML#Block_literals)
for more information and nuances.
This feature is useful for options like `description` who may take a
long string.
for more information on the various way to insert multiline strings
(which mostly change the way newlines will or won't be inserted).
Here is the complete list of options, with a short description. The
usage of some of them is detailed later on.
@ -209,7 +212,7 @@ usage of some of them is detailed later on.
- **`verbose`**
- **type**: boolean
- **default value**: `false`
- Toggle verbose mode
- If set to true, print warnings in Markdown processing
- **`side_notes`**
- **type**: boolean
- **default value**: `false`
@ -220,7 +223,7 @@ usage of some of them is detailed later on.
- Path where to create a temporary directory (default: uses result from Rust's std::env::temp_dir())
- **`numbering_template`**
- **type**: string
- **default value**: `{{number}}. {{title}}`
- **default value**: `"{{number}}. {{title}}"`
- Format of numbered titles
- **`nb_char`**
- **type**: char
@ -265,10 +268,10 @@ usage of some of them is detailed later on.
- **default value**: `not set`
- Path of a LaTeX template file
Note that these options take a type, which in most case should be
Note that these options have a type, which in most case should be
pretty straightforward (a boolean can be `true` or `false`, an integer
must be composed a number, a string is, well, any string, just
remember not to put the quotes). The `path` type might puzzle you a
must be composed a number, a string is, well, any string). The `path`
type might puzzle you a
bit, but it's equivalent a string, except Crowbook will consider it
relatively to the book file.
@ -311,7 +314,6 @@ default, though you can specify the command to use with `tex.command`) to genera
so PDF rendering won't work if it is not installed on your
system. Crowbook also uses the `zip` command to generate the EPUB and
ODT, files.
want to use.)
### Generic options for rendering ###
@ -322,7 +324,7 @@ book. E.g., `1` will only number chapters, while `2` will number
chapters, sections, but not anything below that. `6` is the maximum level
and turns numbering on for all headers.
**default**:: `1`
**default**: `1`
#### numbering_template ####
@ -331,12 +333,14 @@ A string that will be used for chapter titles. You can use `{{number}}` and
`{{title}}` in this string, e.g.:
```
numbering_template: Chapter {{number}} {{title}}
numbering_template: "Chapter {{number}} {{title}}"
```
Note that:
* this string isn't used for unnumbered chapters;
* this string isn't used by LaTeX, either.
* in this case, quoting is necessary because `{` and `}` have special
meaning in YAML;
* this string won't be used for unnumbered chapters;
* this string isn't currently used by LaTeX, either.
#### autoclean ####
@ -348,23 +352,6 @@ However, if `lang` is set to `fr`, it also tries to add non-breaking
spaces in front (or after) characters like '?', '!', ';' to respect
french typography.
#### nb_char ####
This option allows you to specify the non breaking character used by
the french cleaning method (see above). Probably not really something
you need to modify.
### Additional options ###
#### temp_dir ####
When it is generating epub or pdf files, Crowbook creates a temporary
directory (which is then removed), named from a random uuid (so we can
be pretty certain it's not gonna exist). By default, it uses Rust's
[`std::env::temp_dir`](https://doc.rust-lang.org/std/env/fn.temp_dir.html)
function, which should an appropriate place for temporary files, so
you probably won't have to use this option.

View File

@ -1,7 +1,7 @@
# Metadata
author: Élisabeth Henry
title: Crowbook
description: >
description: >-
Crowbook allows to render a book written in Markdown in various
formats. This is some kind of manual for it, and a way to
demonstrate and test it.
@ -10,7 +10,6 @@ lang: en
# Generic options (though not used with LaTeX)
## Number chapters and sections, but not below that
numbering: 2
display_toc: true
# Latex options
tex.links_as_footnotes: false