mirror of
https://github.com/lise-henry/crowbook
synced 2024-09-22 09:10:43 +02:00
330 lines
17 KiB
HTML
330 lines
17 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="generator" content="crowbook">
|
||
<meta name="author" content="Élisabeth Henry">
|
||
<meta name="viewport" content="width=device-width">
|
||
<link rel = "icon" href = "images/image_0.svg">
|
||
<title>Crowbook User Guide – 2. Arguments</title>
|
||
<link rel = "stylesheet" href = "stylesheet.css" type = "text/css"
|
||
/>
|
||
<link rel = "stylesheet" href = "print.css" type = "text/css"
|
||
media = "print" />
|
||
<link rel = "stylesheet" href = "highlight.css" type = "text/css"
|
||
/>
|
||
<script src = "highlight.js"></script>
|
||
<script>
|
||
hljs.initHighlightingOnLoad();
|
||
</script>
|
||
<script>
|
||
function on(name) {
|
||
var elements = document.getElementsByClassName(name);
|
||
for (var i = 0; i < elements.length; i++) {
|
||
var elem = elements[i];
|
||
elem.style.backgroundColor = "pink";
|
||
}
|
||
}
|
||
function off(name) {
|
||
var elements = document.getElementsByClassName(name);
|
||
for (var i = 0; i < elements.length; i++) {
|
||
var elem = elements[i];
|
||
elem.style.backgroundColor = "white";
|
||
}
|
||
}
|
||
|
||
var display_menu = false;
|
||
function toggle() {
|
||
if (display_menu == true) {
|
||
display_menu = false;
|
||
document.getElementById("nav").style.left = "-21%";
|
||
document.getElementById("content").style.marginLeft = "0%";
|
||
document.getElementById("menu").style.left = "1em";
|
||
/* if(document.getElementById("top")) {
|
||
document.getElementById("top").style.left = "0";
|
||
}
|
||
if(document.getElementById("footer")) {
|
||
document.getElementById("footer").style.marginLeft = "0%";
|
||
}*/
|
||
} else {
|
||
display_menu = true;
|
||
document.getElementById("nav").style.left = "0";
|
||
document.getElementById("content").style.marginLeft = "20%";
|
||
document.getElementById("menu").style.left = "20%";
|
||
/* if(document.getElementById("top")) {
|
||
document.getElementById("top").style.left = "20%";
|
||
}
|
||
if(document.getElementById("footer")) {
|
||
document.getElementById("footer").style.marginLeft = "20%";
|
||
}*/
|
||
}
|
||
}
|
||
|
||
</script>
|
||
|
||
|
||
</head>
|
||
<body>
|
||
|
||
<nav id = "nav">
|
||
<h2><a href = "index.html">Crowbook User Guide</a></h2>
|
||
<ul>
|
||
<li><a href = "chapter_000.html#link-1">1. Crowbook</a>
|
||
<ul><li><a href = "chapter_000.html#link-2">1.1. Example</a></li>
|
||
<li><a href = "chapter_000.html#link-3">1.2. Installing</a></li>
|
||
<li><a href = "chapter_000.html#link-6">1.3. Dependencies</a></li>
|
||
<li><a href = "chapter_000.html#link-7">1.4. Quick tour</a></li>
|
||
<li><a href = "chapter_000.html#link-8">1.5. Current features</a></li>
|
||
<li><a href = "chapter_000.html#link-16">1.6. Contributors</a></li>
|
||
<li><a href = "chapter_000.html#link-17">1.7. Acknowledgements</a></li>
|
||
<li><a href = "chapter_000.html#link-18">1.8. ChangeLog</a></li>
|
||
<li><a href = "chapter_000.html#link-19">1.9. Contributing</a></li>
|
||
<li><a href = "chapter_000.html#link-20">1.10. Library</a></li>
|
||
<li><a href = "chapter_000.html#link-21">1.11. License</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_001.html#link-22">2. Arguments</a>
|
||
<ul><li><a href = "chapter_001.html#link-23">2.1. <code>--create</code></a></li>
|
||
<li><a href = "chapter_001.html#link-25">2.2. <code>--single</code></a></li>
|
||
<li><a href = "chapter_001.html#link-26">2.3. <code>--set</code></a></li>
|
||
<li><a href = "chapter_001.html#link-28">2.4. <code>--proofread</code></a></li>
|
||
<li><a href = "chapter_001.html#link-29">2.5. <code>--list-options</code></a></li>
|
||
<li><a href = "chapter_001.html#link-30">2.6. <code>--print-template</code></a></li>
|
||
<li><a href = "chapter_001.html#link-31">2.7. <code>--verbose</code></a></li>
|
||
<li><a href = "chapter_001.html#link-32">2.8. <code>--to</code></a></li>
|
||
<li><a href = "chapter_001.html#link-34">2.9. <code>--output</code></a></li>
|
||
<li><a href = "chapter_001.html#link-35">2.10. <code>--lang</code></a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_002.html#link-37">3. The configuration file</a>
|
||
<ul><li><a href = "chapter_002.html#link-38">3.1. Configuration in an inline YAML block</a></li>
|
||
<li><a href = "chapter_002.html#link-39">3.2. The list of files</a></li>
|
||
<li><a href = "chapter_002.html#link-41">3.3. Crowbook options</a></li>
|
||
<li><a href = "chapter_002.html#link-55">3.4. Full list of options</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_003.html#link-71">4. Templates</a>
|
||
<ul><li><a href = "chapter_003.html#link-72">4.1. Create and edit template</a></li>
|
||
<li><a href = "chapter_003.html#link-76">4.2. List of templates</a></li>
|
||
<li><a href = "chapter_003.html#link-90">4.3. List of accessible variables</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_004.html#link-94">5. Proofreading with Crowbook</a>
|
||
<ul><li><a href = "chapter_004.html#link-95">5.1. Enabling proofreading</a></li>
|
||
<li><a href = "chapter_004.html#link-96">5.2. Repetition detection</a></li>
|
||
<li><a href = "chapter_004.html#link-97">5.3. Grammar checking</a></li>
|
||
<li><a href = "chapter_004.html#link-98">5.4. Highlighting non-breaking spaces</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_005.html#link-99">6. Tips and tricks</a>
|
||
<ul><li><a href = "chapter_005.html#link-100">6.1. Using Crowbook with Emacs’ markdown mode</a></li>
|
||
<li><a href = "chapter_005.html#link-103">6.2. Embedding fonts in an EPUB file</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_006.html#link-104">7. Contributing</a>
|
||
<ul><li><a href = "chapter_006.html#link-105">7.1. Internationalization</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_007.html#link-106">ChangeLog</a>
|
||
<ul><li><a href = "chapter_007.html#link-107">0.11.0 (???)</a></li>
|
||
<li><a href = "chapter_007.html#link-108">0.10.4 (2016-12-16)</a></li>
|
||
<li><a href = "chapter_007.html#link-109">0.10.3 (2016-11-19)</a></li>
|
||
<li><a href = "chapter_007.html#link-110">0.10.2 (2016-10-21)</a></li>
|
||
<li><a href = "chapter_007.html#link-111">0.10.1 (2016-10-18)</a></li>
|
||
<li><a href = "chapter_007.html#link-112">0.10.0 (2016-10-18)</a></li>
|
||
<li><a href = "chapter_007.html#link-113">0.9.1 (2016-09-29)</a></li>
|
||
<li><a href = "chapter_007.html#link-114">0.9.0 (2016-09-23)</a></li>
|
||
<li><a href = "chapter_007.html#link-115">0.8.0 (2016-09-19)</a></li>
|
||
<li><a href = "chapter_007.html#link-116">0.7.0 (2016-09-11)</a></li>
|
||
<li><a href = "chapter_007.html#link-117">0.6.0 (2016-09-09)</a></li>
|
||
<li><a href = "chapter_007.html#link-118">0.5.1 (2016-04-14)</a></li>
|
||
<li><a href = "chapter_007.html#link-119">0.5.0 (2016-04-02)</a></li>
|
||
<li><a href = "chapter_007.html#link-120">0.4.0 (2016-03-01)</a></li>
|
||
<li><a href = "chapter_007.html#link-121">0.3.0 (2016-02-27)</a></li>
|
||
<li><a href = "chapter_007.html#link-122">0.2.2 (2016-02-25)</a></li>
|
||
<li><a href = "chapter_007.html#link-123">0.2.1 (2016-02-25)</a></li>
|
||
<li><a href = "chapter_007.html#link-124">0.2.0 (2016-02-25)</a></li>
|
||
<li><a href = "chapter_007.html#link-125">0.1.0 (2016-02-21)</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_008.html#link-126">GNU LESSER GENERAL PUBLIC LICENSE</a></li>
|
||
|
||
</ul>
|
||
|
||
</nav>
|
||
|
||
<div id = "content">
|
||
<div id = "top"><p id = "para-298">Crowbook User Guide 0.11.0</p>
|
||
</div>
|
||
<div id = "page">
|
||
<header>
|
||
<div id = "menu">
|
||
<img id = "menu-button" onclick="toggle();"
|
||
src="menu.svg" alt = "Table of contents" title = "Table of contents" />
|
||
</div>
|
||
</header>
|
||
<p class = "prev_chapter">
|
||
<a href = "chapter_000.html">
|
||
« 1. Crowbook
|
||
</a>
|
||
</p>
|
||
<h1 id = "link-22">2. Arguments</h1>
|
||
<p id = "para-44">Crowbook can take a number of arguments:</p>
|
||
<pre><code class = "language-text">Render a Markdown book in EPUB, PDF or HTML.
|
||
|
||
USAGE:
|
||
crowbook [OPTIONS] [--] [BOOK]
|
||
|
||
FLAGS:
|
||
-h, --help Print help information
|
||
-l, --list-options List all possible options
|
||
-p, --proofread Enable proofreading
|
||
-q, --quiet Don't print info/error messages
|
||
-s, --single Use a single Markdown file instead of a book configuration file
|
||
-v, --verbose Print warnings in parsing/rendering
|
||
-V, --version Print version information
|
||
|
||
OPTIONS:
|
||
-c, --create <FILES>... Create a new book with existing Markdown files
|
||
-o, --output <FILE> Specify output file
|
||
--print-template <TEMPLATE> Prints the default content of a template
|
||
--set <KEY_VALUES> Set a list of book options
|
||
-t, --to <FORMAT> Generate specific format
|
||
|
||
ARGS:
|
||
<BOOK> File containing the book configuration file, or a Markdown file when called with --single
|
||
</code></pre>
|
||
<p id = "para-45">The most important option is obviously <BOOK>, i.e. the book configuration file. It is mandatory in most cases: if you don’t pass it, Crowbook will simply display this help message. In a normal use case this is the only argument you’ll need to pass, and Crowbook will generate the book in all formats specified in the configuration file.</p>
|
||
<p id = "para-46">It is, however, possible to pass more arguments to <code>crowbook</code>:</p>
|
||
<h2 id = "link-23">2.1. <code>--create</code></h2>
|
||
<p id = "para-47"><b>Usage</b>: <code>crowbook [BOOK] --create file_1.md file_2.md ...</code></p>
|
||
<p id = "para-48">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 <code>BOOK</code> is not specified) or generate the file <code>BOOK</code> (or abort if it already exists).</p>
|
||
<h3 id = "link-24">Examples</h3>
|
||
<pre><code class = "language-bash">crowbook foo.book --create README.md ChangeLog.md LICENSE.md
|
||
</code></pre>
|
||
<p id = "para-49">will generate a file <code>foo.book</code> containing:</p>
|
||
<pre><code class = "language-yaml">author: Your name
|
||
title: Your title
|
||
lang: en
|
||
|
||
# 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)
|
||
# cover: some_cover.png
|
||
|
||
# List of chapters
|
||
+ README.md
|
||
+ ChangeLog.md
|
||
+ LICENSE.md
|
||
</code></pre>
|
||
<p id = "para-50">while</p>
|
||
<pre><code class = "language-bash">crowbook --create README.md ChangeLog.md LICENSE.md
|
||
</code></pre>
|
||
<p id = "para-51">will print the same result, but to stdout (without creating a file).</p>
|
||
<p id = "para-52">When <code>crowbook</code> is run with <code>--create</code>, it can also use the keys/values set by <code>--set</code> (see below):</p>
|
||
<pre><code class = "language-bash">$ crowbook foo.book --create file1.md file2.md --set author "Pierre Dupont" title "Mon œuvre" lang fr
|
||
</code></pre>
|
||
<p id = "para-53">will generate a <code>foo.book</code> file containing:</p>
|
||
<pre><code class = "language-yaml">author: Pierre Dupont
|
||
title: Mon œuvre
|
||
lang: fr
|
||
|
||
# List of chapters
|
||
+ file1.md
|
||
+ file2.md
|
||
</code></pre>
|
||
<h2 id = "link-25">2.2. <code>--single</code></h2>
|
||
<p id = "para-54"><b>usage</b>: <code>crowbook --single <FILE></code></p>
|
||
<p id = "para-55">(or <code>crowbook -s <FILE></code>)</p>
|
||
<p id = "para-56">This argument allows to give <code>crowbook</code> 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 <code>---</code> (three dashes). E.g:</p>
|
||
<pre><code class = "language-yaml">---
|
||
author: Joan Doe
|
||
title: A short story
|
||
output.html: short.html
|
||
---
|
||
</code></pre>
|
||
<p id = "para-57">If this YAML block is not at the beginning of a file, it must also be preceded by a blank line.</p>
|
||
<p id = "para-58">This allows to not have to write a <code>.book</code> configuration file for a short story or an article. <code>crowbook -s foo.md</code> is rougly equivalent to having a book configuration file containing:</p>
|
||
<pre><code class = "language-yaml">! foo.md
|
||
</code></pre>
|
||
<p id = "para-59">That is, the chapter heading (if any) won’t be displayed in the output documents (though they still appear in the TOC).</p>
|
||
<blockquote><p id = "para-60">Note that by default, using <code>--single</code> or <code>-s</code> sets the default LaTeX class of the book to <code>article</code> instead of <code>book</code>.</p>
|
||
</blockquote>
|
||
<h2 id = "link-26">2.3. <code>--set</code></h2>
|
||
<p id = "para-61"><b>usage</b>: <code>crowbook <BOOK> --set [KEY] [VALUE]...</code></p>
|
||
<p id = "para-62">This argument takes a list of <code>KEY</code> <code>VALUE</code> pairs and allows setting or overriding a book configuration option. All valid options in the configuration files are valid as keys. For more information, see <a href = "chapter_002.html">the configuration file</a>.</p>
|
||
<h3 id = "link-27">Examples</h3>
|
||
<pre><code class = "language-bash">$ crowbook foo.book --set html.css style.css
|
||
</code></pre>
|
||
<p id = "para-63">will override the CSS for HTML generation (the <code>html.css</code> key) to the file <code>style.css</code>.</p>
|
||
<pre><code class = "language-bash">$ crowbook foo.book --set author Foo title Bar
|
||
</code></pre>
|
||
<p id = "para-64">will override the book title to <code>Bar</code> and its author to <code>Foo</code>.</p>
|
||
<h2 id = "link-28">2.4. <code>--proofread</code></h2>
|
||
<p id = "para-65"><b>usage</b>: <code>crowbook --proofread <BOOK></code></p>
|
||
<p id = "para-66">(or <code>crowbook -p <BOOK></code>)</p>
|
||
<p id = "para-67">Equivalent to <code>--set proofread true</code>. Enable proofreading. See <a href = "chapter_004.html">Proofreading</a>.</p>
|
||
<h2 id = "link-29">2.5. <code>--list-options</code></h2>
|
||
<p id = "para-68"><b>usage</b>: <code>crowbook --list-options</code></p>
|
||
<p id = "para-69">(or <code>crowbook -l</code>)</p>
|
||
<p id = "para-70">Displays all the valid options to use, whether in a book configuration file, with <code>--set</code>, or in an inline YAML block.</p>
|
||
<h2 id = "link-30">2.6. <code>--print-template</code></h2>
|
||
<p id = "para-71"><b>usage</b>: <code>crowbook --print-template template</code></p>
|
||
<p id = "para-72">Prints the built-in template to stdout. Useful if you want to customize the appearance of your document. E.g., if you want to modify the CSS used for HTML rendering:</p>
|
||
<pre><code class = "language-bash">$ crowbook --print-template html.css > my_style.css
|
||
# edit my_style.css in your favourite editor
|
||
$ crowbook my.book --set html.css my_style.css
|
||
# or add "html.css: my_style.css" in my.book
|
||
</code></pre>
|
||
<h2 id = "link-31">2.7. <code>--verbose</code></h2>
|
||
<p id = "para-73"><b>usage</b>: <code>crowbook <BOOK> --verbose</code></p>
|
||
<p id = "para-74">If this flag is set, Crowbook will print the warnings it detects 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.</p>
|
||
<h2 id = "link-32">2.8. <code>--to</code></h2>
|
||
<p id = "para-75"><b>usage</b>: <code>crowbook <BOOK>--to [FORMAT]</code></p>
|
||
<p id = "para-76">(or <code>crowbook <BOOK> -t [FORMAT]</code>)</p>
|
||
<p id = "para-77">Generate only the specified format. <code>FORMAT</code> must be either <code>epub</code>, <code>pdf</code>, <code>html</code>, <code>html.dir</code>, <code>odt</code> or <code>tex</code>.</p>
|
||
<p id = "para-78">If an output file for the format is not specified in the book configuration file, <code>crowbook</code> will fail to render PDF, ODT and EPUB, whereas it will print HTML and TeX files on stdout. It is, however, possible to specify a file with the <code>--output</code> option.</p>
|
||
<h3 id = "link-33">Examples</h3>
|
||
<pre><code class = "language-bash">crowbook --to html foo.book
|
||
</code></pre>
|
||
<p id = "para-79">will generate some HTML, and prints it either to the file specified by <code>output.html</code> in <code>foo.book</code>, or to stdout if it is not specified.</p>
|
||
<pre><code class = "language-bash">crowbook --to pdf --output foo.pdf foo.book
|
||
</code></pre>
|
||
<p id = "para-80">will generate a <code>foo.pdf</code> file.</p>
|
||
<h2 id = "link-34">2.9. <code>--output</code></h2>
|
||
<p id = "para-81"><b>usage</b>: <code>crowbook <BOOK> --to <FORMAT> --output <FILE></code></p>
|
||
<p id = "para-82">(or <code>crowbook -t <FORMAT> -o <FILE> <BOOK></code>)</p>
|
||
<p id = "para-83">Specifies an output file. Only valid when <code>--to</code> is used.</p>
|
||
<h2 id = "link-35">2.10. <code>--lang</code></h2>
|
||
<p id = "para-84"><b>usage</b>: <code>crowbook --lang <LANG></code></p>
|
||
<p id = "para-85">(or <code>crowbook -L <LANG></code>)</p>
|
||
<p id = "para-86">Set the runtime language used by Crowbook. Currently, only a french translation is available. By default, Crowbook uses the <code>LANG</code> environment variable to determine which language to use, but this option allows to override it (e.g. for operating systems that don’t use such an option, such as Windows).</p>
|
||
<h3 id = "link-36">Example</h3>
|
||
<p id = "para-87"><code>$ crowbook --lang fr --help</code></p>
|
||
<p id = "para-88">will display Crowbook’s help messages in french.</p>
|
||
<blockquote><p id = "para-89">Note that this argument has nothing to do with the <code>lang</code> option that you can set in the book configuration file, which specifies the language <em>of the book</em>. This argument specifies the language of the text messages that Crowbook will display while running.</p>
|
||
</blockquote>
|
||
|
||
<p class = "next_chapter">
|
||
<a href = "chapter_002.html">
|
||
3. The configuration file »
|
||
</a>
|
||
</p>
|
||
</div>
|
||
<footer id = "footer"><p id = "para-297">Generated by <a href = "https://github.com/lise-henry/crowbook">Crowbook</a> 0.11.0-pre</p>
|
||
</footer>
|
||
</div>
|
||
</body>
|
||
</html>
|