mirror of
https://github.com/lise-henry/crowbook
synced 2024-05-09 07:36:21 +02:00
Update book to version 0.13.0
This commit is contained in:
Elisabeth Henry
parent
5267ab54fa
commit
6c1ad18cf2
|
|
@ -10,8 +10,7 @@ crowbook [OPTIONS] [BOOK]
|
|||
The most important argument is obviously the book
|
||||
configuration file. It is mandatory in most cases: if you don't
|
||||
pass it, Crowbook will simply display an error. In a normal use case this is
|
||||
the only argument you'll need to pass, as most options will be set in the
|
||||
the book in all formats specified in the configuration file.
|
||||
the only argument you'll need to pass, as most options will be set in this configuration file.
|
||||
|
||||
It is, however, possible to pass more arguments to `crowbook`:
|
||||
|
||||
|
|
@ -20,66 +19,52 @@ It is, however, possible to pass more arguments to `crowbook`:
|
|||
|
||||
**Usage**: `crowbook [BOOK] --create file_1.md file_2.md ...`
|
||||
|
||||
(or `crowbook [BOOK] -c file_1.md file_2.md ...`)
|
||||
|
||||
Creates a new book from a list of Markdown files. It will generate a
|
||||
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).
|
||||
|
||||
### Examples ###
|
||||
|
||||
```bash
|
||||
crowbook foo.book --create README.md ChangeLog.md LICENSE.md
|
||||
crowbook foo.book --create chapter_1.md chapter_2.md chapter_3.md
|
||||
```
|
||||
|
||||
will generate a file `foo.book` containing:
|
||||
will thus generate a file `foo.book` containing:
|
||||
|
||||
```yaml
|
||||
author: Your name
|
||||
title: Your title
|
||||
lang: en
|
||||
|
||||
## Output formats
|
||||
|
||||
# Uncomment and fill to generate files
|
||||
# output.html: some_file.html
|
||||
# output.epub: some_file.epub
|
||||
# output.pdf: some_file.pdf
|
||||
|
||||
# Uncomment and fill to set cover image (for Epub)
|
||||
# Or uncomment the following to generate PDF, HTML and EPUB files based on this file's name
|
||||
# output: [pdf, epub, html]
|
||||
|
||||
# Uncomment and fill to set cover image (for EPUB)
|
||||
# cover: some_cover.png
|
||||
|
||||
# List of chapters
|
||||
+ README.md
|
||||
+ ChangeLog.md
|
||||
+ LICENSE.md
|
||||
## List of chapters
|
||||
+ chapter_1.md
|
||||
+ chapter_2.md
|
||||
+ chapter_3.md
|
||||
```
|
||||
|
||||
while
|
||||
|
||||
```bash
|
||||
crowbook --create README.md ChangeLog.md LICENSE.md
|
||||
crowbook --create chapter_1.md chapter_2.md chapter_3.md
|
||||
```
|
||||
|
||||
will print the same result, but to stdout (without creating a file).
|
||||
|
||||
When `crowbook` is run with `--create`, it can also use the
|
||||
keys/values set by `--set` (see below):
|
||||
|
||||
```bash
|
||||
$ crowbook foo.book --create file1.md file2.md --set author "Pierre Dupont" title "Mon œuvre" lang fr
|
||||
```
|
||||
|
||||
will generate a `foo.book` file containing:
|
||||
|
||||
```yaml
|
||||
author: Pierre Dupont
|
||||
title: Mon œuvre
|
||||
lang: fr
|
||||
|
||||
# List of chapters
|
||||
+ file1.md
|
||||
+ file2.md
|
||||
```
|
||||
|
||||
`--single`
|
||||
----------
|
||||
|
||||
|
|
@ -87,7 +72,7 @@ lang: fr
|
|||
|
||||
(or `crowbook -s <FILE>`)
|
||||
|
||||
This argument allows to give `crowbook` a single Markdown file. This
|
||||
This argument allows you to give `crowbook` a single Markdown file. This
|
||||
file can contain an inline YAML block to set some book options. Inline
|
||||
YAML blocks must start and end with a line containing only `---` (three dashes). E.g:
|
||||
|
||||
|
|
@ -95,7 +80,7 @@ YAML blocks must start and end with a line containing only `---` (three dashes).
|
|||
---
|
||||
author: Joan Doe
|
||||
title: A short story
|
||||
output.html: short.html
|
||||
output: [html, epub, pdf]
|
||||
---
|
||||
|
||||
Content of the story in Markdown.
|
||||
|
|
@ -129,23 +114,12 @@ 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).
|
||||
|
||||
### Example ###
|
||||
|
||||
```bash
|
||||
$ crowbook foo.book --set tex.paper_size a4paper
|
||||
$ crowbook foo.book --set tex.paper.size a4paper
|
||||
```
|
||||
|
||||
will override the paper size for PDF generation.
|
||||
|
||||
`--proofread`
|
||||
-------------
|
||||
|
||||
**Usage**: `crowbook --proofread <BOOK>`
|
||||
|
||||
(or `crowbook -p <BOOK>`)
|
||||
|
||||
Equivalent to `--set proofread true`. Enable proofreading. See [Proofreading](proofreading.md).
|
||||
|
||||
`--list-options`
|
||||
----------------
|
||||
|
||||
|
|
@ -153,7 +127,7 @@ Equivalent to `--set proofread true`. Enable proofreading. See [Proofreading](pr
|
|||
|
||||
(or `crowbook -l`)
|
||||
|
||||
Displays all the valid options to use, whether in a book configuration
|
||||
Displays all the valid options that can be used, whether in a book configuration
|
||||
file, with `--set`, or in an inline YAML block.
|
||||
|
||||
`--print-template`
|
||||
|
|
@ -173,6 +147,7 @@ $ crowbook my.book --set html.css my_style.css
|
|||
```
|
||||
|
||||
`--stats`
|
||||
------------
|
||||
|
||||
**Usage**: `crowbook --stats <BOOK>`
|
||||
|
||||
|
|
@ -180,6 +155,15 @@ $ crowbook my.book --set html.css my_style.css
|
|||
|
||||
Display some statistics (word and character counts) about the book.
|
||||
|
||||
`--proofread`
|
||||
-------------
|
||||
|
||||
**Usage**: `crowbook --proofread <BOOK>`
|
||||
|
||||
(or `crowbook -p <BOOK>`)
|
||||
|
||||
Equivalent to `--set proofread true`. Enable proofreading. See [Proofreading](proofreading.md).
|
||||
|
||||
`--verbose`
|
||||
-----------
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ author: Joan Doe
|
|||
title: Some book
|
||||
lang: en
|
||||
|
||||
output.html: some_book.html
|
||||
output: [html, pdf, epub]
|
||||
|
||||
# list of chapters
|
||||
- preface.md
|
||||
|
|
@ -45,7 +45,7 @@ author: Joan Doe
|
|||
title: Some (short) book
|
||||
lang: en
|
||||
|
||||
output.html: some_book.html
|
||||
output: [html, pdf, epub]
|
||||
---
|
||||
|
||||
# Some (short) book
|
||||
|
|
@ -121,20 +121,8 @@ does not specify a chapter title, because it will read it directly in
|
|||
```
|
||||
|
||||
Ideally, 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 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).
|
||||
|
||||
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.
|
||||
|
||||
in each Markdown file. If you have more than one, it might mess with
|
||||
the table of contents in some cases (e.g. for EPUB).
|
||||
|
||||
### Parts ###
|
||||
|
||||
|
|
@ -312,13 +300,13 @@ license: CC-BY-SA # Override the license from common.book
|
|||
These options specify which files to generate.
|
||||
|
||||
Note that all file paths are relative to the directory where the
|
||||
config file is, not to the one where you run `crowbook`. So if you set
|
||||
configuration file is, not to the one where you run `crowbook`. So if you set
|
||||
|
||||
```yaml
|
||||
output.epub: foo.epub
|
||||
```
|
||||
|
||||
and runs
|
||||
and run
|
||||
|
||||
```bash
|
||||
$ crowbook some/dir/config.book
|
||||
|
|
@ -433,11 +421,11 @@ These options allow to configure the rendering; they are used (or at
|
|||
least should be) for all formats.
|
||||
|
||||
* `rendering.highlight` (default: `syntect`): specify if and how to perform syntax
|
||||
highlighting for code blocks. Other valid values are:
|
||||
highlighting for code blocks. Valid values are:
|
||||
* `syntect`: uses the [syntect](https://crates.io/crates/syntect)
|
||||
library to perform syntax highlighting. This has the advantage of
|
||||
also enabling syntax highlighting for LaTeX/PDF and EPUB formats;
|
||||
however syntect support is still experimental in Crowbook.
|
||||
however syntect support doesn't seem to work on Windows.
|
||||
* `highlight.js`: this will use (and
|
||||
embed) [`highlight.js`](https://highlightjs.org/) for HTML
|
||||
rendering, and will not perform any syntax highlighting for other
|
||||
|
|
@ -455,7 +443,8 @@ will default to `none` if you try to use it.
|
|||
* `rendering.num_depth`: an integer that represents the maximum level of numbering for your
|
||||
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 is `1`.)
|
||||
and turns numbering on for all headers. (Default is `1`.) This also
|
||||
affects what levels will be displayed in the table of contents.
|
||||
* `rendering.chapter` and `rendering.part`: the
|
||||
strings that will be used to design chapter and part. E.g., if you want
|
||||
your parts to show as "Book III" instead of "Part III", you can set
|
||||
|
|
@ -486,10 +475,12 @@ the default HTML standalone renderer and the HTML multifile renderer):
|
|||
metadata, such as `{{{author}}}`, `{{{title}}}`, or `{{{version}}}`
|
||||
in it. See the [template](templates.md) chapter for more information
|
||||
on the fields you can use.
|
||||
* `html.css` allow to set up a custom CSS file. You can also redefine
|
||||
* `html.css` allows to set up a custom CSS file. You can also redefine
|
||||
the colours in a file and set it using `html.css.colours`.
|
||||
* `html.highlight.theme` is similar to `rendering.highlight.theme` and
|
||||
only sets the theme for EPUB output.
|
||||
* `html.css.add` allows you to add some specific lines of CSS in your
|
||||
book configuration file, that will be appended after the default CSS template.
|
||||
* `html.highlight.theme` is similar to `rendering.highlight.theme` but
|
||||
only sets the theme for HTML output.
|
||||
|
||||
#### Options for standalone HTML ####
|
||||
|
||||
|
|
@ -509,8 +500,10 @@ the generated PDF documents):
|
|||
|
||||
* `tex.template` specifies a different LaTeX template.
|
||||
* `tex.class` changes the LaTeX class used.
|
||||
* `tex.paper_size` and `tex.font.size` (default `a5paper` and `10pt`)
|
||||
* `tex.paper.size` and `tex.font.size` (default `a5paper` and `10pt`)
|
||||
allows to modify the page and font size .
|
||||
* `tex.margin.left`, `tex.margin.right`, `tex.margin.top` and
|
||||
`tex.margin.bottom` specify the margin of the page.
|
||||
* `tex.links_as_footnotes` can be set to `false` if you don't want
|
||||
links to also appear as footnotes (which means losing them
|
||||
if it is actually printed).
|
||||
|
|
@ -1063,7 +1056,7 @@ pretty straightforward (a boolean can be `true` or `false`, an integer
|
|||
must be composed by a number, a string is, well, any string (note that
|
||||
you might need to use quotes if it includes some characters that may
|
||||
lead the YAML parser to read it as an array, an integer or a list), and a
|
||||
list of strings is a list containing only strings). The `path`
|
||||
list of strings is a list containing only strings, see [YAML syntax](https://en.wikipedia.org/wiki/YAML#Basic_components)). The `path`
|
||||
type might puzzle you a bit, but it's equivalent to a string, except
|
||||
Crowbook will consider it relatively to the book file. The `template
|
||||
path` type is just the `path` of a template. Metadata are just
|
||||
|
|
|
|||
|
|
@ -3,6 +3,11 @@ Interactive fiction
|
|||
|
||||
Version `0.12.0` added experimental support for writing interactive fiction.
|
||||
|
||||
> Since this support is experimental, it means it can change at
|
||||
> anytime, and there is no guarentee that the interactive fiction you
|
||||
> write for the current version of Crowbook will work with the next
|
||||
> release, even if it isn't a major release.
|
||||
|
||||
## Basics ##
|
||||
|
||||
If you want to have a non-linear story, you can simply use Markdown
|
||||
|
|
|
|||
|
|
@ -100,6 +100,12 @@ two kind of images, according to their position in the document:
|
|||
Standalone images will typically be resized to fill the width of the
|
||||
page, while inline images are not resized.
|
||||
|
||||
This image is on its own paragraph, and thus considered "standalone" and resized to fit width:
|
||||
|
||||
|
||||
|
||||
While this one  is embedded in a paragraph and its size is unchanged.
|
||||
|
||||
## Interactive fiction ##
|
||||
|
||||
Crowbook also adds some syntax for interactive fiction, to make
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ It is possible to use Crowbook for HTML previewing in this mode, which
|
|||
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.
|
||||
you save your file) in Emacs' integrated browser.
|
||||
|
||||
### Some explanations if it looks a bit cryptic to you
|
||||
|
||||
|
|
|
|||
|
|
@ -1,14 +1,15 @@
|
|||
Proofreading with Crowbook
|
||||
==========================
|
||||
|
||||
Since version 0.9.1, Crowbook includes some proofreading features,
|
||||
Crowbook includes some proofreading features,
|
||||
that can be enabled if you set one of the
|
||||
|
||||
* `output.proofread.html`
|
||||
* `output.proofread.html_dir`
|
||||
* `output.proofread.pdf`
|
||||
|
||||
output files. This allows you to generate different files for
|
||||
output files (or include `proofread.pdf` in the list of formats to
|
||||
render to `output`). This allows you to generate different files for
|
||||
publishing and proofreading (you probably don't want to publish a
|
||||
version that highlights your grammar errors or your repetitions).
|
||||
|
||||
|
|
@ -89,9 +90,9 @@ For more information, see
|
|||
Grammar checking
|
||||
----------------
|
||||
|
||||
## With languagetool
|
||||
### With Languagetool
|
||||
|
||||
Crowbook can also use [LanguageTool](https://languagetool.org/) to
|
||||
Crowbook can use [LanguageTool](https://languagetool.org/) to
|
||||
detect grammar errors in your text. It is, however, a bit more
|
||||
complex to activate.
|
||||
|
||||
|
|
@ -124,10 +125,10 @@ HTML or PDF proofreading output files.
|
|||
> Note: running a grammar check on a long book (like a novel) can take
|
||||
> up to a few minutes.
|
||||
|
||||
## With Grammalecte
|
||||
### With Grammalecte
|
||||
|
||||
[Grammalecte](http://grammalecte.net/) is a grammar checker
|
||||
specialized for french language. If the language of your book is
|
||||
specialized for the french language. If the language of your book is
|
||||
french, you can use it in a similar fashion to languagetool:
|
||||
|
||||
```yaml
|
||||
|
|
@ -146,4 +147,4 @@ $ python3 server.py
|
|||
|
||||
You can then run Crowbook with `--proofread` to check the grammar of
|
||||
your book. It is possible to run both LanguageTool and Grammalecte on
|
||||
the same book (though might take some minutes a long book...).
|
||||
the same book (though might take a while for a long book...).
|
||||
|
|
|
|||
|
|
@ -27,7 +27,15 @@ Create and edit template
|
|||
Except for inline templates, which are set directly in the book configuration file:
|
||||
|
||||
```yaml
|
||||
# Template that modify how a chapter title is displayed
|
||||
rendering.chapter.template: "{{{loc_chapter}}} {{{number}}}: {{{chapter_title}}}"
|
||||
|
||||
# CSS code added to default CSS templates (but don't override it)
|
||||
html.css.add: "h1 { background-color: red; }"
|
||||
epub.css.add: "h1 { background-color: gray; }"
|
||||
|
||||
# LaTeX code added to default LaTeX template (but doesn't override it)
|
||||
template.tex.add: "\usepackage{libertineotf}"
|
||||
```
|
||||
|
||||
most templates must be in a separate file:
|
||||
|
|
@ -92,7 +100,7 @@ In this case, Crowbook sets a variable whose name is equal to
|
|||
`lang_foo` to `true`, allowing to have different styles for some
|
||||
elements according to the language.
|
||||
|
||||
For more information about Mustache syntax, see
|
||||
For more information about Mustache syntax, see the
|
||||
[Mustache manual](http://mustache.github.io/mustache.5.html).
|
||||
|
||||
#### Syntax in LaTeX ####
|
||||
|
|
@ -209,7 +217,7 @@ Crowbook also has some inline templates, that are set in the book configuration
|
|||
inserted at the end of the template (allowing to redefine rules that
|
||||
are set by the template); for the LaTeX template, the code is
|
||||
inserted at the end of the preambule, just before the
|
||||
`\begin{document}` tag.
|
||||
`\begin{document}` tag, allowing to redefine commands.
|
||||
* `rendering.inline_toc.name` sets the name of the inline table of content, if it is displayed. By default, is is set to `{{{loc_toc}}}`, that is, a localised version of "Table of Contents".
|
||||
* `rendering.chapter.template` sets the naming scheme for chapters,
|
||||
while `rendering.part.template` does the same for part. These are
|
||||
|
|
@ -233,6 +241,7 @@ For every template, Crowbook exports all of the metadata:
|
|||
|
||||
* `author`;
|
||||
* `title`;
|
||||
* `subtitle`;
|
||||
* `lang`;
|
||||
* `subject`;
|
||||
* `description`;
|
||||
|
|
@ -314,5 +323,6 @@ below.
|
|||
| `tex_title` | Set to true to run `\maketitle` | `tex.template` |
|
||||
| `tex_size` | The font size to pass to the LaTeX class | `tex.template` |
|
||||
| `has_tex_size` | Set to true if `tex_size` is set | `tex.template` |
|
||||
| `margin_left`, `margin_right`, `margin_top`, `margin_bottom` | The margins of the document | `tex.template` |
|
||||
| `initials` | True if `rendering.initials` is true, not set else | `tex.template` |
|
||||
| `additional_code` | Set to the content of `tex.template.add`, `html.css.add` or `epub.css.add` | `tex.template`, `html.css`, `epub.css` |
|
||||
|
|
|
|||
Loading…
Reference in New Issue