mirror of
https://github.com/lise-henry/crowbook
synced 2024-03-28 18:40:10 +01:00
Update documentation
This commit is contained in:
parent
690cdb76ac
commit
aa6cc9f3a7
|
@ -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
|
||||
|
|
|
@ -1,5 +1,6 @@
|
|||
GNU LESSER GENERAL PUBLIC LICENSE
|
||||
=================================
|
||||
GNU LESSER GENERAL PUBLIC LICENSE
|
||||
==================================
|
||||
|
||||
|
||||
Version 2.1, February 1999
|
||||
|
||||
|
|
68
README.md
68
README.md
|
@ -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.
|
||||
|
||||
|
||||
|
|
|
@ -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`
|
||||
---------
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue